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
#!/usr/bin/env node
/**
* podcli: Web UI Server
*
* Express server that provides:
* - File upload endpoint for podcast videos
* - Transcription with SSE progress streaming
* - Clip creation with real-time progress
* - Static file serving for the frontend
*/
import express from "express";
import { z } from "zod";
import multer from "multer";
import {
createReadStream,
existsSync,
statSync,
readFileSync,
writeFileSync,
chmodSync,
realpathSync,
} from "fs";
import { copyFile, mkdir, readdir, rename, unlink } from "fs/promises";
import path from "path";
import { join, dirname, basename, extname, resolve } from "path";
import { execSync, execFileSync, spawn } from "child_process";
import { lookup } from "dns/promises";
import { isIP } from "net";
import { tmpdir } from "os";
import { stripVTControlCharacters } from "util";
import { fileURLToPath } from "url";
import { safePath } from "../utils/safe-path.js";
import { rejectReason } from "../utils/local-request.js";
import { EventEmitter } from "events";
import { v4 as uuidv4 } from "uuid";
import { createExecutor, terminateProcessTree } from "../services/python-executor.js";
import { needsDiarizationRetry, TranscriptCache } from "../services/transcript-cache.js";
import { resolveTranscribeEngine, engineCanDiarize } from "../services/engine-resolve.js";
import { FileManager } from "../services/file-manager.js";
import { AssetManager, assetTypeSchema, inferType, safeName } from "../services/asset-manager.js";
import { ClipsHistory, reframeStateSchema } from "../services/clips-history.js";
import { KnowledgeBase } from "../services/knowledge-base.js";
import { paths, pythonEnv } from "../config/paths.js";
import { webServerPort } from "../config/server.js";
import { writeFileAtomicSync } from "../utils/atomic-file.js";
import { maxClipSeconds, validateClipRange, validateSuggestionRange } from "../utils/clip-validation.js";
import { playbackDuration, validateHook } from "../utils/clip-hook.js";
import { hookSchema } from "../handlers/suggest-clips.handler.js";
import { needsFrame, thumbnailRenderArgs } from "../utils/thumbnail-layout.js";
import { parseThumbnailRender } from "../utils/thumbnail-render-output.js";
import { advanceProgress, tagSubmittedClip, tagSubmittedClips } from "../utils/clip-results.js";
import { DEMO_ASSETS_DIR } from "./demo-fixtures.js";
import { registerConfigIntegrationRoutes } from "../handlers/integrations.routes.js";
import { childLogger } from "../utils/logger.js";
import {
sliceTranscript,
findContentType,
findGroundingText,
findSuggestionForRange,
findSuggestionSegments,
reconcileSegmentsForRange,
} from "../utils/transcript.js";
import { formatSrtTime, formatVttTime } from "../utils/srt-time.js";
import { computeVideoIdentity, type VideoIdentity } from "../utils/video-identity.js";
import { computeSelectionHash } from "../utils/selection-hash.js";
import { errMsg } from "../utils/errors.js";
import { resolveByteRange } from "../utils/http-range.js";
import {
FULL_EPISODE_CAPTION_STYLES,
fullEpisodeOutputStem,
parseFullEpisodeProgress,
} from "../utils/full-episode-export.js";
import { buildYtDlpArgs, isCookieBrowser, ytDlpHint } from "../utils/ytdlp-args.js";
import type {
BatchClipsResult,
ClipHistoryEntry,
ClipHook,
ClipResult,
Format,
ProgressEvent,
SuggestedClip,
TranscriptResult,
WordTimestamp,
} from "../models/index.js";
const log = childLogger("web-server");
const stringValue = z.string();
const numberValue = z.number();
const __dirname = dirname(fileURLToPath(import.meta.url));
const publicDir = existsSync(join(__dirname, "public", "index.html"))
? join(__dirname, "public")
: resolve(__dirname, "..", "..", "dist", "ui", "public");
const app = express();
const PORT = webServerPort;
const DEMO = process.env.PODCLI_DEMO === "1";
// --- Services ---
const executor = createExecutor();
const cache = new TranscriptCache();
const fileManager = new FileManager();
const assetManager = new AssetManager();
const clipsHistory = new ClipsHistory();
const knowledgeBase = new KnowledgeBase();
// --- State ---
// Track active jobs so the UI can poll progress
interface JobState {
id: string;
type: "transcribe" | "create_clip" | "batch_clips" | "download_video" | "full_episode" | "silence_analysis" | "silence_render" | "multicam";
status: "pending" | "running" | "done" | "error";
progress: number;
message: string;
result?: unknown;
error?: string;
createdAt: number;
finishedAt?: number;
clip_results?: unknown[];
}
// Fires with a job id whenever a tracked field of that job changes, so the
// per-job SSE stream can push instead of polling.
const jobEvents = new EventEmitter();
jobEvents.setMaxListeners(0);
const pendingJobEvents = new Set<string>();
// One event per burst of assignments (status, progress, message, result are
// usually set back to back), so a listener never sees a half-updated job.
function notifyJobChanged(id: string): void {
if (pendingJobEvents.has(id)) return;
pendingJobEvents.add(id);
setImmediate(() => {
pendingJobEvents.delete(id);
jobEvents.emit(id);
});
}
const TRACKED_JOB_FIELDS = ["status", "progress", "message", "result", "error", "clip_results"] as const;
// Job handlers mutate the object they pass to set() in place, in dozens of
// places. Turning its tracked fields into accessors reports every change
// without touching those call sites.
class JobStore extends Map<string, JobState> {
set(id: string, job: JobState): this {
for (const field of TRACKED_JOB_FIELDS) {
let value = job[field];
Object.defineProperty(job, field, {
enumerable: true,
configurable: true,
get: () => value,
set: (next) => {
if (next === value) return;
value = next;
notifyJobChanged(id);
},
});
}
return super.set(id, job);
}
}
const jobs = new JobStore();
// Sweep terminal jobs so the map doesn't grow forever. Completion isn't
// stamped at the many done/error sites; the sweeper stamps it on first sight,
// so a job survives at least one full retention window after finishing.
const JOB_RETENTION_MS = 30 * 60_000;
setInterval(() => {
const now = Date.now();
for (const [id, job] of jobs) {
if (job.status !== "done" && job.status !== "error") continue;
if (job.finishedAt === undefined) {
job.finishedAt = now;
} else if (now - job.finishedAt > JOB_RETENTION_MS) {
jobs.delete(id);
}
}
}, 60_000).unref();
/** Transcript data stored per file, plus optional face-tracking hints. */
type ServerTranscript = TranscriptResult & { face_map?: unknown };
type SilenceOriginal = { videoPath: string; transcript: ServerTranscript };
type SilencePlan = {
keep_segments: Array<{ start: number; end: number }>;
removed_ranges: Array<{ start: number; end: number }>;
source_duration: number;
output_duration: number;
removed_duration: number;
removed_percent: number;
cut_count: number;
};
// Store the latest transcript per uploaded file for the session
const sessionTranscripts = new Map<string, ServerTranscript>();
// --- MCP ↔ UI Bridge State ---
interface UIState {
videoPath: string;
filePath: string;
activeExportJobId: string | null;
transcript: ServerTranscript | null;
transcriptVideoIdentity: VideoIdentity | null;
rawTranscriptText: string;
silenceOriginal: SilenceOriginal | null;
silencePlan: SilencePlan | null;
// True when the persisted videoPath didn't exist at startup (e.g. an
// external drive is unmounted). The session (transcript, suggestions)
// is kept rather than wiped, since the file may well come back.
videoMissing: boolean;
suggestions: SuggestedClip[];
deselectedIndices: number[];
settings: {
captionStyle: string;
cropStrategy: string;
format: string;
logoPath: string;
outroPath: string;
introPath: string;
cleanFillers: boolean;
captionPosition: string;
captionFontScale: number;
logoPosition: string;
onboardingDismissed: boolean;
silenceThreshold: number;
silenceMinPause: number;
silencePadding: number;
};
phase: string;
results: unknown[];
energyData: Record<string, number[]>;
lastUpdated: number;
}
// Load persisted state or use defaults
function loadPersistedState(): UIState {
try {
if (existsSync(paths.uiState)) {
const raw = readFileSync(paths.uiState, "utf-8");
const saved = JSON.parse(raw);
// A missing video (e.g. its external drive is unmounted) doesn't mean
// the episode is gone. The transcript and suggestions are kept as a
// session the file may rejoin; flag it instead so the caller can warn
// and skip anything that needs the file on disk right now.
const videoMissing = !!saved.videoPath && !existsSync(saved.videoPath);
if (saved.silenceOriginal?.videoPath && !existsSync(saved.silenceOriginal.videoPath)) {
saved.silenceOriginal = null;
}
return {
videoPath: saved.videoPath || "",
filePath: saved.filePath || "",
activeExportJobId: null,
transcript: saved.transcript || null,
transcriptVideoIdentity: saved.transcriptVideoIdentity || null,
rawTranscriptText: saved.rawTranscriptText || "",
silenceOriginal: saved.silenceOriginal || null,
silencePlan: saved.silencePlan || null,
videoMissing,
suggestions: saved.suggestions || [],
deselectedIndices: saved.deselectedIndices || [],
settings: {
captionStyle: saved.settings?.captionStyle || "branded",
cropStrategy: saved.settings?.cropStrategy || "speaker",
format: saved.settings?.format || "vertical",
logoPath: saved.settings?.logoPath || "",
outroPath: saved.settings?.outroPath || "",
introPath: saved.settings?.introPath || "",
cleanFillers: saved.settings?.cleanFillers !== false,
captionPosition: ["auto", "upper", "center", "lower"].includes(saved.settings?.captionPosition) ? saved.settings.captionPosition : "auto",
captionFontScale: Math.max(60, Math.min(160, Number(saved.settings?.captionFontScale) || 100)),
logoPosition: ["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"].includes(saved.settings?.logoPosition) ? saved.settings.logoPosition : "top-left",
onboardingDismissed: !!saved.settings?.onboardingDismissed,
silenceThreshold: Math.max(0.25, Math.min(0.8, Number(saved.settings?.silenceThreshold) || 0.5)),
silenceMinPause: Math.max(0.3, Math.min(5, Number(saved.settings?.silenceMinPause) || 0.65)),
silencePadding: Math.max(0.02, Math.min(0.5, Number(saved.settings?.silencePadding) || 0.12)),
},
// Never restore mid-export phases
phase: ["exporting", "parsing", "suggesting"].includes(saved.phase)
? "idle"
: saved.phase || "idle",
results: ["exporting", "parsing", "suggesting"].includes(saved.phase)
? []
: saved.results || [],
energyData: saved.energyData || {},
lastUpdated: saved.lastUpdated || 0,
};
}
} catch (err) {
log.warn("Failed to load persisted UI state; using defaults", {
err: errMsg(err),
});
}
return {
videoPath: "",
filePath: "",
activeExportJobId: null,
transcript: null,
transcriptVideoIdentity: null,
rawTranscriptText: "",
silenceOriginal: null,
silencePlan: null,
videoMissing: false,
suggestions: [],
deselectedIndices: [],
settings: {
captionStyle: "branded",
cropStrategy: "speaker",
format: "vertical",
logoPath: "",
outroPath: "",
introPath: "",
cleanFillers: true,
captionPosition: "auto",
captionFontScale: 100,
logoPosition: "top-left",
onboardingDismissed: false,
silenceThreshold: 0.5,
silenceMinPause: 0.65,
silencePadding: 0.12,
},
phase: "idle",
results: [],
energyData: {},
lastUpdated: 0,
};
}
const uiState: UIState = loadPersistedState();
// Files the server confirmed the user selected; /api/stream-source serves only
// these, so a forged /api/ui-state can't grant reads of arbitrary files.
const allowedSourcePaths = new Set<string>();
// Recent source videos, referenced in place (never copied) so they can be
// re-picked without re-uploading. Persisted as paths only, no GB bloat.
const sourcesFile = join(paths.home, "sources.json");
const VIDEO_SOURCE_EXTS = new Set([".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi"]);
let recentSources: string[] = loadRecentSources();
function loadRecentSources(): string[] {
try {
const raw = JSON.parse(readFileSync(sourcesFile, "utf-8"));
return z.array(z.string()).catch([]).parse(raw);
} catch {
return [];
}
}
function rememberSource(realPath: string): void {
if (!VIDEO_SOURCE_EXTS.has(extname(realPath).toLowerCase())) return;
recentSources = [realPath, ...recentSources.filter((p) => p !== realPath)].slice(0, 40);
try {
writeFileAtomicSync(sourcesFile, JSON.stringify(recentSources, null, 2));
} catch {}
}
function registerSourcePath(p: string | undefined | null): void {
if (!p) return;
try {
const real = realpathSync(path.resolve(p));
allowedSourcePaths.add(real);
rememberSource(real);
} catch {}
}
registerSourcePath(uiState.videoPath);
registerSourcePath(uiState.silenceOriginal?.videoPath);
// Client-supplied source paths are honoured only after the user uploaded or
// selected the file this session. existsSync alone would let a forged request
// probe, read, or re-encode any file the server user can reach.
function resolveAllowedSource(p: string | undefined): string | null {
if (!p) return null;
let real: string;
try {
real = realpathSync(path.resolve(p));
} catch {
return null;
}
return allowedSourcePaths.has(real) ? real : null;
}
// Debounced save to disk
let saveTimer: ReturnType<typeof setTimeout> | null = null;
function persistState() {
if (saveTimer) clearTimeout(saveTimer);
saveTimer = setTimeout(() => {
try {
writeFileAtomicSync(paths.uiState, JSON.stringify(uiState, null, 2));
} catch (err) {
log.warn("Failed to persist UI state to disk", { err: errMsg(err) });
}
}, 500);
}
// SSE clients for the global event bus
import type { Request, Response } from "express";
const sseClients: Response[] = [];
function streamVideo(req: Request, res: Response, filePath: string, contentType = "video/mp4") {
if (contentType === "image/svg+xml") {
// An uploaded SVG can carry script. Sandboxing it keeps that script out of
// the studio's origin when the file is opened directly.
res.setHeader("Content-Security-Policy", "sandbox");
}
const fileSize = statSync(filePath).size;
const range = req.headers.range;
const onErr = (stream: ReturnType<typeof createReadStream>) =>
stream.on("error", () => res.destroy());
if (range) {
const resolved = resolveByteRange(range, fileSize);
if (!resolved) {
res.writeHead(416, { "Content-Range": `bytes */${fileSize}` }).end();
return;
}
const { start, end } = resolved;
res.writeHead(206, {
"Content-Range": `bytes ${start}-${end}/${fileSize}`,
"Accept-Ranges": "bytes",
"Content-Length": end - start + 1,
"Content-Type": contentType,
});
const stream = createReadStream(filePath, { start, end });
onErr(stream);
stream.pipe(res);
} else {
res.writeHead(200, { "Content-Length": fileSize, "Content-Type": contentType });
const stream = createReadStream(filePath);
onErr(stream);
stream.pipe(res);
}
}
function broadcastSSE<T>(event: string, data: T) {
const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
for (let i = sseClients.length - 1; i >= 0; i--) {
try {
sseClients[i].write(payload);
} catch {
sseClients.splice(i, 1);
}
}
}
function broadcastHistoryUpdated(jobId: string | null, clips: unknown[]) {
if (clips.length === 0) return;
broadcastSSE("history-updated", { jobId, count: clips.length });
}
function setExportState(phase: string, activeExportJobId: string | null) {
uiState.phase = phase;
uiState.activeExportJobId = activeExportJobId;
uiState.lastUpdated = Date.now();
persistState();
}
type ExportClip = {
start_second: number;
end_second: number;
keep_segments?: Array<{ start: number; end: number }>;
hook?: ClipHook | null;
};
/** Fill segments and hook the caller left out from the matching suggestion.
* An explicit hook: null stays null, so a render can opt out of one. */
function enrichClipFromSuggestion<T extends ExportClip>(clip: T): T {
const match = findSuggestionForRange(uiState.suggestions, clip.start_second, clip.end_second);
if (!match) return clip;
return {
...clip,
...(!clip.keep_segments?.length && match.segments?.length && { keep_segments: match.segments }),
...(clip.hook === undefined && match.hook && { hook: match.hook }),
};
}
function exportHookError(clips: ExportClip[]): string | null {
for (let i = 0; i < clips.length; i++) {
const c = clips[i];
const err = validateHook(c.hook, c.start_second, c.end_second, c.keep_segments);
if (err) return clips.length > 1 ? `Clip ${i + 1}: ${err}` : err;
}
return null;
}
function createBatchHistoryRecorder({
jobId,
sourceVideo,
transcriptWords,
defaultCaptionStyle,
defaultCropStrategy,
defaultFormat,
label,
clipSpecs,
logoPath,
outroPath,
introPath,
cleanFillers,
}: {
jobId: string;
sourceVideo: string;
transcriptWords: WordTimestamp[];
defaultCaptionStyle?: string;
defaultCropStrategy?: string;
defaultFormat?: Format;
label: string;
clipSpecs?: Array<{
start_second: number;
end_second: number;
caption_style?: string;
crop_strategy?: string;
format?: Format;
keep_segments?: Array<{ start: number; end: number }>;
hook?: ClipHook | null;
}>;
logoPath?: string | null;
outroPath?: string | null;
introPath?: string | null;
cleanFillers?: boolean;
}) {
const recordedClipIndexes = new Set<number>();
const pendingWrites: Promise<void>[] = [];
const recordRows = async (rows: BatchClipsResult["results"]) => {
const recorded = await clipsHistory.recordBatchResults(rows, {
sourceVideo,
transcriptWords,
defaultCaptionStyle,
defaultCropStrategy,
defaultFormat,
contentTypeFor: (s, e) => findContentType(uiState.suggestions, s, e),
suggestions: uiState.suggestions,
});
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 ? clipSpecs?.[row.clip_index] : undefined;
try {
await clipsHistory.persistClipRecipe(rec, {
transcriptWords,
logoPath,
outroPath,
introPath,
cleanFillers,
keepSegments: spec?.keep_segments,
hook: spec?.hook,
});
} catch (err) {
log.warn(`Failed to save recipe for ${label} clip`, { err: errMsg(err) });
}
}
for (const row of rows) {
if (row.status === "success" && row.output_path && row.clip_index !== undefined) {
recordedClipIndexes.add(row.clip_index);
}
}
broadcastHistoryUpdated(jobId, recorded);
};
return {
recordProgress(event: ProgressEvent) {
if (event.stage !== "clip_complete" || !event.clip_result) return;
const write = recordRows([event.clip_result]).catch((err) => {
log.warn(`Failed to record completed ${label} clip to history`, {
err: errMsg(err),
});
});
pendingWrites.push(write);
},
async recordRemaining(results: BatchClipsResult["results"] | undefined) {
await Promise.allSettled(pendingWrites);
const remaining = results?.filter(
(row) =>
row.clip_index === undefined ||
!recordedClipIndexes.has(row.clip_index),
);
if (remaining?.length) await recordRows(remaining);
},
};
}
// --- Middleware ---
const bindHost = process.env.PODCLI_HOST || "127.0.0.1";
const bindsLoopbackOnly = ["127.0.0.1", "localhost", "::1"].includes(bindHost);
app.use((req, res, next) => {
const reason = rejectReason(req.method, req.headers, !bindsLoopbackOnly);
if (reason) {
res.status(403).json({ error: reason });
return;
}
next();
});
app.use(express.json({ limit: "50mb" }));
// Serve static frontend. redirect:false so the /assets page route isn't shadowed
// by a 301 to the Vite bundle's assets/ directory; it falls through to the SPA.
app.use(express.static(publicDir, { redirect: false }));
// File upload config
const uploadDir = join(paths.working, "uploads");
const upload = multer({
storage: multer.diskStorage({
destination: async (_req, _file, cb) => {
await mkdir(uploadDir, { recursive: true });
cb(null, uploadDir);
},
filename: (_req, file, cb) => {
const ext = extname(file.originalname);
cb(null, `${uuidv4()}${ext}`);
},
}),
limits: { fileSize: 10 * 1024 * 1024 * 1024 }, // 10 GB
fileFilter: (_req, file, cb) => {
const allowed = [
".mp4",
".mov",
".mkv",
".webm",
".mp3",
".wav",
".m4a",
".png",
".jpg",
".jpeg",
".svg",
];
const ext = extname(file.originalname).toLowerCase();
if (allowed.includes(ext)) {
cb(null, true);
} else {
cb(
new Error(
`Unsupported format: ${ext}. Use MP4, MOV, MKV, WebM, MP3, WAV, M4A.`,
),
);
}
},
});
function clearEpisodeSessionState(): void {
sessionTranscripts.clear();
allowedSourcePaths.clear();
uiState.videoPath = "";
uiState.filePath = "";
uiState.videoMissing = false;
uiState.activeExportJobId = null;
uiState.transcript = null;
uiState.transcriptVideoIdentity = null;
uiState.rawTranscriptText = "";
uiState.silenceOriginal = null;
uiState.silencePlan = null;
uiState.suggestions = [];
uiState.deselectedIndices = [];
uiState.phase = "idle";
uiState.results = [];
uiState.energyData = {};
uiState.lastUpdated = Date.now();
}
function activeBlockingJobs(): JobState[] {
return [...jobs.values()].filter(
(job) =>
job.status === "running" &&
["transcribe", "create_clip", "batch_clips", "silence_analysis", "silence_render"].includes(job.type),
);
}
function isPublicIp(address: string): boolean {
const family = isIP(address);
const mapped = address.toLowerCase().startsWith("::ffff:") ? address.slice(7) : "";
if (mapped) {
if (isIP(mapped) === 4) return isPublicIp(mapped);
const parts = mapped.split(":").map((part) => Number.parseInt(part, 16));
if (parts.length === 2 && parts.every((part) => Number.isFinite(part))) {
return isPublicIp([
parts[0] >> 8,
parts[0] & 255,
parts[1] >> 8,
parts[1] & 255,
].join("."));
}
}
if (family === 4) {
const parts = address.split(".").map((part) => Number(part));
const [a, b] = parts;
return !(
a === 0 ||
a === 10 ||
a === 127 ||
(a === 100 && b >= 64 && b <= 127) ||
(a === 169 && b === 254) ||
(a === 172 && b >= 16 && b <= 31) ||
(a === 192 && b === 168) ||
(a === 198 && (b === 18 || b === 19)) ||
a >= 224
);
}
if (family === 6) {
const normalized = address.toLowerCase();
return !(
normalized === "::1" ||
normalized === "::" ||
normalized.startsWith("fc") ||
normalized.startsWith("fd") ||
normalized.startsWith("fe80:")
);
}
return false;
}
async function validateDownloadUrl(rawUrl: string | undefined): Promise<string> {
if (!rawUrl?.trim()) {
throw new Error("url is required");
}
let parsed: URL;
try {
parsed = new URL(rawUrl.trim());
} catch {
throw new Error(`Invalid URL: ${rawUrl}`);
}
if (!["http:", "https:"].includes(parsed.protocol)) {
throw new Error(`Unsupported URL protocol: ${parsed.protocol}. Use http or https.`);
}
// Best-effort SSRF preflight: yt-dlp still resolves redirects itself at download time.
const addresses = await lookup(parsed.hostname, { all: true, verbatim: false });
if (addresses.length === 0 || addresses.some((entry) => !isPublicIp(entry.address))) {
throw new Error(`Download URL host is not allowed: ${parsed.hostname}. Use a public video URL.`);
}
return parsed.toString();
}
// --- API Routes ---
/**
* POST /api/session-cache/clear - Clear in-memory UI state.
*/
app.post("/api/session-cache/clear", async (_req, res) => {
try {
const active = activeBlockingJobs();
if (active.length > 0) {
res.status(409).json({
error: "Cannot clear session cache while jobs are running",
jobs: active.map((job) => ({ id: job.id, type: job.type, status: job.status })),
});
return;
}
clearEpisodeSessionState();
persistState();
broadcastSSE("state-sync", uiState);
res.json({ ok: true });
} catch (err) {
res.status(500).json({ error: `Failed to clear session cache: ${errMsg(err)}` });
}
});
/**
* POST /api/upload: Upload a podcast file
*/
app.post("/api/upload", upload.single("file"), (req, res) => {
if (!req.file) {
res.status(400).json({ error: "No file uploaded" });
return;
}
registerSourcePath(req.file.path);
res.json({
file_path: req.file.path,
filename: req.file.originalname,
size_mb: Math.round((req.file.size / (1024 * 1024)) * 100) / 100,
});
});
/**
* POST /api/download-video: Download a video URL with yt-dlp into uploads.
*/
/** The browser whose cookies yt-dlp should read, from the request or the env. */
function cookieBrowser(fromRequest: string | undefined): string | undefined {
if (fromRequest !== undefined && isCookieBrowser(fromRequest)) return fromRequest;
const configured = (process.env.PODCLI_YTDLP_BROWSER || "").trim().toLowerCase();
return isCookieBrowser(configured) ? configured : undefined;
}
app.post("/api/download-video", async (req, res) => {
let url: string;
try {
url = await validateDownloadUrl(stringValue.safeParse(req.body?.url).data);
} catch (err) {
res.status(400).json({ error: errMsg(err) });
return;
}
try {
await mkdir(uploadDir, { recursive: true });
} catch (err) {
res.status(500).json({ error: `Failed to create upload directory: ${errMsg(err)}` });
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "download_video",
status: "running",
progress: 0,
message: "Downloading video",
createdAt: Date.now(),
};
jobs.set(jobId, job);
const args = buildYtDlpArgs({
url,
outputDir: uploadDir,
outputTemplate: "%(title).200B [%(id)s].%(ext)s",
ffmpegLocation: paths.ffmpegPath,
jsRuntimeNodePath: process.execPath,
cookiesFromBrowser: cookieBrowser(stringValue.safeParse(req.body?.browser).data),
extractorArgs: process.env.PODCLI_YT_EXTRACTOR_ARGS || undefined,
progressTemplate: "download:podcli-progress:%(progress._percent_str)s",
});
// Detached so a kill takes out yt-dlp's ffmpeg children with it.
const proc = spawn(paths.pythonPath, args, {
env: pythonEnv(),
detached: process.platform !== "win32",
});
let stdout = "";
let stderr = "";
let outputFilePath = "";
let settled = false;
let responded = false;
const timer = setTimeout(() => terminateProcessTree(proc), 3600_000);
const finish = (action: () => void): void => {
if (settled) return;
settled = true;
clearTimeout(timer);
action();
};
const readYtDlpOutput = (raw: string): void => {
for (const line of raw.split(/\r?\n/)) {
const progress = line.match(/podcli-progress:\s*(\d+(?:\.\d+)?)%/);
if (progress) {
job.progress = Number(progress[1]);
job.message = "Downloading video";
broadcastSSE("job-update", { jobId, progress: job.progress, message: job.message });
continue;
}
const trimmed = line.trim();
if (trimmed.startsWith("podcli-filepath:")) {
outputFilePath = trimmed.slice("podcli-filepath:".length);
}
}
};
proc.stdout.on("data", (chunk: Buffer) => {
const raw = chunk.toString();
stdout += raw;
readYtDlpOutput(raw);
});
proc.stderr.on("data", (chunk: Buffer) => {
const raw = chunk.toString();
stderr += raw;
readYtDlpOutput(raw);
if (stderr && job.progress === 0) {
job.message = "Downloading video";
}
});
proc.on("error", (err) => {
finish(() => {
job.status = "error";
job.error = `Failed to start yt-dlp with ${paths.pythonPath}: ${err.message}`;
job.message = job.error;
broadcastSSE("job-error", { jobId, error: job.error });
});
});
proc.on("close", (code) => {
finish(() => {
if (code !== 0) {
job.status = "error";
const hint = ytDlpHint(stderr);
job.error = `yt-dlp failed for ${url} with exit code ${code}.${hint ? ` ${hint}` : ""} stderr: ${stderr.slice(-1200)}`;
job.message = job.error;
broadcastSSE("job-error", { jobId, error: job.error });
return;
}
const filePath = outputFilePath;
if (!filePath || !existsSync(filePath)) {
job.status = "error";
job.error = `yt-dlp finished but did not report an output file. stdout: ${stdout.slice(-1200)} stderr: ${stderr.slice(-1200)}`;
job.message = job.error;
broadcastSSE("job-error", { jobId, error: job.error });
return;
}
const stat = statSync(filePath);
registerSourcePath(filePath);
uiState.videoPath = filePath;
uiState.filePath = filePath;
uiState.videoMissing = false;
// A fresh download has no transcript yet; a stale identity from
// whatever video was loaded before would otherwise still read as "the
// transcript belongs to this video" until the next transcribe call.
uiState.transcriptVideoIdentity = null;
uiState.lastUpdated = Date.now();
persistState();
broadcastSSE("state-sync", uiState);
job.status = "done";
job.progress = 100;
job.message = "Download complete";
job.result = {
file_path: filePath,
filename: basename(filePath),
size_mb: Math.round((stat.size / (1024 * 1024)) * 100) / 100,
};
broadcastSSE("job-complete", { jobId, result: job.result });
});
});
req.on("close", () => {
if (!responded && !settled) terminateProcessTree(proc);
});
responded = true;
res.json({ job_id: jobId, status: "running" });
});
/**
* POST /api/select-file: Use an existing local file (no upload needed)
*/
app.post("/api/select-file", (req, res) => {
const { file_path } = req.body;
if (!file_path || !existsSync(file_path)) {
res.status(400).json({ error: "File not found" });
return;
}
const stat = statSync(file_path);
registerSourcePath(file_path);
res.json({
file_path,
filename: basename(file_path),
size_mb: Math.round((stat.size / (1024 * 1024)) * 100) / 100,
});
});
/** Native folder dialog; returns the chosen directory, or null when cancelled. */
function pickFolder(): string | null {
const prompt = "Choose the folder with this episode's recordings";
try {
let raw: string;
if (process.platform === "darwin") {
raw = execFileSync("osascript", ["-e", `POSIX path of (choose folder with prompt "${prompt}")`], {
encoding: "utf-8",
timeout: 120_000,
});
} else if (process.platform === "win32") {
const ps = [
"Add-Type -AssemblyName System.Windows.Forms;",
"$f = New-Object System.Windows.Forms.FolderBrowserDialog;",
`$f.Description = '${prompt.replace(/'/g, "''")}';`,
"if ($f.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $f.SelectedPath }",
].join(" ");
raw = execSync(`powershell -NoProfile -STA -EncodedCommand ${Buffer.from(ps, "utf16le").toString("base64")}`, {
encoding: "utf-8",
timeout: 120_000,
});
} else {
raw = execFileSync("zenity", ["--file-selection", "--directory"], { encoding: "utf-8", timeout: 120_000 });
}
const folder = raw.trim();
return folder && existsSync(folder) && statSync(folder).isDirectory() ? folder : null;
} catch {
return null;
}
}
/**
* GET /api/browse-file: Open native OS file dialog and return the selected path
*/
app.get("/api/browse-file", (req, res) => {
const multiple = req.query.multiple === "1" || req.query.multiple === "true";
if (req.query.folder === "1") {
const folder = pickFolder();
res.json(folder ? { folder } : { error: "cancelled" });
return;
}
try {
let raw: string;
if (process.platform === "darwin") {
const mult = multiple ? " with multiple selections allowed" : "";
raw = execFileSync(
"osascript",
[
"-e", `set sel to choose file of type {"mp4","mov","mkv","webm","mp3","wav","m4a"}${mult}`,
"-e", 'if class of sel is not list then set sel to {sel}',
"-e", "set out to \"\"",
"-e", "repeat with f in sel",
"-e", "set out to out & POSIX path of f & linefeed",
"-e", "end repeat",
"-e", "return out",
],
{ encoding: "utf-8", timeout: 120_000 },
);
} else if (process.platform === "win32") {
// EncodedCommand (UTF-16LE base64) sidesteps cmd→PowerShell quoting; -STA is required by WinForms dialogs.
const ps = [
"Add-Type -AssemblyName System.Windows.Forms;",
"$f = New-Object System.Windows.Forms.OpenFileDialog;",
"$f.Filter = 'Media files|*.mp4;*.mov;*.mkv;*.webm;*.mp3;*.wav;*.m4a';",
multiple ? "$f.Multiselect = $true;" : "",
"if ($f.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $f.FileNames -join [Environment]::NewLine }",
].join(" ");
const encoded = Buffer.from(ps, "utf16le").toString("base64");
raw = execSync(`powershell -NoProfile -STA -EncodedCommand ${encoded}`, {
encoding: "utf-8",
timeout: 120_000,
});
} else {
const args = ["--file-selection", "--file-filter=Media files|*.mp4 *.mov *.mkv *.webm *.mp3 *.wav *.m4a"];
if (multiple) args.push("--multiple", "--separator=\n");
raw = execFileSync("zenity", args, { encoding: "utf-8", timeout: 120_000 });
}
const paths = raw.split("\n").map((p) => p.trim()).filter((p) => p && existsSync(p));
if (paths.length === 0) {
res.json({ error: "cancelled" });
return;
}
for (const p of paths) registerSourcePath(p);
const stat = statSync(paths[0]);
res.json({
file_path: paths[0],
file_paths: paths,
filename: basename(paths[0]),
size_mb: Math.round((stat.size / (1024 * 1024)) * 100) / 100,
});
} catch {
// User cancelled the dialog (non-zero exit) or command not found
res.json({ error: "cancelled" });
}
});
/**
* POST /api/import-transcript: Import an existing transcript (skip Whisper)
* Accepts: { file_path, transcript } where transcript is an object with:
* - text: string (full transcript text)
* - words: Array<{ word, start, end, speaker? }>
* - segments?: Array<{ text, start, end, speaker? }>
* - duration?: number
*/
app.post("/api/import-transcript", (req, res) => {
const { file_path, transcript } = req.body;
if (!file_path) {
res.status(400).json({ error: "file_path is required" });
return;
}
if (!transcript || !transcript.words || !Array.isArray(transcript.words)) {
res.status(400).json({
error:
"transcript must include a 'words' array with { word, start, end } objects",
});
return;
}
// Build a full transcript result from the imported data
const result: ServerTranscript & { imported: true } = {
transcript:
transcript.text || transcript.words.map((w: WordTimestamp) => w.word).join(" "),
words: transcript.words,
segments: transcript.segments || [],
duration:
transcript.duration ||
(transcript.words.length > 0
? transcript.words[transcript.words.length - 1].end
: 0),
language: transcript.language || "en",
speakers: transcript.speakers || {},
speaker_segments: transcript.speaker_segments || [],
imported: true,
};
sessionTranscripts.set(file_path, result);
res.json({
status: "done",
cached: false,
imported: true,
data: result,
});
});
/**
* POST /api/parse-transcript: Parse a speaker-labeled plain text transcript
* Format: "Speaker (MM:SS)\ntext...\n\nSpeaker2 (MM:SS)\ntext..."
* Uses Python backend to generate word-level timestamps.
*/
app.post("/api/parse-transcript", async (req, res) => {
const { file_path, raw_text, total_duration, time_adjust = 0, language } = req.body;
if (!file_path) {
res.status(400).json({ error: "file_path is required" });
return;
}
if (!raw_text) {
res.status(400).json({ error: "raw_text is required" });
return;
}
try {
const result = await executor.execute<ServerTranscript>("parse_transcript", {
raw_text,
total_duration: total_duration || null,
time_adjust: time_adjust || 0,
language: language || null,
});
if (result.data) {
sessionTranscripts.set(file_path, result.data);
}
res.json({
status: "done",
imported: true,
data: result.data,
});
} catch (err: any) {
res
.status(500)
.json({ error: err.message || "Failed to parse transcript" });
}
});
/**
* POST /api/transcribe: Start transcription job
*/
app.post("/api/transcribe", async (req, res) => {
const {
file_path,
model_size = "base",
engine,
assemblyai_api_key,
language,
enable_diarization = true,
num_speakers,
start_seconds,
duration_seconds,
} = req.body;
if (!file_path || !existsSync(file_path)) {
res.status(400).json({ error: "File not found" });
return;
}
// A sample is a positive window, not merely a present key, matching
// transcribe.handler.ts and backend/services/transcription.py exactly.
const isSample = (duration_seconds ?? 0) > 0 || (start_seconds ?? 0) > 0;
// Resolve before reading the cache: an unset engine is written under
// whatever transcribe_file actually ran (e.g. "whispercpp" on a native
// install), so reading with the raw unset request always misses.
const resolvedEngine = await resolveTranscribeEngine(executor, engine, model_size);
const cacheKey = { engine: resolvedEngine, model: model_size, language };
// A sample is a throwaway check on a slice of the file. Never serve or
// populate the session/UI state from the main cache (keyed by, and
// assumed to describe, the whole file).
const cachedRaw = isSample ? null : await cache.get(file_path, cacheKey);
const cached = needsDiarizationRetry(cachedRaw, enable_diarization, engineCanDiarize(resolvedEngine))
? null
: cachedRaw;
if (cached) {
const jobId = uuidv4();
sessionTranscripts.set(file_path, cached);
uiState.transcript = cached;
uiState.videoPath = file_path;
uiState.filePath = file_path;
uiState.videoMissing = false;
uiState.transcriptVideoIdentity = computeVideoIdentity(file_path);
registerSourcePath(file_path);
uiState.lastUpdated = Date.now();
persistState();
res.json({
job_id: jobId,
status: "done",
cached: true,
data: cached,
});
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "transcribe",
status: "running",
progress: 0,
message: "Starting transcription...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
res.json({ job_id: jobId, status: "running" });
// Run async
executor
.execute<ServerTranscript>(
"transcribe",
{
file_path,
model_size,
engine,
assemblyai_api_key,
language,
enable_diarization,
num_speakers,
start_seconds,
duration_seconds,
},
(event) => {
job.progress = event.percent;
job.message = event.message;
},
)
.then(async (result) => {
job.status = "done";
job.progress = 100;
job.message = "Transcription complete";
job.result = result.data;
// A sample result is a slice, not the episode. Leave the session/UI
// state and the main cache alone. The caller reads it via job_status.
const transcript = result.data;
if (isSample || !transcript) return;
sessionTranscripts.set(file_path, transcript);
// Populate uiState.transcript with the FULL result so downstream
// batch_create_clips can resolve transcript_words for caption burn-in.
uiState.transcript = transcript;
uiState.videoPath = file_path;
uiState.filePath = file_path;
uiState.videoMissing = false;
uiState.transcriptVideoIdentity = computeVideoIdentity(file_path);
registerSourcePath(file_path);
uiState.lastUpdated = Date.now();
persistState();
// Without this a tab reloaded during a 25-minute run shows an idle screen
// forever: the job id lived only in the tab that started it, and nothing
// else announces that the transcript landed.
broadcastSSE("state-sync", uiState);
// Cache it under the engine it actually ran with. A fresh resolution
// (or the pre-transcribe request) can differ from what transcribe_file
// fell back to once it tried loading the model for real.
try {
const actualEngine = transcript.engine ?? resolvedEngine;
await cache.set(file_path, transcript, {
engine: actualEngine,
model: model_size,
language,
});
} catch (err) {
log.warn("Failed to cache transcript", { file_path, err: errMsg(err) });
}
})
.catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
broadcastSSE("job-error", { jobId, error: job.error });
});
});
/** The session transcript, for callers that render without passing words.
*
* A caller that omits transcript_words used to get a silently uncaptioned
* clip. /api/export already falls back this way; these two did not, so a
* studio session whose client state had dropped the transcript shipped clips
* with no captions and no error. */
function sessionWords(): unknown[] {
return Array.isArray(uiState.transcript?.words) ? uiState.transcript.words : [];
}
/**
* POST /api/create-clip: Start clip creation job
*/
app.post("/api/create-clip", async (req, res) => {
const {
video_path,
start_second,
end_second,
caption_style = "hormozi",
crop_strategy = "speaker",
format = "vertical",
transcript_words = sessionWords(),
title = "clip",
clean_fillers = false,
allow_ass_fallback = false,
content_type = null,
keep_segments,
hook,
caption_position = "auto",
caption_font_scale = 100,
logo_position = "top-left",
} = req.body;
if (!video_path || !existsSync(video_path)) {
res.status(400).json({ error: "Video file not found" });
return;
}
// Resolve asset names (or paths) to real paths; reject only if provided-and-unresolvable.
let logo_path: string | null = null;
let outro_path: string | null = null;
let intro_path: string | null = null;
for (const [key, raw] of [["logo", req.body.logo_path], ["outro", req.body.outro_path], ["intro", req.body.intro_path]] as const) {
if (!raw) continue;
const resolved = await assetManager.resolve(raw);
if (!resolved) {
res.status(400).json({ error: `${key} not found: ${raw}` });
return;
}
if (key === "logo") logo_path = resolved;
else if (key === "outro") outro_path = resolved;
else intro_path = resolved;
}
// Validate clip params before spawning Python
if (!numberValue.safeParse(start_second).success || !numberValue.safeParse(end_second).success) {
res
.status(400)
.json({ error: "start_second and end_second must be numbers" });
return;
}
if (end_second <= start_second) {
res
.status(400)
.json({ error: "end_second must be greater than start_second" });
return;
}
const duration = end_second - start_second;
const maxDur = format === "horizontal" ? 300 : 180;
if (duration > maxDur) {
res.status(400).json({
error: `Clip too long (${Math.round(duration)}s). Max ${maxDur} seconds.`,
});
return;
}
const validStyles = ["hormozi", "karaoke", "subtle", "branded"];
if (!validStyles.includes(caption_style)) {
res
.status(400)
.json({ error: `Invalid caption style. Use: ${validStyles.join(", ")}` });
return;
}
const validCrops = ["center", "face", "speaker"];
if (!validCrops.includes(crop_strategy)) {
res
.status(400)
.json({ error: `Invalid crop strategy. Use: ${validCrops.join(", ")}` });
return;
}
const validFormats = ["vertical", "horizontal", "square"];
if (!validFormats.includes(format)) {
res
.status(400)
.json({ error: `Invalid format. Use: ${validFormats.join(", ")}` });
return;
}
const validCaptionPositions = ["auto", "upper", "center", "lower"];
const validLogoPositions = ["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"];
if (!validCaptionPositions.includes(caption_position) || !validLogoPositions.includes(logo_position)) {
res.status(400).json({ error: "Invalid caption or logo position" });
return;
}
const normalizedFontScale = Math.max(60, Math.min(160, Number(caption_font_scale) || 100));
const parsedHook = hookSchema.nullish().safeParse(hook);
if (!parsedHook.success) {
res.status(400).json({
error:
validateHook(hook, start_second, end_second, keep_segments) ??
"hook must be an object with start, end and mode",
});
return;
}
await fileManager.ensureDirectories();
const enriched = enrichClipFromSuggestion({
start_second,
end_second,
keep_segments: Array.isArray(keep_segments) ? keep_segments : undefined,
hook: parsedHook.data,
});
const hookError = exportHookError([enriched]);
if (hookError) {
res.status(400).json({ error: hookError });
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "create_clip",
status: "running",
progress: 0,
message: "Preparing clip...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
res.json({ job_id: jobId, status: "running" });
executor
.execute<ClipResult>(
"create_clip",
{
video_path,
start_second: enriched.start_second,
end_second: enriched.end_second,
caption_style,
crop_strategy,
format,
transcript_words,
title,
output_dir: paths.output,
logo_path,
outro_path,
intro_path,
clean_fillers,
allow_ass_fallback,
caption_position,
caption_font_scale: normalizedFontScale,
logo_position,
...(enriched.keep_segments?.length && { keep_segments: enriched.keep_segments }),
...(enriched.hook && { hook: enriched.hook }),
},
(event) => {
job.progress = event.percent;
job.message = event.message;
},
)
.then(async (result) => {
job.status = "done";
job.progress = 100;
job.message = "Clip created!";
job.result = result.data;
// Record to history
try {
const d = result.data;
const rec = await clipsHistory.record({
source_video: video_path,
start_second,
end_second,
caption_style,
crop_strategy,
format,
logo_path: logo_path || undefined,
outro_path: outro_path || undefined,
intro_path: intro_path || undefined,
title,
output_path: d?.output_path || "",
file_size_mb: d?.file_size_mb || 0,
duration: d?.duration || 0,
content_type: content_type || undefined,
transcript_slice: sliceTranscript(transcript_words, start_second, end_second),
...findGroundingText(uiState.suggestions, start_second, end_second),
});
await clipsHistory.persistClipRecipe(rec, {
transcriptWords: transcript_words,
logoPath: logo_path,
outroPath: outro_path,
introPath: intro_path,
cleanFillers: clean_fillers,
keepSegments: enriched.keep_segments,
hook: enriched.hook,
});
broadcastHistoryUpdated(jobId, [rec]);
} catch (err) {
log.warn("Failed to record clip to history", {
title,
err: errMsg(err),
});
}
broadcastSSE("job-complete", { jobId, result: result.data });
})
.catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
broadcastSSE("job-error", { jobId, error: err.message });
});
});
/**
* POST /api/batch-clips: Create multiple clips
*/
app.post("/api/batch-clips", async (req, res) => {
const {
video_path,
clips,
transcript_words = sessionWords(),
clean_fillers = false,
keep_caption_overlay = false,
format = "vertical",
caption_position = "auto",
caption_font_scale = 100,
logo_position = "top-left",
} = req.body;
if (!video_path || !existsSync(video_path)) {
res.status(400).json({ error: "Video file not found" });
return;
}
if (!clips || !Array.isArray(clips) || clips.length === 0) {
res.status(400).json({ error: "No clips provided" });
return;
}
if (!["auto", "upper", "center", "lower"].includes(caption_position) ||
!["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"].includes(logo_position)) {
res.status(400).json({ error: "Invalid caption or logo position" });
return;
}
const normalizedFontScale = Math.max(60, Math.min(160, Number(caption_font_scale) || 100));
let logo_path: string | null = null;
let outro_path: string | null = null;
let intro_path: string | null = null;
for (const [key, raw] of [["logo", req.body.logo_path], ["outro", req.body.outro_path], ["intro", req.body.intro_path]] as const) {
if (!raw) continue;
const resolved = await assetManager.resolve(raw);
if (!resolved) {
res.status(400).json({ error: `${key} not found: ${raw}` });
return;
}
if (key === "logo") logo_path = resolved;
else if (key === "outro") outro_path = resolved;
else intro_path = resolved;
}
// Validate each clip's timing
for (let i = 0; i < clips.length; i++) {
const c = clips[i];
const dur = (c.end_second || 0) - (c.start_second || 0);
if (dur <= 0) {
res.status(400).json({ error: `Clip ${i + 1}: end must be after start` });
return;
}
if (c.format && !["vertical", "horizontal", "square"].includes(c.format)) {
res.status(400).json({ error: `Clip ${i + 1}: invalid format "${c.format}". Use: vertical, horizontal, square` });
return;
}
const maxDur = maxClipSeconds(c.format || format);
if (dur > maxDur) {
res.status(400).json({
error: `Clip ${i + 1}: too long (${Math.round(dur)}s). Max ${maxDur}s.`,
});
return;
}
}
await fileManager.ensureDirectories();
const enrichedClips = clips.map((c: ExportClip) => enrichClipFromSuggestion(c));
const batchHookError = exportHookError(enrichedClips);
if (batchHookError) {
res.status(400).json({ error: batchHookError });
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "batch_clips",
status: "running",
progress: 0,
message: "Starting batch...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
const historyRecorder = createBatchHistoryRecorder({
jobId,
sourceVideo: video_path,
transcriptWords: transcript_words,
label: "batch",
clipSpecs: enrichedClips,
logoPath: logo_path,
outroPath: outro_path,
introPath: intro_path,
cleanFillers: clean_fillers,
});
broadcastSSE("export-started", { jobId, clipCount: clips.length });
setExportState("exporting", jobId);
res.json({ job_id: jobId, status: "running" });
executor
.execute<BatchClipsResult>(
"batch_clips",
{
video_path,
clips: enrichedClips,
format,
transcript_words,
output_dir: paths.output,
logo_path,
outro_path,
intro_path,
clean_fillers,
keep_caption_overlay: keep_caption_overlay === true,
face_map: uiState.transcript?.face_map,
caption_position,
caption_font_scale: normalizedFontScale,
logo_position,
},
(event) => {
const progress = advanceProgress(job, event.percent);
job.message = event.message;
historyRecorder.recordProgress(event);
const clipResult = event.clip_result
? tagSubmittedClip(event.clip_result, enrichedClips)
: undefined;
if (event.stage === "clip_complete" && clipResult) {
(job.clip_results ??= []).push(clipResult);
}
broadcastSSE("job-update", {
jobId,
progress,
message: event.message,
stage: event.stage,
clip_result: clipResult,
});
},
)
.then(async (result) => {
const data = tagSubmittedClips(result.data, enrichedClips);
job.status = "done";
job.progress = 100;
job.message = "Batch complete!";
job.result = data;
// Persist here too: the studio tab may be closed (an MCP-driven
// export), and it only stores results when it hears job-complete.
uiState.results = data?.results ?? [];
// Record successful clips to history
try {
await historyRecorder.recordRemaining(result.data?.results);
} catch (err) {
log.warn("Failed to record batch clips to history", {
err: errMsg(err),
});
}
setExportState("done", null);
broadcastSSE("job-complete", { jobId, result: data });
})
.catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
setExportState("review", null);
broadcastSSE("job-error", { jobId, error: err.message });
});
});
function findFullEpisodeRenderer(): string | null {
const candidates = [
join(paths.projectRoot, "remotion", "render-full-episode.mjs"),
join(paths.projectRoot, "runtime", "remotion", "render-full-episode.mjs"),
];
return candidates.find((candidate) => existsSync(candidate)) || null;
}
function reserveFullEpisodeOutput(videoPath: string): string {
const stem = fullEpisodeOutputStem(videoPath);
let candidate = join(paths.output, `${stem}.mp4`);
for (let suffix = 2; existsSync(candidate); suffix++) {
candidate = join(paths.output, `${stem}-${suffix}.mp4`);
}
return candidate;
}
/** Analyze spoken sections locally. The first run downloads a verified 1.3 MB VAD model. */
app.post("/api/analyze-silence", async (req, res) => {
const {
video_path,
transcript_words = [],
threshold = 0.5,
min_silence_seconds = 0.65,
padding_seconds = 0.12,
} = req.body || {};
const sourcePath = resolveAllowedSource(stringValue.safeParse(video_path).data);
if (!sourcePath) {
res.status(400).json({ error: "Select a local episode first" });
return;
}
if (!Array.isArray(transcript_words) || transcript_words.length === 0) {
res.status(400).json({ error: "Transcribe the episode before removing silence" });
return;
}
const normalizedThreshold = Number(threshold);
const normalizedPause = Number(min_silence_seconds);
const normalizedPadding = Number(padding_seconds);
if (
!Number.isFinite(normalizedThreshold) || normalizedThreshold < 0.25 || normalizedThreshold > 0.8 ||
!Number.isFinite(normalizedPause) || normalizedPause < 0.3 || normalizedPause > 5 ||
!Number.isFinite(normalizedPadding) || normalizedPadding < 0.02 || normalizedPadding > 0.5
) {
res.status(400).json({ error: "Invalid silence-removal settings" });
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "silence_analysis",
status: "running",
progress: 0,
message: "Preparing local silence analysis...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
res.json({ job_id: jobId, status: "running" });
executor.execute<SilencePlan>("analyze_silence", {
video_path: sourcePath,
transcript_words,
threshold: normalizedThreshold,
min_silence_seconds: normalizedPause,
padding_seconds: normalizedPadding,
}, (event) => {
job.progress = event.percent;
job.message = event.message;
}).then((result) => {
job.status = "done";
job.progress = 100;
job.message = "Silence analysis ready";
job.result = result.data;
}).catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
});
});
/** Render an approved keep plan locally, preserving the source and remapping captions. */
app.post("/api/render-silence-removed", async (req, res) => {
const { video_path, keep_segments, transcript } = req.body || {};
const sourcePath = resolveAllowedSource(stringValue.safeParse(video_path).data);
if (!sourcePath) {
res.status(400).json({ error: "Source episode not found" });
return;
}
if (!Array.isArray(transcript?.words) || transcript.words.length === 0) {
res.status(400).json({ error: "Transcript is required to keep caption timing aligned" });
return;
}
if (!Array.isArray(keep_segments) || keep_segments.length === 0 || keep_segments.length > 5000) {
res.status(400).json({ error: "Invalid silence-removal plan" });
return;
}
const normalizedSegments: Array<{ start: number; end: number }> = [];
let previousEnd = 0;
for (const item of keep_segments) {
const start = Number(item?.start);
const end = Number(item?.end);
if (!Number.isFinite(start) || !Number.isFinite(end) || start < previousEnd || end <= start) {
res.status(400).json({ error: "Silence-removal ranges must be ordered and non-overlapping" });
return;
}
normalizedSegments.push({ start, end });
previousEnd = end;
}
await fileManager.ensureDirectories();
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "silence_render",
status: "running",
progress: 0,
message: "Creating compact episode...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
res.json({ job_id: jobId, status: "running" });
executor.execute<{
output_path: string;
filename: string;
duration: number;
transcript: ServerTranscript;
}>("render_silence_removed", {
video_path: sourcePath,
keep_segments: normalizedSegments,
transcript,
output_dir: paths.output,
}, (event) => {
job.progress = event.percent;
job.message = event.message;
}).then((result) => {
job.status = "done";
job.progress = 100;
job.message = "Compact episode ready";
job.result = result.data;
if (result.data?.output_path) registerSourcePath(result.data.output_path);
}).catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
});
});
/**
* POST /api/export-full-episode: Burn captions into the complete current source.
*
* Full episodes bypass clip duration limits and retain the source dimensions.
* The renderer chunks its temporary alpha overlay to keep disk use bounded.
*/
app.post("/api/export-full-episode", async (req, res) => {
const {
video_path,
transcript_words = [],
caption_style = "branded",
caption_position = "auto",
caption_font_scale = 100,
logo_position = "top-left",
} = req.body || {};
const sourcePath = resolveAllowedSource(stringValue.safeParse(video_path).data);
if (!sourcePath) {
res.status(400).json({ error: "Video file not found" });
return;
}
if (!Array.isArray(transcript_words) || transcript_words.length === 0) {
res.status(400).json({ error: "Transcribe the episode before exporting it with captions" });
return;
}
if (!FULL_EPISODE_CAPTION_STYLES.includes(caption_style)) {
res.status(400).json({ error: `Invalid caption style. Use: ${FULL_EPISODE_CAPTION_STYLES.join(", ")}` });
return;
}
if (!["auto", "upper", "center", "lower"].includes(caption_position) ||
!["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"].includes(logo_position)) {
res.status(400).json({ error: "Invalid caption or logo position" });
return;
}
const normalizedFontScale = Math.max(60, Math.min(160, Number(caption_font_scale) || 100));
let logoPath: string | null = null;
if (req.body.logo_path) {
logoPath = await assetManager.resolve(req.body.logo_path);
if (!logoPath) {
res.status(400).json({ error: `logo not found: ${req.body.logo_path}` });
return;
}
}
const renderer = findFullEpisodeRenderer();
if (!renderer) {
res.status(500).json({ error: "Full-episode renderer is not installed" });
return;
}
await fileManager.ensureDirectories();
const outputPath = reserveFullEpisodeOutput(sourcePath);
const wordsPath = join(paths.working, `full-episode-${uuidv4()}.words.json`);
writeFileSync(wordsPath, JSON.stringify({ words: transcript_words }), "utf-8");
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "full_episode",
status: "running",
progress: 0,
message: "Preparing full episode...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
res.json({ job_id: jobId, status: "running" });
const args = [
renderer,
"--video", sourcePath,
"--words", wordsPath,
"--style", caption_style,
"--output", outputPath,
"--ffmpeg", paths.ffmpegPath,
"--ffprobe", paths.ffprobePath,
"--caption-position", caption_position,
"--caption-font-scale", String(normalizedFontScale),
"--logo-position", logo_position,
];
if (caption_style === "branded" && logoPath) args.push("--logo", logoPath);
const child = spawn(process.execPath, args, {
cwd: dirname(renderer),
env: {
...process.env,
PODCLI_CACHE_DIR: join(dirname(renderer), ".bundle-cache"),
},
stdio: ["ignore", "pipe", "pipe"],
});
let stdoutCarry = "";
let stderrTail = "";
const consumeStdout = (text: string, flush = false) => {
stdoutCarry += text;
const lines = stdoutCarry.split(/\r?\n/);
stdoutCarry = flush ? "" : lines.pop() || "";
for (const line of lines) {
const update = parseFullEpisodeProgress(line);
if (!update) continue;
job.progress = Math.max(job.progress, update.percent);
job.message = update.message;
}
if (flush && stdoutCarry) {
const update = parseFullEpisodeProgress(stdoutCarry);
if (update) {
job.progress = Math.max(job.progress, update.percent);
job.message = update.message;
}
}
};
child.stdout.on("data", (chunk) => consumeStdout(chunk.toString()));
child.stderr.on("data", (chunk) => {
stderrTail = (stderrTail + chunk.toString()).slice(-4000);
});
child.on("error", async (err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
try { await unlink(wordsPath); } catch { /* best effort */ }
});
child.on("close", async (code) => {
consumeStdout("", true);
try { await unlink(wordsPath); } catch { /* best effort */ }
if (job.status === "error") return;
if (code !== 0 || !existsSync(outputPath)) {
const detail = stderrTail.trim().split(/\r?\n/).slice(-4).join("\n");
job.status = "error";
job.error = detail || `Renderer exited with code ${code}`;
job.message = `Error: ${job.error}`;
return;
}
const stat = statSync(outputPath);
job.status = "done";
job.progress = 100;
job.message = "Full episode ready";
job.result = {
output_path: outputPath,
filename: basename(outputPath),
file_size_mb: Math.round((stat.size / (1024 * 1024)) * 100) / 100,
caption_style,
};
});
});
/**
* GET /api/job/:id: Poll job status + progress
*/
app.get("/api/job/:id", (req, res) => {
const job = jobs.get(req.params.id);
if (!job) {
res.status(404).json({ error: "Job not found" });
return;
}
res.json(job);
});
/**
* GET /api/job/:id/stream: SSE progress stream
*/
app.get("/api/job/:id/stream", (req, res) => {
const jobId = req.params.id;
const job = jobs.get(jobId);
if (!job) {
res.status(404).json({ error: "Job not found" });
return;
}
res.writeHead(200, {
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
Connection: "keep-alive",
});
let closeTimer: NodeJS.Timeout | undefined;
const write = (): boolean => {
const current = jobs.get(jobId);
if (!current) return false;
res.write(
`data: ${JSON.stringify({
status: current.status,
progress: current.progress,
message: current.message,
result: current.result,
error: current.error,
clip_results: current.clip_results,
})}\n\n`,
);
return current.status === "done" || current.status === "error";
};
const cleanup = () => {
jobEvents.off(jobId, send);
clearTimeout(closeTimer);
};
function send() {
const terminal = write();
if (terminal && !closeTimer) {
// Some handlers set status before result, across an await. Hold the
// stream briefly and send the settled job once more.
closeTimer = setTimeout(() => {
write();
cleanup();
res.end();
}, 500);
}
}
jobEvents.on(jobId, send);
req.on("close", cleanup);
send();
});
/**
* GET /api/outputs: List finished clips
*/
/**
* Workspace-wide performance, for signed-in users.
*
* Returns `{ signedIn: false }` rather than an error when there's no account:
* the studio renders the same Analytics page either way, just without the
* workspace section. Nothing is greyed out and nothing says "upgrade".
*/
app.get("/api/pro/insights", async (_req, res) => {
try {
const cloud = await import("../services/podcli-cloud.js");
if (!(await cloud.signedIn())) return res.json({ signedIn: false });
const [insights, preferences] = await Promise.all([
cloud.getInsights(),
cloud.getPreferences(),
]);
res.json({ signedIn: true, insights, preferences });
} catch (err) {
// A workspace that can't be reached must not break the local analytics the
// page is primarily there to show.
res.json({ signedIn: false, error: err instanceof Error ? err.message : String(err) });
}
});
app.get("/api/pro/account", async (_req, res) => {
try {
const cloud = await import("../services/podcli-cloud.js");
if (!(await cloud.signedIn())) return res.json({ signedIn: false });
const me = await cloud.whoami();
res.json({
signedIn: true,
workspace: me.workspace?.name,
plan: me.plan,
episodesUsed: me.workspace?.episodes_used,
cap: me.plan === "team" ? 40 : 10,
});
} catch {
res.json({ signedIn: false });
}
});
app.get("/api/outputs", async (_req, res) => {
try {
await mkdir(paths.output, { recursive: true });
const files = await readdir(paths.output);
const mp4Files = files.filter((f) => f.endsWith(".mp4"));
// A clean (caption-free) variant renders to "<stem>_clean.mp4" next to
// its main clip. Fold it into that clip's entry instead of listing it
// as a second, unrelated-looking clip.
const cleanByStem = new Map<string, string>();
for (const f of mp4Files) {
if (f.endsWith("_clean.mp4")) {
cleanByStem.set(f.slice(0, -"_clean.mp4".length), f);
}
}
const clips = mp4Files
.filter((f) => !f.endsWith("_clean.mp4"))
.map((f) => {
const fullPath = join(paths.output, f);
const stat = statSync(fullPath);
const stem = f.slice(0, -".mp4".length);
const cleanFilename = cleanByStem.get(stem);
return {
filename: f,
path: fullPath,
size_mb: Math.round((stat.size / (1024 * 1024)) * 100) / 100,
created: stat.mtime.toISOString(),
...(cleanFilename && { clean_output_path: join(paths.output, cleanFilename) }),
};
})
.sort(
(a, b) => new Date(b.created).getTime() - new Date(a.created).getTime(),
);
res.json(clips);
} catch {
res.json([]);
}
});
/**
* GET /api/download/:filename: Download a finished clip
*/
app.get("/api/download/:filename", (req, res) => {
const filePath = safePath(paths.output, req.params.filename);
if (!filePath) {
res.status(400).json({ error: "Invalid filename" });
return;
}
if (!existsSync(filePath)) {
res.status(404).json({ error: "File not found" });
return;
}
res.download(filePath);
});
/**
* GET /api/preview/:filename: Stream a video clip for in-browser playback
*/
app.get("/api/preview/:filename", (req, res) => {
const filePath = safePath(paths.output, req.params.filename);
if (!filePath) {
res.status(400).json({ error: "Invalid filename" });
return;
}
if (!existsSync(filePath)) {
res.status(404).json({ error: "File not found" });
return;
}
streamVideo(req, res, filePath);
});
// Clips now render into the user's working dir, not a single output root, so the
// library streams them by history id from wherever they live. The output_path
// recorded in clips.json IS the allowlist: only files podcli itself logged are
// servable, and only as regular files (symlinks resolved, extension checked).
async function serveClipById(
req: Request,
res: Response,
id: string,
mode: "preview" | "download",
) {
const entry = await clipsHistory.findById(id);
if (!entry || !entry.output_path) {
res.status(404).json({ error: "Clip not found" });
return;
}
let real: string;
try {
real = realpathSync(entry.output_path);
} catch {
res.status(404).json({ error: "File no longer exists" });
return;
}
if (!statSync(real).isFile() || !/\.(mp4|mov|mkv|webm)$/i.test(real)) {
res.status(400).json({ error: "Unsupported clip file" });
return;
}
if (mode === "download") {
res.download(real);
return;
}
const mimeTypes = new Map([
[".webm", "video/webm"],
[".mov", "video/quicktime"],
[".mkv", "video/x-matroska"],
]);
streamVideo(req, res, real, mimeTypes.get(extname(real).toLowerCase()) || "video/mp4");
}
app.get("/api/clips/:id/preview", (req, res) => {
void serveClipById(req, res, req.params.id, "preview");
});
app.get("/api/clips/:id/download", (req, res) => {
void serveClipById(req, res, req.params.id, "download");
});
/**
* GET /api/stream-source: Stream the source video for in-browser preview
* Accepts ?path= query param (must be a file previously validated via /select-file or /upload)
*/
app.get("/api/stream-source", (req, res) => {
const filePath = stringValue.safeParse(req.query.path).data;
if (!filePath || !existsSync(filePath)) {
res.status(404).json({ error: "File not found" });
return;
}
// Extension gate: only media/image types stream, so this never serves
// .env/key/token files regardless of the path checks below.
const mediaMime = new Map([
[".mp4", "video/mp4"],
[".m4v", "video/mp4"],
[".webm", "video/webm"],
[".mov", "video/quicktime"],
[".avi", "video/x-msvideo"],
[".mkv", "video/x-matroska"],
[".mp3", "audio/mpeg"],
[".wav", "audio/wav"],
[".m4a", "audio/mp4"],
[".aac", "audio/aac"],
[".flac", "audio/flac"],
[".aif", "audio/aiff"],
[".aiff", "audio/aiff"],
[".mts", "video/mp2t"],
[".png", "image/png"],
[".jpg", "image/jpeg"],
[".jpeg", "image/jpeg"],
[".webp", "image/webp"],
[".gif", "image/gif"],
[".svg", "image/svg+xml"],
]);
const mime = mediaMime.get(extname(filePath).toLowerCase());
if (!mime) {
res.status(403).json({ error: "Access denied: unsupported media type" });
return;
}
// realpath defeats symlinks pointing outside the allowed set.
let resolvedPath: string;
try {
resolvedPath = realpathSync(path.resolve(filePath));
} catch {
res.status(404).json({ error: "File not found" });
return;
}
const uploadsRoot = path.resolve(join(paths.working, "uploads"));
const relativeToUploads = path.relative(uploadsRoot, resolvedPath);
const isUploadedFile =
relativeToUploads !== "" &&
!relativeToUploads.startsWith("..") &&
!path.isAbsolute(relativeToUploads);
if (!allowedSourcePaths.has(resolvedPath) && !isUploadedFile) {
res
.status(403)
.json({ error: "Access denied: path not in allowed sources" });
return;
}
streamVideo(req, res, filePath, mime);
});
// Route through the CLI so the Studio and the renderer resolve the same config
// path (a direct read here can miss it under the launcher's data dir).
app.get("/api/thumbnail-config", async (_req, res) => {
const r = await runCli(["thumbnail-config", "show"]);
if (r.code !== 0) {
res.json({});
return;
}
try { res.json(JSON.parse(r.stdout)); } catch { res.json({}); }
});
app.put("/api/thumbnail-config", async (req, res) => {
const tmp = join(tmpdir(), `podcli-tc-${uuidv4().slice(0, 8)}.json`);
try {
writeFileSync(tmp, JSON.stringify(req.body || {}), "utf-8");
const r = await runCli(["thumbnail-config", "import", tmp]);
if (r.code !== 0) throw new Error(stripAnsi(r.stderr || r.stdout) || "save failed");
res.json({ ok: true });
} catch (e: any) {
res.status(500).json({ error: e.message });
} finally {
try { await unlink(tmp); } catch { /* best effort */ }
}
});
app.get("/api/thumbnail-config/export", async (_req, res) => {
const r = await runCli(["thumbnail-config", "show"]);
if (r.code !== 0) { res.status(500).json({
error: "export failed" });
return;
}
res.setHeader("Content-Disposition", 'attachment; filename="thumbnail-config.json"');
res.type("application/json").send(r.stdout);
});
app.post("/api/thumbnail-config/reset", async (_req, res) => {
const r = await runCli(["thumbnail-config", "reset"]);
if (r.code !== 0) { res.status(500).json({
error: stripAnsi(r.stderr || r.stdout) || "reset failed" });
return;
}
res.json({ ok: true });
});
app.get("/api/image", (req, res) => {
const raw = stringValue.safeParse(req.query.path).data;
const mimes = new Map([
[".png", "image/png"],
[".jpg", "image/jpeg"],
[".jpeg", "image/jpeg"],
[".webp", "image/webp"],
[".gif", "image/gif"],
]);
const mime = raw ? mimes.get(extname(raw).toLowerCase()) : undefined;
if (!raw || !mime) {
res.status(403).json({ error: "unsupported type" });
return;
}
// realpath defeats symlinks pointing outside the allowed roots; home is
// excluded so the integrations/token files under it are never servable.
let resolved: string;
try {
resolved = realpathSync(path.resolve(raw));
} catch {
res.status(404).json({ error: "not found" });
return;
}
const allowedRoots = [paths.output, paths.working, paths.assets].map((p) => path.resolve(p));
if (DEMO) allowedRoots.push(path.resolve(DEMO_ASSETS_DIR));
if (!allowedRoots.some((root) => resolved === root || resolved.startsWith(root + path.sep))) {
res.status(403).json({ error: "access denied" });
return;
}
res.writeHead(200, { "Content-Type": mime, "Cache-Control": "no-cache" });
const stream = createReadStream(resolved);
stream.on("error", () => res.destroy());
stream.pipe(res);
});
registerConfigIntegrationRoutes(app, { executor, uploadDir });
// --- Transcript export (SRT/VTT) ---
app.get("/api/export-transcript", (_req, res) => {
const format = stringValue.safeParse(_req.query.format).data || "srt";
const transcript = uiState.transcript;
if (!transcript?.words?.length) {
res.status(400).json({ error: "No transcript available" });
return;
}
const words = transcript.words;
// Group words into subtitle lines (~8 words each)
const lineSize = 8;
const lines: Array<{ text: string; start: number; end: number }> = [];
for (let i = 0; i < words.length; i += lineSize) {
const chunk = words.slice(i, i + lineSize);
lines.push({
text: chunk.map((w: any) => w.word).join(" "),
start: chunk[0].start,
end: chunk[chunk.length - 1].end,
});
}
const fmtSrt = formatSrtTime;
const fmtVtt = formatVttTime;
if (format === "vtt") {
let vtt = "WEBVTT\n\n";
lines.forEach((line, i) => {
vtt += `${i + 1}\n${fmtVtt(line.start)} --> ${fmtVtt(line.end)}\n${line.text}\n\n`;
});
res.setHeader("Content-Type", "text/vtt");
res.setHeader("Content-Disposition", "attachment; filename=transcript.vtt");
res.send(vtt);
} else if (format === "json") {
res.setHeader(
"Content-Disposition",
"attachment; filename=transcript.json",
);
res.json(transcript);
} else {
// SRT
let srt = "";
lines.forEach((line, i) => {
srt += `${i + 1}\n${fmtSrt(line.start)} --> ${fmtSrt(line.end)}\n${line.text}\n\n`;
});
res.setHeader("Content-Type", "application/x-subrip");
res.setHeader("Content-Disposition", "attachment; filename=transcript.srt");
res.send(srt);
}
});
// --- Analyze audio energy ---
app.post("/api/analyze-energy", async (req, res) => {
const { video_path, segments } = req.body;
if (!video_path)
return res.status(400).json({ error: "video_path required" });
try {
const result = await executor.execute("analyze_energy", {
video_path,
segments: segments || [],
});
res.json(result.data || {});
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
// --- Highlight reel: detect once, then iterate on moments ---
const reelPayloadSchema = z.looseObject({
source: z.string().optional(),
sources: z.array(z.string()).optional(),
reel_path: z.string().optional(),
moments: z
.array(z.looseObject({ clip_path: z.string().optional(), clip_exists: z.boolean().optional() }))
.optional(),
});
app.post("/api/reel", async (req, res) => {
try {
const result = await executor.execute("manage_reel", req.body || {});
const data = result.data || {};
const reel = reelPayloadSchema.safeParse(data).data;
if (reel?.source) registerSourcePath(reel.source);
for (const s of reel?.sources ?? []) registerSourcePath(s);
if (reel?.reel_path) registerSourcePath(reel.reel_path);
for (const m of reel?.moments ?? []) {
if (m.clip_path && m.clip_exists) registerSourcePath(m.clip_path);
}
res.json(data);
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.get("/api/reel-download", (req, res) => {
const filePath = stringValue.safeParse(req.query.path).data;
if (!filePath) {
res.status(400).json({ error: "path required" });
return;
}
let resolved: string;
try {
resolved = realpathSync(path.resolve(filePath));
} catch {
res.status(404).json({ error: "File not found" });
return;
}
if (extname(resolved).toLowerCase() !== ".mp4" || !allowedSourcePaths.has(resolved)) {
res.status(403).json({ error: "Access denied" });
return;
}
res.download(resolved);
});
// --- Multicam: map sources, sync, cut, render one recording ---
const MULTICAM_JOB_ACTIONS = new Set(["sync", "plan", "render", "preview", "cloud", "pull"]);
// activity saves the session when it refreshes its cache, so it waits for jobs like any write.
const MULTICAM_WRITE_ACTIONS = new Set(["map", "cut", "set_cuts", "export", "import_timeline", "delete", "activity", ...MULTICAM_JOB_ACTIONS]);
const multicamPreviewDir = join(paths.working, "multicam");
// A multi-hour, multi-camera render outlasts the default one-hour task limit.
const multicamExecutor = createExecutor(8 * 3600_000);
// A job holds its session for minutes to hours and saves it when done; any
// other write in between would be overwritten, so writes wait their turn.
const multicamRunning = new Map<string, { id: string; action: string }>();
type MulticamPayload = {
session_id?: string;
outputs?: { video?: string; validation?: { warnings?: string[] } };
active_job?: { id: string; action: string };
};
// A render that finished with warnings says so in the job's status line, which is what job_status shows first.
function multicamDoneMessage(data: MulticamPayload | undefined): string {
const warnings = data?.outputs?.validation?.warnings || [];
return warnings.length ? `Done with ${warnings.length} warning(s): ${warnings.join(" ")}` : "Done";
}
// Only the finished episode becomes streamable: paths in a request body are the
// caller's say-so, and registering them would let a request read any media file.
function allowMulticamPaths(data: MulticamPayload | undefined): void {
if (data?.outputs?.video) registerSourcePath(data.outputs.video);
}
function withActiveJob(data: MulticamPayload | undefined): MulticamPayload {
const running = data?.session_id ? multicamRunning.get(data.session_id) : undefined;
return running ? { ...data, active_job: running } : data || {};
}
app.post("/api/multicam", async (req, res) => {
const body = req.body || {};
const action = String(body.action || "show");
const sessionId = stringValue.safeParse(body.session_id).data ?? "";
const running = multicamRunning.get(sessionId);
if (running && MULTICAM_WRITE_ACTIONS.has(action)) {
res.status(409).json({ error: `This edit is busy (${running.action}). Wait for it to finish, then try again.` });
return;
}
if (!MULTICAM_JOB_ACTIONS.has(action)) {
try {
const result = await executor.execute<MulticamPayload>("manage_multicam", body);
allowMulticamPaths(result.data);
res.json(withActiveJob(result.data));
} catch (err) {
res.status(400).json({ error: errMsg(err) });
}
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "multicam",
status: "running",
progress: 0,
message: "Starting...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
multicamRunning.set(sessionId, { id: jobId, action });
res.json({ job_id: jobId, status: "running" });
multicamExecutor.execute<MulticamPayload>("manage_multicam", body, (event) => {
job.progress = event.percent;
job.message = event.message;
}).then((result) => {
allowMulticamPaths(result.data);
job.status = "done";
job.progress = 100;
job.message = action === "render" || action === "pull" ? multicamDoneMessage(result.data) : "Done";
job.result = result.data;
}).catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
}).finally(() => {
multicamRunning.delete(sessionId);
});
});
// Camera stills podcli made for an edit; nothing outside its working folder.
app.get("/api/multicam/image", (req, res) => {
let resolved: string | null = null;
try {
// Python reports resolved paths (/private/tmp on macOS), so compare real paths on both sides.
const root = realpathSync(multicamPreviewDir);
resolved = safePath(root, path.relative(root, realpathSync(String(req.query.path || ""))));
} catch {}
if (!resolved || extname(resolved).toLowerCase() !== ".jpg") {
res.status(404).json({ error: "Preview not found" });
return;
}
res.sendFile(resolved);
});
// Downloads are limited to what a multicam render or export wrote, so this
// route can't turn a path registered elsewhere into a readable file.
app.get("/api/multicam/file", (req, res) => {
let resolved: string | null = null;
try {
const root = realpathSync(paths.output);
const real = realpathSync(String(req.query.path || ""));
const inside = safePath(root, path.relative(root, real));
if (inside && path.basename(path.dirname(inside)).endsWith("_multicam_podcli")) resolved = inside;
} catch {}
if (!resolved || ![".mp4", ".xml", ".fcpxml", ".wav"].includes(extname(resolved).toLowerCase())) {
res.status(403).json({ error: "Access denied" });
return;
}
res.download(resolved);
});
// --- Encoder info ---
app.get("/api/encoder-info", async (_req, res) => {
try {
const result = await executor.execute("detect_encoder", {});
res.json(result.data || {});
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
// --- Speaker Detection Status ---
app.get("/api/speaker-status", (_req, res) => {
if (DEMO) { res.json({
configured: true, setup_url: "", token_url: "" });
return;
}
let token = process.env.HF_TOKEN || "";
for (const envPath of [paths.envFile, join(process.cwd(), ".env")]) {
if (token) break;
if (!existsSync(envPath)) continue;
const match = readFileSync(envPath, "utf-8").match(/^HF_TOKEN=(.+)$/m);
if (match) token = match[1].trim();
}
res.json({
configured: !!token,
setup_url: "https://huggingface.co/pyannote/speaker-diarization-3.1",
token_url: "https://huggingface.co/settings/tokens",
});
});
// --- Presets ---
app.get("/api/presets", async (_req, res) => {
try {
const result = await executor.execute("presets", { action: "list" });
res.json(result.data || { presets: [] });
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
app.post("/api/presets", async (req, res) => {
const { action, name, config } = req.body;
try {
const result = await executor.execute("presets", { action, name, config });
res.json(result.data || {});
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
// --- Assets ---
function uniqueAssetName(base: string, taken: Set<string>): string {
const slug = (base || "asset").replace(/[^a-zA-Z0-9._-]/g, "-").replace(/^-+|-+$/g, "") || "asset";
if (!taken.has(slug)) return slug;
let i = 2;
while (taken.has(`${slug}-${i}`)) i++;
return `${slug}-${i}`;
}
app.get("/api/assets", async (req, res) => {
try {
const items = await assetManager.list(stringValue.safeParse(req.query.type).data);
res.json(items);
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.post("/api/assets/register", async (req, res) => {
const { name, path: filePath, type } = req.body;
try {
const asset = await assetManager.register(name, filePath, type || inferType(filePath));
broadcastSSE("assets-updated", { name });
res.json(asset);
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
}
});
app.post("/api/assets/upload", upload.single("file"), async (req, res) => {
if (!req.file) {
res.status(400).json({ error: "No file uploaded" });
return;
}
try {
const existing = new Set((await assetManager.list()).map((a) => a.name));
const wanted = safeName(stringValue.safeParse(req.body?.name).data || basename(req.file.originalname, extname(req.file.originalname)));
const name = existing.has(wanted) && !req.body?.overwrite ? uniqueAssetName(wanted, existing) : wanted;
const type = assetTypeSchema.safeParse(req.body?.type).data ?? inferType(req.file.originalname);
const asset = await assetManager.importFile(req.file.path, name, type);
broadcastSSE("assets-updated", { name });
res.json(asset);
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
} finally {
await unlink(req.file.path).catch(() => {});
}
});
app.post("/api/assets/url", async (req, res) => {
let url: string;
try {
url = await validateDownloadUrl(req.body?.url);
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "download_video",
status: "running",
progress: 0,
message: "Downloading asset",
createdAt: Date.now(),
};
jobs.set(jobId, job);
res.json({ job_id: jobId });
(async () => {
try {
const existing = new Set((await assetManager.list()).map((a) => a.name));
const wanted = safeName(stringValue.safeParse(req.body?.name).data || basename(new URL(url).pathname) || "asset");
const name = existing.has(wanted) ? uniqueAssetName(wanted, existing) : wanted;
const type = assetTypeSchema.safeParse(req.body?.type).data;
const asset = await assetManager.importUrl(url, name, type);
job.status = "done";
job.progress = 100;
job.result = asset;
broadcastSSE("job-complete", { jobId, result: asset });
broadcastSSE("assets-updated", { name });
} catch (err: unknown) {
job.status = "error";
job.error = errMsg(err);
broadcastSSE("job-error", { jobId, error: job.error });
}
})();
});
app.post("/api/assets/:name/default", async (req, res) => {
try {
const asset = await assetManager.setDefault(req.params.name);
broadcastSSE("assets-updated", { name: asset.name });
res.json(asset);
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
}
});
app.delete("/api/assets/:name/default", async (req, res) => {
try {
await assetManager.clearDefault(req.params.name);
broadcastSSE("assets-updated", { name: req.params.name });
res.json({ ok: true });
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
}
});
app.post("/api/assets/:name/rename", async (req, res) => {
try {
const asset = await assetManager.rename(req.params.name, req.body?.new_name);
broadcastSSE("assets-updated", { name: asset.name });
res.json(asset);
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
}
});
app.get("/api/assets/:name/download", async (req, res) => {
try {
// Look up by registered name only: never fall through to treating the
// param as a filesystem path (that would allow arbitrary file reads).
const asset = (await assetManager.list()).find((a) => a.name === req.params.name);
if (!asset || !existsSync(asset.path)) {
res.status(404).json({ error: `Asset "${req.params.name}" not found` });
return;
}
if (req.query.dl) {
res.download(asset.path, basename(asset.path));
} else {
if (extname(asset.path).toLowerCase() === ".svg") res.setHeader("Content-Security-Policy", "sandbox");
res.sendFile(asset.path);
}
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.delete("/api/assets/:name", async (req, res) => {
try {
await assetManager.unregister(req.params.name);
broadcastSSE("assets-updated", { name: req.params.name });
res.json({ ok: true });
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
}
});
app.post("/api/assets/unregister", async (req, res) => {
try {
await assetManager.unregister(req.body.name);
broadcastSSE("assets-updated", { name: req.body.name });
res.json({ ok: true });
} catch (err: unknown) {
res.status(400).json({ error: errMsg(err) });
}
});
// Recent source videos (referenced in place, not copied).
app.get("/api/sources", (_req, res) => {
const items = recentSources
.map((p) => ({ path: p, name: basename(p), exists: existsSync(p) }))
.filter((s) => s.exists);
res.json(items);
});
// --- Clip History ---
app.get("/api/history", async (req, res) => {
try {
const source = stringValue.safeParse(req.query.source).data;
const limit = parseInt(stringValue.safeParse(req.query.limit).data ?? "") || 50;
const entries = source
? await clipsHistory.getBySource(source)
: await clipsHistory.list(limit);
res.json(entries);
} catch {
res.json([]);
}
});
// Clip edits route through the Python CLI so the web UI and `podcli clips`
// share one history writer (preserves unknown fields like Phase 2 metrics).
const stripAnsi = (s: string) => stripVTControlCharacters(s).trim();
const RUN_PY_TIMEOUT_MS = 15 * 60_000;
function runPy(scriptAndArgs: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
return new Promise((resolve) => {
// Detached so a timeout kill takes out the whole process group (ffmpeg etc.).
const proc = spawn(paths.pythonPath, scriptAndArgs, {
env: pythonEnv({ PODCLI_HOME: paths.home, PODCLI_DATA: paths.dataDir }),
detached: process.platform !== "win32",
});
let stdout = "", stderr = "";
let settled = false;
const finish = (result: { code: number; stdout: string; stderr: string }) => {
if (settled) return;
settled = true;
clearTimeout(timer);
resolve(result);
};
const timer = setTimeout(() => {
terminateProcessTree(proc);
finish({
code: 1,
stdout,
stderr: `${stderr}\nTimed out after ${RUN_PY_TIMEOUT_MS / 1000}s`.trim(),
});
}, RUN_PY_TIMEOUT_MS);
proc.stdout.on("data", (d) => (stdout += d));
proc.stderr.on("data", (d) => (stderr += d));
proc.on("close", (code) => finish({ code: code ?? 1, stdout, stderr }));
proc.on("error", (e) => finish({ code: 1, stdout, stderr: String(e) }));
});
}
const runCli = (args: string[]) =>
runPy([join(paths.backendDir, "cli.py"), "--no-banner", ...args]);
const LOGO_POSITIONS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
type LogoPosition = (typeof LOGO_POSITIONS)[number];
function logoOverlayExpr(position: string, margin = 108): string {
const x = position.endsWith("right") ? `main_w-overlay_w-${margin}` : String(margin);
const y = position.startsWith("bottom") ? `main_h-overlay_h-${margin}` : String(margin);
return `${x}:${y}`;
}
function runFfmpeg(args: string[], timeoutMs = 120_000): Promise<{ code: number; stdout: string; stderr: string }> {
return new Promise((resolve) => {
const proc = spawn(paths.ffmpegPath, args, { detached: process.platform !== "win32" });
let stdout = "", stderr = "";
let settled = false;
const finish = (result: { code: number; stdout: string; stderr: string }) => {
if (settled) return;
settled = true;
clearTimeout(timer);
resolve(result);
};
const timer = setTimeout(() => {
terminateProcessTree(proc);
finish({ code: 1, stdout, stderr: `${stderr}\nTimed out after ${timeoutMs / 1000}s`.trim() });
}, timeoutMs);
proc.stdout.on("data", (d) => (stdout += d));
proc.stderr.on("data", (d) => (stderr += d));
proc.on("close", (code) => finish({ code: code ?? 1, stdout, stderr }));
proc.on("error", (e) => finish({ code: 1, stdout, stderr: String(e) }));
});
}
async function resolveLogoPath(input: string | undefined): Promise<string | null> {
const raw = (input ?? "").trim();
if (!raw) return null;
const resolvedLogo = await assetManager.resolve(raw);
if (!resolvedLogo || !existsSync(resolvedLogo)) return null;
return resolvedLogo;
}
// Composite a thumbnail PNG onto the start of a clip. stripStart > 0 removes a
// prior card first (avoids stacking on re-bake). Returns the bake's success.
async function bakeThumbnailCard(clipPath: string, image: string, stripStart = 0): Promise<{ ok: boolean; error?: string }> {
const r = await runCli([
"bake-thumbnail", clipPath, image, "--position", "start",
...(stripStart ? ["--strip-start", String(stripStart)] : []),
]);
return r.code === 0 ? { ok: true } : { ok: false, error: stripAnsi(r.stderr || r.stdout) };
}
app.patch("/api/clips/:id", async (req, res) => {
if (DEMO) { res.json({ ok: true });
return; } // fixtures are read-only
const { title, caption_style, thumbnail_config } = req.body || {};
const args = ["clips", "edit", req.params.id];
if (title != null) args.push(`--title=${title}`);
if (caption_style != null) args.push("--caption-style", String(caption_style));
if (thumbnail_config != null) args.push("--thumbnail-config", JSON.stringify(thumbnail_config));
if (args.length === 3) {
res.status(400).json({ error: "nothing to update" });
return;
}
const r = await runCli(args);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "edit failed" });
return;
}
res.json({ ok: true });
});
app.delete("/api/clips/:id", async (req, res) => {
if (DEMO) { res.json({ ok: true });
return; } // fixtures are read-only
const r = await runCli(["clips", "delete", req.params.id, "--yes"]);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "delete failed" });
return;
}
broadcastSSE("history-updated", { jobId: null, count: 1 });
res.json({ ok: true });
});
app.post("/api/clips/:id/reopen", async (req, res) => {
const r = await runCli(["clips", "reopen", req.params.id]);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "reopen failed" });
return;
}
res.json({ ok: true });
});
app.post("/api/clips/:id/thumbnail", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) {
res.status(404).json({ error: "clip not found" });
return;
}
const tc = clip.thumbnail_config || {};
// Standalone thumbnail generation: produces variation PNGs, never touches the clip video.
const outDir = join(paths.output, "thumbnails", String(clip.id));
// Free-text values ride behind "--" (positionals) or as --flag=value so a
// title starting with "-" can't be parsed as an option.
const args = [
"thumbnails",
"--output", outDir,
"--variations", "3",
"--json",
"--video", clip.source_video,
"--start", String(clip.start_second),
"--end", String(clip.end_second),
];
if (tc.image_path) args.push("--photo", String(tc.image_path));
else if (numberValue.safeParse(tc.timestamp).success) args.push("--timestamp", String(tc.timestamp));
if (tc.line1) args.push(`--line1=${tc.line1}`);
if (tc.line2) args.push(`--line2=${tc.line2}`);
args.push("--", tc.text || clip.title);
const r = await runCli(args);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "thumbnail failed" });
return;
}
const jsonLine = r.stdout.trim().split("\n").reverse().find((l) => l.trim().startsWith("{"));
let variations: string[] = [];
try { variations = JSON.parse(jsonLine || "{}").paths || []; } catch { /* no paths */ }
if (variations.length === 0) {
res.status(500).json({ error: "no thumbnails generated" });
return;
}
// Bake the chosen thumbnail into the clip as the opening card (stripping any prior card).
if (existsSync(clip.output_path)) {
const bake = await bakeThumbnailCard(clip.output_path, variations[0], clip.thumbnail_config?.card_seconds || 0);
if (!bake.ok) {
res.status(500).json({ error: `thumbnail generated but bake into clip failed: ${bake.error}` });
return;
}
}
const merged = { ...tc, preview_path: variations[0], variations, card_seconds: 1.5 };
await runCli(["clips", "edit", String(clip.id), "--thumbnail-config", JSON.stringify(merged)]);
res.json({ ok: true, preview_path: variations[0], variations });
});
app.post("/api/clips/:id/thumbnail/select", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) { res.status(404).json({
error: "clip not found" });
return;
}
const tc = clip.thumbnail_config || {};
const pick = String(req.body?.path || "");
if (!pick || !(tc.variations || []).includes(pick) || !existsSync(pick)) {
res.status(400).json({ error: "unknown variation" });
return;
}
if (existsSync(clip.output_path)) {
const bake = await bakeThumbnailCard(clip.output_path, pick, tc.card_seconds || 0);
if (!bake.ok) {
res.status(500).json({ error: `bake into clip failed: ${bake.error}` });
return;
}
}
await runCli(["clips", "edit", String(clip.id), "--thumbnail-config", JSON.stringify({ ...tc, preview_path: pick, card_seconds: 1.5 })]);
res.json({ ok: true, preview_path: pick });
});
// CLI flags grounding thumbnail headline copy in the clip's own content
// (payoff, the question it answers, its verbatim opening line) instead of
// just the title. Empty for clips rendered before these fields existed.
function thumbnailGroundingArgs(clip: { payoff?: string; context_line?: string; preview_text?: string }): string[] {
const args: string[] = [];
if (clip.payoff) args.push("--payoff", clip.payoff);
if (clip.context_line) args.push("--context-line", clip.context_line);
if (clip.preview_text) args.push("--preview-text", clip.preview_text);
return args;
}
// Candidate headline texts + face frames for the two-step thumbnail picker.
app.get("/api/clips/:id/thumbnail/options", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) { res.status(404).json({
error: "clip not found" });
return;
}
const tc = clip.thumbnail_config || {};
const clamp = (v: any, d: number) => Math.min(Math.max(parseInt(String(v)) || d, 1), 8);
const outDir = join(paths.output, "thumbnails", String(clip.id), "frames");
const r = await runCli([
"thumbnail-options",
"--output", outDir,
"--video", clip.source_video,
"--start", String(clip.start_second),
"--end", String(clip.end_second),
"--texts", String(clamp(req.query.texts, 6)),
"--frames", String(clamp(req.query.frames, 6)),
...thumbnailGroundingArgs(clip),
"--", tc.text || clip.title,
]);
if (r.code !== 0) { res.status(400).json({
error: stripAnsi(r.stderr || r.stdout) || "options failed" });
return;
}
const jsonLine = r.stdout.trim().split("\n").reverse().find((l) => l.trim().startsWith("{"));
try {
const parsed = JSON.parse(jsonLine || "{}");
if (!parsed.frames?.length && (parsed.texts?.length || 0) > 0) {
parsed.warning = "No suitable frames found in this clip: try another moment or upload a frame.";
}
res.json(parsed);
} catch { res.status(500).json({ error: "bad options output" }); }
});
// Render one final thumbnail from a chosen frame + headline (empty lines = AI writes the text).
app.post("/api/clips/:id/thumbnail/render", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) { res.status(404).json({
error: "clip not found" });
return;
}
const tc = clip.thumbnail_config || {};
const { line1, line2, frame_path, frame_info, layout, swap } = req.body || {};
// The pair layout takes both people from the clip itself; a frame is only
// its fallback when two people cannot be told apart.
if (!frame_path && needsFrame(layout)) { res.status(400).json({
error: "select a frame first" });
return;
}
// Only allow frames podcli itself produced (candidate frames) or the user uploaded:
// never an arbitrary server path passed through to the renderer.
const resolvedFrame = frame_path
? resolveFrameInRoots(frame_path, [join(paths.output, "thumbnails", String(clip.id)), uploadDir])
: null;
if (frame_path && !resolvedFrame) { res.status(400).json({
error: "invalid frame" });
return;
}
const outDir = join(paths.output, "thumbnails", String(clip.id));
await mkdir(outDir, { recursive: true });
const out = join(outDir, `thumb_${uuidv4().slice(0, 8)}.png`);
const args = thumbnailRenderArgs({
output: out, frame: resolvedFrame, frameInfo: frame_info,
line1, line2, layout, swap: !!swap, clip,
});
args.push(...thumbnailGroundingArgs(clip));
args.push("--", tc.text || clip.title);
const r = await runCli(args);
if (r.code !== 0) { res.status(400).json({
error: stripAnsi(r.stderr || r.stdout) || "render failed" });
return;
}
const { path: outPath, report } = parseThumbnailRender(r.stdout);
if (!outPath || !existsSync(outPath)) { res.status(500).json({
error: "no thumbnail produced" });
return;
}
if (clip.output_path && existsSync(clip.output_path)) {
const bake = await bakeThumbnailCard(clip.output_path, outPath, tc.card_seconds || 0);
if (!bake.ok) { res.status(500).json({
error: `rendered but bake into clip failed: ${bake.error}` });
return;
}
}
const merged = {
...tc, line1: line1 || undefined, line2: line2 || undefined, preview_path: outPath, card_seconds: 1.5,
layout: report.layout, people: report.people,
};
const edit = await runCli(["clips", "edit", String(clip.id), "--thumbnail-config", JSON.stringify(merged)]);
if (edit.code !== 0) { res.status(500).json({
error: stripAnsi(edit.stderr || edit.stdout) || "thumbnail metadata update failed" });
return;
}
res.json({ ok: true, preview_path: outPath, ...report });
});
app.get("/api/clips/:id/logo/previews", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) { res.status(404).json({
error: "clip not found" });
return;
}
if (!clip.output_path || !existsSync(clip.output_path)) { res.status(400).json({
error: "rendered file missing" });
return;
}
const logo = await resolveLogoPath(stringValue.safeParse(req.query.logo_path).data);
if (!logo) { res.status(400).json({
error: "select a logo first" });
return;
}
const baseVideo = clip.logo_backup_path && existsSync(clip.logo_backup_path)
? clip.logo_backup_path
: clip.output_path;
const outDir = join(paths.output, "logo-previews", String(clip.id));
await mkdir(outDir, { recursive: true });
const previews = [];
for (const position of LOGO_POSITIONS) {
const out = join(outDir, `${position}.jpg`);
const r = await runFfmpeg([
"-y",
"-ss", String(Math.max(0, Math.min(1, (clip.duration || 1) / 3))),
"-i", baseVideo,
"-i", logo,
"-filter_complex", `[1:v]scale=-1:126[logo];[0:v][logo]overlay=${logoOverlayExpr(position)}[v]`,
"-map", "[v]",
"-frames:v", "1",
"-q:v", "3",
out,
]);
if (r.code !== 0 || !existsSync(out)) {
res.status(400).json({ error: stripAnsi(r.stderr) || "preview failed" });
return;
}
previews.push({ position, path: out });
}
res.json({ previews });
});
app.post("/api/clips/:id/logo", async (req, res) => {
if (DEMO) { res.json({
ok: true });
return;
}
const clip = await clipsHistory.findById(req.params.id);
if (!clip) { res.status(404).json({
error: "clip not found" });
return;
}
if (!clip.output_path || !existsSync(clip.output_path)) { res.status(400).json({
error: "rendered file missing" });
return;
}
const action = String(req.body?.action || "apply");
if (action === "remove") {
const backup = clip.logo_backup_path;
if (!backup || !existsSync(backup)) {
res.status(400).json({ error: "no logo backup available" });
return;
}
await copyFile(backup, clip.output_path);
await clipsHistory.update(clip.id, { logo_path: "", logo_backup_path: "", logo_position: "" });
broadcastSSE("history-updated", { jobId: null, count: 1 });
res.json({ ok: true, restored_from: backup });
return;
}
const logo = await resolveLogoPath(stringValue.safeParse(req.body?.logo_path).data);
if (!logo) { res.status(400).json({
error: "select a logo first" });
return;
}
const position: LogoPosition = z.enum(LOGO_POSITIONS).catch("top-right").parse(req.body?.logo_position);
const backup = clip.logo_backup_path && existsSync(clip.logo_backup_path)
? clip.logo_backup_path
: `${clip.output_path}.pre-logo.mp4`;
if (!existsSync(backup)) await copyFile(clip.output_path, backup);
const baseVideo = existsSync(backup) ? backup : clip.output_path;
const tmp = `${clip.output_path}.logo-${process.pid}.mp4`;
const r = await runFfmpeg([
"-y",
"-i", baseVideo,
"-i", logo,
"-filter_complex", `[1:v]scale=-1:126[logo];[0:v][logo]overlay=${logoOverlayExpr(position)}[v]`,
"-map", "[v]",
"-map", "0:a?",
"-c:v", "libx264",
"-preset", "veryfast",
"-crf", "18",
"-pix_fmt", "yuv420p",
"-c:a", "copy",
"-movflags", "+faststart",
tmp,
], 15 * 60_000);
if (r.code !== 0 || !existsSync(tmp)) {
res.status(400).json({ error: stripAnsi(r.stderr) || "logo apply failed" });
return;
}
await rename(tmp, clip.output_path);
const size = statSync(clip.output_path).size / 1024 / 1024;
await clipsHistory.update(clip.id, {
logo_path: logo,
logo_backup_path: backup,
logo_position: position,
file_size_mb: Math.round(size * 10) / 10,
});
broadcastSSE("history-updated", { jobId: null, count: 1 });
res.json({ ok: true, logo_path: logo, logo_position: position, backup_path: backup });
});
// --- Thumbnail studio (standalone thumbnails, no clip required) ---
const thumbStudioDir = join(paths.output, "thumbnails", "studio");
// realpath both sides so a symlink planted inside an allowed root can't point
// the renderer at a file outside it.
function resolveFrameInRoots(framePath: string, roots: string[]): string | null {
let real: string;
try {
real = realpathSync(path.resolve(framePath));
} catch {
return null;
}
const realRoot = (p: string) => {
try { return realpathSync(p); } catch { return resolve(p); }
};
const ok = roots.map(realRoot).some((root) => real === root || real.startsWith(root + path.sep));
return ok ? real : null;
}
app.post("/api/thumbnail-studio/options", async (req, res) => {
const { title, video_path, start, end, texts, frames } = req.body || {};
if (!title || !String(title).trim()) { res.status(400).json({
error: "title is required" });
return;
}
const clamp = (v: any, d: number) => Math.min(Math.max(parseInt(String(v)) || d, 1), 8);
const args = [
"thumbnail-options",
"--output", join(thumbStudioDir, "frames"),
"--texts", String(clamp(texts, 6)),
"--frames", String(clamp(frames, 6)),
];
if (video_path) {
// Frames come only from files the user explicitly uploaded/selected this
// session: never an arbitrary server path passed to the extractor.
let video: string;
try { video = realpathSync(path.resolve(String(video_path))); } catch { res.status(400).json({
error: "video not found" });
return;
}
if (!allowedSourcePaths.has(video)) { res.status(400).json({
error: "unknown video, upload or select it first" });
return;
}
args.push("--video", video);
if (start != null && start !== "") args.push("--start", String(Math.max(0, Number(start) || 0)));
if (end != null && end !== "") args.push("--end", String(Math.max(0, Number(end) || 0)));
}
args.push("--", String(title));
const r = await runCli(args);
if (r.code !== 0) { res.status(400).json({
error: stripAnsi(r.stderr || r.stdout) || "options failed" });
return;
}
const jsonLine = r.stdout.trim().split("\n").reverse().find((l) => l.trim().startsWith("{"));
try {
const parsed = JSON.parse(jsonLine || "{}");
if (!parsed.frames?.length && (parsed.texts?.length || 0) > 0) {
parsed.warning = "No suitable frames found: try another moment or upload a frame.";
}
res.json(parsed);
} catch { res.status(500).json({ error: "bad options output" }); }
});
app.post("/api/thumbnail-studio/render", async (req, res) => {
const { title, line1, line2, frame_path, frame_info } = req.body || {};
if (!title || !String(title).trim()) { res.status(400).json({
error: "title is required" });
return;
}
if (!frame_path) { res.status(400).json({
error: "select a frame first" });
return;
}
const resolvedFrame = resolveFrameInRoots(frame_path, [thumbStudioDir, uploadDir]);
if (!resolvedFrame) { res.status(400).json({
error: "invalid frame" });
return;
}
await mkdir(thumbStudioDir, { recursive: true });
const out = join(thumbStudioDir, `thumb_${uuidv4().slice(0, 8)}.png`);
const args = ["thumbnail-render", "--frame", resolvedFrame, "--output", out];
if (line1) args.push(`--line1=${line1}`);
if (line2) args.push(`--line2=${line2}`);
if (frame_info) args.push("--frame-info", JSON.stringify(frame_info));
args.push("--", String(title));
const r = await runCli(args);
if (r.code !== 0) { res.status(400).json({
error: stripAnsi(r.stderr || r.stdout) || "render failed" });
return;
}
const jsonLine = r.stdout.trim().split("\n").reverse().find((l) => l.trim().startsWith("{"));
let outPath = "";
try { outPath = JSON.parse(jsonLine || "{}").path || ""; } catch { /* no path */ }
if (!outPath || !existsSync(outPath)) { res.status(500).json({
error: "no thumbnail produced" });
return;
}
res.json({ ok: true, path: outPath });
});
// --- Secrets/settings stored in the global .env (e.g. HF_TOKEN) ---
app.get("/api/settings", async (_req, res) => {
try {
const result = await executor.execute<{ settings?: unknown[] }>("manage_env", { action: "list" });
res.json(result.data ?? { settings: [] });
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.post("/api/settings", async (req, res) => {
const key = stringValue.safeParse(req.body?.key).data ?? "";
const value = stringValue.safeParse(req.body?.value).data ?? "";
if (!key) {
res.status(400).json({ error: "key is required" });
return;
}
try {
const action = value.trim() ? "set" : "unset";
const result = await executor.execute("manage_env", { action, key, value });
res.json(result.data ?? { ok: true });
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.get("/api/ai-cli-status", async (_req, res) => {
try {
const result = await executor.execute<{
configured?: Record<string, string | null>;
candidates?: Array<{ engine: string; path: string }>;
available?: boolean;
}>("ai_cli_status", {});
res.json(result.data ?? { available: false, candidates: [], configured: {} });
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.get("/api/ai-provider-status", async (_req, res) => {
try {
const result = await executor.execute<object>("ai_provider_status", {});
res.json(result.data ?? { available: false, providers: [], candidates: [] });
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
app.get("/api/youtube/config", (_req, res) => {
try {
const all = JSON.parse(readFileSync(paths.integrations, "utf-8"));
const yt = all.youtube || {};
res.json({ client_id: yt.client_id || "", has_secret: !!yt.client_secret });
} catch {
res.json({ client_id: "", has_secret: false });
}
});
const integrationsFileSchema = z.looseObject({
youtube: z
.looseObject({ client_id: z.string().optional(), client_secret: z.string().optional() })
.optional(),
});
type IntegrationsFile = z.infer<typeof integrationsFileSchema>;
app.put("/api/youtube/config", (req, res) => {
try {
let all: IntegrationsFile = {};
try { all = integrationsFileSchema.parse(JSON.parse(readFileSync(paths.integrations, "utf-8"))); } catch { /* new */ }
const yt = { ...all.youtube };
const { client_id, client_secret } = req.body || {};
if (client_id !== undefined) yt.client_id = client_id;
if (client_secret) yt.client_secret = client_secret;
all.youtube = yt;
writeFileAtomicSync(paths.integrations, JSON.stringify(all, null, 2) + "\n");
// Holds the OAuth client secret: keep it owner-only (chmod covers the
// case where the file already existed with looser perms).
try { chmodSync(paths.integrations, 0o600); } catch { /* best effort */ }
res.json({ ok: true });
} catch (e: any) {
res.status(500).json({ error: e.message });
}
});
app.get("/api/youtube/status", async (_req, res) => {
try {
const clips = await clipsHistory.load();
res.json({
authorized: DEMO || existsSync(join(paths.home, "youtube-token.json")),
linked: clips.filter((c) => c.youtube_video_id).length,
with_metrics: clips.filter((c) => c.metrics && (c.metrics.views != null || c.metrics.retention != null)).length,
total: clips.length,
});
} catch {
res.json({ authorized: false, linked: 0, with_metrics: 0, total: 0 });
}
});
app.post("/api/youtube/sync", async (req, res) => {
const csvPath = req.body?.csv_path;
const r = await runCli(["youtube", "sync", ...(csvPath ? ["--csv", String(csvPath)] : [])]);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "sync failed" });
return;
}
res.json({ ok: true, message: stripAnsi(r.stdout) });
});
app.post("/api/youtube/learn", async (_req, res) => {
const r = await runCli(["youtube", "learn"]);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "analysis failed" });
return;
}
res.json({ ok: true, message: stripAnsi(r.stdout) });
});
// Proposed clip↔video links for the authorized channel (live OAuth path).
app.get("/api/youtube/links", async (_req, res) => {
const r = await runCli(["youtube", "link", "--json"]);
let payload: any = {};
try { payload = JSON.parse(r.stdout.trim().split("\n").pop() || "{}"); } catch { /* non-JSON */ }
if (r.code !== 0 || payload.error) {
res.status(400).json({ error: payload.error || stripAnsi(r.stderr || r.stdout) || "could not load proposals" });
return;
}
res.json({ proposals: payload.proposals || [] });
});
app.post("/api/youtube/link", async (req, res) => {
const { clip_id, video_id } = req.body || {};
if (!clip_id || !video_id) {
res.status(400).json({ error: "clip_id and video_id are required" });
return;
}
const r = await runCli(["youtube", "link", String(clip_id), String(video_id), "--json"]);
let payload: any = {};
try { payload = JSON.parse(r.stdout.trim().split("\n").pop() || "{}"); } catch { /* non-JSON */ }
if (r.code !== 0 || !payload.ok) {
res.status(400).json({ error: payload.error || "link failed (clip not found?)" });
return;
}
res.json({ ok: true });
});
app.get("/api/analytics", async (_req, res) => {
const clips = await clipsHistory.load();
const withM = clips.filter((c) => c.metrics && (c.metrics.views != null || c.metrics.retention != null));
const avg = (arr: number[]) => (arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0);
const agg = (keyFn: (c: any) => string) => {
const groups = new Map<string, any[]>();
for (const c of withM) {
const k = keyFn(c) || "unknown";
(groups.get(k) ?? groups.set(k, []).get(k)!).push(c);
}
return Array.from(groups.entries()).map(([key, cs]) => ({
key,
count: cs.length,
avgViews: Math.round(avg(cs.map((c) => c.metrics?.views || 0))),
avgRetention: +avg(cs.map((c) => c.metrics?.retention || 0)).toFixed(1),
avgCtr: +avg(cs.map((c) => c.metrics?.ctr || 0)).toFixed(1),
})).sort((a, b) => b.avgViews - a.avgViews);
};
const lengthBucket = (d: number) => (d < 25 ? "<25s" : d < 35 ? "25-35s" : d < 45 ? "35-45s" : "45s+");
res.json({
published: withM.length,
total: clips.length,
byContentType: agg((c) => c.content_type),
byCaptionStyle: agg((c) => c.caption_style),
byLength: agg((c) => lengthBucket(c.duration || 0)),
top: withM
.slice()
.sort((a, b) => (b.metrics?.views || 0) - (a.metrics?.views || 0))
.slice(0, 12)
.map((c) => ({ id: c.id, title: c.title, content_type: c.content_type, caption_style: c.caption_style, duration: c.duration, metrics: c.metrics })),
});
});
app.get("/api/clips/:id/source", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip || !existsSync(clip.source_video)) {
res.status(404).json({ error: "source not found" });
return;
}
const srcMime = new Map([
[".mp4", "video/mp4"],
[".webm", "video/webm"],
[".mov", "video/quicktime"],
[".mkv", "video/x-matroska"],
[".m4v", "video/mp4"],
]);
streamVideo(req, res, clip.source_video, srcMime.get(extname(clip.source_video).toLowerCase()) || "video/mp4");
});
app.get("/api/clips/:id/reframe", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) { res.status(404).json({
error: "clip not found" });
return;
}
res.json((await clipsHistory.loadReframe(clip.id)) || {});
});
app.get("/api/clips/:id/cuts", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip || !existsSync(clip.source_video)) { res.status(404).json({
error: "source not found" });
return;
}
const start = clip.start_second;
const dur = Math.max(0.1, clip.end_second - clip.start_second);
// pts_time from ffmpeg scene detection is relative to -ss, not the source.
const proc = spawn(paths.ffmpegPath, [
"-ss", String(start), "-i", clip.source_video, "-t", String(dur),
"-vf", "select='gt(scene,0.3)',showinfo", "-an", "-f", "null", "-",
]);
let stderr = "";
proc.stderr.on("data", (d) => (stderr += d));
proc.on("close", () => {
const cuts = [...stderr.matchAll(/pts_time:([\d.]+)/g)].flatMap((m) => {
const t = +(start + parseFloat(m[1])).toFixed(3);
return t > start + 0.2 && t < start + dur - 0.2 ? [t] : [];
});
res.json({ cuts: Array.from(new Set(cuts)) });
});
proc.on("error", () => res.json({ cuts: [] }));
});
const trimWindowSchema = z.looseObject({ inSec: z.number().optional(), outSec: z.number().optional() });
app.post("/api/clips/:id/rerender", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) {
res.status(404).json({ error: "clip not found" });
return;
}
// Editor sends source-absolute keyframes + trim; derive the render's clip-relative
// crop keyframes from it, and persist the editor state so reopening shows it.
const reframe = reframeStateSchema.safeParse(req.body?.reframe).data;
const trim = trimWindowSchema.safeParse(req.body?.trim).data;
const startSecond = reframe?.inSec ?? trim?.inSec ?? numberValue.safeParse(req.body?.start_second).data ?? clip.start_second;
const endSecond = reframe?.outSec ?? trim?.outSec ?? numberValue.safeParse(req.body?.end_second).data ?? clip.end_second;
const keyframes = reframe?.keyframes
? reframe.keyframes
.filter((k) => k.tAbs >= startSecond - 0.001 && k.tAbs <= endSecond + 0.001)
.map((k) => ({ t: +Math.max(0, k.tAbs - startSecond).toFixed(3), x_pct: k.x_pct }))
: req.body?.crop_keyframes;
const trimOnly = !!trim && !reframe && !Array.isArray(keyframes);
if (!trimOnly && (!Array.isArray(keyframes) || keyframes.length === 0)) {
res.status(400).json({ error: "keyframes required" });
return;
}
if (reframe) await clipsHistory.saveReframe(clip.id, reframe);
const recipe = (await clipsHistory.loadRecipe(clip.id)) || {};
let allWords = recipe.transcript_words ?? (await clipsHistory.loadWords(clip.id));
if (!allWords.length) {
// Fallback for clips rendered before recipes existed: recover words from the cached source transcript.
try {
const t = await cache.get(clip.source_video);
if (t?.words?.length) allWords = t.words;
} catch { /* no cached transcript */ }
}
// If trimmed wider/narrower, keep only words inside the new bounds.
const words = allWords.filter((w) => w.start >= startSecond && w.start < endSecond);
const recipeSegments = trimOnly ? undefined : recipe.keep_segments;
// A trim that no longer holds the hook's passage renders without it.
const recipeHook = recipe.hook;
const trimOnlyCrop = recipe.crop_strategy || clip.crop_strategy || "face";
const hook = recipeHook && !validateHook(recipeHook, startSecond, endSecond, recipeSegments)
? recipeHook
: undefined;
const recipeAsset = (key: "logo_path" | "outro_path" | "intro_path") => {
const value = recipe[key];
return value?.trim() ? value : undefined;
};
try {
const result = await executor.execute<ClipResult>("create_clip", {
video_path: clip.source_video,
start_second: startSecond,
end_second: endSecond,
caption_style: req.body?.caption_style || recipe.caption_style || clip.caption_style,
crop_strategy: trimOnly ? trimOnlyCrop : "manual",
...(!trimOnly && { crop_keyframes: keyframes }),
transcript_words: words,
logo_path: recipeAsset("logo_path") ?? clip.logo_path ?? null,
outro_path: recipeAsset("outro_path") ?? clip.outro_path ?? null,
intro_path: recipeAsset("intro_path") ?? clip.intro_path ?? null,
clean_fillers: trimOnly ? false : (recipe.clean_fillers ?? true),
trim_opening: trimOnly ? false : undefined,
preserve_timing: trimOnly ? true : undefined,
...(recipeSegments && { keep_segments: recipeSegments }),
...(hook && { hook }),
title: clip.title,
output_dir: dirname(clip.output_path),
});
if (!result.data) throw new Error("no render output");
const outPath = result.data.output_path || clip.output_path;
// Re-bake the chosen thumbnail card onto the fresh clip (no strip needed:
// create_clip always renders a cardless clip).
const tnail = clip.thumbnail_config?.preview_path;
let thumbnailBaked = false;
if (tnail && existsSync(tnail) && existsSync(outPath)) {
const bake = await bakeThumbnailCard(outPath, tnail);
thumbnailBaked = bake.ok;
if (!bake.ok) {
res.status(500).json({ error: `reframe rendered but thumbnail bake failed: ${bake.error}` });
return;
}
}
await clipsHistory.update(clip.id, {
start_second: startSecond,
end_second: endSecond,
crop_strategy: trimOnly ? trimOnlyCrop : "manual",
duration: result.data.duration ?? clip.duration,
file_size_mb: result.data.file_size_mb ?? clip.file_size_mb,
output_path: outPath,
});
res.json({ ok: true, output_path: outPath, file_size_mb: result.data.file_size_mb, thumbnail_baked: thumbnailBaked });
} catch (e: unknown) {
res.status(500).json({ error: errMsg(e) });
}
});
app.post("/api/clips/:id/davinci", async (req, res) => {
const clip = await clipsHistory.findById(req.params.id);
if (!clip) {
res.status(404).json({ error: "clip not found" });
return;
}
if (!existsSync(clip.output_path)) {
res.status(400).json({ error: "rendered file missing" });
return;
}
const cli = join(paths.backendDir, "services", "integrations", "davinci_resolve", "cli.py");
const r = await runPy([cli, "--source", clip.output_path, `--title=${clip.title}`]);
if (r.code !== 0) {
res.status(400).json({ error: stripAnsi(r.stderr || r.stdout) || "export failed" });
return;
}
const wrote = (r.stdout.match(/wrote:\s*(.+)/) || [])[1]?.trim();
res.json({ ok: true, path: wrote });
});
app.get("/api/history/check", async (req, res) => {
try {
const {
source,
start,
end,
style = "hormozi",
crop = "speaker",
} = req.query;
if (!source || !start || !end) {
res.json({ duplicate: null });
return;
}
const dup = await clipsHistory.findDuplicate(
stringValue.parse(source),
parseFloat(stringValue.parse(start)),
parseFloat(stringValue.parse(end)),
stringValue.parse(style),
stringValue.parse(crop),
);
res.json({ duplicate: dup });
} catch {
res.json({ duplicate: null });
}
});
// --- Transcript Corrections ---
const correctionsPath = paths.corrections;
app.get("/api/corrections", (_req, res) => {
try {
if (existsSync(correctionsPath)) {
res.json(JSON.parse(readFileSync(correctionsPath, "utf-8")));
} else {
res.json({});
}
} catch {
res.json({});
}
});
app.put("/api/corrections", express.json(), (req, res) => {
try {
const corrections = req.body || {};
writeFileAtomicSync(correctionsPath, JSON.stringify(corrections, null, 2));
res.json({ ok: true, corrections });
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
app.post("/api/corrections/add", express.json(), (req, res) => {
const { wrong, correct } = req.body;
if (!wrong || !correct) {
res.status(400).json({ error: "'wrong' and 'correct' are required" });
return;
}
try {
let corrections: Record<string, string> = {};
if (existsSync(correctionsPath)) {
corrections = JSON.parse(readFileSync(correctionsPath, "utf-8"));
}
corrections[wrong] = correct;
writeFileAtomicSync(correctionsPath, JSON.stringify(corrections, null, 2));
res.json({ ok: true, corrections });
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
app.delete("/api/corrections/:wrong", (req, res) => {
try {
let corrections: Record<string, string> = {};
if (existsSync(correctionsPath)) {
corrections = JSON.parse(readFileSync(correctionsPath, "utf-8"));
}
delete corrections[req.params.wrong];
writeFileAtomicSync(correctionsPath, JSON.stringify(corrections, null, 2));
res.json({ ok: true, corrections });
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
// --- Knowledge Base ---
app.get("/api/knowledge", async (_req, res) => {
try {
const files = await knowledgeBase.listFiles();
res.json(files);
} catch {
res.json([]);
}
});
app.get("/api/knowledge/dir", (_req, res) => {
res.json({ path: paths.knowledge });
});
// Must stay ahead of the :filename routes, which would otherwise claim "init".
app.post("/api/knowledge/init", async (_req, res) => {
try {
res.json(await knowledgeBase.initFromTemplates());
} catch (err: unknown) {
res.status(500).json({ error: errMsg(err) });
}
});
// Knowledge file upload (drag & drop .md files), must be before :filename routes
const knowledgeUpload = multer({
storage: multer.diskStorage({
destination: async (_req, _file, cb) => {
await mkdir(paths.knowledge, { recursive: true });
cb(null, paths.knowledge);
},
filename: (_req, file, cb) => cb(null, basename(file.originalname)),
}),
fileFilter: (_req, file, cb) => {
const name = basename(file.originalname);
if (name.endsWith(".md") || name.endsWith(".txt")) {
cb(null, true);
} else {
cb(new Error("Only .md and .txt files are allowed"));
}
},
});
app.post(
"/api/knowledge/upload",
knowledgeUpload.array("files", 50),
(req, res) => {
const files = Array.isArray(req.files) ? req.files : [];
if (!files || files.length === 0) {
res.status(400).json({ error: "No files uploaded" });
return;
}
res.json({ uploaded: files.map((f) => f.originalname) });
},
);
app.get("/api/knowledge/:filename", async (req, res) => {
if (!safePath(paths.knowledge, req.params.filename)) {
res.status(400).json({ error: "Invalid filename" });
return;
}
try {
const content = await knowledgeBase.readFile(req.params.filename);
res.json({ filename: req.params.filename, content });
} catch (err: any) {
res.status(404).json({ error: err.message });
}
});
app.post("/api/knowledge/:filename", async (req, res) => {
if (!safePath(paths.knowledge, req.params.filename)) {
res.status(400).json({ error: "Invalid filename" });
return;
}
try {
await knowledgeBase.writeFile(req.params.filename, req.body.content);
res.json({ ok: true, filename: req.params.filename });
} catch (err: any) {
res.status(400).json({ error: err.message });
}
});
app.delete("/api/knowledge/:filename", async (req, res) => {
if (!safePath(paths.knowledge, req.params.filename)) {
res.status(400).json({ error: "Invalid filename" });
return;
}
try {
await knowledgeBase.deleteFile(req.params.filename);
res.json({ ok: true });
} catch (err: any) {
res.status(500).json({ error: err.message });
}
});
// --- Onboarding readiness ---
app.get("/api/onboarding", async (_req, res) => {
const knowledge = await knowledgeBase
.status()
.catch(() => ({ templates: [], present: [], filled: [], missing: [] }));
const assets = await assetManager.list().catch(() => []);
const clips = await clipsHistory.load().catch(() => []);
let aiCli = false;
try {
const result = await executor.execute<{ available?: boolean }>("ai_cli_status", {});
aiCli = !!result.data?.available;
} catch {
// A failed probe reads the same as no CLI installed.
}
res.json({
knowledge: {
total: knowledge.templates.length,
present: knowledge.present.length,
filled: knowledge.filled,
missing: knowledge.missing,
},
assets: {
count: assets.length,
branding: assets.some((a) => a.type === "logo" || a.type === "outro"),
},
aiCli: { available: aiCli },
clips: { count: clips.length },
dismissed: !!uiState.settings.onboardingDismissed,
});
});
// --- Prompt Builder (shared by /api/generate-prompt and /api/mcp-hints) ---
function getStateContext() {
const hasVideo = !!uiState.videoPath;
const hasTranscript = (uiState.transcript?.words?.length ?? 0) > 0;
const hasRawTranscript = !!uiState.rawTranscriptText?.trim();
const hasSuggestions = uiState.suggestions.length > 0;
const selectedCount =
uiState.suggestions.length - uiState.deselectedIndices.length;
return {
hasVideo,
hasTranscript,
hasRawTranscript,
hasSuggestions,
selectedCount,
phase: uiState.phase,
};
}
function buildPromptForAction(
action: "suggest" | "export" | "restyle",
): string {
const ctx = getStateContext();
const parts: string[] = [];
const settingsSummary = [
uiState.videoPath ? `Video: ${uiState.videoPath.split(/[/\\]/).pop()}` : null,
`Style: ${uiState.settings.captionStyle}`,
`Crop: ${uiState.settings.cropStrategy}`,
uiState.settings.logoPath ? `Logo: set` : null,
uiState.settings.outroPath ? `Outro: set` : null,
]
.filter(Boolean)
.join(", ");
if (action === "suggest") {
if (!ctx.hasTranscript && !ctx.hasRawTranscript) {
// No transcript yet: prompt includes transcribe step
if (uiState.videoPath) {
parts.push(
`Transcribe the podcast at ${uiState.videoPath} using transcribe_podcast.`,
);
} else {
parts.push(
"Set a video path first, then transcribe it using transcribe_podcast.",
);
}
parts.push(
"Then find the 5-8 best viral-worthy moments and call suggest_clips.",
);
} else {
parts.push(
"Use get_ui_state with include_transcript=true to read the full transcript.",
);
parts.push(
"Find the 5-8 best viral-worthy moments, such as hot takes, strong opinions, funny moments, actionable advice, and emotional stories.",
);
parts.push("Then call suggest_clips with your suggestions.");
}
parts.push(`Current settings: ${settingsSummary}`);
} else if (action === "export") {
parts.push("Use get_ui_state to read the selected clips.");
parts.push(
`Export all ${ctx.selectedCount} selected clip${ctx.selectedCount !== 1 ? "s" : ""} using batch_create_clips.`,
);
parts.push(`Current settings: ${settingsSummary}`);
} else if (action === "restyle") {
parts.push("Use get_ui_state to read the current clips.");
parts.push("Re-export all clips with the updated style settings.");
parts.push(`Current settings: ${settingsSummary}`);
}
return parts.join("\n");
}
// --- MCP Prompt Hints ---
/**
* GET /api/mcp-hints: Returns contextual MCP prompt suggestions based on current state.
* Prompts are practical clip-generation actions, not generic help.
* Phrased generically (not Claude-specific) since any MCP client can use them.
*/
app.get("/api/mcp-hints", (_req, res) => {
const ctx = getStateContext();
interface Hint {
prompt: string;
description: string;
category: "analyze" | "create" | "refine" | "export";
}
const hints: Hint[] = [];
// The UI handles video upload and transcript input directly.
// MCP hints only appear once there's something to work with.
if ((ctx.hasRawTranscript || ctx.hasTranscript) && !ctx.hasSuggestions) {
// Transcript is ready: suggest clip-finding prompts
hints.push(
{
prompt: "Find the 5 best viral moments from this podcast",
description: "Clips optimized for TikTok/Shorts",
category: "analyze",
},
{
prompt: "Find moments with hot takes and strong opinions",
description: "Controversial, high-engagement clips",
category: "analyze",
},
{
prompt: "Find funny moments and quotable one-liners",
description: "Entertainment-focused clips",
category: "analyze",
},
{
prompt: "Find actionable advice and key insights",
description: "Value-driven educational clips",
category: "analyze",
},
);
} else if (
ctx.phase === "review" &&
ctx.hasSuggestions &&
ctx.selectedCount > 0
) {
// Clips suggested, ready for action
hints.push(
{
prompt: "Export all selected clips",
description: `Render ${ctx.selectedCount} clip${ctx.selectedCount !== 1 ? "s" : ""} as vertical shorts`,
category: "export",
},
{
prompt: "Export clip #1",
description: "Render just the first clip",
category: "export",
},
{
prompt: "Change all clips to hormozi style",
description: "Bold uppercase, yellow highlight",
category: "refine",
},
{
prompt: "Extend clip #1 by 10 seconds",
description: "Adjust timing before export",
category: "refine",
},
{
prompt: "Find 5 more moments",
description: "Additional clips from the transcript",
category: "analyze",
},
);
} else if (ctx.phase === "done") {
hints.push(
{
prompt: "Find more viral moments from the transcript",
description: "Get another batch of clips",
category: "analyze",
},
{
prompt: "Re-export all clips with karaoke style",
description: "Try a different caption look",
category: "refine",
},
{
prompt: "Save these settings as a preset called 'myshow'",
description: "Reuse this config next time",
category: "refine",
},
);
}
res.json({
hints,
phase: ctx.phase,
hasVideo: ctx.hasVideo,
hasTranscript: ctx.hasTranscript,
hasSuggestions: ctx.hasSuggestions,
selectedCount: ctx.selectedCount,
});
});
/**
* POST /api/generate-prompt: Build an MCP prompt for the given action using authoritative server state.
* Body: { action: "suggest" | "export" | "restyle" }
* Returns: { prompt, action, context }
*/
app.post("/api/generate-prompt", (req, res) => {
const action = req.body.action || "suggest";
if (!["suggest", "export", "restyle"].includes(action)) {
res
.status(400)
.json({ error: "action must be 'suggest', 'export', or 'restyle'" });
return;
}
const prompt = buildPromptForAction(action);
const ctx = getStateContext();
res.json({ prompt, action, context: ctx });
});
// --- AI-powered clip suggestion (delegates to Python backend) ---
app.post("/api/claude-suggest", async (req, res) => {
const { top_n = 5, min_duration, max_duration } = req.body;
// Need transcript in state
if (!uiState.transcript && !uiState.rawTranscriptText) {
res
.status(400)
.json({ error: "No transcript loaded. Transcribe or import one first." });
return;
}
const segs = uiState.transcript?.segments;
if (!segs || !Array.isArray(segs) || segs.length === 0) {
res.status(400).json({ error: "No transcript segments available." });
return;
}
try {
// Feed already-known moments to the AI so it doesn't re-suggest the same
// ranges: clips already rendered for this video plus current suggestions.
const rendered = uiState.videoPath
? await clipsHistory.getBySource(uiState.videoPath).catch(() => [])
: [];
const existing_clips = [
...rendered.map((c) => ({ start_second: c.start_second, end_second: c.end_second, title: c.title })),
...uiState.suggestions.map((s) => ({ start_second: s.start_second, end_second: s.end_second, title: s.title })),
];
// The backend derives laughter/reaction anchors from the audio, so it needs
// the source video, not just the segments.
const suggestVideo = uiState.filePath || uiState.videoPath;
const params = {
segments: segs,
top_n,
existing_clips,
...(suggestVideo && { video_path: suggestVideo }),
...(min_duration && { min_duration }),
...(max_duration && { max_duration }),
// Duration bounds are per-format, so the numbers above mean nothing without it.
...(uiState.settings.format && { format: uiState.settings.format }),
};
const result = await executor.execute<{ clips?: SuggestedClip[] }>(
"suggest_clips",
params,
(event) =>
broadcastSSE("job-update", {
progress: event.percent,
message: event.message,
}),
);
const clips = result.data?.clips ?? [];
// Auto-push to UI state as suggestions
if (clips.length > 0) {
uiState.suggestions = clips.map((c, i) => ({
clip_id: `claude-${i}`,
title: c.title,
start_second: c.start_second,
end_second: c.end_second,
duration: c.duration ?? c.end_second - c.start_second,
segments: c.segments,
reasoning: c.reasoning ?? "",
payoff: c.payoff ?? "",
standalone: c.standalone ?? "",
context_line: c.context_line ?? "",
preview_text: c.preview_text ?? "",
content_type: c.content_type,
score: c.score,
rank: c.rank,
suggested_caption_style: c.suggested_caption_style || "hormozi",
}));
uiState.deselectedIndices = [];
uiState.phase = "review";
broadcastSSE("state-sync", uiState);
} else {
uiState.phase = "idle";
broadcastSSE("state-sync", uiState);
}
res.json({ clips, source: "python" });
} catch (err: unknown) {
const msg = errMsg(err);
uiState.phase = "idle";
broadcastSSE("state-sync", uiState);
res
.status(500)
.json({ error: `Suggestion failed: ${msg.substring(0, 200)}` });
}
});
// --- Find user-pasted moments (paste a description/quotes, AI locates them) ---
app.post("/api/find-moment", async (req, res) => {
const text = (stringValue.safeParse(req.body?.text).data ?? "").trim();
if (!text) {
res.status(400).json({ error: "Paste a moment or description to search for." });
return;
}
const segs = uiState.transcript?.segments;
if (!segs || !Array.isArray(segs) || segs.length === 0) {
res
.status(400)
.json({ error: "No transcript loaded. Transcribe or import one first." });
return;
}
try {
const existing = uiState.suggestions.map((s) => ({
start_second: s.start_second,
end_second: s.end_second,
title: s.title,
}));
const result = await executor.execute<{ clips?: SuggestedClip[] }>(
"find_moment",
{ text, segments: segs, existing_clips: existing, max_results: 8 },
(event) =>
broadcastSSE("job-update", { progress: event.percent, message: event.message }),
);
const found = result.data?.clips ?? [];
// Append to existing suggestions, skipping anything at a range we already have.
const seen = new Set(
uiState.suggestions.map(
(s) => `${Math.round(s.start_second * 10)}-${Math.round(s.end_second * 10)}`,
),
);
const added: SuggestedClip[] = [];
for (const c of found) {
const key = `${Math.round(c.start_second * 10)}-${Math.round(c.end_second * 10)}`;
if (seen.has(key)) continue;
seen.add(key);
added.push({
clip_id: `manual-${Date.now()}-${added.length}`,
title: c.title,
start_second: c.start_second,
end_second: c.end_second,
duration: c.duration ?? c.end_second - c.start_second,
segments: c.segments,
reasoning: c.reasoning ?? "",
payoff: c.payoff ?? "",
standalone: c.standalone ?? "",
context_line: c.context_line ?? "",
preview_text: c.preview_text ?? "",
content_type: c.content_type,
score: c.score,
rank: c.rank,
suggested_caption_style: c.suggested_caption_style || "hormozi",
});
}
if (added.length > 0) {
uiState.suggestions = [...uiState.suggestions, ...added];
uiState.phase = "review";
uiState.lastUpdated = Date.now();
persistState();
broadcastSSE("state-sync", uiState);
}
res.json({ clips: added, found: found.length, added: added.length });
} catch (err: unknown) {
const msg = errMsg(err);
res.status(500).json({ error: `Moment search failed: ${msg.substring(0, 200)}` });
}
});
// --- Per-clip content generation (titles, descriptions, tags) ---
app.post("/api/generate-content", async (req, res) => {
const { clip, transcript_segments } = req.body;
if (!clip) {
res.status(400).json({ error: "clip is required" });
return;
}
// Use transcript segments from request or fall back to UI state
const segs = transcript_segments || uiState.transcript?.segments || [];
try {
const result = await executor.execute(
"generate_content",
{ clip, transcript_segments: segs },
(event) => {
if (event.partial) {
broadcastSSE("content-partial", { stream_id: clip?.id ? String(clip.id) : null, partial: event.partial });
return;
}
broadcastSSE("job-update", {
progress: event.percent,
message: event.message,
});
},
);
const data: any = result.data || {};
// Persist onto the clip's history entry so the generated metadata survives a
// reload: generation is expensive and was previously discarded after display.
const clipId = clip?.id ? await clipsHistory.resolveId(String(clip.id)) : null;
if (clipId) {
const patch: Partial<ClipHistoryEntry> = {};
if (Array.isArray(data.titles) && data.titles.length) patch.generated_titles = data.titles;
if (data.description) patch.description = data.description;
if (data.tags) patch.tags = data.tags;
if (data.hashtags) patch.hashtags = data.hashtags;
if (Object.keys(patch).length) await clipsHistory.update(clipId, patch);
}
res.json(data);
} catch (err: any) {
res.status(500).json({
error: `Content generation failed: ${err.message?.substring(0, 200)}`,
});
}
});
// --- Content studio (transcript-first generation, no clip required) ---
const CONTENT_MAX_SEGMENTS = 30;
// Long transcripts get sampled evenly so titles reflect the whole episode,
// not just the opening minutes (the generator reads at most 30 segments).
function packTranscriptText(text: string): Array<{ start: number; text: string }> {
const clean = text.replace(/\r/g, "").trim();
const segChars = 1000;
const stride = Math.max(segChars, Math.floor(clean.length / CONTENT_MAX_SEGMENTS));
const segs: Array<{ start: number; text: string }> = [];
for (let off = 0; off < clean.length && segs.length < CONTENT_MAX_SEGMENTS; off += stride) {
const chunk = clean.slice(off, off + segChars).trim();
if (chunk) segs.push({ start: segs.length, text: chunk });
}
return segs;
}
function condenseSegments(segments: Array<{ start?: number; text?: string }>): Array<{ start: number; text: string }> {
const clean = segments.flatMap((s) => {
const text = String(s.text || "").trim();
return text ? [{ start: Number(s.start) || 0, text }] : [];
});
if (clean.length <= CONTENT_MAX_SEGMENTS) return clean;
const per = Math.ceil(clean.length / CONTENT_MAX_SEGMENTS);
const out: Array<{ start: number; text: string }> = [];
for (let i = 0; i < clean.length; i += per) {
const group = clean.slice(i, i + per);
out.push({ start: group[0].start, text: group.map((s) => s.text).join(" ").slice(0, 1200) });
}
return out;
}
app.post("/api/content-studio/generate", async (req, res) => {
const { title, transcript_text, mode, stream_id } = req.body || {};
let segs: Array<{ start: number; text: string }>;
const pastedText = stringValue.safeParse(transcript_text).data;
if (pastedText?.trim()) {
segs = packTranscriptText(pastedText);
} else if (uiState.transcript?.segments?.length) {
segs = condenseSegments(uiState.transcript.segments);
} else {
res.status(400).json({ error: "paste a transcript or load an episode first" });
return;
}
const episode = mode === "episode";
const lastStart = segs.length ? segs[segs.length - 1].start : 0;
const clip = {
title: String(title || "").trim() || "Untitled episode",
start_second: 0,
end_second: lastStart + 60,
content_type: episode ? "full episode" : "highlight",
};
try {
const result = await executor.execute(
"generate_content",
{ clip, transcript_segments: segs, mode: episode ? "episode" : "shorts" },
(event) => {
if (event.partial) {
broadcastSSE("content-partial", { stream_id: stream_id || null, partial: event.partial });
return;
}
broadcastSSE("job-update", {
progress: event.percent,
message: event.message,
});
},
);
res.json(result.data || {});
} catch (err: any) {
res.status(500).json({
error: `Content generation failed: ${err.message?.substring(0, 200)}`,
});
}
});
/**
* POST /api/content-studio/custom: free-form or per-section content request.
*/
app.post("/api/content-studio/custom", async (req, res) => {
const { instruction, transcript_text, mode } = req.body || {};
if (!instruction || !String(instruction).trim()) {
res.status(400).json({ error: "instruction is required" });
return;
}
let segs: Array<{ start: number; text: string }>;
const pastedText = stringValue.safeParse(transcript_text).data;
if (pastedText?.trim()) {
segs = packTranscriptText(pastedText);
} else if (uiState.transcript?.segments?.length) {
segs = condenseSegments(uiState.transcript.segments);
} else {
res.status(400).json({ error: "paste a transcript or load an episode first" });
return;
}
try {
const result = await executor.execute(
"generate_custom",
{
instruction: String(instruction),
transcript_segments: segs,
mode: mode === "episode" ? "episode" : "shorts",
},
(event) => {
broadcastSSE("job-update", { progress: event.percent, message: event.message });
},
);
res.json(result.data || {});
} catch (err: any) {
res.status(500).json({
error: `Custom generation failed: ${err.message?.substring(0, 200)}`,
});
}
});
// --- MCP ↔ UI Bridge Endpoints ---
/**
* GET /api/events: Global SSE channel for real-time MCP→UI events
*/
app.get("/api/events", (_req, res) => {
res.writeHead(200, {
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
Connection: "keep-alive",
});
// Send current state on connect
res.write(`event: state\ndata: ${JSON.stringify(uiState)}\n\n`);
sseClients.push(res);
// Heartbeat every 15s
const heartbeat = setInterval(() => {
try {
res.write(`: heartbeat\n\n`);
} catch {
clearInterval(heartbeat);
}
}, 15_000);
_req.on("close", () => {
clearInterval(heartbeat);
const idx = sseClients.indexOf(res);
if (idx !== -1) sseClients.splice(idx, 1);
});
});
/**
* GET /api/ui-state: MCP reads current UI state
*/
app.get("/api/ui-state", (_req, res) => {
const selected = uiState.suggestions.filter(
(_, i) => !uiState.deselectedIndices.includes(i),
);
res.json({
videoPath: uiState.videoPath,
filePath: uiState.filePath,
activeExportJobId: uiState.activeExportJobId,
phase: uiState.phase,
settings: uiState.settings,
selectedClips: selected,
suggestions: uiState.suggestions,
deselectedIndices: uiState.deselectedIndices,
totalSuggestions: uiState.suggestions.length,
deselectedCount: uiState.deselectedIndices.length,
transcriptWordCount: Array.isArray(uiState.transcript?.words)
? (uiState.transcript?.words ?? []).length
: 0,
transcript: uiState.transcript,
rawTranscriptText: uiState.rawTranscriptText,
silenceOriginal: uiState.silenceOriginal,
silencePlan: uiState.silencePlan,
videoMissing: uiState.videoMissing,
lastUpdated: uiState.lastUpdated,
});
});
/**
* POST /api/ui-state: UI syncs state changes to server
*/
app.post("/api/ui-state", (req, res) => {
const body = req.body;
// Track which fields changed for targeted SSE broadcasts
const source = body._source || "mcp"; // UI sends _source:'ui'
// A newly mounted React client briefly holds form defaults before its SSE
// snapshot commits. Ignore that exact destructive shape so refresh/navigation
// cannot erase an existing episode. User-initiated Clear opts in explicitly.
const looksLikeMountDefaults =
source === "ui" &&
body._allowClear !== true &&
!!uiState.videoPath &&
body.videoPath === "";
if (looksLikeMountDefaults) {
res.json({ ok: true, ignored: "stale hydration defaults" });
return;
}
// Changing the video without a transcript arriving in the same call means
// the old transcript, suggestions and selections describe a recording
// that's no longer loaded. Carrying them forward lets create_clip burn
// captions and timings from the wrong video. transcribe_podcast and
// import_transcript always send videoPath and transcript together, so
// this only fires for a bare set_video.
const videoChanged =
body.videoPath !== undefined &&
body.videoPath !== uiState.videoPath &&
body.transcript === undefined;
if (videoChanged) {
uiState.transcript = null;
uiState.transcriptVideoIdentity = null;
uiState.rawTranscriptText = "";
uiState.suggestions = [];
uiState.deselectedIndices = [];
uiState.energyData = {};
uiState.silenceOriginal = null;
uiState.silencePlan = null;
}
if (body.videoPath !== undefined) {
uiState.videoPath = body.videoPath;
uiState.videoMissing = !!body.videoPath && !existsSync(body.videoPath);
}
if (body.filePath !== undefined) uiState.filePath = body.filePath;
if (body.transcript !== undefined) {
uiState.transcript = body.transcript;
uiState.transcriptVideoIdentity = body.transcript
? computeVideoIdentity(body.videoPath ?? uiState.videoPath ?? "")
: null;
}
if (body.rawTranscriptText !== undefined)
uiState.rawTranscriptText = body.rawTranscriptText;
if (body.silenceOriginal !== undefined) {
const original = body.silenceOriginal;
if (original === null) {
uiState.silenceOriginal = null;
} else if (
stringValue.safeParse(original?.videoPath).success &&
existsSync(original.videoPath) &&
Array.isArray(original?.transcript?.words)
) {
uiState.silenceOriginal = original;
registerSourcePath(original.videoPath);
}
}
if (body.silencePlan !== undefined) {
const plan = body.silencePlan;
uiState.silencePlan = plan === null || (
Array.isArray(plan?.keep_segments) &&
Array.isArray(plan?.removed_ranges)
) ? plan : uiState.silencePlan;
}
if (body.suggestions !== undefined) {
if (body._source === "ui" && Array.isArray(body.suggestions)) {
const previousSuggestions = uiState.suggestions;
uiState.suggestions = body.suggestions.map((incoming: SuggestedClip) => {
const existingIndex = previousSuggestions.findIndex(
(s) =>
Math.abs(s.start_second - incoming.start_second) < 0.5 &&
Math.abs(s.end_second - incoming.end_second) < 0.5,
);
const existing = existingIndex >= 0 ? previousSuggestions[existingIndex] : undefined;
let merged = incoming;
if (!incoming.segments?.length) {
const segments = findSuggestionSegments(
previousSuggestions,
incoming.start_second,
incoming.end_second,
);
if (segments?.length) {
// The restored segments (and any hook) change what actually
// plays, so the duration has to be recomputed rather than
// carried over from before the edit. Otherwise a clip with an
// opening hook reports a duration that excludes it.
merged = {
...incoming,
segments,
duration:
Math.round(
playbackDuration(incoming.start_second, incoming.end_second, segments, incoming.hook) * 10,
) / 10,
};
}
}
// A studio edit (retiming, segment trim, hook change, ...) lands here
// the same way MCP's modify_clip lands on /api/suggestions/modify;
// an already-approved clip needs the same "no longer matches what
// was selected" flag, or a studio edit after selection silently
// exports something other than what was approved.
if (existing?.selectionHash && !uiState.deselectedIndices.includes(existingIndex)) {
const currentHash = computeSelectionHash(merged, uiState.transcript?.words);
if (currentHash !== existing.selectionHash) {
merged = { ...merged, selectionHash: existing.selectionHash, changedSinceSelection: true };
}
}
return merged;
});
} else {
uiState.suggestions = body.suggestions;
}
}
if (body.deselectedIndices !== undefined)
uiState.deselectedIndices = body.deselectedIndices;
if (body.phase !== undefined) uiState.phase = body.phase;
if (body.results !== undefined) uiState.results = body.results;
if (body.energyData !== undefined) uiState.energyData = body.energyData;
if (body.settings) {
if (body.settings.captionStyle !== undefined)
uiState.settings.captionStyle = body.settings.captionStyle;
if (body.settings.cropStrategy !== undefined)
uiState.settings.cropStrategy = body.settings.cropStrategy;
if (body.settings.format !== undefined)
uiState.settings.format = body.settings.format;
if (body.settings.logoPath !== undefined)
uiState.settings.logoPath = body.settings.logoPath;
if (body.settings.outroPath !== undefined)
uiState.settings.outroPath = body.settings.outroPath;
if (body.settings.introPath !== undefined)
uiState.settings.introPath = body.settings.introPath;
if (body.settings.cleanFillers !== undefined)
uiState.settings.cleanFillers = body.settings.cleanFillers !== false;
if (["auto", "upper", "center", "lower"].includes(body.settings.captionPosition))
uiState.settings.captionPosition = body.settings.captionPosition;
if (body.settings.captionFontScale !== undefined)
uiState.settings.captionFontScale = Math.max(60, Math.min(160, Number(body.settings.captionFontScale) || 100));
if (["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"].includes(body.settings.logoPosition))
uiState.settings.logoPosition = body.settings.logoPosition;
if (body.settings.onboardingDismissed !== undefined)
uiState.settings.onboardingDismissed = !!body.settings.onboardingDismissed;
if (body.settings.silenceThreshold !== undefined)
uiState.settings.silenceThreshold = Math.max(0.25, Math.min(0.8, Number(body.settings.silenceThreshold) || 0.5));
if (body.settings.silenceMinPause !== undefined)
uiState.settings.silenceMinPause = Math.max(0.3, Math.min(5, Number(body.settings.silenceMinPause) || 0.65));
if (body.settings.silencePadding !== undefined)
uiState.settings.silencePadding = Math.max(0.02, Math.min(0.5, Number(body.settings.silencePadding) || 0.12));
}
uiState.lastUpdated = Date.now();
persistState();
// Broadcast to UI when changes come from MCP (not from UI itself).
// Send the stored (server-enriched) values, not the raw request body, so
// clients see keep_segments etc.; energyData rides along so unrelated syncs
// don't wipe computed energy client-side.
if (source !== "ui") {
broadcastSSE("state-sync", {
...(body.videoPath !== undefined && { videoPath: uiState.videoPath }),
...(body.filePath !== undefined && { filePath: uiState.filePath }),
// The request body only carried videoPath, but a bare set_video also
// cleared the transcript/suggestions/selections server-side; without
// forcing these onto the broadcast too, the studio's in-memory state
// never learns they were cleared and later syncs the stale ones right
// back.
...((body.suggestions !== undefined || videoChanged) && { suggestions: uiState.suggestions }),
...((body.deselectedIndices !== undefined || videoChanged) && {
deselectedIndices: uiState.deselectedIndices,
}),
...(body.phase !== undefined && { phase: uiState.phase }),
...((body.transcript !== undefined || videoChanged) && { transcript: uiState.transcript }),
...(body.silenceOriginal !== undefined && { silenceOriginal: uiState.silenceOriginal }),
...(body.silencePlan !== undefined && { silencePlan: uiState.silencePlan }),
...(body.settings && { settings: uiState.settings }),
energyData: uiState.energyData,
});
}
res.json({ ok: true });
});
// Mirrors clipKey() in the studio client: energy scores are keyed by clip
// identity, not by position, so they survive a suggestion being spliced out.
function dropEnergy(clip: SuggestedClip): void {
const key =
clip.clip_id ||
`${clip.start_second.toFixed(2)}:${clip.end_second.toFixed(2)}`;
delete uiState.energyData[key];
}
/**
* POST /api/suggestions/modify: mutate one suggestion in-place on the server.
* Replaces the read-modify-replace cycle MCP tools used, which lost concurrent
* edits between the GET and the wholesale POST.
* Body: { action: "update" | "delete" | "toggle", index? | clip_id?, updates?, selected? }
*/
// A field of the wrong type is skipped, not rejected, so one bad value does not drop the whole edit.
const ignoreWrongType = <T extends z.ZodType>(schema: T) => schema.optional().catch(undefined);
const clipFieldUpdatesSchema = z.looseObject({
title: ignoreWrongType(z.string()),
start_second: ignoreWrongType(z.number()),
end_second: ignoreWrongType(z.number()),
payoff: ignoreWrongType(z.string()),
standalone: ignoreWrongType(z.string()),
context_line: ignoreWrongType(z.string()),
reasoning: ignoreWrongType(z.string()),
preview_text: ignoreWrongType(z.string()),
suggested_caption_style: ignoreWrongType(z.string()),
});
app.post("/api/suggestions/modify", (req, res) => {
const { action = "update", clip_id, updates, selected } = req.body || {};
let index = numberValue.safeParse(req.body?.index).data ?? -1;
if (index === -1 && clip_id) {
index = uiState.suggestions.findIndex((s) => s.clip_id === clip_id);
}
if (index < 0 || index >= uiState.suggestions.length) {
res.status(404).json({ error: "Clip not found", total: uiState.suggestions.length });
return;
}
let clip: SuggestedClip;
if (action === "delete") {
[clip] = uiState.suggestions.splice(index, 1);
uiState.deselectedIndices = uiState.deselectedIndices
.filter((i) => i !== index)
.map((i) => (i > index ? i - 1 : i));
dropEnergy(clip);
} else if (action === "toggle") {
if (!z.boolean().safeParse(selected).success) {
res.status(400).json({ error: "selected must be a boolean for action 'toggle'" });
return;
}
clip = uiState.suggestions[index];
if (selected) {
uiState.deselectedIndices = uiState.deselectedIndices.filter((i) => i !== index);
// Stamp what's being approved so a later edit to the same clip can be
// caught instead of silently rendering something else.
clip.selectionHash = computeSelectionHash(clip, uiState.transcript?.words);
clip.changedSinceSelection = false;
} else {
if (!uiState.deselectedIndices.includes(index)) {
uiState.deselectedIndices = [...uiState.deselectedIndices, index];
}
delete clip.selectionHash;
delete clip.changedSinceSelection;
}
} else if (action === "update") {
const upd = updates || {};
const fields = clipFieldUpdatesSchema.catch({}).parse(upd);
clip = uiState.suggestions[index];
const nextStart = fields.start_second ?? clip.start_second;
const nextEnd = fields.end_second ?? clip.end_second;
const rangeError = validateSuggestionRange(nextStart, nextEnd);
if (rangeError) {
res.status(400).json({ error: rangeError });
return;
}
const reTimed = nextStart !== clip.start_second || nextEnd !== clip.end_second;
// The old segments array is scoped to the old range; if left stale it
// overrides the new start/end at render time (create_clip reads
// keep_segments ahead of start_second/end_second).
const nextSegments = reTimed
? reconcileSegmentsForRange(clip.segments, clip.start_second, clip.end_second, nextStart, nextEnd)
: clip.segments;
const nextHook: ClipHook | undefined =
upd.hook === null ? undefined : upd.hook !== undefined ? upd.hook : clip.hook;
const hookError = validateHook(nextHook, nextStart, nextEnd, nextSegments);
if (hookError) {
res.status(400).json({
error: upd.hook === undefined
? `${hookError} The new range no longer holds this clip's hook. Pass hook: null to clear it, or a new hook.`
: hookError,
});
return;
}
// The energy score was measured over the old range.
if (reTimed) {
dropEnergy(clip);
clip.segments = nextSegments;
}
if (nextHook) clip.hook = { start: nextHook.start, end: nextHook.end, mode: nextHook.mode };
else delete clip.hook;
if (fields.title !== undefined) clip.title = fields.title;
clip.start_second = nextStart;
clip.end_second = nextEnd;
if (fields.payoff !== undefined) clip.payoff = fields.payoff;
if (fields.standalone !== undefined) clip.standalone = fields.standalone;
if (fields.context_line !== undefined) clip.context_line = fields.context_line;
if (fields.reasoning !== undefined) clip.reasoning = fields.reasoning;
if (fields.preview_text !== undefined) clip.preview_text = fields.preview_text;
if (fields.suggested_caption_style !== undefined) {
clip.suggested_caption_style = fields.suggested_caption_style;
}
clip.duration =
Math.round(playbackDuration(clip.start_second, clip.end_second, clip.segments, clip.hook) * 10) / 10;
const fmtTime = (s: number) =>
`${Math.floor(s / 60)}:${Math.floor(s % 60).toString().padStart(2, "0")}`;
clip.timestamp_display = `${fmtTime(clip.start_second)} → ${fmtTime(clip.end_second)}`;
// Approval was for a specific render; if this edit changed any
// render-relevant field on an already-selected clip, flag it instead of
// silently exporting something other than what got approved.
if (clip.selectionHash && !uiState.deselectedIndices.includes(index)) {
const currentHash = computeSelectionHash(clip, uiState.transcript?.words);
if (currentHash !== clip.selectionHash) {
clip.changedSinceSelection = true;
}
}
} else {
res.status(400).json({ error: `Unknown action: ${action}` });
return;
}
uiState.lastUpdated = Date.now();
persistState();
broadcastSSE("state-sync", {
suggestions: uiState.suggestions,
deselectedIndices: uiState.deselectedIndices,
energyData: uiState.energyData,
});
res.json({
ok: true,
index,
clip,
total: uiState.suggestions.length,
selectedCount: uiState.suggestions.length - uiState.deselectedIndices.length,
});
});
/**
* POST /api/mcp/export: MCP triggers export using current UI state
*/
app.post("/api/mcp/export", async (req, res) => {
// Use UI state if no explicit params provided
const videoPath =
req.body.video_path || uiState.filePath || uiState.videoPath;
const clips =
req.body.clips ||
uiState.suggestions.filter(
(_, i) => !uiState.deselectedIndices.includes(i),
);
const transcriptWords =
req.body.transcript_words ||
(Array.isArray(uiState.transcript?.words)
? (uiState.transcript?.words ?? [])
: []);
const logoPath = req.body.logo_path || uiState.settings.logoPath || null;
const outroPath = req.body.outro_path || uiState.settings.outroPath || null;
const introPath = req.body.intro_path || uiState.settings.introPath || null;
const captionStyle =
req.body.caption_style || uiState.settings.captionStyle || "branded";
const cropStrategy =
req.body.crop_strategy || uiState.settings.cropStrategy || "speaker";
const format =
req.body.format || uiState.settings.format || "vertical";
const allowAssFallback = req.body.allow_ass_fallback === true;
// An agent that says nothing about fillers gets the studio's toggle, so an
// export it triggers matches what the user set up there.
const cleanFillers =
req.body.clean_fillers !== undefined
? req.body.clean_fillers !== false
: uiState.settings.cleanFillers !== false;
const keepCaptionOverlay = req.body.keep_caption_overlay === true;
const writeCleanVariant = req.body.write_clean_variant === true;
if (!videoPath || !existsSync(videoPath)) {
res.status(400).json({ error: "Video file not found" });
return;
}
if (!clips.length) {
res.status(400).json({ error: "No clips to export" });
return;
}
for (let i = 0; i < clips.length; i++) {
const c = clips[i];
const rangeError = validateClipRange(c.start_second, c.end_second, c.format || format);
if (rangeError) {
res.status(400).json({ error: `Clip ${i + 1}: ${rangeError}` });
return;
}
}
await fileManager.ensureDirectories();
// Apply style settings to clips that don't have their own
const styledClips = clips.map((c: any) =>
enrichClipFromSuggestion({
start_second: c.start_second,
end_second: c.end_second,
title: c.title || "clip",
caption_style: c.caption_style || captionStyle,
crop_strategy: c.crop_strategy || cropStrategy,
format: c.format || format,
allow_ass_fallback: c.allow_ass_fallback === true || allowAssFallback,
keep_segments:
(Array.isArray(c.segments) && c.segments.length > 0 && c.segments) ||
(Array.isArray(c.keep_segments) && c.keep_segments.length > 0 && c.keep_segments) ||
(Array.isArray(c.keep_segment) && c.keep_segment.length > 0 && c.keep_segment) ||
undefined,
hook: c.hook,
}),
);
const mcpHookError = exportHookError(styledClips);
if (mcpHookError) {
res.status(400).json({ error: mcpHookError });
return;
}
const jobId = uuidv4();
const job: JobState = {
id: jobId,
type: "batch_clips",
status: "running",
progress: 0,
message: "Starting MCP export...",
createdAt: Date.now(),
};
jobs.set(jobId, job);
const historyRecorder = createBatchHistoryRecorder({
jobId,
sourceVideo: videoPath,
transcriptWords,
defaultCaptionStyle: captionStyle,
defaultCropStrategy: cropStrategy,
defaultFormat: format,
label: "MCP export",
clipSpecs: styledClips,
logoPath,
outroPath,
introPath,
cleanFillers,
});
// Broadcast to UI so it can track progress
broadcastSSE("export-started", { jobId, clipCount: styledClips.length });
setExportState("exporting", jobId);
res.json({ job_id: jobId, status: "running", clipCount: styledClips.length });
executor
.execute<BatchClipsResult>(
"batch_clips",
{
video_path: videoPath,
clips: styledClips,
transcript_words: transcriptWords,
output_dir: paths.output,
logo_path: logoPath,
outro_path: outroPath,
intro_path: introPath,
clean_fillers: cleanFillers,
keep_caption_overlay: keepCaptionOverlay,
write_clean_variant: writeCleanVariant,
face_map: uiState.transcript?.face_map,
},
(event) => {
const progress = advanceProgress(job, event.percent);
job.message = event.message;
historyRecorder.recordProgress(event);
const clipResult = event.clip_result
? tagSubmittedClip(event.clip_result, styledClips)
: undefined;
if (event.stage === "clip_complete" && clipResult) {
(job.clip_results ??= []).push(clipResult);
}
broadcastSSE("job-update", {
jobId,
progress,
message: event.message,
stage: event.stage,
clip_result: clipResult,
});
},
)
.then(async (result) => {
const data = tagSubmittedClips(result.data, styledClips);
job.status = "done";
job.progress = 100;
job.message = "Export complete!";
job.result = data;
uiState.results = data?.results ?? [];
// Record clips to history
try {
await historyRecorder.recordRemaining(result.data?.results);
} catch (err) {
log.warn("Failed to record batch export clips to history", {
err: errMsg(err),
});
}
setExportState("done", null);
broadcastSSE("job-complete", { jobId, result: data });
})
.catch((err) => {
job.status = "error";
job.error = err.message;
job.message = `Error: ${err.message}`;
setExportState("review", null);
broadcastSSE("job-error", { jobId, error: err.message });
});
});
// --- Start ---
async function main() {
await fileManager.ensureDirectories();
await knowledgeBase.ensureDir();
await mkdir(uploadDir, { recursive: true });
// Cleanup old temp files on startup (>48h)
try {
const cleaned = await fileManager.cleanupOldTasks(48);
if (cleaned > 0) log.info(`Cleaned up ${cleaned} old temp files`);
} catch (err) {
log.warn("Startup temp-file cleanup failed", { err: errMsg(err) });
}
try {
const status = await executor.execute<{
legacy_cache_pending?: boolean;
legacy_presets_pending?: boolean;
}>("manage_config", {
action: "status",
});
if (status.data?.legacy_cache_pending || status.data?.legacy_presets_pending) {
await executor.execute("manage_config", { action: "migrate" });
log.info("Migrated legacy transcription cache to data/cache");
}
} catch (err) {
log.warn("Legacy cache migration skipped", { err: errMsg(err) });
}
// SPA fallback: client-side routes (/, /episode, /clip/:id) resolve to the
// built index.html. Registered last so it never shadows /api or static assets.
// root: the install path can contain a dot segment (a global npm install under
// ~/.nvm, say), and sendFile's dotfile rule would 404 the whole app.
app.get(/^(?!\/api\/).*/, (_req, res) => {
res.sendFile("index.html", { root: publicDir });
});
// Bind to loopback by default: the studio serves local files (clips, assets,
// source video) with no auth. Set PODCLI_HOST=0.0.0.0 to expose it on the LAN.
const server = app.listen(PORT, bindHost, () => {
log.info(`podcli running at http://localhost:${PORT}`);
});
server.on("error", (err: NodeJS.ErrnoException) => {
if (err.code === "EADDRINUSE") {
log.error(`Port ${PORT} is already in use. Is the studio already running? Set PODCLI_PORT to use another.`);
} else {
log.error("Web server failed to start", { err: err.message });
}
process.exit(1);
});
}
main().catch((err) => {
log.error("Fatal error during startup", {
err: err instanceof Error ? err.stack : String(err),
});
process.exit(1);
});