Skip to content

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

8.4 KB
Raw Blame
import { spawn, type ChildProcess, type SpawnOptions } from "child_process";
import { v4 as uuidv4 } from "uuid";
import { z } from "zod";
import { absentWhenNull } from "../utils/zod-helpers.js";
import { paths, pythonEnv } from "../config/paths.js";
import type { TaskRequest, TaskResult, ProgressEvent } from "../models/index.js";

type ProgressCallback = (event: ProgressEvent) => void;

const isWindows = process.platform === "win32";

/** The one shape of spawn that taskkill needs, so a test can stand in for it. */
export type SpawnProcess = (command: string, args: string[], options: SpawnOptions) => ChildProcess;

type ProcessTreeOptions = {
  platform?: NodeJS.Platform;
  spawnProcess?: SpawnProcess;
};

function hasExited(proc: ChildProcess): boolean {
  return proc.exitCode !== null || proc.signalCode !== null;
}

export function killProcessTree(
  proc: ChildProcess,
  signal: NodeJS.Signals,
  options: ProcessTreeOptions = {}
): void {
  if (proc.pid === undefined || hasExited(proc)) return;
  const platform = options.platform ?? process.platform;

  try {
    if (platform === "win32") {
      const taskkill = (options.spawnProcess ?? spawn)(
        "taskkill",
        ["/pid", String(proc.pid), "/T", "/F"],
        { stdio: "ignore", windowsHide: true }
      );

      taskkill.once("error", () => undefined);
    } else process.kill(-proc.pid, signal);
  } catch {}
}

const KILL_GRACE_MS = 2000;

export function terminateProcessTree(
  proc: ChildProcess,
  graceMs = KILL_GRACE_MS,
  options: ProcessTreeOptions = {}
): void {
  if (hasExited(proc)) return;
  const platform = options.platform ?? process.platform;

  if (platform === "win32") {
    killProcessTree(proc, "SIGKILL", options);

    return;
  }

  let exited = false;
  let escalation: NodeJS.Timeout | undefined;

  const onExit = (): void => {
    exited = true;

    if (escalation) clearTimeout(escalation);
  };

  proc.once("exit", onExit);

  if (hasExited(proc)) {
    proc.removeListener("exit", onExit);

    return;
  }

  killProcessTree(proc, "SIGTERM", options);

  if (exited || hasExited(proc)) return;

  escalation = setTimeout(() => {
    if (!exited && !hasExited(proc)) killProcessTree(proc, "SIGKILL", options);
  }, graceMs);
  escalation.unref();
}

// Prefer the last traceback block: that's where the actual failure is,
// and keep a tail long enough to include it.
export function stderrTail(stderr: string, maxChars = 4000): string {
  const tb = stderr.lastIndexOf("Traceback (most recent call last):");
  const tail = tb !== -1 ? stderr.slice(tb) : stderr;

  return tail.slice(-maxChars);
}

const resultEnvelopeSchema = z.looseObject({
  task_id: z.string(),
  status: z.enum(["success", "error"]),
  data: z.unknown().optional(),
  error: absentWhenNull(z.string()),
});

const clipResultRowSchema = z.looseObject({
  clip_index: absentWhenNull(z.number()),
  status: z.enum(["success", "error"]),
  output_path: absentWhenNull(z.string()),
  start_second: absentWhenNull(z.number()),
  end_second: absentWhenNull(z.number()),
  source_start_second: absentWhenNull(z.number()),
  source_end_second: absentWhenNull(z.number()),
  caption_style: absentWhenNull(z.string()),
  crop_strategy: absentWhenNull(z.string()),
  format: absentWhenNull(z.enum(["vertical", "horizontal", "square"])),
  title: absentWhenNull(z.string()),
  file_size_mb: absentWhenNull(z.number()),
  duration: absentWhenNull(z.number()),
  srt_path: absentWhenNull(z.string()),
  vtt_path: absentWhenNull(z.string()),
  clean_output_path: absentWhenNull(z.string()),
  error: absentWhenNull(z.string()),
});

const progressEventSchema = z.looseObject({
  task_id: z.string(),
  stage: z.string(),
  percent: z.number(),
  message: z.string(),
  clip_result: absentWhenNull(clipResultRowSchema),
  partial: absentWhenNull(z.looseObject({})),
});

function parseResultLine<T>(stdout: string): TaskResult<T> | null {
  // The result is the last stdout line that parses to a JSON object with a
  // status field; the backend may also print stray lines.
  const lines = stdout.trim().split("\n");

  for (let i = lines.length - 1; i >= 0; i--) {
    const trimmed = lines[i].trim();

    if (!trimmed.startsWith("{")) continue;

    try {
      const parsed = resultEnvelopeSchema.safeParse(JSON.parse(trimmed));

      if (parsed.success) {
        // SAFETY: T is the data shape the caller declared for this task type, which the backend handler returns.
        return { ...parsed.data, data: parsed.data.data as T | undefined };
      }
    } catch {
      continue;
    }
  }

  return null;
}

/** The part of PythonExecutor that callers need, so a test can hand in a stand-in. */
export type TaskExecutor = Pick<PythonExecutor, "execute">;

export type ExecutorFactory = (timeoutMs?: number) => TaskExecutor;

let executorFactory: ExecutorFactory = (timeoutMs) => new PythonExecutor(timeoutMs);

/** The executor a long-lived service (the studio server) runs its backend tasks through. */
export function createExecutor(timeoutMs?: number): TaskExecutor {
  return executorFactory(timeoutMs);
}

/** Swap how createExecutor builds executors. Tests use this to keep Python out of the loop. */
export function setExecutorFactory(factory: ExecutorFactory): void {
  executorFactory = factory;
}

/**
 * Executes Python backend tasks via subprocess.
 * Communication: JSON over stdin (request) → stdout (result), stderr (progress logs).
 */
export class PythonExecutor {
  private timeoutMs: number;

  constructor(timeoutMs = 3600_000) {
    // Default 1 hour for long podcasts
    this.timeoutMs = timeoutMs;
  }

  async execute<T = object, P extends object = object>(
    taskType: TaskRequest["task_type"],
    params: P,
    onProgress?: ProgressCallback
  ): Promise<TaskResult<T>> {
    const taskId = uuidv4();

    const request: TaskRequest = {
      task_id: taskId,
      task_type: taskType,
      params,
    };

    return new Promise<TaskResult<T>>((resolve, reject) => {
      const proc = spawn(paths.pythonPath, [paths.pythonBackend], {
        stdio: ["pipe", "pipe", "pipe"],
        detached: !isWindows,
        env: pythonEnv({
          PODCLI_HOME: paths.home,
          PODCLI_DATA: paths.dataDir,
        }),
      });

      let stdout = "";
      let stderr = "";
      let settled = false;
      let timer: NodeJS.Timeout | undefined;

      const finish = (action: () => void): void => {
        if (settled) return;
        settled = true;

        if (timer) clearTimeout(timer);
        action();
      };

      proc.stdout.on("data", (chunk: Buffer) => {
        stdout += chunk.toString();
      });

      // Buffer across chunks so a progress event split over a chunk boundary
      // isn't dropped.
      let stderrBuffer = "";
      proc.stderr.on("data", (chunk: Buffer) => {
        const raw = chunk.toString();
        stderr += raw;
        stderrBuffer += raw;

        const lines = stderrBuffer.split("\n");
        stderrBuffer = lines.pop() ?? "";

        for (const line of lines) {
          const trimmed = line.trim();

          if (!trimmed || !trimmed.startsWith("{")) continue;

          try {
            const event = progressEventSchema.parse(JSON.parse(trimmed));

            if (event.task_id === taskId && onProgress) {
              onProgress(event);
            }
          } catch {
            continue;
          }
        }
      });

      proc.on("error", (err) => {
        finish(() => reject(new Error(`Failed to spawn Python process: ${err.message}`)));
      });

      // Without this, an EPIPE from a fast-crashing child becomes an unhandled
      // error that crashes the server.
      proc.stdin.on("error", () => {});

      proc.on("close", (code) => {
        finish(() => {
          const result = parseResultLine<T>(stdout);

          if (!result) {
            reject(
              new Error(
                `No parseable output from Python task. Exit code: ${code}. ` +
                  `Stdout: ${stdout.slice(-300)}. Stderr: ${stderrTail(stderr)}`
              )
            );

            return;
          }

          if (result.status === "error") {
            reject(new Error(result.error || "Unknown Python error"));

            return;
          }

          resolve(result);
        });
      });

      try {
        proc.stdin.write(JSON.stringify(request) + "\n");
        proc.stdin.end();
      } catch {}

      timer = setTimeout(() => {
        terminateProcessTree(proc);
        finish(() => reject(new Error(`Task timed out after ${this.timeoutMs / 1000}s`)));
      }, this.timeoutMs);
    });
  }
}