Skip to content

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

11.7 KB
Raw Blame
import type { ClipHook } from "../utils/clip-hook.js";
import type { ThumbnailLayout, ThumbnailPerson } from "../utils/thumbnail-layout.js";

export type { ClipHook, HookMode } from "../utils/clip-hook.js";

export type { ThumbnailLayout, ThumbnailPerson } from "../utils/thumbnail-layout.js";

// === Task Communication Models ===

export interface TaskRequest {
  task_id: string;
  task_type: "transcribe" | "resolve_transcribe_engine" | "compare_engines" | "parse_transcript" | "create_clip" | "batch_clips" | "analyze_energy" | "detect_highlights" | "manage_reel" | "pack_transcript" | "detect_encoder" | "presets" | "ping" | "suggest_clips" | "rank_candidates" | "process_episode" | "find_moment" | "generate_content" | "generate_custom" | "corrections" | "manage_integrations" | "run_integration_tool" | "manage_config" | "manage_env" | "ai_cli_status" | "ai_provider_status" | "analyze_silence" | "render_silence_removed" | "manage_multicam";
  params: object;
}

export interface TaskResult<T = object> {
  task_id: string;
  status: "success" | "error";
  data?: T;
  error?: string;
}

export interface ProgressEvent {
  task_id: string;
  stage: string;
  percent: number;
  message: string;
  clip_result?: BatchClipsResult["results"][number];
  partial?: object;
}

// === Transcript Models ===

export interface WordTimestamp {
  word: string;
  start: number;
  end: number;
  confidence: number;
  speaker?: string | null;
}

export interface TranscriptSegment {
  id: number;
  start: number;
  end: number;
  text: string;
  speaker?: string | null;
}

export interface SpeakerInfo {
  total_time: number;
  segments: number;
  label: string;
}

export interface SpeakerSummary {
  num_speakers: number;
  speakers: Record<string, SpeakerInfo>;
}

export interface SpeakerSegment {
  speaker: string;
  start: number;
  end: number;
}

export interface TranscriptResult {
  transcript: string;
  segments: TranscriptSegment[];
  words: WordTimestamp[];
  duration: number;
  language: string;
  speakers: SpeakerSummary;
  speaker_segments: SpeakerSegment[];
  engine?: string;
  // Present only for a sample-mode transcription (start_seconds/duration_seconds):
  // complete is always false, and timestamps are relative to the sample window,
  // offset from the source by sample_offset_seconds.
  complete?: boolean;
  sample_offset_seconds?: number;
  // Whether diarization was actually tried for this result (set by every
  // branch of backend/services/transcription.py). False for engines that
  // never diarize (whispercpp, omnilingual) regardless of what was
  // requested, see needsDiarizationRetry in services/transcript-cache.ts.
  diarization_attempted?: boolean;
}

// === Clip Models ===

export type CaptionStyle = "branded" | "hormozi" | "karaoke" | "subtle";

export type CropStrategy = "center" | "face" | "speaker";

export type Format = "vertical" | "horizontal" | "square";

export interface ClipRequest {
  video_path: string;
  start_second: number;
  end_second: number;
  caption_style: CaptionStyle;
  crop_strategy: CropStrategy;
  title?: string;
  transcript_words: WordTimestamp[];
}

export interface ClipResult {
  output_path: string;
  duration: number;
  file_size_mb: number;
  format?: Format;
  caption_overlay_path?: string;
  cropped_source_path?: string;
  /** Sidecar subtitles, retimed to the exported file's own playback clock. */
  srt_path?: string;
  vtt_path?: string;
  /** Same audio/loudness/intro/outro, without burned captions. */
  clean_output_path?: string;
  /** The hook as rendered, edges widened to whole words. */
  hook?: ClipHook;
}

export interface SuggestedClip {
  clip_id: string;
  title: string;
  start_second: number;
  end_second: number;
  duration: number;
  payoff?: string;
  standalone?: string;
  context_line?: string;
  reasoning: string;
  preview_text: string;
  segments?: Array<{ start: number; end: number }>;
  /** Spoken passage from inside the clip, played before it. */
  hook?: ClipHook;
  suggested_caption_style?: string;
  timestamp_display?: string;
  content_type?: string;
  score?: number;
  rank?: number;
  /** Fingerprint of render-relevant fields, stamped when the clip is selected for export. */
  selectionHash?: string;
  /** True when the clip was edited after selectionHash was stamped, the selection may be stale. */
  changedSinceSelection?: boolean;
}

export interface UIState {
  videoPath?: string;
  filePath?: string;
  activeExportJobId?: string | null;
  transcript?: TranscriptResult | null;
  /** Identity (path + size + mtime) of the video the transcript was generated from. */
  transcriptVideoIdentity?: { path: string; size: number; mtimeMs: number } | null;
  rawTranscriptText?: string;
  silenceOriginal?: { videoPath: string; transcript: TranscriptResult } | null;
  silencePlan?: object | null;
  /** True when videoPath didn't exist at last check (e.g. an external drive
   * is unmounted). The session is kept, not wiped, while this is set. */
  videoMissing?: boolean;
  suggestions?: SuggestedClip[];
  deselectedIndices?: number[];
  settings?: {
    captionStyle?: string;
    cropStrategy?: string;
    format?: Format;
    logoPath?: string;
    outroPath?: string;
    introPath?: string;
    cleanFillers?: boolean;
    captionPosition?: string;
    captionFontScale?: number;
    logoPosition?: string;
    onboardingDismissed?: boolean;
    silenceThreshold?: number;
    silenceMinPause?: number;
    silencePadding?: number;
  };
  phase?: string;
  lastUpdated?: number;
}

/**
 * Decisions the user has already answered for one episode, so /auto and
 * /produce-shorts ask each question once and reuse the answer on every later
 * run against the same video, including after a Web UI restart, since this
 * is keyed by video identity and stored independently of ui-state.json.
 */
export interface EpisodeDecisions {
  videoPath: string;
  fileSize: number;
  clipCount?: number;
  clipDurationRange?: { min?: number; max?: number };
  captionStyle?: string;
  captionsEnabled?: boolean;
  language?: string;
  thumbnailsWanted?: boolean;
  deliveryTarget?: string;
  notes?: string;
  updatedAt: number;
}

/** One decision from EpisodeDecisions that has no answer yet. */
export interface OpenQuestion {
  field: keyof EpisodeDecisions;
  question: string;
}

/** Who is speaking, shown as a lower third for the first seconds of a clip. */
export interface NameCard {
  title: string;
  subtitle?: string;
  seconds?: number;
  accent?: string;
}

/**
 * How a part of a clip arrives and leaves.
 *
 * Omitted, each caption style uses the motion it has always had.
 */
export interface Motion {
  enter?: "none" | "fade" | "rise" | "pop";
  exit?: "none" | "fade" | "sink";
  /** Frames, at the render's fps. */
  duration?: number;
  feel?: "snap" | "soft" | "linear";
}

export interface ClipMotion {
  captions?: Motion;
  nameCard?: Motion;
}

export interface CreateClipInput {
  clip_number?: number;
  video_path?: string;
  start_second?: number;
  end_second?: number;
  title?: string;
  caption_style?: string;
  crop_strategy?: string;
  format?: Format;
  logo_path?: string;
  outro_path?: string;
  intro_path?: string;
  name_card?: NameCard;
  motion?: ClipMotion;
  transcript_words?: WordTimestamp[];
  clean_fillers?: boolean;
  allow_ass_fallback?: boolean;
  keep_caption_overlay?: boolean;
  write_clean_variant?: boolean;
  /** Overrides the suggestion's hook; null renders without one. */
  hook?: ClipHook | null;
}

export interface BatchClipSpec {
  start_second: number;
  end_second: number;
  title?: string;
  caption_style?: string;
  crop_strategy?: string;
  format?: Format;
  logo_path?: string | null;
  intro_path?: string | null;
  allow_ass_fallback?: boolean;
  keep_caption_overlay?: boolean;
  write_clean_variant?: boolean;
  keep_segments?: Array<{ start: number; end: number }>;
  hook?: ClipHook | null;
}

export interface BatchClipsInput {
  video_path?: string;
  transcript_words?: WordTimestamp[];
  clip_numbers?: number[];
  clips?: BatchClipSpec[];
  export_selected?: boolean;
  format?: Format;
  clean_fillers?: boolean;
  allow_ass_fallback?: boolean;
  keep_caption_overlay?: boolean;
  write_clean_variant?: boolean;
  /**
   * When true, POST to the Web UI's /api/batch-clips and return a job_id
   * immediately so the caller can poll job_status and emit live progress.
   * Requires the Web UI to be running (npm run ui).
   */
  async_mode?: boolean;
}

export interface BatchClipsResult {
  total_clips: number;
  successful_clips: number;
  results: Array<{
    clip_index?: number;
    status: "success" | "error";
    output_path?: string;
    start_second?: number;
    end_second?: number;
    /** Bounds of the clip as submitted; the renderer may trim start_second. */
    source_start_second?: number;
    source_end_second?: number;
    caption_style?: string;
    crop_strategy?: string;
    format?: Format;
    title?: string;
    file_size_mb?: number;
    duration?: number;
    srt_path?: string;
    vtt_path?: string;
    clean_output_path?: string;
    error?: string;
  }>;
}

// === Asset Models ===

export type AssetType =
  | "logo"
  | "outro"
  | "intro"
  | "music"
  | "video"
  | "image"
  | "audio"
  | "other";

export interface Asset {
  name: string;
  type: AssetType;
  path: string;
  addedAt: string;
  default?: boolean;
}

export const ASSETS_SCHEMA_VERSION = 2;

export interface AssetRegistry {
  schemaVersion?: number;
  assets: Asset[];
}

// === Clip History Models ===

export interface ClipPerformanceMetrics {
  views?: number;
  retention?: number; // averageViewPercentage, 0-100
  ctr?: number; // impressionsClickThroughRate, 0-100
  impressions?: number;
  fetched_at?: string;
}

export interface ClipThumbnailConfig {
  text?: string;
  line1?: string; // explicit first line (overrides the AI split)
  line2?: string; // explicit second line
  image_path?: string; // user-supplied background image
  timestamp?: number; // absolute second in the source video for the frame
  preview_path?: string; // chosen thumbnail PNG
  variations?: string[]; // all generated thumbnail PNGs to pick from
  card_seconds?: number; // duration of the thumbnail card baked into the clip start
  layout?: ThumbnailLayout; // the layout the chosen thumbnail was drawn with
  people?: ThumbnailPerson[]; // pair layout only: who sits on each side
}

export interface ClipHistoryEntry {
  id: string;
  source_video: string;
  start_second: number;
  end_second: number;
  caption_style: string;
  crop_strategy: string;
  format?: Format;
  logo_path?: string;
  outro_path?: string;
  intro_path?: string;
  title: string;
  output_path: string;
  file_size_mb: number;
  duration: number;
  created_at: string;
  content_type?: string;
  transcript_slice?: string;
  // Carried from the suggestion at render time: the payoff, the question it
  // answers, and its verbatim opening line. Thumbnail generation grounds
  // headline copy in these instead of the title alone.
  payoff?: string;
  context_line?: string;
  preview_text?: string;
  logo_backup_path?: string;
  logo_position?: string;
  keep_segments?: Array<{ start: number; end: number }>;
  thumbnail_config?: ClipThumbnailConfig;
  youtube_video_id?: string;
  metrics?: ClipPerformanceMetrics;
  // AI-generated publishing metadata (titles/description/tags/hashtags), persisted
  // so it survives a page reload instead of vanishing after generation.
  generated_titles?: string[];
  description?: string;
  tags?: string;
  hashtags?: string;
  // Set for signed-in users once the clip is mirrored to the workspace. A false
  // cloud_synced marks a clip a later sweep should backfill; the local file
  // stays the source of truth either way.
  cloud_id?: string;
  cloud_synced?: boolean;
  cloud_video_uploaded?: boolean;
}

// === Knowledge Base Models ===

export interface KnowledgeFile {
  filename: string;
  content: string;
  updatedAt: string;
}