videoclaw 3.0.0-alpha.1

package/dist/video/assemble/text-card.d.ts

@@ -0,0 +1,78 @@
+/** One timed full-frame title card (the text is pre-positioned inside the PNG). */
+export interface TitleCard {
+    /** Full-frame transparent PNG (same WxH as the base video). */
+    pngPath: string;
+    /** When the card becomes visible, seconds. */
+    startSec: number;
+    /** When it disappears, seconds. */
+    endSec: number;
+    /** Alpha fade-in duration (default 0.6). */
+    fadeInSec?: number;
+    /** Alpha fade-out duration (default 0.6). 0 = no fade-out (e.g. an end card that holds to EOF). */
+    fadeOutSec?: number;
+}
+export interface BuildTitleCompositeInput {
+    baseVideo: string;
+    cards: TitleCard[];
+    outputPath: string;
+    /** Image input framerate for the looped PNGs (default 24). */
+    fps?: number;
+    /** H.264 CRF (default 16 — preserve text edges). */
+    crf?: number;
+    preset?: string;
+}
+/**
+ * Build the FFmpeg args to composite N timed title cards onto `baseVideo`. PURE.
+ * Each PNG is a looped input (`-loop 1 -framerate fps`) so alpha fades on a
+ * delayed start actually animate; cards chain via successive `overlay=0:0`
+ * filters gated with `enable='between(t,start,end)'`. `-shortest` bounds the
+ * infinite looped images to the base video.
+ */
+export declare function buildTitleCompositeArgs(input: BuildTitleCompositeInput): string[];
+/** One line in a card. `font` is an alias (see FONT_ALIASES) or an absolute font path. */
+export interface TextCardLine {
+    text: string;
+    font: string;
+    size: number;
+    /** Hex like "#f5f0e6". */
+    color: string;
+    /** Extra px between glyphs (Didot/caps look). Default 0. */
+    tracking?: number;
+}
+export interface TextCardSpec {
+    width: number;
+    height: number;
+    outputPath: string;
+    /** Where the stack sits. 'bottom-left' = lower-third; 'center' = end card. */
+    anchor: 'bottom-left' | 'center';
+    /** Explicit top Y for the text block. For a 'center' anchor this keeps the
+     *  horizontal centering but overrides the default vertical centering — used to
+     *  drop an end card into the lower third so it clears a centered subject. */
+    y?: number;
+    lines: TextCardLine[];
+    /** Base vertical gap added below each line's measured ink bottom. Default 28. */
+    gap?: number;
+    /** Soft drop shadow for legibility over footage. Default true. */
+    shadow?: boolean;
+    /** Optional ember accent rule to the left of a bottom-left stack. */
+    accentRule?: {
+        color: string;
+        width?: number;
+    };
+}
+/** Font aliases → macOS system font files (override by passing an absolute path as `font`). */
+export declare const FONT_ALIASES: Record<string, string>;
+export interface RenderTextCardOptions {
+    /** python3 binary (default 'python3'). */
+    python?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** True iff python3 + Pillow + RAQM (Devanagari/complex-script shaping) are available. */
+export declare function pillowAvailable(options?: RenderTextCardOptions): Promise<boolean>;
+/**
+ * Render a {@link TextCardSpec} to a transparent PNG at `spec.outputPath` (Pillow
+ * + RAQM, measure-and-stack). Spawns python3. Call {@link pillowAvailable} first
+ * to fail clearly on a host without the dep. Returns the output path.
+ */
+export declare function renderTextCard(spec: TextCardSpec, options?: RenderTextCardOptions): Promise<string>;
+//# sourceMappingURL=text-card.d.ts.map

package/dist/video/assemble/text-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-card.d.ts","sourceRoot":"","sources":["../../../src/video/assemble/text-card.ts"],"names":[],"mappings":"AA2BA,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAyCjF;AAID,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,MAAM,EAAE,aAAa,GAAG,QAAQ,CAAC;IACjC;;iFAE6E;IAC7E,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AAED,+FAA+F;AAC/F,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO/C,CAAC;AAmGF,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,0FAA0F;AAC1F,wBAAsB,eAAe,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3F;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB7G"}

package/dist/video/assemble/text-card.js

@@ -0,0 +1,210 @@
+/**
+ * text-card.ts — music-video title overlays that work on ANY ffmpeg and ANY
+ * script (Devanagari/Arabic included).
+ *
+ * Two halves:
+ *  1. A text→PNG renderer ({@link renderTextCard}) that rasterizes a stack of
+ *     lines to a transparent full-frame PNG via Pillow + RAQM (HarfBuzz shaping),
+ *     using MEASURE-INK-BOTTOM-AND-STACK so a tall Devanagari glyph's vowel marks
+ *     can never overlap the line beneath it. This sidesteps ffmpeg `drawtext`,
+ *     which (a) needs a libfreetype build and (b) can't shape complex scripts.
+ *  2. A PURE compositor ({@link buildTitleCompositeArgs}) that burns one or MORE
+ *     timed cards onto a base video.
+ *
+ * WHY a new compositor instead of {@link buildOverlayArgs}: that one takes the
+ * graphic as a plain `-i` input with no `-loop 1`. A static PNG is then a single
+ * frame at t=0, so a delayed `fade=in:st=N` (N>0) never reaches its window and
+ * the card stays invisible — the exact bug a hand-built run hit. Looping each
+ * image input fixes the fade, and chaining lets a lower-third AND an end card
+ * coexist. `buildTitleCompositeArgs` is the tested core (ffmpeg is never spawned
+ * here); `-y` is auto-prepended by runFfmpeg.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { TARGET_FPS } from './animate-slides.js';
+/**
+ * Build the FFmpeg args to composite N timed title cards onto `baseVideo`. PURE.
+ * Each PNG is a looped input (`-loop 1 -framerate fps`) so alpha fades on a
+ * delayed start actually animate; cards chain via successive `overlay=0:0`
+ * filters gated with `enable='between(t,start,end)'`. `-shortest` bounds the
+ * infinite looped images to the base video.
+ */
+export function buildTitleCompositeArgs(input) {
+    if (input.cards.length === 0) {
+        throw new Error('buildTitleCompositeArgs: at least one card is required.');
+    }
+    const fps = input.fps ?? TARGET_FPS;
+    const crf = input.crf ?? 16;
+    const preset = input.preset ?? 'medium';
+    const args = ['-i', input.baseVideo];
+    for (const card of input.cards) {
+        args.push('-loop', '1', '-framerate', String(fps), '-i', card.pngPath);
+    }
+    // Per-card alpha chain, then chained overlays onto the base.
+    const filters = [];
+    input.cards.forEach((card, i) => {
+        const inputIdx = i + 1; // input 0 is the base video
+        const fadeIn = card.fadeInSec ?? 0.6;
+        const fadeOut = card.fadeOutSec ?? 0.6;
+        const chain = ['format=rgba'];
+        if (fadeIn > 0)
+            chain.push(`fade=t=in:st=${card.startSec}:d=${fadeIn}:alpha=1`);
+        if (fadeOut > 0) {
+            chain.push(`fade=t=out:st=${Math.max(0, card.endSec - fadeOut)}:d=${fadeOut}:alpha=1`);
+        }
+        filters.push(`[${inputIdx}:v]${chain.join(',')}[c${i}]`);
+    });
+    let prev = '[0:v]';
+    input.cards.forEach((card, i) => {
+        const out = i === input.cards.length - 1 ? '[v]' : `[v${i}]`;
+        filters.push(`${prev}[c${i}]overlay=0:0:enable='between(t,${card.startSec},${card.endSec})'${out}`);
+        prev = `[v${i}]`;
+    });
+    args.push('-filter_complex', filters.join(';'), '-map', '[v]', '-map', '0:a?', '-c:v', 'libx264', '-preset', preset, '-crf', String(crf), '-pix_fmt', 'yuv420p', '-c:a', 'copy', '-shortest', '-movflags', '+faststart', input.outputPath);
+    return args;
+}
+/** Font aliases → macOS system font files (override by passing an absolute path as `font`). */
+export const FONT_ALIASES = {
+    didot: '/System/Library/Fonts/Supplemental/Didot.ttc',
+    devanagari: '/System/Library/Fonts/Kohinoor.ttc',
+    kohinoor: '/System/Library/Fonts/Kohinoor.ttc',
+    avenir: '/System/Library/Fonts/Avenir Next.ttc',
+    georgia: '/System/Library/Fonts/Supplemental/Georgia.ttf',
+    helvetica: '/System/Library/Fonts/HelveticaNeue.ttc',
+};
+/** The embedded renderer — productized render_overlays.py. Reads a spec JSON (argv[1]). */
+const TEXT_CARD_PY = String.raw `
+import sys, json
+from PIL import Image, ImageDraw, ImageFont, ImageFilter
+spec = json.load(open(sys.argv[1]))
+W, H = spec["width"], spec["height"]
+RAQM = ImageFont.Layout.RAQM
+def hx(c):
+    c = c.lstrip("#"); return tuple(int(c[i:i+2], 16) for i in (0, 2, 4))
+def font(path, size):
+    return ImageFont.truetype(path, size, layout_engine=RAQM)
+def tw(d, text, f, tr):
+    if tr == 0: return d.textbbox((0, 0), text, font=f)[2]
+    return sum(d.textbbox((0, 0), ch, font=f)[2] + tr for ch in text) - tr
+def put(d, xy, text, f, rgba, tr):
+    x, y = xy
+    if tr == 0:
+        d.text((x, y), text, font=f, fill=rgba); return
+    for ch in text:
+        d.text((x, y), ch, font=f, fill=rgba); x += d.textbbox((0,0), ch, font=f)[2] + tr
+img = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+shadow_on = spec.get("shadow", True)
+gap = spec.get("gap", 28)
+anchor = spec["anchor"]
+# render each line into a temp layer, measure ink bottom, stack below previous
+layers = []
+_md = ImageDraw.Draw(img)
+for ln in spec["lines"]:
+    f = font(ln["font"], ln["size"]); tr = ln.get("tracking", 0)
+    w = tw(_md, ln["text"], f, tr)
+    layers.append((ln, f, tr, w))
+total_w = max((w for _, _, _, w in layers), default=0)
+# Fit-to-width: never let a line overflow the frame. If the widest line exceeds
+# the safe width (frame minus side margins), shrink EVERY line's font by the
+# same factor (preserving the size hierarchy + tracking) until it fits. Without
+# this a long end-card tagline rendered past the canvas edge and was cropped.
+safe_w = int(W * (1 - 2 * spec.get("safeMarginRatio", 0.07)))
+if total_w > safe_w and total_w > 0:
+    fit = safe_w / total_w
+    rescaled = []
+    for (ln, f, tr, w) in layers:
+        ns = max(8, int(ln["size"] * fit)); ntr = (tr * ns) // ln["size"] if ln["size"] else 0
+        nf = font(ln["font"], ns)
+        rescaled.append((ln, nf, ntr, tw(_md, ln["text"], nf, ntr)))
+    layers = rescaled
+    total_w = max((w for _, _, _, w in layers), default=0)
+# starting x
+if anchor == "bottom-left":
+    x0 = spec.get("x", 150); rule_w = (spec.get("accentRule") or {}).get("width", 7)
+    text_x = x0 + rule_w + 26
+    # bottom-anchored: estimate total height first via a dry stack
+top = spec.get("y")
+def stack(start_top):
+    yb = start_top; first_top = None; last_bottom = None
+    for (ln, f, tr, w) in layers:
+        layer = Image.new("RGBA", (W, H), (0, 0, 0, 0)); d = ImageDraw.Draw(layer)
+        x = (W - w) // 2 if anchor == "center" else text_x
+        y = yb + (0 if last_bottom is None else gap)
+        if shadow_on:
+            sh = Image.new("RGBA", (W, H), (0, 0, 0, 0)); sd = ImageDraw.Draw(sh)
+            put(sd, (x, y), ln["text"], f, (0, 0, 0, 170), tr)
+            img.alpha_composite(sh.filter(ImageFilter.GaussianBlur(7)))
+        put(d, (x, y), ln["text"], f, hx(ln["color"]) + (255,), tr)
+        img.alpha_composite(layer)
+        bb = layer.split()[3].getbbox()
+        if bb:
+            if first_top is None: first_top = bb[1]
+            last_bottom = bb[3]; yb = bb[3]
+    return first_top, last_bottom
+if anchor == "center" and top is None:
+    # two-pass: dry-run to center the block vertically (clear img between passes)
+    tmp = img.copy(); ft, lb = stack(0)
+    img.paste(tmp); img.alpha_composite  # noop guard
+    block_h = (lb - ft) if (ft is not None and lb is not None) else 0
+    img = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+    stack(max(0, (H - block_h) // 2 - (ft or 0)))
+else:
+    if top is None: top = H - 360 if anchor == "bottom-left" else (H // 2 - 200)
+    ft, lb = stack(top)
+# ember accent rule for the lower-third
+ar = spec.get("accentRule")
+if ar and anchor == "bottom-left":
+    a = img.split()[3].getbbox()
+    if a:
+        d = ImageDraw.Draw(img); rw = ar.get("width", 7)
+        d.rectangle([spec.get("x",150), a[1], spec.get("x",150)+rw, a[3]], fill=hx(ar["color"]) + (255,))
+img.save(spec["outputPath"])
+print(spec["outputPath"])
+`;
+function resolveFonts(lines) {
+    return lines.map((ln) => ({
+        ...ln,
+        font: ln.font.startsWith('/') ? ln.font : (FONT_ALIASES[ln.font.toLowerCase()] ?? ln.font),
+    }));
+}
+/** True iff python3 + Pillow + RAQM (Devanagari/complex-script shaping) are available. */
+export async function pillowAvailable(options = {}) {
+    const python = options.python ?? 'python3';
+    return new Promise((resolve) => {
+        const child = spawn(python, ['-c', "from PIL import features; raise SystemExit(0 if features.check('raqm') else 1)"], {
+            stdio: 'ignore', env: options.env ?? process.env,
+        });
+        child.on('error', () => resolve(false));
+        child.on('exit', (code) => resolve(code === 0));
+    });
+}
+/**
+ * Render a {@link TextCardSpec} to a transparent PNG at `spec.outputPath` (Pillow
+ * + RAQM, measure-and-stack). Spawns python3. Call {@link pillowAvailable} first
+ * to fail clearly on a host without the dep. Returns the output path.
+ */
+export async function renderTextCard(spec, options = {}) {
+    const python = options.python ?? 'python3';
+    const resolved = { ...spec, lines: resolveFonts(spec.lines) };
+    const dir = await mkdtemp(join(tmpdir(), 'vclaw-textcard-'));
+    const scriptPath = join(dir, 'render.py');
+    const specPath = join(dir, 'spec.json');
+    try {
+        await writeFile(scriptPath, TEXT_CARD_PY, 'utf8');
+        await writeFile(specPath, JSON.stringify(resolved), 'utf8');
+        await new Promise((resolve, reject) => {
+            const child = spawn(python, [scriptPath, specPath], { stdio: ['ignore', 'ignore', 'pipe'], env: options.env ?? process.env });
+            let stderr = '';
+            child.stderr?.on('data', (d) => (stderr += String(d)));
+            child.on('error', reject);
+            child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`renderTextCard failed (exit ${code}): ${stderr.slice(0, 400)}`))));
+        });
+        return spec.outputPath;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=text-card.js.map

package/dist/video/assemble/text-card.js.map

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

package/dist/video/assemble/title-card.d.ts

@@ -0,0 +1,39 @@
+export interface GenerateTitleCardInput {
+    /** Main heading text. Rendered upper-cased to match the Python pipeline. */
+    title: string;
+    /** Optional secondary line below the title. */
+    subtitle?: string;
+    /** Where to write the composed PNG. */
+    outputPath: string;
+    /** Card width in pixels (default: 1280, matching LANDSCAPE_WIDTH). */
+    width?: number;
+    /** Card height in pixels (default: 720, matching LANDSCAPE_HEIGHT). */
+    height?: number;
+    /**
+     * Background: a hex colour (e.g. `#101018`) for a solid fill, or a path to an
+     * image to center-crop + resize to the card dimensions. Default: solid
+     * `#101018` (a dark slate consistent with the Python "dark" style band).
+     */
+    background?: string;
+    /** Title colour (default: white, matching TITLE_CARD_TITLE_COLOR). */
+    textColor?: string;
+    /** Title font size in px (default: 58, matching TITLE_CARD_TITLE_FONT_SIZE). */
+    fontSize?: number;
+    /** Skip composition + file write; return dimensions only. */
+    dryRun?: boolean;
+}
+export interface GenerateTitleCardResult {
+    /** Path written to (empty string on dry-run). */
+    path: string;
+    width: number;
+    height: number;
+}
+/**
+ * Compose a title-card PNG.
+ *
+ * Throws `VclawError('invalid_video_format', ...)` for non-positive dimensions
+ * and `VclawError('unexpected_internal_error', ...)` if sharp composition or
+ * the file write fails.
+ */
+export declare function generateTitleCard(input: GenerateTitleCardInput): Promise<GenerateTitleCardResult>;
+//# sourceMappingURL=title-card.d.ts.map

package/dist/video/assemble/title-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-card.d.ts","sourceRoot":"","sources":["../../../src/video/assemble/title-card.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAiCD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAwFlC"}

package/dist/video/assemble/title-card.js

@@ -0,0 +1,127 @@
+/**
+ * Title-card image generation for the assemble stage (sub-slice 3d).
+ *
+ * Source of truth: `skills/video-replicator/scripts/generate_title_card.py`
+ * (the `process_image` / text-overlay path). The Python pipeline composes a
+ * 16:9 card (1280x720), draws a semi-transparent dark band across the bottom,
+ * then renders an upper-cased title (58px, white, with a 2px outline) and an
+ * optional subtitle (28px, light blue #C8DCFF) centered in that band.
+ *
+ * We reproduce that purely in-process with `sharp`: build a base layer (a solid
+ * colour, or a center-cropped/resized background image), then composite an SVG
+ * holding the band + text on top. SVG-via-sharp is the most portable text path
+ * here — no native font installation step, generic-family fallbacks
+ * (sans-serif) resolve on every platform, and the geometry is declarative so it
+ * matches the Python layout 1:1.
+ *
+ * Pure module: no CLI wiring (that lands in sub-slice 3i), no network, no
+ * FFmpeg hold-video step (the Python Phase-2 `create_hold_video` is a separate
+ * concern handled by the stitch sub-slice).
+ */
+import sharp from 'sharp';
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { VclawError } from '../errors.js';
+// Python config defaults (skills/.../config.py).
+const DEFAULT_WIDTH = 1280;
+const DEFAULT_HEIGHT = 720;
+const DEFAULT_TITLE_FONT_SIZE = 58;
+const SUBTITLE_FONT_SIZE = 28;
+const DEFAULT_TITLE_COLOR = 'white';
+const SUBTITLE_COLOR = '#C8DCFF';
+const TITLE_OUTLINE_COLOR = 'black';
+const TITLE_OUTLINE_WIDTH = 2;
+// Band spans from BAND_TOP to the bottom edge in the Python 720px layout; we
+// express it as a fraction so non-default heights keep the same proportion.
+const BAND_TOP_FRACTION = 560 / 720;
+const BAND_OPACITY = 160 / 255; // 0..1 alpha for the SVG fill.
+// Text baselines are offset from the band top (Python: +30 title, +95 subtitle,
+// measured against the 720px layout). Keep them proportional to height.
+const TITLE_OFFSET_FRACTION = 30 / 720;
+const SUBTITLE_OFFSET_FRACTION = 95 / 720;
+const FONT_FAMILY = "'Arial', 'Helvetica', sans-serif";
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** Minimal XML escaping for text injected into the SVG. */
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Compose a title-card PNG.
+ *
+ * Throws `VclawError('invalid_video_format', ...)` for non-positive dimensions
+ * and `VclawError('unexpected_internal_error', ...)` if sharp composition or
+ * the file write fails.
+ */
+export async function generateTitleCard(input) {
+    const width = input.width ?? DEFAULT_WIDTH;
+    const height = input.height ?? DEFAULT_HEIGHT;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+        throw new VclawError('invalid_video_format', `Title-card dimensions must be positive integers (got ${width}x${height}).`, { width, height });
+    }
+    if (input.dryRun) {
+        return { path: '', width, height };
+    }
+    const titleColor = input.textColor ?? DEFAULT_TITLE_COLOR;
+    const titleFontSize = input.fontSize ?? DEFAULT_TITLE_FONT_SIZE;
+    const subtitleFontSize = Math.round(SUBTITLE_FONT_SIZE * (titleFontSize / DEFAULT_TITLE_FONT_SIZE));
+    const bandTop = Math.round(height * BAND_TOP_FRACTION);
+    const bandHeight = height - bandTop;
+    const titleY = bandTop + Math.round(height * TITLE_OFFSET_FRACTION) + titleFontSize;
+    const subtitleY = bandTop + Math.round(height * SUBTITLE_OFFSET_FRACTION) + subtitleFontSize;
+    const centerX = width / 2;
+    const titleText = escapeXml(input.title.toUpperCase());
+    const subtitleText = input.subtitle ? escapeXml(input.subtitle) : undefined;
+    // SVG overlay: band rectangle + outlined title + optional subtitle. Text is
+    // center-anchored so it lands centered like the Python textbbox math.
+    const titleNode = `<text x="${centerX}" y="${titleY}" text-anchor="middle" font-family="${FONT_FAMILY}" font-size="${titleFontSize}" font-weight="bold" fill="${titleColor}" stroke="${TITLE_OUTLINE_COLOR}" stroke-width="${TITLE_OUTLINE_WIDTH}" paint-order="stroke fill">${titleText}</text>`;
+    const subtitleNode = subtitleText
+        ? `<text x="${centerX}" y="${subtitleY}" text-anchor="middle" font-family="${FONT_FAMILY}" font-size="${subtitleFontSize}" fill="${SUBTITLE_COLOR}">${subtitleText}</text>`
+        : '';
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+  <rect x="0" y="${bandTop}" width="${width}" height="${bandHeight}" fill="black" fill-opacity="${BAND_OPACITY}" />
+  ${titleNode}
+  ${subtitleNode}
+</svg>`;
+    let base;
+    const background = input.background ?? '#101018';
+    if (HEX_RE.test(background)) {
+        base = sharp({
+            create: {
+                width,
+                height,
+                channels: 4,
+                background,
+            },
+        });
+    }
+    else {
+        // Treat as an image path: center-crop + resize to the card (cover fit).
+        try {
+            await stat(background);
+        }
+        catch {
+            throw new VclawError('image_not_found', `Title-card background image not found: "${background}".`, { background });
+        }
+        base = sharp(background).resize(width, height, { fit: 'cover', position: 'center' });
+    }
+    try {
+        const composed = await base
+            .composite([{ input: Buffer.from(svg), top: 0, left: 0 }])
+            .png()
+            .toBuffer();
+        await mkdir(dirname(input.outputPath), { recursive: true });
+        await writeFile(input.outputPath, composed);
+    }
+    catch (err) {
+        if (err instanceof VclawError)
+            throw err;
+        throw new VclawError('unexpected_internal_error', `Failed to generate title card at "${input.outputPath}": ${err.message}`, { outputPath: input.outputPath });
+    }
+    return { path: input.outputPath, width, height };
+}
+//# sourceMappingURL=title-card.js.map

package/dist/video/assemble/title-card.js.map

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

package/dist/video/assemble/transcript.d.ts

@@ -0,0 +1,66 @@
+import type { TtsSegment } from './tts.js';
+export interface MultiVoiceSegment {
+    speaker: string;
+    text: string;
+}
+/** A scene's narration: plain text, or multi-voice speaker segments. */
+export type SceneText = string | MultiVoiceSegment[];
+export interface SceneTranscript {
+    sceneNumber: number;
+    text: SceneText;
+    hasSpeech: boolean;
+}
+export interface LoadedTranscript {
+    fullText: string;
+    sceneTranscripts: SceneTranscript[];
+    warnings: string[];
+}
+/**
+ * Normalize a parsed transcript JSON into {@link LoadedTranscript}. Supports
+ * the standalone and SEALCAM+-embedded shapes; anything else yields an empty
+ * transcript with a warning (mirrors the Python's logged warning).
+ */
+export declare function parseTranscript(data: unknown): LoadedTranscript;
+/**
+ * Parse `editable_transcript.json`-style per-scene overrides into a
+ * sceneNumber → text map. Non-numeric scene keys are skipped with a warning
+ * (the Python would have thrown on `int(key)`).
+ */
+export declare function parseEditedTranscript(data: unknown): {
+    edits: Map<number, SceneText>;
+    warnings: string[];
+};
+export interface SceneTextEntry {
+    sceneNumber: number;
+    text: SceneText;
+    edited: boolean;
+}
+/**
+ * Extract per-scene text, applying edits and skips — the Python
+ * `get_scene_texts`. With no per-scene data, the full text becomes a single
+ * scene 1 (the Python fallback).
+ */
+export declare function sceneTexts(transcript: LoadedTranscript, options?: {
+    edits?: Map<number, SceneText>;
+    skipScenes?: Set<number>;
+}): SceneTextEntry[];
+/**
+ * Resolve a transcript (plus optional edits) into TTS segments. Multi-voice
+ * scenes are flattened to one joined text with a warning; scenes with no
+ * speech are skipped (the Python's `has_speech`).
+ */
+export declare function transcriptToTtsSegments(transcript: LoadedTranscript, options?: {
+    edits?: Map<number, SceneText>;
+    skipScenes?: Set<number>;
+}): {
+    segments: TtsSegment[];
+    warnings: string[];
+};
+/** Read + parse a transcript file (standalone or SEALCAM+-embedded shape). */
+export declare function loadTranscriptFile(path: string): Promise<LoadedTranscript>;
+/** Read + parse an editable-transcript overrides file. */
+export declare function loadEditedTranscriptFile(path: string): Promise<{
+    edits: Map<number, SceneText>;
+    warnings: string[];
+}>;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/video/assemble/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../src/video/assemble/transcript.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CA8C/D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAkB1G;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAO,GACzE,cAAc,EAAE,CAkBlB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAO,GACzE;IAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAchD;AAED,8EAA8E;AAC9E,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAchF;AAED,0DAA0D;AAC1D,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAchE"}