Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

20.5 KB
Raw Blame
import { readFile, writeFile, mkdir, rm } from "fs/promises";
import { existsSync, readFileSync } from "fs";
import { basename, join } from "path";
import { v4 as uuidv4 } from "uuid";
import { z } from "zod";
import { paths } from "../config/paths.js";
import { writeFileAtomic } from "../utils/atomic-file.js";
import type * as cloudApi from "./podcli-cloud.js";
import { sliceTranscript, sliceWords, findGroundingText } from "../utils/transcript.js";
import { isDemoMode, demoClips } from "../ui/demo-fixtures.js";
import type { BatchClipsResult, ClipHistoryEntry, ClipHook, Format, WordTimestamp } from "../models/index.js";

/**
 * Cloud clip sync uploads rendered videos and transcript slices, so it stays
 * off until PODCLI_CLOUD_SYNC is turned on in the environment or the settings
 * .env. The TypeScript side does not load that file itself, so it is read here.
 */
export function cloudSyncEnabled(): boolean {
  const on = (v: string | undefined) => ["1", "true", "yes", "on"].includes((v ?? "").trim().toLowerCase());

  if (process.env.PODCLI_CLOUD_SYNC !== undefined) return on(process.env.PODCLI_CLOUD_SYNC);

  try {
    const match = readFileSync(paths.envFile, "utf-8").match(/^PODCLI_CLOUD_SYNC=(.*)$/m);

    return on(match?.[1]);
  } catch {
    return false;
  }
}

type BatchResultRow = BatchClipsResult["results"][number];

const wordsSchema = z.array(
  z.object({
    word: z.string(),
    start: z.number(),
    end: z.number(),
    confidence: z.number().default(0),
    speaker: z.string().nullish(),
  }),
);

const timeRangeSchema = z.object({ start: z.number(), end: z.number() });

/** What a render needs to be repeated faithfully. Unknown fields are kept on rewrite. */
const clipRecipeSchema = z.looseObject({
  caption_style: z.string().optional(),
  crop_strategy: z.string().optional(),
  format: z.string().optional(),
  logo_path: z.string().nullish(),
  outro_path: z.string().nullish(),
  intro_path: z.string().nullish(),
  clean_fillers: z.boolean().optional(),
  transcript_words: wordsSchema.optional(),
  keep_segments: z.array(timeRangeSchema).optional(),
  hook: z
    .object({ start: z.number(), end: z.number(), mode: z.enum(["repeat", "move"]) })
    .optional(),
});

export type ClipRecipe = z.infer<typeof clipRecipeSchema>;

/** Reframe editor state: source-absolute keyframes plus the trim window. */
export const reframeStateSchema = z.looseObject({
  keyframes: z.array(z.object({ tAbs: z.number(), x_pct: z.number() })).optional(),
  inSec: z.number().optional(),
  outSec: z.number().optional(),
});

export type ReframeState = z.infer<typeof reframeStateSchema>;

interface BatchRecordContext {
  sourceVideo: string;
  transcriptWords?: WordTimestamp[] | null;
  defaultCaptionStyle?: string;
  defaultCropStrategy?: string;
  defaultFormat?: Format;
  contentTypeFor?: (start: number, end: number) => string | undefined;
  suggestions?: Array<{
    start_second: number;
    end_second: number;
    payoff?: string;
    context_line?: string;
    preview_text?: string;
  }> | null;
}

export interface BatchClipSpec {
  start_second: number;
  end_second: number;
  keep_segments?: Array<{ start: number; end: number }>;
  hook?: ClipHook | null;
}

export interface BatchRecipeContext {
  transcriptWords?: WordTimestamp[] | null;
  logoPath?: string | null;
  outroPath?: string | null;
  introPath?: string | null;
  cleanFillers?: boolean;
  clipSpecs?: BatchClipSpec[];
}

/** The workspace calls clip sync makes. Tests pass a stand-in instead of the hosted API. */
export type HistoryCloud = Pick<
  typeof cloudApi,
  "signedIn" | "sourceHash" | "registerClip" | "uploadClipVideo" | "logClipEvent"
>;

export class ClipsHistory {
  constructor(private readonly cloudClient?: HistoryCloud) {}

  private async loadCloud(): Promise<HistoryCloud> {
    return this.cloudClient ?? (await import("./podcli-cloud.js"));
  }

  private historyPath = paths.clipsHistory;
  // Serializes this process's own read-modify-write cycles so concurrent HTTP
  // requests can't lose each other's edits. Cross-process safety (vs the Python
  // CLI) rests on the atomic temp-file rename in save().
  private writeChain: Promise<unknown> = Promise.resolve();
  private syncing = new Set<string>();

  private async ensureDir() {
    if (!existsSync(paths.history)) {
      await mkdir(paths.history, { recursive: true });
    }
  }

  async load(): Promise<ClipHistoryEntry[]> {
    if (isDemoMode()) return demoClips();

    try {
      if (!existsSync(this.historyPath)) return [];
      const raw = await readFile(this.historyPath, "utf-8");

      // SAFETY: clips.json is written only by save(), which serializes ClipHistoryEntry[].
      return JSON.parse(raw) as ClipHistoryEntry[];
    } catch {
      return [];
    }
  }

  private async save(entries: ClipHistoryEntry[]): Promise<void> {
    if (isDemoMode()) return; // demo fixtures are read-only; never persist to clips.json
    await this.ensureDir();
    await writeFileAtomic(this.historyPath, JSON.stringify(entries, null, 2));
  }

  // Run load → mutate → save as one critical section, queued behind any
  // in-flight mutation. The callback returns the value the caller wants back.
  private mutate<T>(fn: (entries: ClipHistoryEntry[]) => T | Promise<T>): Promise<T> {
    const run = this.writeChain.then(async () => {
      const entries = await this.load();
      const result = await fn(entries);
      await this.save(entries);

      return result;
    });

    this.writeChain = run.then(() => undefined, () => undefined);

    return run;
  }

  async record(entry: Omit<ClipHistoryEntry, "id" | "created_at">): Promise<ClipHistoryEntry> {
    const full: ClipHistoryEntry = {
      ...entry,
      id: uuidv4(),
      created_at: new Date().toISOString(),
    };

    await this.mutate((entries) => {
      entries.push(full);
    });
    void this.syncToCloud(full);

    return full;
  }

  /**
   * Mirror a rendered clip to the workspace, for signed-in users who turned
   * on PODCLI_CLOUD_SYNC.
   *
   * Deliberately not awaited and unable to throw: a clip that rendered
   * successfully must be recorded locally whether or not a server was reachable.
   * The local history file remains the source of truth; this is a copy.
   *
   * Clips that fail to sync are left marked so a later sweep can backfill them,
   * the performance model wants the whole history, not the part that happened to
   * have a working network.
   */
  private async syncToCloud(entry: ClipHistoryEntry): Promise<void> {
    // record() starts this in the background, so `podcli sync` can reach the
    // same entry while it is still in flight and register the clip twice.
    if (!cloudSyncEnabled()) return;

    if (this.syncing.has(entry.id)) return;
    this.syncing.add(entry.id);

    try {
      const cloud = await this.loadCloud();

      if (!(await cloud.signedIn())) return;

      const source = entry.source_video;

      if (!source) return;

      const clipId = entry.cloud_id ?? (await cloud.registerClip({
        sourceHash: await cloud.sourceHash(source),
        episodeTitle: basename(source),
        title: entry.title,
        startSecond: entry.start_second,
        endSecond: entry.end_second,
        durationSec: entry.duration,
        contentType: entry.content_type,
        captionStyle: entry.caption_style,
        aspectRatio: entry.format,
        transcriptSlice: entry.transcript_slice,
      }))?.id;

      if (!clipId) return;

      await this.update(entry.id, { cloud_id: clipId });

      // Metadata alone leaves a share link with nothing to play, so the
      // rendered file follows it. Uploaded once: the server keeps the first
      // copy and answers `unchanged` after that.
      let hasVideo = entry.cloud_video_uploaded === true;
      // A rendered file that no longer exists locally can never be uploaded.
      // There is nothing left to do for it, and reporting it as failed on every
      // run is the unfixable number this file already refuses to print.
      const uploadable = !hasVideo && existsSync(entry.output_path);

      if (uploadable) {
        hasVideo = await cloud.uploadClipVideo(clipId, entry.output_path);

        if (hasVideo) await this.update(entry.id, { cloud_video_uploaded: true });
      }

      // Synchronised means the clip is watchable, not merely described: an
      // upload that failed while still reporting success is how `podcli sync`
      // exits happy with every share link playing nothing.
      await this.update(entry.id, {
        cloud_synced: hasVideo || !existsSync(entry.output_path),
      });
    } catch {
      await this.update(entry.id, { cloud_synced: false }).catch(() => {});
    } finally {
      this.syncing.delete(entry.id);
    }
  }

  // Persist every successful row of a batch render. Single source of truth for
  // turning backend batch results into history entries. Callers used to inline
  // this loop, drifting on defaults and on which fields got recorded.
  async recordBatchResults(
    results: BatchResultRow[] | undefined,
    ctx: BatchRecordContext,
  ): Promise<ClipHistoryEntry[]> {
    if (!results) return [];
    const recorded: ClipHistoryEntry[] = [];

    for (const r of results) {
      if (r.status !== "success" || !r.output_path) continue;
      const start = r.start_second || 0;
      const end = r.end_second || 0;
      recorded.push(
        await this.record({
          source_video: ctx.sourceVideo,
          start_second: start,
          end_second: end,
          caption_style: r.caption_style || ctx.defaultCaptionStyle || "hormozi",
          crop_strategy: r.crop_strategy || ctx.defaultCropStrategy || "speaker",
          format: r.format || ctx.defaultFormat || "vertical",
          title: r.title || "clip",
          output_path: r.output_path,
          file_size_mb: r.file_size_mb || 0,
          duration: r.duration || 0,
          content_type: ctx.contentTypeFor?.(start, end),
          transcript_slice: sliceTranscript(ctx.transcriptWords, start, end),
          ...findGroundingText(ctx.suggestions, start, end),
        }),
      );
    }

    return recorded;
  }

  async persistBatchRecipes(
    rows: BatchResultRow[] | undefined,
    recorded: ClipHistoryEntry[],
    ctx: BatchRecipeContext,
  ): Promise<void> {
    if (!rows?.length || !recorded.length) return;
    let recordedIdx = 0;

    for (const row of rows) {
      if (row.status !== "success" || !row.output_path) continue;
      const rec = recorded[recordedIdx++];

      if (!rec) continue;

      const spec = row.clip_index !== undefined ? ctx.clipSpecs?.[row.clip_index] : undefined;

      await this.persistClipRecipe(rec, {
        transcriptWords: ctx.transcriptWords,
        logoPath: ctx.logoPath,
        outroPath: ctx.outroPath,
        introPath: ctx.introPath,
        cleanFillers: ctx.cleanFillers,
        keepSegments: spec?.keep_segments,
        hook: spec?.hook,
      });
    }
  }

  async persistClipRecipe(
    rec: ClipHistoryEntry,
    ctx: {
      transcriptWords?: WordTimestamp[] | null;
      logoPath?: string | null;
      outroPath?: string | null;
      introPath?: string | null;
      cleanFillers?: boolean;
      keepSegments?: Array<{ start: number; end: number }>;
      hook?: ClipHook | null;
    },
  ): Promise<void> {
    const words = sliceWords(ctx.transcriptWords ?? [], rec.start_second, rec.end_second);
    await this.saveWords(rec.id, words);
    await this.saveRecipe(rec.id, {
      caption_style: rec.caption_style,
      crop_strategy: rec.crop_strategy,
      format: rec.format || "vertical",
      logo_path: ctx.logoPath ?? rec.logo_path ?? null,
      outro_path: ctx.outroPath ?? rec.outro_path ?? null,
      intro_path: ctx.introPath ?? rec.intro_path ?? null,
      clean_fillers: ctx.cleanFillers ?? false,
      transcript_words: words,
      ...(ctx.keepSegments?.length && { keep_segments: ctx.keepSegments }),
      ...(ctx.hook && { hook: ctx.hook }),
    });

    if (ctx.keepSegments?.length) {
      await this.update(rec.id, { keep_segments: ctx.keepSegments });
    }
  }

  /**
   * Check if a clip with the same source, time range, and style already exists.
   * Uses basename matching for source video and ±2s tolerance on time range.
   */
  async findDuplicate(
    sourceVideo: string,
    startSecond: number,
    endSecond: number,
    captionStyle: string,
    cropStrategy: string,
    format: string = "vertical"
  ): Promise<ClipHistoryEntry | null> {
    const entries = await this.load();
    const srcName = basename(sourceVideo);

    return (
      entries.find((e) => {
        if (basename(e.source_video) !== srcName) return false;

        if (e.caption_style !== captionStyle) return false;

        if (e.crop_strategy !== cropStrategy) return false;

        if ((e.format || "vertical") !== format) return false;

        if (Math.abs(e.start_second - startSecond) > 2) return false;

        if (Math.abs(e.end_second - endSecond) > 2) return false;

        // Check output still exists
        return existsSync(e.output_path);
      }) || null
    );
  }

  // mine_channel's yt-dlp download writes "<title> [<video_id>].<ext>" (see
  // ytdlp-args.ts's output template), so the id survives in source_video even
  // though nothing else in the schema tracks where a video came from.
  async minedYouTubeVideoIds(): Promise<Set<string>> {
    const entries = await this.load();
    const ids = new Set<string>();

    for (const e of entries) {
      const m = basename(e.source_video || "").match(/\[([A-Za-z0-9_-]{6,})\]\.[^.]+$/);

      if (m) ids.add(m[1]);
    }

    return ids;
  }

  async list(limit = 50): Promise<ClipHistoryEntry[]> {
    const entries = await this.load();

    return entries.slice(-limit).reverse();
  }

  // Exact match only: REST routes feed req.params.id straight in, so a loose
  // prefix could target the wrong clip (and an empty prefix the first one).
  async findById(id: string): Promise<ClipHistoryEntry | undefined> {
    if (!id) return undefined;
    const entries = await this.load();

    return entries.find((e) => e.id === id);
  }

  // Resolve a full id or an unambiguous ≥4-char prefix to a full id. For the
  // human-facing MCP tool, where typing a short prefix is convenient.
  async resolveId(idOrPrefix: string): Promise<string | null> {
    if (!idOrPrefix) return null;
    const entries = await this.load();

    if (entries.some((e) => e.id === idOrPrefix)) return idOrPrefix;

    if (idOrPrefix.length < 4) return null;
    const matches = entries.filter((e) => e.id.startsWith(idOrPrefix));

    return matches.length === 1 ? matches[0].id : null;
  }

  async update(id: string, patch: Partial<ClipHistoryEntry>): Promise<ClipHistoryEntry | null> {
    if (!id) return null;

    const changed = await this.mutate((entries) => {
      const e = entries.find((x) => x.id === id);

      if (!e) return null;
      const before = e.title;
      Object.assign(e, patch);

      return { entry: e, previousTitle: before };
    });

    if (!changed) return null;

    // A human rewriting a generated title is the clearest taste signal podcli
    // gets: it says what the model produced and what a person preferred
    // instead. Reported only when the title actually changed, so the sync
    // bookkeeping in syncToCloud can't trigger it.
    if (patch.title !== undefined && patch.title !== changed.previousTitle) {
      void this.reportEvent(changed.entry, "title_edited", changed.previousTitle, patch.title);
    }

    return changed.entry;
  }

  /** Best-effort; never blocks or fails the edit that produced it. */
  private async reportEvent(
    entry: ClipHistoryEntry,
    kind: "title_edited" | "discarded" | "thumbnail_regenerated",
    before?: string,
    after?: string,
  ): Promise<void> {
    if (!entry.cloud_id) return;

    try {
      const cloud = await this.loadCloud();

      if (!(await cloud.signedIn())) return;
      await cloud.logClipEvent(entry.cloud_id, kind, before, after);
    } catch {
      // The signal is nice to have, not worth surfacing an error over.
    }
  }

  /**
   * Push clips that never reached the workspace.
   *
   * Covers two cases that both matter: a render that happened while the network
   * was down, and, more importantly, everything rendered *before* the user
   * subscribed. A new Pro user should start with their back catalogue behind the
   * performance model, not an empty history.
   */
  async backfillCloud(limit = 200): Promise<{ synced: number; failed: number }> {
    if (!cloudSyncEnabled()) return { synced: 0, failed: 0 };
    const cloud = await this.loadCloud();

    if (!(await cloud.signedIn())) return { synced: 0, failed: 0 };

    // A clip whose source video has been moved or deleted can never be hashed,
    // so it can never sync. Skipping it keeps `podcli sync` quiet; counting it
    // as a failure would report the same unfixable number on every run until
    // people stopped reading the output.
    const pending = (await this.load())
      .filter((e) => e.source_video && existsSync(e.source_video))
      .filter((e) => !e.cloud_id || !e.cloud_video_uploaded)
      .slice(0, limit);

    let synced = 0;
    let failed = 0;

    for (const entry of pending) {
      try {
        await this.syncToCloud(entry);
        const after = await this.findById(entry.id);

        if (after?.cloud_synced) synced++;
        else failed++;
      } catch {
        failed++;
      }
    }

    return { synced, failed };
  }

  // Remove a clip and the artifacts podcli rendered for it (output video,
  // word/recipe/reframe sidecars, thumbnail dir). The source video is never touched.
  // Accepts a full id or an unambiguous prefix (MCP convenience).
  async remove(idOrPrefix: string): Promise<ClipHistoryEntry | null> {
    const id = await this.resolveId(idOrPrefix);

    if (!id) return null;

    // Demo entries are read-only fixtures: never delete their (shipped) artifacts.
    if (isDemoMode()) return (await this.findById(id)) ?? null;

    const entry = await this.mutate((entries) => {
      const idx = entries.findIndex((e) => e.id === id);

      if (idx < 0) return null;

      return entries.splice(idx, 1)[0];
    });

    if (!entry) return null;

    const artifacts = [
      this.wordsPath(entry.id),
      this.recipePath(entry.id),
      this.reframePath(entry.id),
      entry.output_path,
    ];

    await Promise.all(
      artifacts.map((p) => (p ? rm(p, { force: true }) : Promise.resolve())),
    );
    await rm(join(paths.output, "thumbnails", entry.id), { recursive: true, force: true });

    return entry;
  }

  async getBySource(videoPath: string): Promise<ClipHistoryEntry[]> {
    const entries = await this.load();
    const srcName = basename(videoPath);

    return entries.filter((e) => basename(e.source_video) === srcName).reverse();
  }

  // Word timings are kept in a sidecar (not in clips.json) so re-rendering a
  // clip can re-burn captions without bloating the history file.
  private wordsPath(id: string): string {
    return join(paths.history, "words", `${id}.json`);
  }

  async saveWords(id: string, words: WordTimestamp[]): Promise<void> {
    if (words.length === 0) return;
    await mkdir(join(paths.history, "words"), { recursive: true });
    await writeFile(this.wordsPath(id), JSON.stringify(words), "utf-8");
  }

  async loadWords(id: string): Promise<WordTimestamp[]> {
    try {
      return wordsSchema.parse(JSON.parse(await readFile(this.wordsPath(id), "utf-8")));
    } catch {
      return [];
    }
  }

  // Full render recipe (logo/outro/captions/fillers/segments/words) so a clip
  // can be re-rendered faithfully: e.g. after a manual reframe.
  private recipePath(id: string): string {
    return join(paths.history, "recipes", `${id}.json`);
  }

  async saveRecipe(id: string, recipe: ClipRecipe): Promise<void> {
    await mkdir(join(paths.history, "recipes"), { recursive: true });
    await writeFile(this.recipePath(id), JSON.stringify(recipe), "utf-8");
  }

  async loadRecipe(id: string): Promise<ClipRecipe | null> {
    try {
      return clipRecipeSchema.safeParse(JSON.parse(await readFile(this.recipePath(id), "utf-8"))).data ?? null;
    } catch {
      return null;
    }
  }

  // Reframe editor state (keyframes + trim) so reopening shows prior edits.
  private reframePath(id: string): string {
    return join(paths.history, "reframe", `${id}.json`);
  }

  async saveReframe(id: string, state: ReframeState): Promise<void> {
    await mkdir(join(paths.history, "reframe"), { recursive: true });
    await writeFile(this.reframePath(id), JSON.stringify(state), "utf-8");
  }

  async loadReframe(id: string): Promise<ReframeState | null> {
    try {
      return reframeStateSchema.safeParse(JSON.parse(await readFile(this.reframePath(id), "utf-8"))).data ?? null;
    } catch {
      return null;
    }
  }
}