rikrok 0.5.0

package/src/lib/render-job.mjs

@@ -0,0 +1,76 @@
+// Renders one reel. Run as a child process (under `nice -n 19` where available).
+// Usage: node src/lib/render-job.mjs <workDir>
+import fs from "node:fs";
+import path from "node:path";
+import { bundle } from "@remotion/bundler";
+import { ensureBrowser, renderMedia, selectComposition } from "@remotion/renderer";
+import { BUNDLE_DIR, REMOTION_DIR, PKG_VERSION } from "./config.mjs";
+
+const workDir = process.argv[2];
+if (!workDir) {
+  console.error("usage: node src/lib/render-job.mjs <workDir>");
+  process.exit(2);
+}
+const job = JSON.parse(fs.readFileSync(path.join(workDir, "job.json"), "utf-8"));
+fs.mkdirSync(path.dirname(job.outPath), { recursive: true });
+
+// Re-bundle only when the composition sources or the package version change.
+function sourceFingerprint() {
+  const out = [`version:${PKG_VERSION}`];
+  const walk = (dir) => {
+    for (const f of fs.readdirSync(dir)) {
+      const full = path.join(dir, f);
+      const st = fs.statSync(full);
+      if (st.isDirectory()) {
+        if (f !== "public") walk(full);
+      } else if (/\.(tsx?|css)$/.test(f)) out.push(`${path.relative(REMOTION_DIR, full)}:${st.mtimeMs}`);
+    }
+  };
+  walk(REMOTION_DIR);
+  return out.sort().join("|");
+}
+
+async function ensureBundle() {
+  const marker = path.join(BUNDLE_DIR, ".fingerprint");
+  const fp = sourceFingerprint();
+  if (fs.existsSync(marker) && fs.readFileSync(marker, "utf-8") === fp) return BUNDLE_DIR;
+  fs.rmSync(BUNDLE_DIR, { recursive: true, force: true });
+  const out = await bundle({ entryPoint: path.join(REMOTION_DIR, "index.ts"), outDir: BUNDLE_DIR, publicDir: path.join(REMOTION_DIR, "public") });
+  fs.writeFileSync(marker, fp);
+  return out;
+}
+
+// Headless Chrome: RIKROK_BROWSER points at your own binary, otherwise Remotion's
+// managed download (a few hundred MB, once) with progress on stderr.
+const browserExecutable = process.env.RIKROK_BROWSER || null;
+let lastPct = -1;
+await ensureBrowser({
+  browserExecutable,
+  onBrowserDownload: () => {
+    console.error("[render] downloading headless Chrome for rendering (one-off)...");
+    return {
+      version: null,
+      onProgress: ({ percent }) => {
+        const pct = Math.floor((percent || 0) * 10) * 10;
+        if (pct !== lastPct) {
+          lastPct = pct;
+          console.error(`[render] chrome download ${pct}%`);
+        }
+      },
+    };
+  },
+});
+
+const serveUrl = await ensureBundle();
+
+// Drop the narration into the served public dir so staticFile() finds it.
+const audioFile = `narration-${job.id}.wav`;
+fs.mkdirSync(path.join(BUNDLE_DIR, "public"), { recursive: true });
+fs.copyFileSync(job.audioPath, path.join(BUNDLE_DIR, "public", audioFile));
+
+const inputProps = { ...job.props, audioFile };
+const composition = await selectComposition({ serveUrl, id: job.composition || "Reel", inputProps, browserExecutable });
+await renderMedia({ composition, serveUrl, codec: "h264", outputLocation: job.outPath, inputProps, concurrency: 4, audioCodec: "aac", browserExecutable });
+
+fs.rmSync(path.join(BUNDLE_DIR, "public", audioFile), { force: true });
+console.log(`rendered ${job.outPath}`);

package/src/lib/script-claude.mjs

@@ -0,0 +1,48 @@
+// Script writer that uses your Claude Code subscription: a headless `claude -p` call with
+// the same system prompt and evidence the local-model path uses. No local model needed.
+// RIKROK_HOOK_SKIP=1 rides along in the environment so the SessionEnd hook ignores this session
+// and a recap can never trigger another recap.
+import { spawn } from "node:child_process";
+import { CLAUDE_BIN, CLAUDE_MODEL } from "./config.mjs";
+
+export function claudeAvailable() {
+  return new Promise((resolve) => {
+    const p = spawn(CLAUDE_BIN, ["--version"], { stdio: "ignore" });
+    p.on("error", () => resolve(false));
+    p.on("close", (code) => resolve(code === 0));
+  });
+}
+
+// messages: [{role:"system"|"user", content}] -> assistant text
+export function claudeChat(messages, { timeoutMs = 240_000 } = {}) {
+  const system = messages.filter((m) => m.role === "system").map((m) => m.content).join("\n\n");
+  const user = messages.filter((m) => m.role !== "system").map((m) => m.content).join("\n\n");
+  const args = ["-p", "--no-session-persistence", "--output-format", "json", "--model", CLAUDE_MODEL];
+  if (system) args.push("--append-system-prompt", system);
+  return new Promise((resolve, reject) => {
+    const p = spawn(CLAUDE_BIN, args, { stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, RIKROK_HOOK_SKIP: "1" } });
+    let out = "", err = "";
+    const t = setTimeout(() => {
+      p.kill("SIGKILL");
+      reject(new Error(`claude -p timed out after ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+    p.stdout.on("data", (d) => (out += d));
+    p.stderr.on("data", (d) => (err += d));
+    p.on("error", (e) => {
+      clearTimeout(t);
+      reject(new Error(`cannot run ${CLAUDE_BIN}: ${e.message}`));
+    });
+    p.on("close", (code) => {
+      clearTimeout(t);
+      if (code !== 0) return reject(new Error(`claude -p exited ${code}: ${(err || out).slice(0, 200)}`));
+      try {
+        const j = JSON.parse(out);
+        if (j.is_error) return reject(new Error(`claude: ${String(j.result).slice(0, 200)}`));
+        resolve(String(j.result ?? ""));
+      } catch {
+        resolve(out); // text fallback
+      }
+    });
+    p.stdin.end(user);
+  });
+}

package/src/lib/state.mjs

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import { STATE_FILE } from "./config.mjs";
+
+export function loadState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return { backfillDone: false, sessions: {} };
+  }
+}
+
+export function saveState(state) {
+  const tmp = STATE_FILE + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, STATE_FILE);
+}
+
+// State is keyed per source so two agents' session ids can never collide.
+export const sessionKey = (f) => `${f.source}:${f.sessionId}`;

package/src/lib/stt.mjs

@@ -0,0 +1,26 @@
+// Optional transcribe-back QA for narration via an OpenAI-compatible
+// /v1/audio/transcriptions endpoint with word timestamps. Off unless RIKROK_STT_URL is set.
+import fs from "node:fs";
+import { STT_URL, STT_MODEL, STT_KEY, authHeaders } from "./config.mjs";
+
+export const sttEnabled = () => Boolean(STT_URL);
+
+export async function transcribeWords(wavPath) {
+  if (!STT_URL) return [];
+  const fd = new FormData();
+  fd.append("file", new Blob([fs.readFileSync(wavPath)]), "audio.wav");
+  fd.append("model", STT_MODEL);
+  fd.append("response_format", "verbose_json");
+  fd.append("word_timestamps", "true");
+  try {
+    const resp = await fetch(`${STT_URL}/v1/audio/transcriptions`, { method: "POST", headers: authHeaders(STT_KEY), body: fd, signal: AbortSignal.timeout(120_000) });
+    if (!resp.ok) return [];
+    const j = await resp.json();
+    const words = [];
+    for (const seg of j.segments ?? []) for (const w of seg.words ?? []) words.push({ w: String(w.word).trim(), s: +w.start, e: +w.end });
+    for (const w of j.words ?? []) words.push({ w: String(w.word).trim(), s: +w.start, e: +w.end });
+    return words.filter((x) => x.w && Number.isFinite(x.s));
+  } catch {
+    return [];
+  }
+}

package/src/lib/watcher.mjs

@@ -0,0 +1,102 @@
+// The watcher: scans every session source (read-only), spots sessions idle for
+// IDLE_MINUTES with meaningful new work, and pushes each through the pipeline one
+// at a time. Retries with backoff when the LLM or voice server is down. First run
+// backfills the most recent qualifying sessions so the feed is never empty.
+import { ensureDirs, IDLE_MINUTES, MAX_REELS_PER_HOUR } from "./config.mjs";
+import { sources } from "../sources/index.mjs";
+import { loadState, saveState, sessionKey } from "./state.mjs";
+import { buildReel } from "./pipeline.mjs";
+import { runBackfill } from "./backfill.mjs";
+
+const SCAN_INTERVAL_MS = 60_000;
+const MAX_RETRIES = 5;
+// Sessions already idle for longer than this are backlog, not news; history is
+// the backfill's job, so the first scan never floods the feed with old sessions.
+const BACKLOG_CUTOFF_MS = 48 * 3600_000;
+
+export async function scanOnce(ctx) {
+  if (ctx.busy) return;
+  ctx.busy = true;
+  try {
+    const state = loadState();
+    if (!state.backfillDone) {
+      console.log("[watcher] first run, backfilling...");
+      await runBackfill(state);
+      state.backfillDone = true;
+      saveState(state);
+      console.log("[watcher] backfill complete");
+    }
+
+    const now = Date.now();
+    const idleCutoff = now - IDLE_MINUTES * 60_000;
+    for (const src of sources()) {
+      for (const f of src.listSessions()) {
+        if (f.mtimeMs > idleCutoff) continue; // still active
+        const key = sessionKey(f);
+        const st = state.sessions[key];
+        if (st && st.lastMtimeMs >= f.mtimeMs) continue; // this idle period already recapped
+        if (now - f.mtimeMs > BACKLOG_CUTOFF_MS) {
+          state.sessions[key] = { lastMtimeMs: f.mtimeMs, lastLine: st?.lastLine || 0, backlog: true };
+          saveState(state);
+          continue;
+        }
+        const r = ctx.retryAt.get(key);
+        if (r && now < r.nextTry) continue;
+
+        const fromLine = st?.lastLine || 0;
+        let act;
+        try {
+          act = await src.parseSession(f.path, fromLine);
+        } catch (err) {
+          console.error(`[watcher] parse failed ${key}: ${err.message}`);
+          continue;
+        }
+        if (!src.qualifies(act)) {
+          // Not meaningful: remember the mtime so we don't re-parse every scan,
+          // but keep the line offset so a later burst of real work gets recapped.
+          state.sessions[key] = { lastMtimeMs: f.mtimeMs, lastLine: fromLine, skipped: true };
+          saveState(state);
+          continue;
+        }
+
+        while (ctx.reelTimes.length && now - ctx.reelTimes[0] > 3600_000) ctx.reelTimes.shift();
+        if (ctx.reelTimes.length >= MAX_REELS_PER_HOUR) {
+          console.log(`[watcher] rate limit (${MAX_REELS_PER_HOUR}/h) reached, deferring remaining sessions`);
+          return;
+        }
+        console.log(`[watcher] recapping ${key} (lines ${fromLine}..)`);
+        ctx.reelTimes.push(now);
+        try {
+          const { totalLines } = await buildReel(f, fromLine);
+          state.sessions[key] = { lastMtimeMs: f.mtimeMs, lastLine: totalLines, lastRecapAt: new Date().toISOString() };
+          saveState(state);
+          ctx.retryAt.delete(key);
+        } catch (err) {
+          const attempts = (r?.attempts || 0) + 1;
+          const backoffMin = Math.min(60, 2 ** attempts);
+          console.error(`[watcher] reel failed for ${key} (attempt ${attempts}): ${err.message}, retry in ${backoffMin}min`);
+          if (attempts >= MAX_RETRIES) {
+            console.error(`[watcher] giving up on ${key} this idle period`);
+            state.sessions[key] = { lastMtimeMs: f.mtimeMs, lastLine: fromLine, failed: true };
+            saveState(state);
+            ctx.retryAt.delete(key);
+          } else {
+            ctx.retryAt.set(key, { attempts, nextTry: now + backoffMin * 60_000 });
+          }
+        }
+      }
+    }
+  } catch (err) {
+    console.error(`[watcher] scan error: ${err.message}`);
+  } finally {
+    ctx.busy = false;
+  }
+}
+
+export function startWatcher() {
+  ensureDirs();
+  const ctx = { busy: false, retryAt: new Map(), reelTimes: [] };
+  console.log(`[watcher] started: scanning every ${SCAN_INTERVAL_MS / 1000}s, idle bar ${IDLE_MINUTES}min, sources ${sources().map((s) => s.id).join(",")}`);
+  scanOnce(ctx);
+  return setInterval(() => scanOnce(ctx), SCAN_INTERVAL_MS);
+}

package/src/sources/claude.mjs

@@ -0,0 +1,168 @@
+// Claude Code sessions: ~/.claude/projects/<encoded cwd>/<session>.jsonl, read-only.
+// Never writes anything under that directory.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { CLAUDE_PROJECTS, MIN_ASSISTANT_TURNS, MIN_TOOL_USES, PROJECT_NAME_RE } from "../lib/config.mjs";
+
+export const id = "claude";
+
+export function listSessions() {
+  const out = [];
+  let dirs = [];
+  try {
+    dirs = fs.readdirSync(CLAUDE_PROJECTS);
+  } catch {
+    return out;
+  }
+  for (const d of dirs) {
+    const full = path.join(CLAUDE_PROJECTS, d);
+    let files;
+    try {
+      files = fs.readdirSync(full);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = path.join(full, f);
+      let st;
+      try {
+        st = fs.statSync(p);
+      } catch {
+        continue;
+      }
+      out.push({ source: id, path: p, sessionId: f.replace(/\.jsonl$/, ""), projectDir: d, mtimeMs: st.mtimeMs, size: st.size });
+    }
+  }
+  return out;
+}
+
+// Parse a session file from a given line offset into the shared Activity shape.
+export async function parseSession(filePath, fromLine = 0) {
+  const rl = readline.createInterface({ input: fs.createReadStream(filePath, { encoding: "utf-8" }), crlfDelay: Infinity });
+
+  const act = {
+    totalLines: 0,
+    fromLine,
+    assistantTurns: 0,
+    toolUses: 0,
+    firstTs: null,
+    lastTs: null,
+    activeMs: 0, // sum of inter-event gaps capped at 5 min: honest working time
+    cwd: null,
+    gitBranch: null,
+    userPrompts: [], // {ts, text}
+    assistantTexts: [], // {ts, text}
+    tools: [], // {ts, name, detail}
+    filesTouched: new Set(),
+    commands: [], // {ts, command, desc}
+    urls: new Set(), // URLs surfaced in assistant text (deploy targets, live endpoints)
+    todoSnapshots: [], // last TodoWrite payload wins
+  };
+
+  let lineNo = -1;
+  for await (const line of rl) {
+    lineNo++;
+    act.totalLines = lineNo + 1;
+    if (lineNo < fromLine) continue;
+    if (!line.trim()) continue;
+    let d;
+    try {
+      d = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const ts = d.timestamp ? Date.parse(d.timestamp) : null;
+    if (ts) {
+      if (!act.firstTs) act.firstTs = ts;
+      if (act.lastTs && ts > act.lastTs) act.activeMs += Math.min(ts - act.lastTs, 5 * 60_000);
+      act.lastTs = ts;
+    }
+    if (d.cwd) act.cwd = d.cwd;
+    if (d.gitBranch) act.gitBranch = d.gitBranch;
+    if (d.isSidechain) continue; // subagent traffic is not the story
+
+    if (d.type === "user" && d.message) {
+      const content = d.message.content;
+      let text = null;
+      if (typeof content === "string") text = content;
+      else if (Array.isArray(content)) {
+        const t = content.find((c) => c.type === "text");
+        if (t) text = t.text;
+      }
+      // Skip tool results and injected system-ish content
+      if (text && !text.startsWith("<") && d.userType !== "internal") act.userPrompts.push({ ts, text: text.slice(0, 400) });
+    } else if (d.type === "assistant" && d.message) {
+      const content = d.message.content;
+      if (!Array.isArray(content)) continue;
+      let counted = false;
+      for (const c of content) {
+        if (c.type === "text" && c.text && c.text.trim()) {
+          if (!counted) {
+            act.assistantTurns++;
+            counted = true;
+          }
+          act.assistantTexts.push({ ts, text: c.text.slice(0, 700) });
+          for (const m of c.text.matchAll(/https?:\/\/[^\s)\]>"'`]+/g)) {
+            const u = m[0].replace(/[.,;:*`]+$/, "");
+            if (!/localhost|127\.0\.0\.1|github\.com\/anthropics|docs\./.test(u)) act.urls.add(u);
+          }
+        } else if (c.type === "tool_use") {
+          if (!counted) {
+            act.assistantTurns++;
+            counted = true;
+          }
+          act.toolUses++;
+          const name = c.name || "tool";
+          const input = c.input || {};
+          let detail = "";
+          if (input.file_path) {
+            detail = input.file_path;
+            if (["Edit", "Write", "NotebookEdit", "MultiEdit"].includes(name)) act.filesTouched.add(input.file_path);
+          } else if (input.command) {
+            detail = String(input.command).slice(0, 120);
+            act.commands.push({ ts, command: detail, desc: input.description || "" });
+          } else if (input.prompt) {
+            detail = String(input.prompt).slice(0, 120);
+          } else if (Array.isArray(input.todos)) {
+            act.todoSnapshots = input.todos;
+          } else if (input.pattern) {
+            detail = input.pattern;
+          } else if (input.url) {
+            detail = input.url;
+          }
+          act.tools.push({ ts, name, detail });
+        }
+      }
+    }
+  }
+  act.filesTouched = [...act.filesTouched];
+  act.urls = [...act.urls];
+  return act;
+}
+
+export function qualifies(act) {
+  return act.assistantTurns >= MIN_ASSISTANT_TURNS && act.toolUses >= MIN_TOOL_USES;
+}
+
+// Human project name: RIKROK_PROJECT_NAME_RE capture group on the cwd if set
+// (e.g. "workspaces/([^/]+)/" for worktree layouts), else the cwd's last segment.
+export function projectName(act, projectDir) {
+  if (act.cwd) {
+    if (PROJECT_NAME_RE) {
+      try {
+        const m = act.cwd.match(new RegExp(PROJECT_NAME_RE));
+        if (m && m[1]) return m[1];
+      } catch {}
+    }
+    const parts = act.cwd.split("/").filter(Boolean);
+    return parts[parts.length - 1] || projectDir;
+  }
+  // Encoded dir name: "/" became "-". Best effort: drop the home prefix.
+  const homeEnc = os.homedir().replace(/\//g, "-");
+  return projectDir.startsWith(homeEnc) ? projectDir.slice(homeEnc.length).replace(/^-/, "") || projectDir : projectDir;
+}
+
+export const resumeHint = (sessionId) => `claude --resume ${sessionId}`;

package/src/sources/index.mjs

@@ -0,0 +1,26 @@
+// Session sources. Each module exports:
+//   id            "claude" | "codex" | ...
+//   listSessions()               -> [{ source, path, sessionId, projectDir, mtimeMs, size }]
+//   parseSession(path, fromLine) -> Activity (see claude.mjs for the shape)
+//   qualifies(act)               -> boolean
+//   projectName(act, projectDir) -> string
+//   resumeHint(sessionId)        -> string shown to humans and comment hooks
+// Enable with RIKROK_SOURCES=claude,codex (default: claude).
+import { SOURCES } from "../lib/config.mjs";
+import * as claude from "./claude.mjs";
+
+const REGISTRY = { claude };
+
+export function sourceById(id) {
+  const s = REGISTRY[id];
+  if (!s) throw new Error(`unknown session source "${id}" (known: ${Object.keys(REGISTRY).join(", ")})`);
+  return s;
+}
+
+export function sources() {
+  return SOURCES.map(sourceById);
+}
+
+export function listAllSessions() {
+  return sources().flatMap((s) => s.listSessions());
+}

package/src/voices/clone.mjs

@@ -0,0 +1,66 @@
+// Your own voice: a 15 to 20 second reference clip plus its transcript, sent with every
+// request to a local speech server that supports zero-shot cloning (oMLX with Qwen3-TTS
+// today; any server that accepts ref_audio / ref_text on /v1/audio/speech).
+// Set up with `rikrok voice setup`. Nothing is trained and nothing leaves the machine.
+import fs from "node:fs";
+import { TTS_URL, TTS_KEY, CLONE_MODEL, CLONE_REF, CLONE_TEXT, CLONE_API, authHeaders } from "../lib/config.mjs";
+
+export function cloneVoice() {
+  const refText = () => {
+    try {
+      return fs.readFileSync(CLONE_TEXT, "utf-8").trim();
+    } catch {
+      return "";
+    }
+  };
+  return {
+    name: "clone",
+    async available() {
+      if (!fs.existsSync(CLONE_REF)) return { ok: false, reason: `no reference clip at ${CLONE_REF} (run \`rikrok voice setup\`)` };
+      if (!refText()) return { ok: false, reason: `no transcript at ${CLONE_TEXT} (run \`rikrok voice setup\`)` };
+      try {
+        const r = await fetch(`${TTS_URL}/v1/models`, { headers: authHeaders(TTS_KEY), signal: AbortSignal.timeout(5000) });
+        if (!r.ok) return { ok: false, reason: `HTTP ${r.status} from ${TTS_URL}/v1/models` };
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, reason: `${TTS_URL} unreachable (${e.message})` };
+      }
+    },
+    async synth(text, outPath) {
+      try {
+        if (CLONE_API === "voice-clone") {
+          // Qwen3-TTS OpenAI FastAPI server (what `rikrok voice serve` runs): dedicated endpoint.
+          const r = await fetch(`${TTS_URL}/v1/audio/voice-clone`, {
+            method: "POST",
+            headers: { ...authHeaders(TTS_KEY), "Content-Type": "application/json" },
+            body: JSON.stringify({ input: text, ref_audio: fs.readFileSync(CLONE_REF).toString("base64"), ref_text: refText(), x_vector_only_mode: false, language: "English", response_format: "wav", speed: 1.0 }),
+            signal: AbortSignal.timeout(300_000),
+          });
+          if (!r.ok) return { ok: false, error: `HTTP ${r.status}: ${(await r.text()).slice(0, 200)}` };
+          fs.writeFileSync(outPath, Buffer.from(await r.arrayBuffer()));
+          return { ok: true };
+        }
+        const body = {
+          model: CLONE_MODEL,
+          input: text,
+          ref_audio: fs.readFileSync(CLONE_REF).toString("base64"),
+          ref_text: refText(),
+          temperature: 0.3,
+          top_p: 0.85,
+          response_format: "wav",
+        };
+        const r = await fetch(`${TTS_URL}/v1/audio/speech`, {
+          method: "POST",
+          headers: { ...authHeaders(TTS_KEY), "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(180_000),
+        });
+        if (!r.ok) return { ok: false, error: `HTTP ${r.status}: ${(await r.text()).slice(0, 200)}` };
+        fs.writeFileSync(outPath, Buffer.from(await r.arrayBuffer()));
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, error: e.message };
+      }
+    },
+  };
+}

package/src/voices/fx.mjs

@@ -0,0 +1,22 @@
+// Optional robot post-processing, in place. RIKROK_VOICE_FX = none | light | strong.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+
+export function applyFx(wavPath, level = "none") {
+  if (!level || level === "none") return;
+  const out = wavPath.replace(/\.wav$/, "_fx.wav");
+  const chain =
+    level === "strong"
+      ? [
+          "atempo=1.04",
+          "acompressor=threshold=-20dB:ratio=4:attack=5:release=90:makeup=4",
+          "asplit[a][b];[b]tremolo=f=70:d=1,volume=0.35[m];[a][m]amix=inputs=2:normalize=0",
+          "highpass=f=120",
+          "lowpass=f=6500",
+          "aecho=0.7:0.25:12:0.12",
+          "loudnorm=I=-20:TP=-1.5:LRA=8",
+        ]
+      : ["atempo=1.03", "acompressor=threshold=-18dB:ratio=3:attack=8:release=120:makeup=3", "tremolo=f=40:d=0.05", "highpass=f=100", "lowpass=f=8500", "loudnorm=I=-20:TP=-1.5:LRA=9"];
+  execFileSync("ffmpeg", ["-y", "-i", wavPath, "-af", chain.join(","), "-ar", "24000", "-ac", "1", out], { stdio: "ignore" });
+  fs.renameSync(out, wavPath);
+}

package/src/voices/index.mjs

@@ -0,0 +1,46 @@
+// Voice backends. Spec strings (RIKROK_VOICE):
+//   clone                   your own voice from a reference clip (rikrok voice setup)
+//   say:<Voice>             macOS `say` (default on a Mac)
+//   openai-speech:<voice>   any OpenAI-compatible /v1/audio/speech server
+//   module:<path>           your own module (private voice clones live here)
+//   none                    silent reel, captions only
+import { VOICE } from "../lib/config.mjs";
+import { saySpeech } from "./say.mjs";
+import { openaiSpeech } from "./openai-speech.mjs";
+import { moduleVoice } from "./module.mjs";
+import { silentVoice } from "./none.mjs";
+import { cloneVoice } from "./clone.mjs";
+
+export const VOICE_SPECS = ["clone", "say:<Voice>", "openai-speech:<voice>", "module:<path>", "none"];
+
+export async function loadVoice(spec = VOICE) {
+  if (spec === "none") return silentVoice();
+  if (spec === "clone") return cloneVoice();
+  if (spec === "say") return saySpeech();
+  if (spec.startsWith("say:")) return saySpeech(spec.slice(4));
+  if (spec === "openai-speech") return openaiSpeech();
+  if (spec.startsWith("openai-speech:")) return openaiSpeech(spec.slice("openai-speech:".length));
+  if (spec.startsWith("module:")) return moduleVoice(spec.slice(7));
+  throw new Error(`unknown voice "${spec}" (use one of: ${VOICE_SPECS.join(", ")})`);
+}
+
+// Configured voice, else macOS say, else silence. Never throws.
+export async function resolveVoice(spec = VOICE, log = console.log) {
+  const chain = [spec];
+  if (process.platform === "darwin" && !spec.startsWith("say") && spec !== "none") chain.push("say:Samantha");
+  if (spec !== "none") chain.push("none");
+  for (const s of chain) {
+    try {
+      const v = await loadVoice(s);
+      const a = await v.available();
+      if (a.ok) {
+        if (s !== spec) log(`[voice] ${spec} unavailable, using ${s}`);
+        return v;
+      }
+      log(`[voice] ${s} unavailable: ${a.reason}`);
+    } catch (e) {
+      log(`[voice] ${s} failed to load: ${e.message}`);
+    }
+  }
+  return silentVoice();
+}

package/src/voices/module.mjs

@@ -0,0 +1,18 @@
+// Bring your own voice: RIKROK_VOICE=module:/path/to/voice.mjs
+// The module's default export is { name?, available?(), synth(text, outWavPath) -> {ok, error?} }.
+// Keeps private engines (a personal voice clone, say) out of this repo entirely.
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { expandHome } from "../lib/paths.mjs";
+
+export async function moduleVoice(spec) {
+  const p = path.resolve(expandHome(spec));
+  const m = await import(pathToFileURL(p).href);
+  const v = m.default ?? m.voice ?? m;
+  if (typeof v.synth !== "function") throw new Error(`voice module ${p} must export default { synth(text, outPath) }`);
+  return {
+    name: v.name || `module:${path.basename(p)}`,
+    available: typeof v.available === "function" ? () => v.available() : async () => ({ ok: true }),
+    synth: (text, out) => v.synth(text, out),
+  };
+}

package/src/voices/none.mjs

@@ -0,0 +1,23 @@
+// Silent narration: captions carry the reel, timing comes from word count.
+// Last link of the fallback chain so a reel always ships.
+import { execFileSync } from "node:child_process";
+
+export const WORDS_PER_SECOND = 2.7;
+
+export function silentVoice() {
+  return {
+    name: "none",
+    async available() {
+      return { ok: true };
+    },
+    async synth(text, outPath) {
+      const secs = Math.max(1.2, String(text).split(/\s+/).filter(Boolean).length / WORDS_PER_SECOND);
+      try {
+        execFileSync("ffmpeg", ["-y", "-f", "lavfi", "-i", "anullsrc=r=24000:cl=mono", "-t", secs.toFixed(2), outPath], { stdio: "ignore" });
+        return { ok: true, silent: true };
+      } catch (e) {
+        return { ok: false, error: e.message };
+      }
+    },
+  };
+}