@1agh/maude 0.42.0 → 0.44.0

package/apps/studio/bin/_transcribe.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env bun
+// _transcribe.mjs — internal shim behind `maude design transcribe` (DDR-062).
+// Local, no-key speech-to-text for automatic subtitles: spawn whisper.cpp
+// (whisper-cli) on an audio/video file, parse its word-level JSON, and emit
+// SRT/VTT through the SHARED captions.ts reflow (the same rules the cloud STT
+// providers — ElevenLabs Scribe, Groq Whisper — run through, so local + cloud
+// subtitles never drift on line-length / timing). Runs under Bun so it can
+// import the `.ts` caption module directly (mirrors _svg-optimize.mjs).
+//
+// whisper.cpp is a SOFT dependency (plugins/design/dependencies.json): absent →
+// this exits non-zero with an actionable message (install it, or use the cloud
+// Scribe path). No dev server, no ffmpeg of our own — mirrors the footage-probe
+// shim shape.
+//
+// Model + binary resolution (whisper.cpp ships neither a default model nor
+// auto-download): `--model <path>` or $MAUDE_WHISPER_MODEL (a ggml .bin);
+// `--whisper <path>` or $MAUDE_WHISPER_CLI, else whisper-cli / whisper / main.
+//
+// Stdout (last line): the produced .srt path. Stderr: progress/diagnostics.
+// Exit: 0 ok / 1 dependency-or-input problem / 3 transcription failed.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+
+import { wordsToSrt, wordsToVtt } from '../generation/captions.ts';
+import { resolveWhisperModel } from '../generation/whisper-models.ts';
+
+/** Read `.design/config.json` → generation.transcription.whisperModel, or null
+ *  (the preferred managed model id, e.g. "base"). */
+function readConfigWhisperModel(repo) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(repo, '.design', 'config.json'), 'utf8'));
+    const m = cfg?.generation?.transcription?.whisperModel;
+    return typeof m === 'string' ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * whisper.cpp can't decode arbitrary containers (mp4/mov/m4a) unless built with
+ * ffmpeg — the owner hit this on a real clip (GOTCHA C). If the input isn't
+ * already a WAV and system ffmpeg is present, transcode to a temp 16 kHz mono
+ * WAV (whisper's native rate) and transcribe THAT. Best-effort: no ffmpeg → we
+ * pass the original through and let whisper try (with the existing hint on
+ * failure). Returns { path, cleanup } — cleanup removes the temp file (if any).
+ */
+function ensureWav(input) {
+  if (/\.wav$/i.test(input)) return { path: input, cleanup: () => {} };
+  const ffmpeg = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' });
+  if (ffmpeg.error) return { path: input, cleanup: () => {} }; // no ffmpeg → try as-is
+  // Security (ethical-hacker Finding 1): write into a FRESH 0700 private dir
+  // (mkdtemp), NOT a predictable `/tmp/maude-transcribe-<name>-<pid>.wav`. On a
+  // shared/multi-user host (Linux CI, the hub Docker image) a co-tenant could
+  // pre-plant a symlink at a guessable path and ffmpeg's `-y` would follow it
+  // and overwrite the target. An unguessable per-run dir removes the primitive.
+  const dir = mkdtempSync(join(tmpdir(), 'maude-transcribe-'));
+  const wav = join(dir, `${basename(input, extname(input))}.wav`);
+  process.stderr.write('transcribe: converting to 16 kHz mono WAV via ffmpeg…\n');
+  const conv = spawnSync(
+    'ffmpeg',
+    ['-y', '-i', input, '-ar', '16000', '-ac', '1', '-c:a', 'pcm_s16le', wav],
+    { stdio: ['ignore', 'ignore', 'inherit'] }
+  );
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  if (conv.status !== 0 || !existsSync(wav)) {
+    cleanup();
+    return { path: input, cleanup: () => {} }; // conversion failed → fall back
+  }
+  return { path: wav, cleanup };
+}
+
+/**
+ * whisper.cpp `-oj` JSON → word timings. With `-ml 1` each `transcription[]`
+ * entry is ~one word; `offsets.from/to` are milliseconds from the audio start.
+ * Pure + exported so the parsing is unit-testable without whisper installed.
+ */
+export function whisperJsonToWords(jsonText) {
+  let doc;
+  try {
+    doc = JSON.parse(jsonText);
+  } catch {
+    return [];
+  }
+  const segs = Array.isArray(doc?.transcription) ? doc.transcription : [];
+  const words = [];
+  for (const s of segs) {
+    const text = typeof s?.text === 'string' ? s.text.trim() : '';
+    if (!text) continue;
+    const from = Number(s?.offsets?.from);
+    const to = Number(s?.offsets?.to);
+    words.push({
+      text,
+      start: Number.isFinite(from) ? from / 1000 : 0,
+      end: Number.isFinite(to) ? to / 1000 : 0,
+    });
+  }
+  return words;
+}
+
+function parseArgs(argv) {
+  const out = { format: 'srt', words: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    if (a === '--source') out.source = next();
+    else if (a === '--root') out.root = next();
+    else if (a === '--out') out.out = next();
+    else if (a === '--format')
+      out.format = next(); // srt | vtt | both
+    else if (a === '--model') out.model = next();
+    else if (a === '--whisper') out.whisper = next();
+    else if (a === '--provider')
+      out.provider = next(); // whisper | elevenlabs | groq
+    else if (a === '--lang') out.lang = next();
+    else if (a === '--segments')
+      out.words = false; // segment-level, not per-word
+    else if (a === '--help' || a === '-h') out.help = true;
+  }
+  return out;
+}
+
+const CLOUD_PROVIDERS = new Set(['elevenlabs', 'groq']);
+const KNOWN_PROVIDERS = new Set(['whisper', 'elevenlabs', 'groq']);
+
+/**
+ * Resolve the transcription engine as an EXPLICIT choice (Task 2.6): the
+ * --provider flag wins; else the project's `generation.transcription.provider`
+ * config default; else `whisper` (local, free) — and we SAY which we chose.
+ * Maude never silently reaches for a paid cloud engine. Returns { provider,
+ * defaulted } where `defaulted` means neither the flag nor config set it.
+ */
+export function resolveProvider(flag, repo) {
+  if (flag) {
+    if (!KNOWN_PROVIDERS.has(flag)) {
+      process.stderr.write(
+        `transcribe: unknown --provider '${flag}' (use whisper | elevenlabs | groq)\n`
+      );
+      process.exit(2);
+    }
+    return { provider: flag, defaulted: false };
+  }
+  const configured = readConfigProvider(repo);
+  if (configured && KNOWN_PROVIDERS.has(configured))
+    return { provider: configured, defaulted: false };
+  return { provider: 'whisper', defaulted: true };
+}
+
+/** Read `.design/config.json` → generation.transcription.provider, or null. */
+function readConfigProvider(repo) {
+  try {
+    const raw = readFileSync(join(repo, '.design', 'config.json'), 'utf8');
+    const cfg = JSON.parse(raw);
+    const p = cfg?.generation?.transcription?.provider;
+    return typeof p === 'string' ? p : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveWhisper(explicit) {
+  // Security (Phase-2 ethical-hacker): do NOT include the bare name `main`
+  // (whisper.cpp's legacy binary) in the fallback chain — it is one of the most
+  // common executable names in the wild, and the probe below EXECUTES each
+  // candidate (`--help`). A user running this inside an untrusted repo with `.`
+  // on $PATH could otherwise auto-run a seeded `main`. Only the explicit
+  // --whisper / $MAUDE_WHISPER_CLI (owner's own choice) and the specific
+  // whisper-cli / whisper names are probed.
+  const candidates = [explicit, process.env.MAUDE_WHISPER_CLI, 'whisper-cli', 'whisper'].filter(
+    Boolean
+  );
+  for (const c of candidates) {
+    const probe = spawnSync(c, ['--help'], { stdio: 'ignore' });
+    if (!probe.error) return c;
+  }
+  return null;
+}
+
+/**
+ * Cloud STT path (Task 2.6): the user CHOSE elevenlabs / groq. The transcription
+ * runs on the dev server's privileged generate route (the key is resolved
+ * server-side — never handed to this CLI), which writes the SRT sidecar next to
+ * the source and returns its `assets/<sha8>.srt` path. No-silent-switch: if the
+ * server is down or the source isn't an assets/ path, we ERROR clearly naming
+ * the fix AND the local alternative — we NEVER quietly fall back to whisper.
+ */
+async function runCloud(args, repo, provider) {
+  const source = args.source;
+  if (!source.startsWith('assets/') || source.includes('..')) {
+    process.stderr.write(
+      `transcribe: cloud engine '${provider}' needs a content-addressed source (assets/<sha8>.<ext>).\n` +
+        '  Ingest the file into the project first, or use --provider whisper for an arbitrary local path.\n'
+    );
+    process.exit(2);
+  }
+  const serverPath = join(repo, '.design', '_server.json');
+  if (!existsSync(serverPath)) {
+    process.stderr.write(
+      `transcribe: cloud engine '${provider}' needs the dev server running (it resolves your key server-side).\n` +
+        '  Start it: maude design server-up   — or use --provider whisper (local, no server, no key).\n'
+    );
+    process.exit(1);
+  }
+  let port;
+  try {
+    port = JSON.parse(readFileSync(serverPath, 'utf8'))?.port;
+  } catch {
+    /* handled below */
+  }
+  if (!port) {
+    process.stderr.write(`transcribe: could not read a port from ${serverPath}\n`);
+    process.exit(1);
+  }
+
+  const base = `http://127.0.0.1:${port}/_api/generate-jobs`;
+  const body = { modality: 'transcription', provider, sourceAsset: source };
+  if (args.model) body.model = args.model;
+  if (args.lang) body.params = { language: args.lang };
+
+  process.stderr.write(`transcribe: submitting to ${provider} (cloud STT)…\n`);
+  let jobId;
+  try {
+    const res = await fetch(base, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      process.stderr.write(
+        `transcribe: ${provider} enqueue rejected: ${json?.error ?? res.status}\n`
+      );
+      process.exit(3);
+    }
+    jobId = json.jobId;
+  } catch (err) {
+    process.stderr.write(`transcribe: could not reach the dev server: ${err?.message ?? err}\n`);
+    process.exit(1);
+  }
+  if (!jobId) {
+    process.stderr.write('transcribe: enqueue returned no job id\n');
+    process.exit(3);
+  }
+
+  const deadline = Date.now() + 300_000;
+  for (;;) {
+    await new Promise((r) => setTimeout(r, 2000));
+    let job;
+    try {
+      const jobs = await (await fetch(base)).json();
+      job = Array.isArray(jobs?.jobs) ? jobs.jobs.find((j) => j.id === jobId) : null;
+    } catch {
+      /* transient — keep polling until the deadline */
+    }
+    if (job?.status === 'done') {
+      const out = job.assets?.[0];
+      if (!out) {
+        process.stderr.write('transcribe: job done but produced no caption sidecar\n');
+        process.exit(3);
+      }
+      // Chosen engine may only produce SRT; the shared reflow output is SRT. If a
+      // VTT was asked for, note that the cloud path currently writes SRT only.
+      process.stdout.write(`${out.startsWith('/') ? out.slice(1) : out}\n`);
+      return;
+    }
+    if (job?.status === 'failed') {
+      process.stderr.write(
+        `transcribe: ${provider} transcription failed: ${job.error ?? 'unknown'}\n`
+      );
+      process.exit(3);
+    }
+    if (Date.now() >= deadline) {
+      process.stderr.write(`transcribe: timed out waiting for ${provider} (job ${jobId})\n`);
+      process.exit(3);
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stderr.write(
+      'usage: maude design transcribe --source <assets/x.mp4|file> [--root <repo>]\n' +
+        '  [--provider whisper|elevenlabs|groq] [--format srt|vtt|both] [--model <id>]\n' +
+        '  [--whisper <bin>] [--lang <code>] [--segments]\n' +
+        '\n' +
+        '  The engine is an EXPLICIT choice: --provider wins, else the project\n' +
+        '  generation.transcription.provider, else local whisper (never a silent\n' +
+        '  switch to a paid cloud engine). whisper = local/free/no-key;\n' +
+        '  elevenlabs|groq = cloud (needs the dev server + a key in Settings).\n'
+    );
+    process.exit(0);
+  }
+  if (!args.source) {
+    process.stderr.write('transcribe: --source is required\n');
+    process.exit(1);
+  }
+
+  const repo = args.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  // Resolve the engine as an explicit choice (Task 2.6). A chosen cloud engine
+  // routes through the dev server (key server-side); the local default stays
+  // whisper. We NEVER auto-switch between them.
+  const { provider, defaulted } = resolveProvider(args.provider, repo);
+  if (defaulted)
+    process.stderr.write(
+      'transcribe: no engine configured — using local whisper ' +
+        '(set generation.transcription.provider or pass --provider to choose)\n'
+    );
+  if (CLOUD_PROVIDERS.has(provider)) {
+    await runCloud(args, repo, provider);
+    return;
+  }
+
+  // Resolve the input: an `assets/<name>` under the design root, or a plain path.
+  // For the assets/ form, reject `..` so the content-addressed branch can't be
+  // used to climb out of <designRoot>/assets/ (parity with api.readAssetBytes —
+  // the network Scribe path is fully contained; keep this local path close). The
+  // plain-path branch intentionally accepts an owner-named file (transcribing an
+  // arbitrary local clip is a legitimate CLI use; there is no untrusted caller).
+  if (args.source.startsWith('assets/') && args.source.includes('..')) {
+    process.stderr.write('transcribe: invalid assets/ path (no "..")\n');
+    process.exit(1);
+  }
+  const input = args.source.startsWith('assets/')
+    ? join(repo, '.design', args.source)
+    : resolve(repo, args.source);
+  if (!existsSync(input)) {
+    process.stderr.write(`transcribe: input not found: ${input}\n`);
+    process.exit(1);
+  }
+
+  const whisper = resolveWhisper(args.whisper);
+  if (!whisper) {
+    process.stderr.write(
+      'transcribe: whisper.cpp not found (whisper-cli / whisper / main).\n' +
+        '  Install: brew install whisper-cpp  (or build https://github.com/ggml-org/whisper.cpp)\n' +
+        '  Or set $MAUDE_WHISPER_CLI. For cloud STT instead, use ElevenLabs Scribe / Groq Whisper.\n'
+    );
+    process.exit(1);
+  }
+
+  // Model resolution (Task 2.7 — one-click): explicit --model / $MAUDE_WHISPER_MODEL
+  // wins; otherwise auto-resolve a model downloaded via Settings ("Download &
+  // enable"), preferring the configured `generation.transcription.whisperModel`.
+  const model =
+    args.model ||
+    process.env.MAUDE_WHISPER_MODEL ||
+    resolveWhisperModel(readConfigWhisperModel(repo));
+  if (!model || !existsSync(model)) {
+    process.stderr.write(
+      'transcribe: no whisper.cpp model available.\n' +
+        '  One-click: open Settings (⌘,) → Subtitles → "Download model" (base is a good multilingual default).\n' +
+        '  Or pass --model <ggml-*.bin> / set $MAUDE_WHISPER_MODEL, or use a cloud engine (--provider elevenlabs|groq).\n'
+    );
+    process.exit(1);
+  }
+
+  // The owner's Czech-footage gotcha: an English-only `.en` model garbles other
+  // languages. Warn (don't block — the user may know their audio is English).
+  if (/\.en\.bin$/i.test(model) && args.lang && args.lang.toLowerCase() !== 'en') {
+    process.stderr.write(
+      `transcribe: WARNING — model ${basename(model)} is English-only but --lang ${args.lang} was given; expect garbled output. Use a multilingual model (e.g. ggml-base.bin).\n`
+    );
+  }
+
+  // Transcode to a WAV whisper.cpp can always read (GOTCHA C), when needed.
+  const wav = ensureWav(input);
+
+  const outBase = args.out
+    ? args.out.replace(/\.(srt|vtt|json)$/i, '')
+    : join(dirname(input), basename(input, extname(input)));
+
+  // whisper.cpp: JSON output for the shared reflow, `-ml 1` for word-level timings.
+  const flags = ['-m', model, '-f', wav.path, '-oj', '-of', outBase];
+  if (args.words) flags.push('-ml', '1');
+  if (args.lang) flags.push('-l', args.lang);
+
+  process.stderr.write(`transcribe: running ${whisper} (${basename(model)})…\n`);
+  const run = spawnSync(whisper, flags, { stdio: ['ignore', 'inherit', 'inherit'] });
+  wav.cleanup();
+  if (run.status !== 0) {
+    process.stderr.write(
+      `transcribe: whisper.cpp exited ${run.status ?? '?'} — if the input is a non-WAV container, install ffmpeg so Maude can auto-convert it (or convert to 16 kHz mono WAV first).\n`
+    );
+    process.exit(3);
+  }
+
+  const jsonPath = `${outBase}.json`;
+  if (!existsSync(jsonPath)) {
+    process.stderr.write(`transcribe: whisper produced no JSON at ${jsonPath}\n`);
+    process.exit(3);
+  }
+  const words = whisperJsonToWords(readFileSync(jsonPath, 'utf8'));
+  if (words.length === 0) {
+    process.stderr.write('transcribe: no words recognized (silent or unsupported audio?)\n');
+    process.exit(3);
+  }
+
+  const written = [];
+  if (args.format === 'srt' || args.format === 'both') {
+    const p = `${outBase}.srt`;
+    writeFileSync(p, wordsToSrt(words));
+    written.push(p);
+  }
+  if (args.format === 'vtt' || args.format === 'both') {
+    const p = `${outBase}.vtt`;
+    writeFileSync(p, wordsToVtt(words));
+    written.push(p);
+  }
+  // Last stdout line = the primary (SRT-preferred) caption path, for $(…) capture.
+  process.stdout.write(`${written[0]}\n`);
+}
+
+// Only run main when invoked directly (import.meta.main) so the parser can be
+// imported by the test without spawning whisper (mirrors the F3 CLI-guard fix).
+if (import.meta.main) main();

package/apps/studio/bin/_transcribe.test.mjs

@@ -0,0 +1,80 @@
+// _transcribe.test.mjs — the whisper.cpp JSON → word-timings parser (Phase 2).
+// The spawn/model resolution is a soft-dep live gate; this covers the pure,
+// deterministic parsing that turns whisper.cpp `-oj` output into CaptionWords
+// (then captions.ts renders the SRT — covered in captions.test.ts).
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { wordsToSrt } from '../generation/captions.ts';
+import { resolveProvider, whisperJsonToWords } from './_transcribe.mjs';
+
+function tmpRepo(config) {
+  const root = mkdtempSync(join(tmpdir(), 'maude-transcribe-'));
+  mkdirSync(join(root, '.design'), { recursive: true });
+  if (config !== undefined)
+    writeFileSync(join(root, '.design', 'config.json'), JSON.stringify(config));
+  return root;
+}
+
+const WHISPER_JSON = JSON.stringify({
+  transcription: [
+    { offsets: { from: 0, to: 480 }, text: ' Hello' },
+    { offsets: { from: 480, to: 900 }, text: ' there.' },
+    { offsets: { from: 1200, to: 1800 }, text: ' Maude' },
+    { offsets: { from: 0, to: 0 }, text: '   ' }, // blank → dropped
+  ],
+});
+
+describe('whisperJsonToWords', () => {
+  test('maps offsets (ms) to seconds and trims text', () => {
+    const words = whisperJsonToWords(WHISPER_JSON);
+    expect(words).toHaveLength(3);
+    expect(words[0]).toEqual({ text: 'Hello', start: 0, end: 0.48 });
+    expect(words[1]).toEqual({ text: 'there.', start: 0.48, end: 0.9 });
+    expect(words[2].text).toBe('Maude');
+  });
+
+  test('feeds captions.ts to produce a valid SRT', () => {
+    const srt = wordsToSrt(whisperJsonToWords(WHISPER_JSON));
+    expect(srt).toContain('00:00:00,000 --> 00:00:00,900');
+    expect(srt).toContain('Hello there.');
+  });
+
+  test('malformed / empty JSON yields no words (never throws)', () => {
+    expect(whisperJsonToWords('not json')).toEqual([]);
+    expect(whisperJsonToWords('{}')).toEqual([]);
+    expect(whisperJsonToWords(JSON.stringify({ transcription: [] }))).toEqual([]);
+  });
+
+  test('tolerates missing offsets', () => {
+    const words = whisperJsonToWords(JSON.stringify({ transcription: [{ text: 'x' }] }));
+    expect(words).toEqual([{ text: 'x', start: 0, end: 0 }]);
+  });
+});
+
+describe('resolveProvider (Task 2.6 — explicit engine choice, no silent switch)', () => {
+  test('an explicit valid flag wins over config', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'groq' } } });
+    expect(resolveProvider('elevenlabs', repo)).toEqual({
+      provider: 'elevenlabs',
+      defaulted: false,
+    });
+  });
+
+  test('falls back to the project config default', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'groq' } } });
+    expect(resolveProvider(undefined, repo)).toEqual({ provider: 'groq', defaulted: false });
+  });
+
+  test('defaults to local whisper (marked defaulted) when nothing is set', () => {
+    const repo = tmpRepo(); // no config
+    expect(resolveProvider(undefined, repo)).toEqual({ provider: 'whisper', defaulted: true });
+  });
+
+  test('a malformed config provider is ignored → whisper default', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'bogus' } } });
+    expect(resolveProvider(undefined, repo)).toEqual({ provider: 'whisper', defaulted: true });
+  });
+});