Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
feat: async render — batch_create_clips async_mode + generic job_status
Nika Siradze33f87b8276e0
diff --git a/.claude/commands/auto.md b/.claude/commands/auto.mdindex 43bb2a4..d3516ca 100644--- a/.claude/commands/auto.md+++ b/.claude/commands/auto.md@@ -80,13 +80,16 @@ Confirm? (yes / redirect / change specific clips)**Stop here. Wait for the user's response.** Do not call `batch_create_clips` on implicit approval — require an explicit "yes", "go", "ship it", or similar.-### Phase 3 — Render+### Phase 3 — Render (with live progress)Once the user confirms:-1. Call `batch_create_clips(clip_numbers=[1,2,...])` with the confirmed list.-2. Stream progress events back to the user as they arrive.-3. When done, print the output paths and a one-line-per-clip summary.+1. Call `batch_create_clips(clip_numbers=[1,2,...], async_mode: true)` → returns `{job_id, clip_count}` immediately.+2. Emit to the user: _"Rendering {clip_count} clips — I'll report progress per clip."_+3. Loop: `job_status(job_id, wait_seconds: 30)` → emit ONE terse line per poll, e.g. `"Rendering 3/7 — clip #3 (speaker crop)"`. Exit when `done: true`.+4. When done, print the output paths and a one-line-per-clip summary (from the result field).++**Fallback**: if `async_mode` fails (Web UI down), fall back to sync `batch_create_clips(clip_numbers=[...])` — renders silently but still works.### Phase 4 — Persistdiff --git a/src/handlers/batch-clips.handler.ts b/src/handlers/batch-clips.handler.tsindex d1462d4..690fe7c 100644--- a/src/handlers/batch-clips.handler.ts+++ b/src/handlers/batch-clips.handler.ts@@ -103,6 +103,14 @@ export const batchClipsToolDef = {},},},+ async_mode: {+ type: "boolean",+ description:+ "Return a job_id immediately and render in the background. Use for multi-clip " ++ "batches so Claude can poll job_status and emit live progress to the user. " ++ "Requires the Web UI to be running (npm run ui). Default: false (sync).",+ default: false,+ },},required: [],},@@ -180,6 +188,42 @@ export async function handleBatchClips(input: BatchClipsInput): Promise<string>});}+ // Async path — route through Web UI so caller can poll job_status for+ // live progress during a multi-minute render. Falls back to sync if the+ // UI isn't running.+ if (input.async_mode) {+ try {+ const res = await fetch("http://localhost:3847/api/batch-clips", {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ video_path: videoPath,+ clips,+ transcript_words: transcriptWords,+ clean_fillers: input.clean_fillers !== false,+ logo_path: settings.logoPath || null,+ outro_path: settings.outroPath || null,+ }),+ });+ if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);+ const data = (await res.json()) as { job_id: string; status: string };+ return JSON.stringify({+ job_id: data.job_id,+ status: data.status,+ clip_count: clips.length,+ next_step: `Poll job_status("${data.job_id}", wait_seconds: 30) in a loop, emitting one terse progress line to the user between polls (e.g. "Rendering 3/7 — clip #3"). Stop when done=true.`,+ });+ } catch (err: unknown) {+ const msg = err instanceof Error ? err.message : String(err);+ if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {+ log.warn("Web UI unavailable, falling back to sync batch render", { err: msg });+ // fall through to sync path+ } else {+ throw err;+ }+ }+ }+const result = await executor.execute<BatchClipsResult>("batch_clips", {video_path: videoPath,clips,diff --git a/src/handlers/transcribe.handler.ts b/src/handlers/transcribe.handler.tsindex 3b19c29..bcae77b 100644--- a/src/handlers/transcribe.handler.ts+++ b/src/handlers/transcribe.handler.ts@@ -195,7 +195,7 @@ export async function handleTranscribeStart(input: TranscribeInput): Promise<strestimate,next_step: data.cached? "Cached — skip polling, read via get_ui_state(include_transcript: true)."- : `Poll transcribe_status("${data.job_id}", wait_seconds: 30) in a loop, emitting progress text to the user between polls.`,+ : `Poll job_status("${data.job_id}", wait_seconds: 30) in a loop, emitting one terse progress line to the user between polls.`,});} catch (err: unknown) {const msg = err instanceof Error ? err.message : String(err);@@ -208,15 +208,15 @@ export async function handleTranscribeStart(input: TranscribeInput): Promise<str}}-export const transcribeStatusToolDef = {- name: "transcribe_status",+export const jobStatusToolDef = {+ name: "job_status",description:- "Poll the status of a background transcription job started via transcribe_start. " ++ "Poll the status of any background job (transcription, clip render, batch export). " +"Supports long-polling: pass wait_seconds (1–60) to block until the job changes state " +- "or the timeout elapses, whichever comes first. This paces Claude's polling naturally " +- "so the spinner doesn't spam.\n\n" ++ "or the timeout elapses, whichever comes first. Paces Claude's polling naturally so " ++ "the spinner doesn't spam and the user sees steady progress text.\n\n" +"Returns { status: 'running'|'done'|'error', progress, message, done, result? }.\n" +- "When done=true, read the packed transcript via get_ui_state(include_transcript: true).",+ "Use after transcribe_start or batch_create_clips(async_mode: true).",inputSchema: {type: "object" as const,properties: {@@ -233,9 +233,10 @@ export const transcribeStatusToolDef = {},};-export async function handleTranscribeStatus(input: {+export async function handleJobStatus(input: {job_id: string;wait_seconds?: number;+ job_kind?: string;}): Promise<string> {const wait = Math.max(0, Math.min(60, input.wait_seconds ?? 30));const deadline = Date.now() + wait * 1000;@@ -268,10 +269,10 @@ export async function handleTranscribeStatus(input: {error: job.error,next_step:job.status === "done"- ? "Read transcript via get_ui_state(include_transcript: true)."+ ? "Job complete. For transcription: get_ui_state(include_transcript: true). For renders: clips are on disk — the result field lists paths.": job.status === "error"- ? "Job failed — check the error and retry transcribe_start if needed."- : `Still running — call transcribe_status("${input.job_id}", wait_seconds: 30) again.`,+ ? "Job failed — check the error. Retry the original start call if appropriate."+ : `Still running — call job_status("${input.job_id}", wait_seconds: 30) again and emit one terse progress line to the user between polls.`,});}diff --git a/src/models/index.ts b/src/models/index.tsindex 8686214..6bf2129 100644--- a/src/models/index.ts+++ b/src/models/index.ts@@ -152,6 +152,12 @@ export interface BatchClipsInput {export_selected?: boolean;clean_fillers?: boolean;allow_ass_fallback?: 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 {diff --git a/src/server.ts b/src/server.tsindex 2516360..c20d943 100644--- a/src/server.ts+++ b/src/server.ts@@ -6,8 +6,8 @@ import {handleTranscribe,transcribeStartToolDef,handleTranscribeStart,- transcribeStatusToolDef,- handleTranscribeStatus,+ jobStatusToolDef,+ handleJobStatus,} from "./handlers/transcribe.handler.js";import { suggestClipsToolDef, handleSuggestClips } from "./handlers/suggest-clips.handler.js";import { createClipToolDef, handleCreateClip } from "./handlers/create-clip.handler.js";@@ -300,18 +300,18 @@ export function createServer(): McpServer {);// =============================================- // Tool: transcribe_status (poll)+ // Tool: job_status (generic poll — transcribe, render, batch)// =============================================server.tool(- transcribeStatusToolDef.name,- transcribeStatusToolDef.description,+ jobStatusToolDef.name,+ jobStatusToolDef.description,{job_id: z.string(),wait_seconds: z.number().min(0).max(60).optional().default(30),},async (input) => {try {- const text = await handleTranscribeStatus(input);+ const text = await handleJobStatus(input);return { content: [{ type: "text" as const, text }] };} catch (err: unknown) {const msg = err instanceof Error ? err.message : String(err);@@ -633,6 +633,14 @@ export function createServer(): McpServer {.describe("Word-level timestamps. Auto-loaded from session state if omitted."),export_selected: z.boolean().optional().describe("If true, export all selected suggestions from the UI."),clip_numbers: z.array(z.number()).optional().describe("Export specific clip numbers from suggestions (e.g. [1, 3, 5])."),+ async_mode: z+ .boolean()+ .optional()+ .default(false)+ .describe(+ "Return a job_id immediately and render in background. Use for multi-clip batches " ++ "so Claude can poll job_status and emit live progress. Requires Web UI running."+ ),},async (params) => {try {@@ -699,7 +707,25 @@ export function createServer(): McpServer {const webData = (await webRes.json()) as WebJob;const jobId = webData.job_id;- // Poll the job until completion (1 hour max)+ // async_mode: return job_id immediately so the caller can narrate+ // progress by polling job_status between outputs.+ if (params.async_mode) {+ return {+ content: [+ {+ type: "text" as const,+ text: JSON.stringify({+ job_id: jobId,+ status: "running",+ clip_count: (resolvedClips || []).length,+ next_step: `Poll job_status("${jobId}", wait_seconds: 30) in a loop, emitting one terse progress line per poll (e.g. "Rendering 3/7 — clip #3"). Stop when done=true.`,+ }),+ },+ ],+ };+ }++ // Sync path — poll internally until completion (1 hour max)const deadline = Date.now() + 3600_000;while (Date.now() < deadline) {await new Promise((r) => setTimeout(r, 2000));