@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/tools/video/scene-render.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Scene render — turns one planned scene into a premium 1080p clip: a framed
+ * visual (rounded corners + drop shadow on a gradient) or an animated text card,
+ * with a slow Ken Burns push, a cinematic vignette, burned karaoke captions and
+ * the scene's narration muxed in. This is the "wow" recipe, native (spawn ffmpeg
+ * + optional ImageMagick `convert`), fail-open, argv-testable — the productized
+ * form of the earlier build_wow.py prototype.
+ *
+ * @module tools/video/scene-render
+ */
+import { spawn as realSpawn } from 'child_process';
+export interface RenderSceneInput {
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** Narration text (for captions). */
+    narrationText?: string;
+    /** Synthesized narration WAV to mux (from narration.ts). */
+    narrationWav?: string;
+    /** Final clip duration in seconds. */
+    duration: number;
+    /** 'image' → framed still (imagePath required); else an animated text card. */
+    visual: {
+        kind: 'text' | 'image';
+        imagePath?: string;
+    };
+    /** Gradient endpoints (hex like '#0f2027') for text cards / framing backdrop. */
+    c0?: string;
+    c1?: string;
+    outPath: string;
+    width?: number;
+    height?: number;
+    /** Silence before the narration inside the clip (default 0.6). */
+    lead?: number;
+    /** Burn karaoke captions (default true when there's narration text). */
+    subtitles?: boolean;
+}
+export interface RenderSceneDeps {
+    spawn?: typeof realSpawn;
+    ffmpegBin?: string;
+    ffprobeBin?: string;
+    convertBin?: string;
+    identifyBin?: string;
+    /** Working dir for intermediate stills / ass (default: alongside outPath). */
+    workDir?: string;
+    /** Force-disable ImageMagick (tests / degraded mode). */
+    noImageMagick?: boolean;
+}
+/** Escape a filename for the ffmpeg `subtitles=` filter value. */
+export declare function escapeSubtitlesPath(p: string): string;
+/**
+ * The ffmpeg argv for a scene clip: Ken Burns + vignette + optional burned
+ * captions on the still, with the narration delayed/padded to fill the clip.
+ * Pure — the main test seam.
+ */
+export declare function buildSceneVideoArgs(opts: {
+    ffmpegBin: string;
+    still: string;
+    outPath: string;
+    duration: number;
+    width: number;
+    height: number;
+    narrationWav?: string;
+    assPath?: string;
+    lead: number;
+}): string[];
+/** ImageMagick argv for a centered "hero" text card on a gradient (pure). */
+export declare function buildHeroCardArgs(opts: {
+    width: number;
+    height: number;
+    c0: string;
+    c1: string;
+    title: string;
+    subtitle?: string;
+    outPath: string;
+    big: boolean;
+}): string[];
+/** ffmpeg fallback argv to make a still (gradient + title via textfile) when ImageMagick is absent (pure). */
+export declare function buildFallbackStillArgs(opts: {
+    ffmpegBin: string;
+    width: number;
+    height: number;
+    c0: string;
+    c1: string;
+    titleFile: string;
+    outPath: string;
+}): string[];
+/** Title-band + image-box geometry for a framed still (pure, unit-tested). */
+export declare function computeFramedLayout(w: number, h: number, hasSubtitle: boolean): {
+    side: number;
+    titleZone: number;
+    captionZone: number;
+    imgBoxW: number;
+    imgBoxH: number;
+    brandSize: number;
+    titleSize: number;
+    subSize: number;
+    tx: number;
+    brandY: number;
+    titleY: number;
+    subtitleY: number;
+};
+export interface RenderSceneResult {
+    ok: boolean;
+    outPath: string;
+    error?: string;
+}
+export declare function renderScene(input: RenderSceneInput, deps?: RenderSceneDeps): Promise<RenderSceneResult>;

package/dist/tools/video/scene-render.js

@@ -0,0 +1,418 @@
+/**
+ * Scene render — turns one planned scene into a premium 1080p clip: a framed
+ * visual (rounded corners + drop shadow on a gradient) or an animated text card,
+ * with a slow Ken Burns push, a cinematic vignette, burned karaoke captions and
+ * the scene's narration muxed in. This is the "wow" recipe, native (spawn ffmpeg
+ * + optional ImageMagick `convert`), fail-open, argv-testable — the productized
+ * form of the earlier build_wow.py prototype.
+ *
+ * @module tools/video/scene-render
+ */
+import { spawn as realSpawn } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+import { logger } from '../../utils/logger.js';
+import { buildKaraokeAss } from './subtitles.js';
+const FB = '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf';
+const FR = '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf';
+// ============================================================================
+// Pure argv builders (unit-tested)
+// ============================================================================
+/** Escape a filename for the ffmpeg `subtitles=` filter value. */
+export function escapeSubtitlesPath(p) {
+    return p.replace(/\\/g, '\\\\').replace(/:/g, '\\:').replace(/'/g, "\\'");
+}
+/**
+ * The ffmpeg argv for a scene clip: Ken Burns + vignette + optional burned
+ * captions on the still, with the narration delayed/padded to fill the clip.
+ * Pure — the main test seam.
+ */
+export function buildSceneVideoArgs(opts) {
+    const { width: w, height: h, duration: D } = opts;
+    const vfParts = [
+        `zoompan=z='min(zoom+0.00035,1.06)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${w}x${h}:fps=30`,
+        'vignette=PI/4.5',
+    ];
+    if (opts.assPath)
+        vfParts.push(`subtitles=${escapeSubtitlesPath(opts.assPath)}`);
+    vfParts.push(`fade=t=in:st=0:d=0.4`, `fade=t=out:st=${round2(D - 0.5)}:d=0.5`, 'format=yuv420p');
+    const vf = vfParts.join(',');
+    const args = ['-y', '-hide_banner', '-loglevel', 'error', '-loop', '1', '-i', opts.still];
+    if (opts.narrationWav)
+        args.push('-i', opts.narrationWav);
+    const filter = opts.narrationWav
+        ? `[0:v]${vf}[v];[1:a]adelay=${Math.round(opts.lead * 1000)}:all=1,` +
+            `aformat=sample_rates=48000:channel_layouts=stereo,apad,atrim=0:${round2(D)}[a]`
+        : `[0:v]${vf}[v]`;
+    args.push('-filter_complex', filter, '-map', '[v]');
+    if (opts.narrationWav)
+        args.push('-map', '[a]');
+    args.push('-t', String(round2(D)), '-r', '30', '-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-pix_fmt', 'yuv420p');
+    if (opts.narrationWav)
+        args.push('-c:a', 'aac', '-b:a', '192k');
+    args.push(opts.outPath);
+    return args;
+}
+/** ImageMagick argv for a centered "hero" text card on a gradient (pure). */
+export function buildHeroCardArgs(opts) {
+    // Scale text with the frame so a vertical (9:16) card reads as well as a wide one.
+    const w = opts.width;
+    const h = opts.height;
+    const titleSize = Math.round(w * (opts.big ? 0.068 : 0.045));
+    const subSize = Math.round(w * (opts.big ? 0.024 : 0.02));
+    const titleY = -Math.round(h * 0.037);
+    const subY = Math.round(h * 0.065);
+    const args = [
+        '-size',
+        `${w}x${h}`,
+        '-define',
+        'gradient:angle=135',
+        `gradient:${opts.c0}-${opts.c1}`,
+        '-gravity',
+        'center',
+        '-font',
+        FB,
+        '-pointsize',
+        String(titleSize),
+        '-fill',
+        'white',
+        '-annotate',
+        `+0${titleY}`,
+        opts.title,
+    ];
+    if (opts.subtitle) {
+        args.push('-font', FR, '-pointsize', String(subSize), '-fill', '#e6ecff', '-annotate', `+0+${subY}`, opts.subtitle);
+    }
+    args.push(opts.outPath);
+    return args;
+}
+/** ffmpeg fallback argv to make a still (gradient + title via textfile) when ImageMagick is absent (pure). */
+export function buildFallbackStillArgs(opts) {
+    const { width: w, height: h } = opts;
+    const vf = `gradients=s=${w}x${h}:c0=0x${hex(opts.c0)}:c1=0x${hex(opts.c1)}:x0=0:y0=0:x1=${w}:y1=${h}:nb_colors=2,` +
+        `drawtext=fontfile=${FB}:textfile=${opts.titleFile}:fontcolor=white:fontsize=76:x=(w-text_w)/2:y=(h-text_h)/2:` +
+        `shadowcolor=black@0.5:shadowx=3:shadowy=3`;
+    return [
+        '-y',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-f',
+        'lavfi',
+        '-i',
+        `color=black:s=${w}x${h}`,
+        '-vf',
+        vf,
+        '-frames:v',
+        '1',
+        opts.outPath,
+    ];
+}
+function hex(c) {
+    return c.replace(/^#/, '').replace(/^0x/i, '');
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Title-band + image-box geometry for a framed still (pure, unit-tested). */
+export function computeFramedLayout(w, h, hasSubtitle) {
+    const side = Math.round(w * 0.06);
+    // Keep the title + subtitle in the reserved band. 0.14*h was too small on
+    // 9:16: the subtitle baseline sat *below* the diagram (GK4 scene 2).
+    const titleZone = Math.round(h * (hasSubtitle ? 0.2 : 0.14));
+    const captionZone = Math.round(h * 0.14);
+    return {
+        side,
+        titleZone,
+        captionZone,
+        imgBoxW: w - 2 * side,
+        imgBoxH: Math.max(120, h - titleZone - captionZone),
+        brandSize: Math.round(h * 0.028),
+        titleSize: Math.round(h * 0.05),
+        subSize: Math.round(h * 0.028),
+        tx: Math.round(w * 0.048),
+        brandY: Math.round(h * 0.05),
+        titleY: Math.round(h * 0.092),
+        subtitleY: Math.round(h * 0.152),
+    };
+}
+// ============================================================================
+// Spawn helpers (injectable)
+// ============================================================================
+function run(spawn, cmd, args, timeoutMs = 5 * 60 * 1000) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        let child;
+        try {
+            child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch (err) {
+            finish({ code: null, stdout: '', stderr: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* gone */
+            }
+            finish({ code: null, stdout, stderr: `${stderr}\n[timeout]` });
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => (stdout = `${stdout}${String(d)}`.slice(-200_000)));
+        child.stderr?.on('data', (d) => (stderr = `${stderr}${String(d)}`.slice(-200_000)));
+        child.on('error', (err) => finish({ code: null, stdout, stderr: `${stderr}${err.message}` }));
+        child.on('close', (code) => finish({ code, stdout, stderr }));
+    });
+}
+async function hasBinary(spawn, bin) {
+    const { code } = await run(spawn, bin, ['-version'], 10_000);
+    return code === 0;
+}
+async function verifyVideoArtifact(spawn, ffprobeBin, file) {
+    try {
+        const metadata = await fs.lstat(file);
+        if (!metadata.isFile() || metadata.size <= 0)
+            return false;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            logger.warn(`[scene-render] could not inspect ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return false;
+    }
+    const probe = await run(spawn, ffprobeBin, ['-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', file], 30_000);
+    if (probe.code !== 0)
+        return false;
+    try {
+        const json = JSON.parse(probe.stdout);
+        const duration = json.format?.duration ? Number(json.format.duration) : NaN;
+        return Number.isFinite(duration) && duration > 0 && !!json.streams?.some((s) => s.codec_type === 'video');
+    }
+    catch (error) {
+        logger.warn(`[scene-render] invalid ffprobe metadata for ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+// ============================================================================
+// Still composition
+// ============================================================================
+/** Compose a premium framed still (rounded image + shadow on a gradient + title). Requires ImageMagick. */
+async function composeFramedStill(input, stillPath, deps, w, h) {
+    const c0 = input.c0 ?? '#0f2027';
+    const c1 = input.c1 ?? '#243b55';
+    const { titleZone, imgBoxW, imgBoxH, brandSize, titleSize, subSize, tx, brandY, titleY, subtitleY, } = computeFramedLayout(w, h, !!input.subtitle);
+    const resized = `${stillPath}.rs.png`;
+    const rounded = `${stillPath}.rnd.png`;
+    const bg = `${stillPath}.bg.png`;
+    const cleanup = async () => {
+        await Promise.all([resized, rounded, bg].map((f) => fs.rm(f, { force: true }).catch(() => undefined)));
+    };
+    try {
+        if ((await run(deps.spawn, deps.convertBin, [
+            input.visual.imagePath,
+            '-resize',
+            `${imgBoxW}x${imgBoxH}`,
+            resized,
+        ])).code !== 0)
+            return false;
+        const dim = await run(deps.spawn, deps.identifyBin, ['-format', '%w %h', resized]);
+        const [iw, ih] = dim.stdout.trim().split(/\s+/).map(Number);
+        if (!iw || !ih)
+            return false;
+        const roundArgs = [
+            resized,
+            '(',
+            '-size',
+            `${iw}x${ih}`,
+            'xc:black',
+            '-fill',
+            'white',
+            '-draw',
+            `roundrectangle 0,0,${iw - 1},${ih - 1},20,20`,
+            ')',
+            '-alpha',
+            'off',
+            '-compose',
+            'CopyOpacity',
+            '-composite',
+            rounded,
+        ];
+        if ((await run(deps.spawn, deps.convertBin, roundArgs)).code !== 0)
+            return false;
+        if ((await run(deps.spawn, deps.convertBin, [
+            '-size',
+            `${w}x${h}`,
+            '-define',
+            'gradient:angle=135',
+            `gradient:${c0}-${c1}`,
+            bg,
+        ])).code !== 0)
+            return false;
+        const composeArgs = [
+            bg,
+            '(',
+            rounded,
+            '(',
+            '+clone',
+            '-background',
+            'black',
+            '-shadow',
+            '55x30+0+24',
+            ')',
+            '+swap',
+            '-background',
+            'none',
+            '-layers',
+            'merge',
+            '+repage',
+            ')',
+            '-gravity',
+            'north',
+            '-geometry',
+            `+0+${titleZone}`,
+            '-composite',
+            '-gravity',
+            'northwest',
+            '-font',
+            FB,
+            '-pointsize',
+            String(brandSize),
+            '-fill',
+            '#9fb4ff',
+            '-annotate',
+            `+${tx}+${brandY}`,
+            '● code-buddy',
+            '-font',
+            FB,
+            '-pointsize',
+            String(titleSize),
+            '-fill',
+            'white',
+            '-annotate',
+            `+${tx}+${titleY}`,
+            input.title,
+        ];
+        if (input.subtitle)
+            composeArgs.push('-font', FR, '-pointsize', String(subSize), '-fill', '#cdd6f4', '-annotate', `+${tx}+${subtitleY}`, input.subtitle);
+        composeArgs.push(stillPath);
+        return (await run(deps.spawn, deps.convertBin, composeArgs)).code === 0;
+    }
+    finally {
+        await cleanup();
+    }
+}
+/** Build the still for a scene (premium via ImageMagick, else an ffmpeg fallback). */
+async function composeStill(input, stillPath, deps, w, h, useIM) {
+    const spawn = deps.spawn ?? realSpawn;
+    const convertBin = deps.convertBin ?? 'convert';
+    const identifyBin = deps.identifyBin ?? 'identify';
+    const c0 = input.c0 ?? (input.visual.kind === 'image' ? '#0f2027' : '#0f2027');
+    const c1 = input.c1 ?? '#2c5364';
+    if (useIM && input.visual.kind === 'image' && input.visual.imagePath) {
+        return composeFramedStill(input, stillPath, { spawn, convertBin, identifyBin }, w, h);
+    }
+    if (useIM) {
+        const args = buildHeroCardArgs({
+            width: w,
+            height: h,
+            c0,
+            c1,
+            title: input.title,
+            ...(input.subtitle ? { subtitle: input.subtitle } : {}),
+            outPath: stillPath,
+            big: true,
+        });
+        return (await run(spawn, convertBin, args)).code === 0;
+    }
+    // ffmpeg fallback: gradient + title (via textfile to dodge drawtext escaping)
+    const titleFile = `${stillPath}.txt`;
+    await fs.writeFile(titleFile, input.title).catch(() => undefined);
+    const ok = (await run(spawn, deps.ffmpegBin ?? 'ffmpeg', buildFallbackStillArgs({
+        ffmpegBin: deps.ffmpegBin ?? 'ffmpeg',
+        width: w,
+        height: h,
+        c0,
+        c1,
+        titleFile,
+        outPath: stillPath,
+    })).catch(() => ({ code: 1 }))).code === 0;
+    await fs.rm(titleFile, { force: true }).catch(() => undefined);
+    return ok;
+}
+export async function renderScene(input, deps = {}) {
+    const spawn = deps.spawn ?? realSpawn;
+    const ffmpegBin = deps.ffmpegBin ?? 'ffmpeg';
+    const w = input.width ?? 1920;
+    const h = input.height ?? 1080;
+    const lead = input.lead ?? 0.6;
+    const workDir = deps.workDir ?? path.dirname(input.outPath);
+    await fs.mkdir(workDir, { recursive: true }).catch(() => undefined);
+    const useIM = !deps.noImageMagick && (await hasBinary(spawn, deps.convertBin ?? 'convert'));
+    const stillPath = path.join(workDir, `${input.id}.still.png`);
+    if (!(await composeStill(input, stillPath, deps, w, h, useIM))) {
+        return { ok: false, outPath: input.outPath, error: 'still composition failed' };
+    }
+    let assPath;
+    let subtitleError;
+    const wantSubs = input.subtitles ?? !!input.narrationText;
+    if (wantSubs && input.narrationText && input.narrationWav) {
+        assPath = path.join(workDir, `${input.id}.ass`);
+        // Captions are timed to the narration span; leave LEAD of silence before them.
+        const narrSpan = round2(input.duration - lead - 0.9);
+        await fs
+            .writeFile(assPath, buildKaraokeAss(input.narrationText, Math.max(1, narrSpan), lead, {
+            playResX: w,
+            playResY: h,
+        }))
+            .catch((error) => {
+            assPath = undefined;
+            subtitleError = error instanceof Error ? error.message : String(error);
+        });
+    }
+    if (subtitleError) {
+        await fs.rm(stillPath, { force: true }).catch(() => undefined);
+        logger.warn(`[scene-render] ${input.id} subtitles could not be written: ${subtitleError}`);
+        return {
+            ok: false,
+            outPath: input.outPath,
+            error: `subtitle file could not be written: ${subtitleError}`,
+        };
+    }
+    const args = buildSceneVideoArgs({
+        ffmpegBin,
+        still: stillPath,
+        outPath: input.outPath,
+        duration: input.duration,
+        width: w,
+        height: h,
+        ...(input.narrationWav ? { narrationWav: input.narrationWav } : {}),
+        ...(assPath ? { assPath } : {}),
+        lead,
+    });
+    const { code, stderr } = await run(spawn, ffmpegBin, args, 10 * 60 * 1000);
+    await fs.rm(stillPath, { force: true }).catch(() => undefined);
+    if (code !== 0) {
+        logger.warn(`[scene-render] ${input.id} ffmpeg failed: ${stderr.trim().split('\n').slice(-3).join(' ')}`);
+        return { ok: false, outPath: input.outPath, error: `ffmpeg render failed (exit ${code})` };
+    }
+    if (!(await verifyVideoArtifact(spawn, deps.ffprobeBin ?? 'ffprobe', input.outPath))) {
+        logger.warn(`[scene-render] ${input.id} ffmpeg exited 0 but produced no valid non-empty video artifact`);
+        return {
+            ok: false,
+            outPath: input.outPath,
+            error: 'ffmpeg render reported success but produced no valid non-empty video artifact',
+        };
+    }
+    return { ok: true, outPath: input.outPath };
+}
+//# sourceMappingURL=scene-render.js.map

package/dist/tools/video/subtitles.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Subtitles — karaoke (word-by-word) captions for the film producer, as a
+ * burnable ASS (Advanced SubStation Alpha) string.
+ *
+ * We do NOT transcribe the synthesized voice (an STT pass garbles proper nouns —
+ * "Code Buddy" → "budile"). Instead we start from the KNOWN narration text and
+ * estimate per-word timings proportionally (letter count + punctuation pauses).
+ * Piper reads at an even pace, so this tracks the voice well while keeping the
+ * text 100% correct. Pure + unit-testable; the ffmpeg `subtitles=` burn lives in
+ * the scene renderer.
+ *
+ * @module tools/video/subtitles
+ */
+export interface WordTiming {
+    /** Start time in seconds (relative to the narration start). */
+    start: number;
+    /** End time in seconds. */
+    end: number;
+    word: string;
+}
+export interface KaraokeStyle {
+    /** Video width/height the ASS is authored against (must match the burn target). */
+    playResX?: number;
+    playResY?: number;
+    fontName?: string;
+    fontSize?: number;
+    /** ASS colour &HAABBGGRR — already-sung / current word. */
+    primary?: string;
+    /** ASS colour — upcoming (not-yet-sung) words. */
+    secondary?: string;
+    outline?: number;
+    marginV?: number;
+    /** Max words per displayed line. */
+    wordsPerLine?: number;
+}
+/**
+ * Estimate per-word timings for `text` spanning `duration` seconds. Weight each
+ * word by its letter count plus a pause after punctuation (mimicking the voice's
+ * natural breaks). Pure.
+ */
+export declare function estimateWordTimings(text: string, duration: number): WordTiming[];
+/** Format seconds as ASS time `H:MM:SS.cs`. */
+export declare function assTime(seconds: number): string;
+/**
+ * Build a full ASS document that karaoke-highlights the narration word by word.
+ * `leadSec` offsets all times (the narration usually starts a beat into the clip).
+ * Pure — returns the ASS string to write next to the clip and burn via ffmpeg.
+ */
+export declare function buildKaraokeAss(text: string, durationSec: number, leadSec?: number, style?: KaraokeStyle): string;

package/dist/tools/video/subtitles.js

@@ -0,0 +1,116 @@
+/**
+ * Subtitles — karaoke (word-by-word) captions for the film producer, as a
+ * burnable ASS (Advanced SubStation Alpha) string.
+ *
+ * We do NOT transcribe the synthesized voice (an STT pass garbles proper nouns —
+ * "Code Buddy" → "budile"). Instead we start from the KNOWN narration text and
+ * estimate per-word timings proportionally (letter count + punctuation pauses).
+ * Piper reads at an even pace, so this tracks the voice well while keeping the
+ * text 100% correct. Pure + unit-testable; the ffmpeg `subtitles=` burn lives in
+ * the scene renderer.
+ *
+ * @module tools/video/subtitles
+ */
+const DEFAULT_STYLE = {
+    playResX: 1920,
+    playResY: 1080,
+    fontName: 'DejaVu Sans',
+    fontSize: 50,
+    primary: '&H00FFFFFF', // white (sung)
+    secondary: '&H00D9B36A', // code-buddy blue (upcoming) — note ASS is &HAABBGGRR
+    outline: 3,
+    marginV: 78,
+    wordsPerLine: 6,
+};
+const WORD_LETTERS = /[^\wàâäéèêëïîôöùûüÿçœæ']/gi;
+/**
+ * Estimate per-word timings for `text` spanning `duration` seconds. Weight each
+ * word by its letter count plus a pause after punctuation (mimicking the voice's
+ * natural breaks). Pure.
+ */
+export function estimateWordTimings(text, duration) {
+    const raw = (text ?? '').trim().split(/\s+/).filter(Boolean);
+    if (raw.length === 0 || !(duration > 0))
+        return [];
+    const weights = raw.map((w) => {
+        const letters = Math.max(1, w.replace(WORD_LETTERS, '').length);
+        const extra = /[.!?:]$/.test(w) ? 4.0 : /[,;]$/.test(w) ? 2.2 : 0;
+        return letters + 1.6 + extra;
+    });
+    const total = weights.reduce((a, b) => a + b, 0) || 1;
+    const scale = duration / total;
+    const out = [];
+    let t = 0;
+    for (let i = 0; i < raw.length; i++) {
+        const d = weights[i] * scale;
+        out.push({ start: round2(t), end: round2(t + d), word: raw[i] });
+        t += d;
+    }
+    return out;
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Format seconds as ASS time `H:MM:SS.cs`. */
+export function assTime(seconds) {
+    const cs = Math.max(0, Math.round(seconds * 100));
+    const h = Math.floor(cs / 360000);
+    const m = Math.floor((cs % 360000) / 6000);
+    const s = Math.floor((cs % 6000) / 100);
+    const c = cs % 100;
+    return `${h}:${pad(m)}:${pad(s)}.${pad(c)}`;
+}
+function pad(n) {
+    return n.toString().padStart(2, '0');
+}
+/** Escape a word for safe inclusion in an ASS Dialogue line. */
+function sanitizeWord(w) {
+    return w.replace(/[{}\\]/g, '').replace(/\n/g, ' ');
+}
+/**
+ * Build a full ASS document that karaoke-highlights the narration word by word.
+ * `leadSec` offsets all times (the narration usually starts a beat into the clip).
+ * Pure — returns the ASS string to write next to the clip and burn via ffmpeg.
+ */
+export function buildKaraokeAss(text, durationSec, leadSec = 0, style = {}) {
+    // Scale caption size/position with the target height, and use fewer words per
+    // line on vertical (9:16) videos — then let any explicit style override.
+    const h = style.playResY ?? DEFAULT_STYLE.playResY;
+    const vertical = (style.playResX ?? DEFAULT_STYLE.playResX) < h;
+    const scaled = {
+        ...DEFAULT_STYLE,
+        fontSize: Math.round(h * 0.046),
+        marginV: Math.round(h * 0.072),
+        wordsPerLine: vertical ? 4 : 6,
+    };
+    const st = { ...scaled, ...style };
+    const words = estimateWordTimings(text, durationSec);
+    const header = `[Script Info]\nScriptType: v4.00+\nPlayResX: ${st.playResX}\nPlayResY: ${st.playResY}\nScaledBorderAndShadow: yes\n\n` +
+        `[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, ` +
+        `Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, ` +
+        `Alignment, MarginL, MarginR, MarginV, Encoding\n` +
+        `Style: K,${st.fontName},${st.fontSize},${st.primary},${st.secondary},&H00101418,&H90000000,` +
+        `-1,0,0,0,100,100,0,0,1,${st.outline},1,2,200,200,${st.marginV},1\n\n` +
+        `[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n`;
+    const lines = [];
+    for (let i = 0; i < words.length; i += st.wordsPerLine) {
+        const group = words.slice(i, i + st.wordsPerLine);
+        const start = group[0].start + leadSec;
+        const end = group[group.length - 1].end + leadSec;
+        let prev = start;
+        let txt = '';
+        for (const wd of group) {
+            const ws = wd.start + leadSec;
+            const we = wd.end + leadSec;
+            const gap = Math.max(0, Math.round((ws - prev) * 100));
+            if (gap)
+                txt += `{\\k${gap}}`;
+            const dur = Math.max(1, Math.round((we - ws) * 100));
+            txt += `{\\k${dur}}${sanitizeWord(wd.word)} `;
+            prev = we;
+        }
+        lines.push(`Dialogue: 0,${assTime(start)},${assTime(end)},K,,0,0,0,,${txt.trim()}`);
+    }
+    return header + lines.join('\n') + '\n';
+}
+//# sourceMappingURL=subtitles.js.map