Skip to content

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

feat: async render — batch_create_clips async_mode + generic job_status

Nika Siradze33f87b8276e0
diff --git a/.claude/commands/auto.md b/.claude/commands/auto.md
index 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 — Persist
diff --git a/src/handlers/batch-clips.handler.ts b/src/handlers/batch-clips.handler.ts
index 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.ts
index 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<str
estimate,
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.ts
index 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.ts
index 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));