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 transcribe_start/transcribe_status tools for live progress

Nika Siradzec17936f7fcee
diff --git a/.claude/commands/auto.md b/.claude/commands/auto.md
index 63d25ad..43bb2a4 100644
--- a/.claude/commands/auto.md
+++ b/.claude/commands/auto.md
@@ -1,6 +1,6 @@
---
description: One-verb pipeline — drop a video, confirm strategy, render clips
-allowed-tools: Read, Bash, mcp__podcli__transcribe_podcast, mcp__podcli__get_ui_state, mcp__podcli__set_video, mcp__podcli__suggest_clips, mcp__podcli__batch_create_clips, mcp__podcli__knowledge_base, mcp__podcli__clip_history
+allowed-tools: Read, Bash, mcp__podcli__transcribe_podcast, mcp__podcli__transcribe_start, mcp__podcli__transcribe_status, mcp__podcli__get_ui_state, mcp__podcli__set_video, mcp__podcli__suggest_clips, mcp__podcli__batch_create_clips, mcp__podcli__knowledge_base, mcp__podcli__clip_history
argument-hint: [video-path-or-episode-slug] [optional: count e.g. "5 clips"]
triggers:
- auto
@@ -40,10 +40,18 @@ This command orchestrates the existing MCP tools on top of the compact packed tr
### Phase 1 — Inventory
-1. If a video path was given, call `set_video(file_path)` then `transcribe_podcast(file_path)`. If no path, read `get_ui_state` and use the current video.
-2. Read the packed transcript: `get_ui_state(include_transcript: true)`. This returns a compact phrase-grouped view with speakers, silence gaps, and energy peaks.
-3. If `.podcli/knowledge/` exists, read `01-brand-identity.md`, `02-voice-and-tone.md`, and `04-shorts-creation-guide.md` for show context. Skip silently if missing — `/auto` works on any content.
-4. Call `clip_history` to see what's already been shipped for this episode. Avoid duplicates in the proposal.
+1. If a video path was given, call `set_video(file_path)`. If no path, read `get_ui_state` and use the current video.
+2. **Transcribe with progress narration.** Transcription takes 15–25 min on a 60-min episode — do NOT use the silent `transcribe_podcast` for long files. Instead:
+ - Call `transcribe_start(file_path)` → returns `{job_id, cached, estimate}` immediately.
+ - If `cached: true`, skip to step 3.
+ - Otherwise emit a short status to the user: _"Transcription started — estimated {estimate}. I'll check progress every 30s."_
+ - Loop: call `transcribe_status(job_id, wait_seconds: 30)`. Between calls, emit ONE terse line to the user like `"Progress: 47% — pyannote diarization"`. Keep it to one line per poll — no repeat prose. Exit the loop when `done: true`.
+ - If `status: "error"`, stop and report the error.
+3. Read the packed transcript: `get_ui_state(include_transcript: true)`. This returns a compact phrase-grouped view with speakers, silence gaps, and energy peaks.
+4. If `.podcli/knowledge/` exists, read `01-brand-identity.md`, `02-voice-and-tone.md`, and `04-shorts-creation-guide.md` for show context. Skip silently if missing — `/auto` works on any content.
+5. Call `clip_history` to see what's already been shipped for this episode. Avoid duplicates in the proposal.
+
+**Fallback**: if `transcribe_start` returns an error about the Web UI not running, tell the user and offer either (a) run `npm run ui` in another terminal then retry, or (b) fall back to the synchronous `transcribe_podcast` (no live progress, works silently).
### Phase 2 — Strategy Proposal (GATE)
diff --git a/src/handlers/transcribe.handler.ts b/src/handlers/transcribe.handler.ts
index b5a6c29..3b19c29 100644
--- a/src/handlers/transcribe.handler.ts
+++ b/src/handlers/transcribe.handler.ts
@@ -128,3 +128,161 @@ function formatResult(data: TranscriptResult) {
next_step: "Read the transcript via get_ui_state(include_transcript: true), then suggest_clips.",
};
}
+
+// =============================================
+// Async transcription via Web UI job queue
+// =============================================
+
+export const transcribeStartToolDef = {
+ name: "transcribe_start",
+ description:
+ "Start transcription as a background job and return a job_id immediately. " +
+ "Use this instead of transcribe_podcast for long files so you can narrate progress " +
+ "to the user while it runs (a 60-min episode takes 15–25 min).\n\n" +
+ "Flow: call transcribe_start(file_path) → emit status text to user → " +
+ "call transcribe_status(job_id, wait_seconds: 30) in a loop until done → " +
+ "then read the packed transcript via get_ui_state(include_transcript: true).\n\n" +
+ "Requires the Web UI to be running (npm run ui). Returns { job_id, cached, status, estimate_minutes }.",
+ inputSchema: {
+ type: "object" as const,
+ properties: {
+ file_path: { type: "string", description: "Absolute path to the podcast file" },
+ model_size: {
+ type: "string",
+ enum: ["tiny", "base", "small", "medium", "large"],
+ default: "base",
+ },
+ language: { type: "string" },
+ enable_diarization: { type: "boolean", default: true },
+ num_speakers: { type: "number" },
+ },
+ required: ["file_path"],
+ },
+};
+
+export async function handleTranscribeStart(input: TranscribeInput): Promise<string> {
+ try {
+ const res = await fetch("http://localhost:3847/api/transcribe", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ file_path: input.file_path,
+ model_size: input.model_size ?? "base",
+ language: input.language,
+ enable_diarization: input.enable_diarization !== false,
+ num_speakers: input.num_speakers,
+ }),
+ });
+ if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+ const data = (await res.json()) as { job_id: string; status: string; cached?: boolean };
+
+ // Rough estimate — Whisper base + diarization is roughly 1/3× audio duration on CPU.
+ // We don't know duration here; ballpark from file size.
+ let estimate = "10–30 min depending on episode length";
+ try {
+ const { statSync } = await import("fs");
+ const mb = statSync(input.file_path).size / (1024 * 1024);
+ const mins = Math.max(2, Math.round(mb / 50)); // very rough: ~50MB/min of processing
+ estimate = data.cached ? "instant (cached)" : `~${mins}–${mins * 2} min`;
+ } catch {
+ // ignore
+ }
+
+ return JSON.stringify({
+ job_id: data.job_id,
+ cached: !!data.cached,
+ status: data.status,
+ 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.`,
+ });
+ } catch (err: unknown) {
+ const msg = err instanceof Error ? err.message : String(err);
+ if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+ return JSON.stringify({
+ error: "Web UI not running. Start it with `npm run ui`, or fall back to transcribe_podcast for synchronous transcription.",
+ });
+ }
+ throw err;
+ }
+}
+
+export const transcribeStatusToolDef = {
+ name: "transcribe_status",
+ description:
+ "Poll the status of a background transcription job started via transcribe_start. " +
+ "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" +
+ "Returns { status: 'running'|'done'|'error', progress, message, done, result? }.\n" +
+ "When done=true, read the packed transcript via get_ui_state(include_transcript: true).",
+ inputSchema: {
+ type: "object" as const,
+ properties: {
+ job_id: { type: "string" },
+ wait_seconds: {
+ type: "number",
+ default: 30,
+ minimum: 0,
+ maximum: 60,
+ description: "How long to wait for a status change before returning. Default 30s.",
+ },
+ },
+ required: ["job_id"],
+ },
+};
+
+export async function handleTranscribeStatus(input: {
+ job_id: string;
+ wait_seconds?: number;
+}): Promise<string> {
+ const wait = Math.max(0, Math.min(60, input.wait_seconds ?? 30));
+ const deadline = Date.now() + wait * 1000;
+ let lastProgress = -1;
+
+ try {
+ while (true) {
+ const res = await fetch(`http://localhost:3847/api/job/${input.job_id}`);
+ if (res.status === 404) {
+ return JSON.stringify({ error: `Job ${input.job_id} not found` });
+ }
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ const job = (await res.json()) as {
+ status: "running" | "done" | "error";
+ progress: number;
+ message: string;
+ result?: unknown;
+ error?: string;
+ };
+
+ const progressChanged = job.progress !== lastProgress;
+ const terminal = job.status === "done" || job.status === "error";
+
+ if (terminal || progressChanged || Date.now() >= deadline) {
+ return JSON.stringify({
+ status: job.status,
+ progress: job.progress,
+ message: job.message,
+ done: terminal,
+ error: job.error,
+ next_step:
+ job.status === "done"
+ ? "Read transcript via get_ui_state(include_transcript: true)."
+ : 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.`,
+ });
+ }
+
+ lastProgress = job.progress;
+ await new Promise((r) => setTimeout(r, 2000));
+ }
+ } catch (err: unknown) {
+ const msg = err instanceof Error ? err.message : String(err);
+ if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+ return JSON.stringify({ error: "Web UI not running." });
+ }
+ throw err;
+ }
+}
diff --git a/src/server.ts b/src/server.ts
index 373d794..2516360 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -1,7 +1,14 @@
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
-import { transcribeToolDef, handleTranscribe } from "./handlers/transcribe.handler.js";
+import {
+ transcribeToolDef,
+ handleTranscribe,
+ transcribeStartToolDef,
+ handleTranscribeStart,
+ transcribeStatusToolDef,
+ handleTranscribeStatus,
+} from "./handlers/transcribe.handler.js";
import { suggestClipsToolDef, handleSuggestClips } from "./handlers/suggest-clips.handler.js";
import { createClipToolDef, handleCreateClip } from "./handlers/create-clip.handler.js";
import { batchClipsToolDef, handleBatchClips } from "./handlers/batch-clips.handler.js";
@@ -265,6 +272,57 @@ export function createServer(): McpServer {
}
);
+ // =============================================
+ // Tool: transcribe_start (async)
+ // =============================================
+ server.tool(
+ transcribeStartToolDef.name,
+ transcribeStartToolDef.description,
+ {
+ file_path: z.string(),
+ model_size: z.enum(["tiny", "base", "small", "medium", "large"]).optional().default("base"),
+ language: z.string().optional(),
+ enable_diarization: z.boolean().optional().default(true),
+ num_speakers: z.number().optional(),
+ },
+ async (input) => {
+ try {
+ const text = await handleTranscribeStart(input);
+ return { content: [{ type: "text" as const, text }] };
+ } catch (err: unknown) {
+ const msg = err instanceof Error ? err.message : String(err);
+ return {
+ content: [{ type: "text" as const, text: `Error: ${msg}` }],
+ isError: true,
+ };
+ }
+ }
+ );
+
+ // =============================================
+ // Tool: transcribe_status (poll)
+ // =============================================
+ server.tool(
+ transcribeStatusToolDef.name,
+ transcribeStatusToolDef.description,
+ {
+ job_id: z.string(),
+ wait_seconds: z.number().min(0).max(60).optional().default(30),
+ },
+ async (input) => {
+ try {
+ const text = await handleTranscribeStatus(input);
+ return { content: [{ type: "text" as const, text }] };
+ } catch (err: unknown) {
+ const msg = err instanceof Error ? err.message : String(err);
+ return {
+ content: [{ type: "text" as const, text: `Error: ${msg}` }],
+ isError: true,
+ };
+ }
+ }
+ );
+
// =============================================
// Tool: suggest_clips
// =============================================