tutorial-forge 0.1.0

package/dist/pipeline/record.js

@@ -0,0 +1,176 @@
+import { join } from 'node:path';
+import { writeFile, readFile, rename } from 'node:fs/promises';
+import { chromium } from 'playwright';
+import { StepError } from '../types.js';
+import { stepId } from '../spec.js';
+import { CURSOR_INIT_SCRIPT } from '../browser/cursor.js';
+import { CALLOUT_INIT_SCRIPT } from '../browser/callout.js';
+import { RecordingClock, stepHoldUntilMs } from '../browser/timing.js';
+import { instrumentPage } from '../browser/instrument.js';
+import { ensureDir } from '../util/fs.js';
+import { logger } from '../util/logger.js';
+export const RAW_VIDEO_FILE = 'raw.webm';
+export const MANIFEST_FILE = 'manifest.json';
+const FINAL_HOLD_MS = 1000;
+const FLASH_MS = 120;
+/**
+ * Phase 2 — drive the browser through the tutorial while Playwright records
+ * video, pacing each step to its narration budget. Writes raw.webm and
+ * manifest.json into workDir.
+ */
+export async function runRecordPhase(tutorial, adapter, tts, opts) {
+    const videoDir = join(opts.workDir, 'video');
+    await ensureDir(videoDir);
+    const browser = await launchChromium(opts.headless);
+    try {
+        // Playwright's screencast captures at CSS-viewport size and pads (never
+        // scales up) when recordVideo.size is larger, so record at viewport size.
+        // deviceScaleFactor 2 still sharpens text: Chromium rasterizes at 2x and
+        // downscales into the captured frame.
+        const context = await browser.newContext({
+            viewport: opts.viewport,
+            deviceScaleFactor: 2,
+            recordVideo: { dir: videoDir, size: opts.viewport },
+        });
+        if (opts.cursor)
+            await context.addInitScript(CURSOR_INIT_SCRIPT);
+        if (opts.callouts || opts.cursor)
+            await context.addInitScript(CALLOUT_INIT_SCRIPT);
+        const page = await context.newPage();
+        const clock = new RecordingClock();
+        // Clock zero + calibration flash: paint a magenta frame the post phase
+        // can find to align the manifest clock with the video's first frame.
+        await page.goto('about:blank');
+        await page.waitForTimeout(250);
+        clock.zero();
+        await page.evaluate((ms) => {
+            document.documentElement.style.background = '#ff00ff';
+            return new Promise((resolve) => setTimeout(() => {
+                document.documentElement.style.background = '';
+                resolve();
+            }, ms));
+        }, FLASH_MS);
+        logger.info(`record: setup (${adapter.baseURL})`);
+        await adapter.setup(page);
+        const callouts = tutorial.steps.map(() => []);
+        let currentStep = 0;
+        const instrumented = instrumentPage(page, {
+            cursor: opts.cursor,
+            callouts: opts.callouts,
+            nowMs: () => clock.now(),
+            onCallout: (c) => callouts[currentStep]?.push(c),
+        });
+        const manifestSteps = [];
+        for (let i = 0; i < tutorial.steps.length; i++) {
+            currentStep = i;
+            const step = tutorial.steps[i];
+            const id = stepId(step, i);
+            const audio = tts.steps[i];
+            if (!audio || audio.id !== id) {
+                throw new Error(`tts.json is stale (step ${i}: expected "${id}", got "${audio?.id}") — re-run the tts phase`);
+            }
+            const startMs = clock.now();
+            logger.info(`record: step ${i + 1}/${tutorial.steps.length} "${id}"`);
+            await page.waitForTimeout(opts.leadInMs);
+            const actionStartMs = clock.now();
+            try {
+                await step.run(instrumented);
+                await step.waitFor?.(instrumented);
+            }
+            catch (cause) {
+                await captureFailure(page, opts.workDir, id);
+                await saveManifest(tutorial, clock, manifestSteps, opts.workDir);
+                await safeClose(context.close());
+                throw new StepError(tutorial.id, id, cause);
+            }
+            const actionEndMs = clock.now();
+            const holdUntil = stepHoldUntilMs({
+                startMs,
+                leadInMs: opts.leadInMs,
+                audioDurationMs: audio.audioDurationMs,
+                actionEndMs,
+                settleMs: step.settleMs ?? 400,
+            });
+            const remaining = holdUntil - clock.now();
+            if (remaining > 0)
+                await page.waitForTimeout(remaining);
+            manifestSteps.push({
+                id,
+                narration: step.narration,
+                audioFile: audio.audioFile,
+                audioDurationMs: audio.audioDurationMs,
+                startMs,
+                actionStartMs,
+                actionEndMs,
+                endMs: clock.now(),
+                callouts: callouts[i],
+            });
+        }
+        await page.waitForTimeout(FINAL_HOLD_MS);
+        const manifest = await saveManifest(tutorial, clock, manifestSteps, opts.workDir);
+        if (adapter.teardown) {
+            try {
+                await adapter.teardown(page);
+            }
+            catch (err) {
+                logger.warn(`teardown failed (ignored): ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        const video = page.video();
+        await context.close(); // flushes the webm
+        if (!video)
+            throw new Error('Playwright returned no video — recordVideo was not active');
+        await rename(await video.path(), join(opts.workDir, RAW_VIDEO_FILE));
+        return manifest;
+    }
+    finally {
+        await safeClose(browser.close());
+    }
+}
+async function launchChromium(headless) {
+    try {
+        return await chromium.launch({ headless, channel: 'chromium' });
+    }
+    catch {
+        // 'chromium' channel (new headless) not installed; default build works too.
+        return chromium.launch({ headless });
+    }
+}
+async function saveManifest(tutorial, clock, steps, workDir) {
+    const manifest = {
+        tutorialId: tutorial.id,
+        fps: 25,
+        recordingStartEpochMs: clock.zeroEpoch,
+        steps,
+        totalDurationMs: clock.now(),
+    };
+    await writeFile(join(workDir, MANIFEST_FILE), JSON.stringify(manifest, null, 2));
+    return manifest;
+}
+async function captureFailure(page, workDir, id) {
+    try {
+        await page.screenshot({ path: join(workDir, `failure-${id}.png`) });
+        logger.error(`record: step "${id}" failed — screenshot at ${join(workDir, `failure-${id}.png`)}`);
+    }
+    catch {
+        /* page may already be unusable */
+    }
+}
+async function safeClose(p) {
+    try {
+        await p;
+    }
+    catch {
+        /* already closed */
+    }
+}
+/** Load a previous run's manifest.json (for `--phase post`). */
+export async function loadManifest(workDir) {
+    try {
+        return JSON.parse(await readFile(join(workDir, MANIFEST_FILE), 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`No ${MANIFEST_FILE} in ${workDir} — run the record phase first (cause: ${err instanceof Error ? err.message : err})`);
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/pipeline/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/pipeline/record.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/render.d.ts

@@ -0,0 +1,12 @@
+import type { RenderOptions, TimingManifest, Tutorial, TutorialAdapter } from '../types.js';
+import { type PostPhaseResult } from './post.js';
+export interface RenderResult extends PostPhaseResult {
+    manifest: TimingManifest;
+    workDir: string;
+}
+/**
+ * Run the full pipeline (or a single phase) for one tutorial.
+ * Phases: tts → record → post. The work directory is kept on failure
+ * (and on success with keepWorkDir: true) so every stage is inspectable.
+ */
+export declare function render(tutorial: Tutorial, adapter: TutorialAdapter, options: RenderOptions): Promise<RenderResult>;

package/dist/pipeline/render.js

@@ -0,0 +1,91 @@
+import { resolve, join } from 'node:path';
+import { validateTutorial } from '../spec.js';
+import { runTTSPhase, loadTTSResult } from './tts.js';
+import { runRecordPhase, loadManifest } from './record.js';
+import { runPostPhase } from './post.js';
+import { defaultCacheDir } from '../tts/cache.js';
+import { ensureDir, removeDir } from '../util/fs.js';
+import { logger } from '../util/logger.js';
+/**
+ * Run the full pipeline (or a single phase) for one tutorial.
+ * Phases: tts → record → post. The work directory is kept on failure
+ * (and on success with keepWorkDir: true) so every stage is inspectable.
+ */
+export async function render(tutorial, adapter, options) {
+    validateTutorial(tutorial);
+    const workDir = resolve(options.workDir ?? join('.forge', tutorial.id));
+    const output = resolve(options.output);
+    const viewport = options.viewport ?? { width: 1920, height: 1080 };
+    const leadInMs = options.leadInMs ?? 300;
+    const phase = options.phase ?? 'all';
+    await ensureDir(workDir);
+    try {
+        const tts = phase === 'all' || phase === 'tts'
+            ? await runTTSPhase(tutorial, {
+                provider: options.tts,
+                workDir,
+                cacheDir: options.ttsCacheDir ?? defaultCacheDir(),
+                concurrency: options.ttsConcurrency ?? 4,
+            })
+            : await loadTTSResult(workDir);
+        if (phase === 'tts') {
+            return partialResult(workDir, output, await safeLoadManifest(workDir, tutorial));
+        }
+        const manifest = phase === 'all' || phase === 'record'
+            ? await runRecordPhase(tutorial, adapter, tts, {
+                workDir,
+                viewport,
+                headless: options.headless ?? true,
+                cursor: options.cursor ?? true,
+                callouts: options.callouts ?? true,
+                leadInMs,
+            })
+            : await loadManifest(workDir);
+        if (phase === 'record') {
+            return partialResult(workDir, output, manifest);
+        }
+        const post = await runPostPhase(manifest, {
+            workDir,
+            output,
+            viewport,
+            subtitles: options.subtitles ?? 'sidecar',
+            leadInMs,
+        });
+        if (!(options.keepWorkDir ?? false)) {
+            await removeDir(workDir);
+        }
+        else {
+            logger.info(`work dir kept at ${workDir}`);
+        }
+        return { ...post, manifest, workDir };
+    }
+    catch (err) {
+        logger.error(`render failed — work dir kept at ${workDir}`);
+        throw err;
+    }
+}
+async function safeLoadManifest(workDir, tutorial) {
+    try {
+        return await loadManifest(workDir);
+    }
+    catch {
+        return {
+            tutorialId: tutorial.id,
+            fps: 25,
+            recordingStartEpochMs: 0,
+            steps: [],
+            totalDurationMs: 0,
+        };
+    }
+}
+function partialResult(workDir, output, manifest) {
+    return {
+        output,
+        srtPath: null,
+        videoClockOffsetMs: manifest.videoClockOffsetMs ?? 0,
+        outputDurationMs: 0,
+        manifest,
+        workDir,
+    };
+}
+//# sourceMappingURL=render.js.map

package/dist/pipeline/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/pipeline/render.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/tts.d.ts

@@ -0,0 +1,23 @@
+import type { TTSProvider, Tutorial } from '../types.js';
+export interface TTSPhaseResult {
+    /** Per step, in step order. Null audioFile / 0 duration for silent steps. */
+    steps: Array<{
+        id: string;
+        narration: string;
+        audioFile: string | null;
+        audioDurationMs: number;
+    }>;
+}
+/**
+ * Phase 1 — synthesize + measure every narration line. No browser dependency;
+ * bounded concurrency. Result is persisted to workDir/tts.json so the record
+ * phase can re-run without re-synthesizing.
+ */
+export declare function runTTSPhase(tutorial: Tutorial, opts: {
+    provider: TTSProvider;
+    workDir: string;
+    cacheDir: string;
+    concurrency: number;
+}): Promise<TTSPhaseResult>;
+/** Load a previous run's tts.json (for `--phase record`/`--phase post`). */
+export declare function loadTTSResult(workDir: string): Promise<TTSPhaseResult>;

package/dist/pipeline/tts.js

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { writeFile, readFile } from 'node:fs/promises';
+import { stepId } from '../spec.js';
+import { synthesizeCached } from '../tts/cache.js';
+import { probeDurationMs } from '../post/ffmpeg.js';
+import { ensureDir, mapLimit } from '../util/fs.js';
+import { logger } from '../util/logger.js';
+const TTS_RESULT_FILE = 'tts.json';
+/**
+ * Phase 1 — synthesize + measure every narration line. No browser dependency;
+ * bounded concurrency. Result is persisted to workDir/tts.json so the record
+ * phase can re-run without re-synthesizing.
+ */
+export async function runTTSPhase(tutorial, opts) {
+    const audioDir = join(opts.workDir, 'audio');
+    await ensureDir(audioDir);
+    const steps = await mapLimit(tutorial.steps, opts.concurrency, async (step, i) => {
+        const id = stepId(step, i);
+        if (!step.narration.trim()) {
+            return { id, narration: step.narration, audioFile: null, audioDurationMs: 0 };
+        }
+        const audioFile = join(audioDir, `step-${id}.wav`);
+        await synthesizeCached(opts.provider, step.narration, audioFile, opts.cacheDir);
+        const audioDurationMs = await probeDurationMs(audioFile);
+        return { id, narration: step.narration, audioFile, audioDurationMs };
+    });
+    const result = { steps };
+    await writeFile(join(opts.workDir, TTS_RESULT_FILE), JSON.stringify(result, null, 2));
+    logger.info(`tts: ${steps.filter((s) => s.audioFile).length} narrated step(s), ` +
+        `${Math.round(steps.reduce((a, s) => a + s.audioDurationMs, 0) / 1000)}s of narration`);
+    return result;
+}
+/** Load a previous run's tts.json (for `--phase record`/`--phase post`). */
+export async function loadTTSResult(workDir) {
+    try {
+        return JSON.parse(await readFile(join(workDir, TTS_RESULT_FILE), 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`No ${TTS_RESULT_FILE} in ${workDir} — run the tts phase first (cause: ${err instanceof Error ? err.message : err})`);
+    }
+}
+//# sourceMappingURL=tts.js.map

package/dist/pipeline/tts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.js","sourceRoot":"","sources":["../../src/pipeline/tts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAO3C,MAAM,eAAe,GAAG,UAAU,CAAC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAkB,EAClB,IAAuF;IAEvF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE;QAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3B,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;QAChF,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChF,MAAM,eAAe,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAmB,EAAE,KAAK,EAAE,CAAC;IACzC,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACtF,MAAM,CAAC,IAAI,CACT,QAAQ,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,qBAAqB;QAClE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,gBAAgB,CACzF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAmB,CAAC;IAC9F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,MAAM,eAAe,OAAO,OAAO,sCAAsC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CACrH,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/post/ffmpeg.d.ts

@@ -0,0 +1,53 @@
+import type { TimingManifest } from '../types.js';
+export declare class FfmpegError extends Error {
+    readonly stderr: string;
+    constructor(cmd: string, stderr: string);
+}
+export declare function ffmpegVersion(bin?: 'ffmpeg' | 'ffprobe'): Promise<string | null>;
+/** Exact media duration in milliseconds, via ffprobe. */
+export declare function probeDurationMs(file: string): Promise<number>;
+/** Re-encode any audio file to 48kHz mono 16-bit WAV. */
+export declare function normalizeToWav(input: string, output: string): Promise<void>;
+/**
+ * Find the calibration flash (a solid magenta frame painted at clock zero) in
+ * the first seconds of the raw recording. Returns the offset in ms from the
+ * start of the video file to the first flash frame, or null if not found.
+ *
+ * Uses the signalstats filter: magenta has extreme U and V averages
+ * (both near max), which never occurs in normal page content.
+ */
+export declare function detectFlashOffsetMs(video: string, scanSeconds?: number): Promise<number | null>;
+/**
+ * Parse signalstats metadata=print output. Frames arrive as
+ *   frame:N pts:P pts_time:T
+ *   lavfi.signalstats.UAVG=...
+ *   lavfi.signalstats.VAVG=...
+ * A full-frame magenta (#ff00ff) flash measures UAVG≈201 / VAVG≈221 in
+ * Chromium's VP8 webm; we accept anything with both chroma averages far from
+ * neutral (128) in the magenta direction.
+ */
+export declare function parseFlashFromMetadata(out: string): number | null;
+export interface MergeArgsInput {
+    rawVideo: string;
+    manifest: TimingManifest;
+    /** Resolved absolute audio file per narrated step, in step order (nulls for silent steps). */
+    audioFiles: Array<string | null>;
+    output: string;
+    leadInMs: number;
+    /** ms on the manifest clock where step playback starts (pre-roll trim point). */
+    trimStartMs: number;
+    /** ms into the raw video where the manifest clock's zero falls (calibration flash). */
+    videoOffsetMs: number;
+    /** Scale to this size in post (recording runs at deviceScaleFactor 2). */
+    targetWidth: number;
+    targetHeight: number;
+    /** Burn this .srt into the video, if set. */
+    burnSrt?: string;
+}
+/**
+ * Build the single-invocation ffmpeg arg list that trims pre-roll, lays each
+ * narration clip at its manifest offset over silence, downscales, and
+ * transcodes to H.264/AAC. Pure function: tested by asserting on args.
+ */
+export declare function buildMergeArgs(input: MergeArgsInput): string[];
+export declare function runFfmpeg(args: string[]): Promise<void>;

package/dist/post/ffmpeg.js

@@ -0,0 +1,162 @@
+import { execa } from 'execa';
+import { logger } from '../util/logger.js';
+export class FfmpegError extends Error {
+    stderr;
+    constructor(cmd, stderr) {
+        super(`${cmd} failed:\n${stderr.split('\n').slice(-12).join('\n')}`);
+        this.stderr = stderr;
+        this.name = 'FfmpegError';
+    }
+}
+async function run(bin, args) {
+    logger.debug(`${bin} ${args.join(' ')}`);
+    try {
+        const { stdout } = await execa(bin, args);
+        return stdout;
+    }
+    catch (err) {
+        const stderr = err.stderr ?? String(err);
+        throw new FfmpegError(bin, stderr);
+    }
+}
+export async function ffmpegVersion(bin = 'ffmpeg') {
+    try {
+        const { stdout } = await execa(bin, ['-version']);
+        return /version\s+(\S+)/.exec(stdout)?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Exact media duration in milliseconds, via ffprobe. */
+export async function probeDurationMs(file) {
+    const out = await run('ffprobe', [
+        '-v', 'error',
+        '-show_entries', 'format=duration',
+        '-of', 'default=noprint_wrappers=1:nokey=1',
+        file,
+    ]);
+    const seconds = parseFloat(out.trim());
+    if (!Number.isFinite(seconds))
+        throw new Error(`ffprobe returned no duration for ${file}`);
+    return Math.round(seconds * 1000);
+}
+/** Re-encode any audio file to 48kHz mono 16-bit WAV. */
+export async function normalizeToWav(input, output) {
+    // -f wav: output may land at a temp path without a .wav extension.
+    await run('ffmpeg', ['-y', '-i', input, '-ar', '48000', '-ac', '1', '-c:a', 'pcm_s16le', '-f', 'wav', output]);
+}
+/**
+ * Find the calibration flash (a solid magenta frame painted at clock zero) in
+ * the first seconds of the raw recording. Returns the offset in ms from the
+ * start of the video file to the first flash frame, or null if not found.
+ *
+ * Uses the signalstats filter: magenta has extreme U and V averages
+ * (both near max), which never occurs in normal page content.
+ */
+export async function detectFlashOffsetMs(video, scanSeconds = 4) {
+    try {
+        const { stdout } = await execa('ffmpeg', [
+            '-t', String(scanSeconds),
+            '-i', video,
+            '-vf', 'signalstats,metadata=print:file=-',
+            '-f', 'null', '-',
+        ]);
+        return parseFlashFromMetadata(stdout);
+    }
+    catch (err) {
+        logger.warn(`flash detection failed: ${err instanceof Error ? err.message : err}`);
+        return null;
+    }
+}
+/**
+ * Parse signalstats metadata=print output. Frames arrive as
+ *   frame:N pts:P pts_time:T
+ *   lavfi.signalstats.UAVG=...
+ *   lavfi.signalstats.VAVG=...
+ * A full-frame magenta (#ff00ff) flash measures UAVG≈201 / VAVG≈221 in
+ * Chromium's VP8 webm; we accept anything with both chroma averages far from
+ * neutral (128) in the magenta direction.
+ */
+export function parseFlashFromMetadata(out) {
+    let ptsTime = null;
+    let uavg = null;
+    let vavg = null;
+    for (const line of out.split('\n')) {
+        const frame = /pts_time:([\d.]+)/.exec(line);
+        if (frame) {
+            ptsTime = parseFloat(frame[1]);
+            uavg = vavg = null;
+            continue;
+        }
+        const u = /lavfi\.signalstats\.UAVG=([\d.]+)/.exec(line);
+        if (u)
+            uavg = parseFloat(u[1]);
+        const v = /lavfi\.signalstats\.VAVG=([\d.]+)/.exec(line);
+        if (v)
+            vavg = parseFloat(v[1]);
+        if (ptsTime !== null && uavg !== null && vavg !== null) {
+            if (uavg > 180 && vavg > 170)
+                return Math.round(ptsTime * 1000);
+            uavg = vavg = null;
+        }
+    }
+    return null;
+}
+/**
+ * Build the single-invocation ffmpeg arg list that trims pre-roll, lays each
+ * narration clip at its manifest offset over silence, downscales, and
+ * transcodes to H.264/AAC. Pure function: tested by asserting on args.
+ */
+export function buildMergeArgs(input) {
+    const { manifest, audioFiles, leadInMs, trimStartMs, videoOffsetMs } = input;
+    const args = ['-y', '-i', input.rawVideo];
+    const narrated = [];
+    manifest.steps.forEach((s, i) => {
+        const file = audioFiles[i];
+        if (!file)
+            return;
+        args.push('-i', file);
+        // Audio offsets are relative to the *trimmed* video start.
+        const delayMs = Math.max(0, s.startMs + leadInMs - trimStartMs);
+        narrated.push({ inputIndex: narrated.length + 1, delayMs });
+    });
+    const filters = [];
+    const durationS = ((manifest.totalDurationMs - trimStartMs) / 1000).toFixed(3);
+    // Video chain: trim pre-roll + post-tutorial tail (manifest clock shifted
+    // into video time by the flash offset), reset timestamps, downscale.
+    const videoTrimStartS = ((trimStartMs + videoOffsetMs) / 1000).toFixed(3);
+    const videoTrimEndS = ((manifest.totalDurationMs + videoOffsetMs) / 1000).toFixed(3);
+    const vf = [
+        `trim=start=${videoTrimStartS}:end=${videoTrimEndS}`,
+        'setpts=PTS-STARTPTS',
+    ];
+    vf.push(`scale=${input.targetWidth}:${input.targetHeight}:flags=lanczos`);
+    if (input.burnSrt) {
+        vf.push(`subtitles=${escapeFilterPath(input.burnSrt)}`);
+    }
+    filters.push(`[0:v]${vf.join(',')}[vout]`);
+    // Audio chain: silence base + each clip delayed to its slot, mixed.
+    filters.push(`anullsrc=channel_layout=mono:sample_rate=48000,atrim=duration=${durationS}[abase]`);
+    const mixInputs = ['[abase]'];
+    narrated.forEach(({ inputIndex, delayMs }, n) => {
+        filters.push(`[${inputIndex}:a]adelay=${delayMs}:all=1[a${n}]`);
+        mixInputs.push(`[a${n}]`);
+    });
+    if (narrated.length > 0) {
+        filters.push(`${mixInputs.join('')}amix=inputs=${mixInputs.length}:duration=first:normalize=0[aout]`);
+    }
+    else {
+        filters.push('[abase]acopy[aout]');
+    }
+    args.push('-filter_complex', filters.join(';'), '-map', '[vout]', '-map', '[aout]', '-c:v', 'libx264', '-crf', '18', '-preset', 'slow', '-pix_fmt', 'yuv420p', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', input.output);
+    return args;
+}
+/** ffmpeg filter args need ':' and '\' escaped inside path values. */
+function escapeFilterPath(p) {
+    return `'${p.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/:/g, '\\:')}'`;
+}
+export async function runFfmpeg(args) {
+    await run('ffmpeg', args);
+}
+//# sourceMappingURL=ffmpeg.js.map

package/dist/post/ffmpeg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/post/ffmpeg.ts"],"names":[],"mappings":"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"}

package/dist/post/subtitles.d.ts

@@ -0,0 +1,14 @@
+import type { TimingManifest } from '../types.js';
+/**
+ * One SRT cue per narrated step: text = narration, range = narration playback
+ * window. Cue times are relative to the trimmed video, so trimStartMs (manifest
+ * clock) is subtracted.
+ */
+export declare function generateSrt(manifest: TimingManifest, opts: {
+    leadInMs: number;
+    trimStartMs: number;
+    maxLineChars?: number;
+}): string;
+export declare function srtTime(ms: number): string;
+/** Greedy word wrap at ~max chars/line. */
+export declare function wrapText(text: string, max: number): string;