reelson 0.7.0

package/skills/reelson-compose/schemas/video.schema.json

@@ -0,0 +1,172 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "reelson video (video.json)",
+    "description": "The source of truth for one video. `reelson build` regenerates video/index.html from it; every time in here is a RECORDING time (seconds in recording.mp4, as in markers.json), so trims and templates can change without re-timing anything.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["title"],
+    "properties": {
+        "title": { "type": "string", "description": "Cover title: the task, e.g. \"Find a customer\"." },
+        "subtitle": { "type": "string", "description": "Cover subtitle: the benefit or context." },
+        "template": { "type": "string", "description": "Overrides demo.config.json `template` for this video." },
+        "sections": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Overrides demo.config.json `sections` per slot, e.g. { \"intro\": \"minimal\", \"recap\": \"none\" }. Run `reelson templates` for the list.",
+            "properties": {
+                "intro": { "type": "string", "description": "Opening section; frame 0 is the poster. Kit: poster, minimal, split." },
+                "recap": { "type": "string", "description": "Steps card after the recording, or \"none\". Kit: steps, compact, none." },
+                "outro": { "type": "string", "description": "Closing brand card. Kit: wordmark, compact, endcard." }
+            }
+        },
+        "recapTitle": { "type": "string", "description": "Overrides demo.config.json `strings.recapTitle`." },
+        "brand": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Per-video overrides of demo.config.json `brand` text.",
+            "properties": {
+                "name": { "type": "string" },
+                "tagline": { "type": "string" },
+                "eyebrow": { "type": "string" },
+                "logo": { "type": ["string", "null"], "description": "Overrides demo.config.json `brand.logo`: an .svg/.png/.webp relative to the project root, or null for the text wordmark." }
+            }
+        },
+        "trim": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "The part of the recording the video uses. Prefer \"auto\" or a marker/click anchor: a plain number goes stale when the demo is re-recorded.",
+            "properties": {
+                "start": {
+                    "description": "Where the footage starts: \"auto\" (just before the first glide or marker, i.e. after the login), { \"marker\": label, \"offset\"?: s }, { \"click\": n, \"offset\"?: s } (from the glide towards click n), or recording seconds.",
+                    "anyOf": [
+                        { "type": "number", "minimum": 0 },
+                        { "enum": ["auto"] },
+                        { "$ref": "#/definitions/markerPoint" },
+                        { "$ref": "#/definitions/clickPoint" }
+                    ]
+                },
+                "end": {
+                    "description": "Where the footage stops: { \"marker\": label, \"offset\"?: s }, { \"click\": n, \"offset\"?: s }, or recording seconds. Default: the end of the recording.",
+                    "anyOf": [
+                        { "type": "number", "exclusiveMinimum": 0 },
+                        { "$ref": "#/definitions/markerPoint" },
+                        { "$ref": "#/definitions/clickPoint" }
+                    ]
+                }
+            }
+        },
+        "music": {
+            "type": ["string", "boolean", "null"],
+            "description": "Music bed: a file (relative to the project root) for this video only, false for none, null/omitted for demo.config.json `music.file`."
+        },
+        "callouts": {
+            "type": "array",
+            "maxItems": 20,
+            "description": "Numbered step pills over the recording; they also become the recap. Give each a `marker` (a markers.json label) or an `at`.",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["text"],
+                "properties": {
+                    "text": { "type": "string", "description": "Imperative step in the UI's language, ≤ 6 words." },
+                    "marker": { "type": "string", "description": "markers.json label this callout is timed from." },
+                    "anchor": { "enum": ["step", "marker"], "description": "Where a marker callout starts: step (default) — as the step it names begins (the first glide/click after the previous marker; a marker comes right after its action); marker — on the marker itself." },
+                    "offset": { "type": "number", "description": "Seconds after that start (negative: before). Keeps the callout tied to its marker when you nudge it." },
+                    "at": { "type": "number", "minimum": 0, "description": "Recording time instead of a marker (manual recordings)." },
+                    "duration": { "type": "number", "exclusiveMinimum": 0, "description": "Seconds on screen. Default: through its step and 1.2 s past its marker (at least 3 s), ending before the next callout." },
+                    "group": { "type": "string", "description": "Role tag (two-actor videos). Default: taken from the hand-off cards." },
+                    "say": { "type": ["string", "boolean"], "not": { "const": true }, "description": "Voice-over (\"voice\": true): what is spoken for this step, when it should differ from the text (e.g. a full sentence); false: nothing." }
+                }
+            }
+        },
+        "voice": {
+            "description": "Voice-over: true speaks each callout (its `say`, else its text) with the demo.config.json `voice` provider (OpenAI by default; ElevenLabs, a local Piper voice or a local command); lines are cached in <demo>/voice/. An object turns it on with this video's own provider / model / voice / instructions / speed and may add an `intro` line spoken over the intro.",
+            "oneOf": [
+                { "type": "boolean" },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "provider": { "enum": ["openai", "elevenlabs", "piper", "command"], "description": "This video's provider, from its defaults (baseURL, command and options stay with the project's provider)." },
+                        "model": { "type": "string" },
+                        "voice": { "type": "string" },
+                        "instructions": { "type": "string" },
+                        "speed": { "type": "number", "minimum": 0.5, "maximum": 2 },
+                        "intro": { "type": "string", "description": "Spoken over the intro, e.g. the title as a sentence." }
+                    }
+                }
+            ]
+        },
+        "formats": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "enum": ["portrait", "square"] },
+            "description": "Versions every `reelson render` adds besides the 16:9 one, as with --portrait / --square. A square version needs the square take (`reelson record --square`); without one it is skipped with a note."
+        },
+        "portrait": {
+            "enum": ["auto", "mobile", "desktop"],
+            "description": "Source of `reelson render --portrait`: mobile = the phone take (`reelson record --mobile`), desktop = a camera framing each element on the desktop recording, auto (default) = the phone take when there is one."
+        },
+        "cursor": {
+            "description": "The cursor layer (recordings with record.cursor \"layer\", the default since reelson 0.4): false hides it, or tune it. Has no effect when the cursor is filmed in.",
+            "anyOf": [
+                { "enum": [false] },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "size": { "type": "number", "minimum": 16, "maximum": 120, "description": "Arrow size in recording CSS px. Default 44 (the classic macOS-style arrow)." },
+                        "ripple": { "type": "boolean", "description": "The brand-coloured ring on each press. Default true." },
+                        "idle": { "type": "number", "minimum": 0, "maximum": 30, "description": "Fade the cursor out after this many seconds without moving or clicking, back in as it moves again. Default 0 (always shown)." }
+                    }
+                }
+            ]
+        },
+        "zooms": {
+            "type": "array",
+            "description": "Zoom-ins on the framed recording. Prefer `clicks`: timing and focus are computed from the cursor so the zoom rides along with the glide.",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["scale"],
+                "properties": {
+                    "clicks": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": 2,
+                        "items": { "type": "integer", "minimum": 1 },
+                        "description": "[first, last] click numbers (1-based, markers.json `clicks`) the zoom frames. Timing and focus are computed."
+                    },
+                    "scale": { "type": "number", "minimum": 1.1, "maximum": 4, "description": "1.5–2.0 reads well." },
+                    "follow": { "type": "boolean", "description": "Pan with the cursor while zoomed, so the clicks need not fit one view (recordings with a logged cursor, record.cursor \"layer\"). Default false." },
+                    "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Focus point, fraction of the frame width. Default: centred on the clicks." },
+                    "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Focus point, fraction of the frame height." },
+                    "at": { "type": "number", "minimum": 0, "description": "Manual zoom: recording time the zoom-in starts (instead of `clicks`)." },
+                    "duration": { "type": "number", "exclusiveMinimum": 0, "description": "Manual zoom: seconds from zoom-in start to zoomed-out." },
+                    "in": { "type": "number", "minimum": 0.4, "description": "Zoom-in ease seconds (default 0.8)." },
+                    "out": { "type": "number", "minimum": 0.4, "description": "Zoom-out ease seconds (default 0.8)." }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "markerPoint": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["marker"],
+            "properties": {
+                "marker": { "type": "string", "description": "markers.json label." },
+                "offset": { "type": "number", "description": "Seconds after the marker (negative: before)." }
+            }
+        },
+        "clickPoint": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["click"],
+            "properties": {
+                "click": { "type": "integer", "minimum": 1, "description": "1-based click in markers.json `clicks`: the time the cursor starts gliding towards it." },
+                "offset": { "type": "number", "description": "Seconds after that (negative: before)." }
+            }
+        }
+    }
+}

package/skills/reelson-compose/scripts/build.js

@@ -0,0 +1,424 @@
+/**
+ * Builds a demo's HyperFrames project from its video.json.
+ *
+ *   reelson build <slug|dir> [--title ".."] [--subtitle ".."] [--trim-start s] [--trim-end s]
+ *                            [--template name] [--intro name] [--recap name|none] [--outro name]
+ *                            [--music file | --no-music]
+ *
+ * video.json is the source of truth; video/ is generated and can be deleted at
+ * any time. The first build creates video.json from markers.json (one callout
+ * per marker, a suggested trim); the flags above edit video.json in place.
+ *
+ * Writes <demo>/video/{index.html, hyperframes.json, package.json, assets/*}:
+ * the template's stage with the chosen intro/recap/outro sections, its own assets
+ * (vendored GSAP + fonts), each section's assets, the brand logo, the recording, narration
+ * (when the recording has audio) and the music bed (trimmed, loudness-normalised,
+ * faded; cached between builds).
+ */
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { countLabel, fromRoot } from "../../reelson-record/scripts/config.js";
+import { renderComposition } from "./composition.js";
+import { phoneLayout, portraitLayout, squareLayout } from "./portrait.js";
+import { renderVoiceTrack, spokenLength, voiceLines, voiceSettings } from "./voice.js";
+import { HYPERFRAMES_VERSION, RENDER_FLAGS } from "./hyperframes.js";
+import { readMarkers, readSection, readVideoSpec, ReelsonError, resolveDesign, videoSchemaRef, } from "./project.js";
+import { computeTimeline, defaultCallouts, round, } from "./timeline.js";
+import { compositionClicks, followPath, planZoom, ZoomError } from "./zooms.js";
+/** Everything a build needs, computed without touching video/ (check uses it too). */
+export function plan(demoDir, config, options = {}) {
+    const markers = readMarkers(demoDir);
+    const existing = readVideoSpec(demoDir);
+    const spec = existing ?? {
+        title: options.title ?? humanize(basename(demoDir)),
+        // Follows the recording: a re-record never leaves a stale trim behind.
+        trim: { start: 'auto' },
+        callouts: defaultCallouts(markers),
+        zooms: [],
+    };
+    applyOptions(spec, options);
+    return { ...planSpec(demoDir, spec, markers, config), created: existing === null };
+}
+/** The plan for a given video.json (validated elsewhere), without reading it from disk. */
+export function planSpec(demoDir, spec, markers, config) {
+    const design = resolveDesign(spec.template ?? config.template, [config.sections, spec.sections], config);
+    let computed;
+    try {
+        // With a voice-over, the callouts wait for their (cached) lines to be said.
+        const voice = voiceSettings(spec, config);
+        computed = computeTimeline(markers, spec, design.timing, voice ? spokenLength(voice, resolve(demoDir, 'voice')) : undefined);
+    }
+    catch (error) {
+        throw new ReelsonError(`${resolve(demoDir, 'video.json')}: ${error.message}`);
+    }
+    const { timeline, warnings } = computed;
+    const clicks = compositionClicks(markers, timeline);
+    const zooms = (spec.zooms ?? []).map((z, i) => {
+        try {
+            const zoom = planZoom(z, clicks, timeline);
+            if (z.follow && timeline.cursor) {
+                zoom.path = followPath(zoom, timeline.cursor, timeline.viewport);
+            }
+            else if (z.follow) {
+                warnings.push(`zoom ${i + 1}: "follow" needs the cursor log of a record.cursor "layer" recording — it stays on its focus`);
+            }
+            return zoom;
+        }
+        catch (error) {
+            if (error instanceof ZoomError) {
+                throw new ReelsonError(`video.json zooms[${i}]: ${error.message}`);
+            }
+            throw error;
+        }
+    });
+    return { spec, markers, design, timeline, clicks, zooms, warnings };
+}
+export function build(demoDir, config, options = {}) {
+    const log = options.log ?? console.log;
+    const recording = resolve(demoDir, 'recording.mp4');
+    if (!existsSync(recording)) {
+        throw new ReelsonError(`missing ${recording} — run \`reelson record\` first (or export one from OpenScreen)`);
+    }
+    const result = plan(demoDir, config, options);
+    const { spec, timeline, design } = result;
+    const { template } = design;
+    // video.json first: it is the source of truth even if a later step fails.
+    const specPath = resolve(demoDir, 'video.json');
+    const serialized = serializeVideoSpec(spec, demoDir, config);
+    if (!existsSync(specPath) || readFileSync(specPath, 'utf8') !== serialized) {
+        writeFileSync(specPath, serialized);
+        log(result.created ? `created ${specPath} — word the callouts and add zooms there` : `updated ${specPath}`);
+    }
+    const videoDir = resolve(demoDir, 'video');
+    const assets = resolve(videoDir, 'assets');
+    mkdirSync(assets, { recursive: true });
+    if (existsSync(resolve(template.dir, 'assets'))) {
+        cpSync(resolve(template.dir, 'assets'), assets, { recursive: true, preserveTimestamps: true });
+    }
+    const sections = Object.values(design.sections)
+        .filter((section) => section !== null)
+        .map((section) => {
+        const source = readSection(section);
+        if (source.assets) {
+            cpSync(resolve(section.dir, 'assets'), resolve(videoDir, source.assets), { recursive: true, preserveTimestamps: true });
+        }
+        return source;
+    });
+    const logo = copyLogo(spec, config, assets, log);
+    copyIfChanged(recording, resolve(assets, 'recording.mp4'));
+    const narration = extractNarration(recording, resolve(assets, 'narration.m4a'), timeline, log);
+    const voice = voiceTrack(demoDir, config, spec, timeline, resolve(assets, 'voice.m4a'), log);
+    const music = renderMusicBed(spec, config, timeline, resolve(assets, 'music.m4a'), narration || voice, log);
+    const brand = { ...config.brand, ...spec.brand };
+    const composition = {
+        stage: readFileSync(resolve(template.dir, 'stage.html'), 'utf8'),
+        sections,
+        timeline,
+        zooms: result.zooms,
+        narration,
+        music,
+        voice,
+        text: {
+            language: config.language,
+            brand,
+            logo,
+            title: spec.title,
+            subtitle: spec.subtitle ?? '',
+            recapTitle: spec.recapTitle ?? config.strings.recapTitle,
+            stepsChip: countLabel(timeline.callouts.length, config.strings.stepsLabel, config.language),
+            secondsChip: countLabel(Math.round(timeline.total), config.strings.secondsLabel, config.language),
+        },
+    };
+    const html = renderComposition(composition);
+    writeFileSync(resolve(videoDir, 'index.html'), html);
+    // The same video for phones (`reelson render --portrait`): from the phone take when there
+    // is one (video.json "portrait"), else a camera framing each element on this recording.
+    const portrait = renderPortrait(demoDir, config, spec, composition, result, assets, log);
+    writeFileSync(resolve(videoDir, 'portrait.html'), portrait.html);
+    // The square video (`reelson render --square`): only from a square take, which fills it.
+    const square = renderSquare(demoDir, config, spec, composition, result, assets, log);
+    if (square) {
+        writeFileSync(resolve(videoDir, 'square.html'), square.html);
+    }
+    else {
+        rmSync(resolve(videoDir, 'square.html'), { force: true });
+    }
+    writeFileSync(resolve(videoDir, 'hyperframes.json'), JSON.stringify({
+        $schema: 'https://hyperframes.heygen.com/schema/hyperframes.json',
+        paths: { blocks: 'compositions', components: 'compositions/components', assets: 'assets' },
+        // autoProxy swaps big media for a downscaled proxy, which throws away the 2x capture.
+        media: { autoProxy: false },
+    }, null, 2) + '\n');
+    const hf = `npx --yes hyperframes@${HYPERFRAMES_VERSION}`;
+    writeFileSync(resolve(videoDir, 'package.json'), JSON.stringify({
+        name: `reelson-video-${basename(demoDir)}`,
+        private: true,
+        type: 'module',
+        scripts: { dev: `${hf} preview`, check: `${hf} check`, render: `${hf} render ${RENDER_FLAGS.join(' ')}` },
+    }, null, 2) + '\n');
+    const t = timeline;
+    const { intro, recap, outro } = design.sections;
+    log(`built ${resolve(videoDir, 'index.html')} (template '${template.name}')`);
+    log(`  timeline: intro/${intro.name} 0–${t.intro.duration}s | recording ${t.clipStart}–${t.clipEnd}s (media ${t.mediaStart}–${t.mediaEnd}s) | ` +
+        (recap && t.recap ? `recap/${recap.name} ${t.recap.start}–${round(t.recap.start + t.recap.duration)}s | ` : 'no recap | ') +
+        `outro/${outro.name} ${t.outro.start}–${t.total}s`);
+    if (t.transitions.length) {
+        log(`  hand-off card(s) at ${t.transitions.map((tr) => `${tr.at}s`).join(', ')}`);
+    }
+    log(`  frame ${t.frame.width}x${t.frame.height}, ${t.callouts.length} callout(s), ${result.zooms.length} zoom(s)`);
+    for (const w of result.warnings) {
+        log(`  warning: ${w}`);
+    }
+    return { ...result, versions: { portrait: portrait.timeline, square: square?.timeline ?? null } };
+}
+/** The portrait composition (see `build`). */
+function renderPortrait(demoDir, config, spec, composition, result, assets, log) {
+    const source = spec.portrait ?? 'auto';
+    const phoneTake = resolve(demoDir, 'recording.mobile.mp4');
+    const phoneMarkers = resolve(demoDir, 'markers.mobile.json');
+    const hasPhone = existsSync(phoneTake) && existsSync(phoneMarkers);
+    if (source === 'mobile' && !hasPhone) {
+        log('  warning: video.json "portrait": "mobile", but there is no phone take — run `reelson record <slug> --mobile`; using the desktop camera');
+    }
+    if (source !== 'desktop' && hasPhone) {
+        try {
+            // The same video.json on the phone take: callouts follow their markers; zooms are
+            // numbered by the desktop clicks, so they don't apply.
+            const markers = JSON.parse(readFileSync(phoneMarkers, 'utf8'));
+            const phone = planSpec(demoDir, { ...spec, zooms: [] }, markers, config);
+            copyIfChanged(phoneTake, resolve(assets, 'recording.mobile.mp4'));
+            const narration = extractNarration(phoneTake, resolve(assets, 'narration.mobile.m4a'), phone.timeline, () => { });
+            const voice = voiceTrack(demoDir, config, spec, phone.timeline, resolve(assets, 'voice.mobile.m4a'), () => { });
+            const music = renderMusicBed(spec, config, phone.timeline, resolve(assets, 'music.mobile.m4a'), narration || voice, () => { });
+            const layout = phoneLayout(phone.timeline);
+            log(`  portrait: the phone take (${markers.viewport.width}x${markers.viewport.height}), ${phone.timeline.total}s`);
+            const html = renderComposition({
+                ...composition,
+                timeline: phone.timeline,
+                layout: layout.layout,
+                cursor: layout.cursor,
+                zooms: [],
+                narration,
+                music,
+                voice,
+                media: {
+                    recording: 'assets/recording.mobile.mp4',
+                    narration: 'assets/narration.mobile.m4a',
+                    music: 'assets/music.mobile.m4a',
+                    voice: 'assets/voice.mobile.m4a',
+                },
+                text: {
+                    ...composition.text,
+                    stepsChip: countLabel(phone.timeline.callouts.length, config.strings.stepsLabel, config.language),
+                    secondsChip: countLabel(Math.round(phone.timeline.total), config.strings.secondsLabel, config.language),
+                },
+            });
+            return { html, timeline: phone.timeline };
+        }
+        catch (error) {
+            log(`  warning: the phone take does not fit video.json (${error.message}) — portrait uses the desktop camera`);
+        }
+    }
+    const camera = portraitLayout(result.timeline);
+    return { html: renderComposition({ ...composition, layout: camera.layout, cursor: camera.cursor, zooms: camera.zooms }), timeline: result.timeline };
+}
+/**
+ * The square composition (see `build`), or null without a square take (or one that no longer
+ * fits video.json).
+ */
+function renderSquare(demoDir, config, spec, composition, result, assets, log) {
+    const take = resolve(demoDir, 'recording.square.mp4');
+    const takeMarkers = resolve(demoDir, 'markers.square.json');
+    if (!existsSync(take) || !existsSync(takeMarkers)) {
+        return null;
+    }
+    try {
+        // The same video.json on the square take: callouts follow their markers. Zooms are
+        // anchored by click number, so they carry over only while the clicks match.
+        const markers = JSON.parse(readFileSync(takeMarkers, 'utf8'));
+        const clicks = markers.clicks?.length ?? 0;
+        const desktopClicks = result.markers.clicks?.length ?? 0;
+        const sameClicks = clicks === desktopClicks;
+        if (!sameClicks && spec.zooms?.length) {
+            log(`  warning: the square take has ${clicks} click(s), the desktop take ${desktopClicks} — the square video leaves out the zooms`);
+        }
+        const plan = planSpec(demoDir, sameClicks ? spec : { ...spec, zooms: [] }, markers, config);
+        copyIfChanged(take, resolve(assets, 'recording.square.mp4'));
+        const narration = extractNarration(take, resolve(assets, 'narration.square.m4a'), plan.timeline, () => { });
+        const voice = voiceTrack(demoDir, config, spec, plan.timeline, resolve(assets, 'voice.square.m4a'), () => { });
+        const music = renderMusicBed(spec, config, plan.timeline, resolve(assets, 'music.square.m4a'), narration || voice, () => { });
+        const layout = squareLayout(plan.timeline);
+        log(`  square: the square take (${markers.viewport.width}x${markers.viewport.height}), ${plan.timeline.total}s`);
+        const html = renderComposition({
+            ...composition,
+            timeline: plan.timeline,
+            layout: layout.layout,
+            cursor: layout.cursor,
+            zooms: plan.zooms,
+            narration,
+            music,
+            voice,
+            media: {
+                recording: 'assets/recording.square.mp4',
+                narration: 'assets/narration.square.m4a',
+                music: 'assets/music.square.m4a',
+                voice: 'assets/voice.square.m4a',
+            },
+            text: {
+                ...composition.text,
+                stepsChip: countLabel(plan.timeline.callouts.length, config.strings.stepsLabel, config.language),
+                secondsChip: countLabel(Math.round(plan.timeline.total), config.strings.secondsLabel, config.language),
+            },
+        });
+        return { html, timeline: plan.timeline };
+    }
+    catch (error) {
+        log(`  warning: the square take does not fit video.json (${error.message}) — re-record it: \`reelson record ${basename(demoDir)} --square\``);
+        return null;
+    }
+}
+/** The voice-over track for one version (see voice.ts); false when the video has none. */
+function voiceTrack(demoDir, config, spec, t, target, log) {
+    const settings = voiceSettings(spec, config);
+    if (!settings) {
+        return false;
+    }
+    return renderVoiceTrack(voiceLines(t, spec, settings), settings, resolve(demoDir, 'voice'), t.total, target, log);
+}
+function applyOptions(spec, o) {
+    if (o.title !== undefined)
+        spec.title = o.title;
+    if (o.subtitle !== undefined)
+        spec.subtitle = o.subtitle;
+    if (o.template !== undefined)
+        spec.template = o.template;
+    if (o.sections && Object.keys(o.sections).length)
+        spec.sections = { ...spec.sections, ...o.sections };
+    if (o.trimStart !== undefined)
+        spec.trim = { ...spec.trim, start: o.trimStart };
+    if (o.trimEnd !== undefined)
+        spec.trim = { ...spec.trim, end: o.trimEnd };
+    if (o.music !== undefined)
+        spec.music = o.music;
+}
+function humanize(slug) {
+    const words = slug.replace(/[-_]+/g, ' ').trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** video.json as the build writes it: `$schema` first, then a stable, readable key order. */
+export function serializeVideoSpec(spec, demoDir, config) {
+    return JSON.stringify({ $schema: videoSchemaRef(demoDir, config), ...withoutSchema(spec) }, null, 4) + '\n';
+}
+/** video.json in a stable, readable key order, without `$schema` (re-added on write). */
+function withoutSchema(spec) {
+    const { $schema: _ignored, ...rest } = spec;
+    const order = ['title', 'subtitle', 'template', 'sections', 'recapTitle', 'brand', 'trim', 'music', 'callouts', 'zooms', 'cursor', 'voice', 'portrait', 'formats'];
+    const known = order.filter((k) => rest[k] !== undefined).map((k) => [k, rest[k]]);
+    const others = Object.entries(rest).filter(([k]) => !order.includes(k));
+    return Object.fromEntries([...known, ...others]);
+}
+const LOGO_TYPES = ['.svg', '.png', '.webp'];
+/**
+ * brand.logo (video.json over demo.config.json) → assets/brand-logo.<ext>. Returns its
+ * path for the composition, or '' when the brand is drawn as a text wordmark.
+ */
+function copyLogo(spec, config, assets, log) {
+    const file = spec.brand?.logo !== undefined ? spec.brand.logo : config.brand.logo;
+    if (!file) {
+        return '';
+    }
+    const source = fromRoot(config, file);
+    const ext = extname(source).toLowerCase();
+    if (!LOGO_TYPES.includes(ext)) {
+        throw new ReelsonError(`brand.logo must be ${LOGO_TYPES.join(', ')} (SVG stays sharpest), got ${source}`);
+    }
+    if (!existsSync(source)) {
+        throw new ReelsonError(`brand logo not found: ${source} — fix brand.logo, or set it to null for the text wordmark`);
+    }
+    const height = ext === '.png' ? pngHeight(source) : null;
+    if (height !== null && height < MIN_LOGO_HEIGHT) {
+        log(`  warning: ${basename(source)} is ${height}px tall — under ${MIN_LOGO_HEIGHT}px it looks soft on the cards; use an SVG or a taller PNG`);
+    }
+    const name = `brand-logo${ext}`;
+    copyIfChanged(source, resolve(assets, name));
+    return `assets/${name}`;
+}
+/** The biggest wordmark (168px tall on the outro) at 2x, so the logo stays crisp. */
+const MIN_LOGO_HEIGHT = 340;
+function pngHeight(path) {
+    const header = readFileSync(path).subarray(0, 24);
+    return header.toString('ascii', 12, 16) === 'IHDR' ? header.readUInt32BE(20) : null;
+}
+function copyIfChanged(from, to) {
+    if (existsSync(to)) {
+        const a = statSync(from);
+        const b = statSync(to);
+        if (a.size === b.size && b.mtimeMs >= a.mtimeMs) {
+            return;
+        }
+    }
+    copyFileSync(from, to);
+}
+/** Extracts the recording's audio track (OpenScreen voiceover), if any. */
+function extractNarration(source, target, t, log) {
+    const probe = spawnSync('ffprobe', ['-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=codec_name', '-of', 'csv=p=0', source], { encoding: 'utf8' });
+    if (probe.status !== 0 || probe.stdout.trim() === '') {
+        return false;
+    }
+    if (t.transitions.length) {
+        log('  warning: narration is not split at hand-offs; it drifts after the first transition card');
+    }
+    if (existsSync(target) && statSync(target).mtimeMs >= statSync(source).mtimeMs) {
+        return true;
+    }
+    const extract = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', source, '-vn', '-c:a', 'aac', '-b:a', '160k', target], {
+        stdio: 'inherit',
+    });
+    if (extract.status !== 0) {
+        log('  warning: ffmpeg could not extract the audio track; continuing without narration');
+        return false;
+    }
+    log('  audio track found — narration extracted to assets/narration.m4a');
+    return true;
+}
+/**
+ * Pre-renders the music bed with ffmpeg (trim, loudnorm, fades) so the
+ * composition plays it at unity. Cached: re-rendered only when the source,
+ * length or loudness changes.
+ */
+function renderMusicBed(spec, config, t, target, underNarration, log) {
+    const choice = spec.music ?? null;
+    if (choice === false) {
+        return false;
+    }
+    const file = typeof choice === 'string' ? choice : config.music.file;
+    if (!file) {
+        log('  no music: set music.file in demo.config.json (or "music" in video.json)');
+        return false;
+    }
+    const source = fromRoot(config, file);
+    if (!existsSync(source)) {
+        throw new ReelsonError(`music not found: ${source} — fix music.file / video.json "music", or set "music": false`);
+    }
+    const lufs = underNarration ? config.music.lufsUnderNarration : config.music.lufs;
+    const fadeOut = 3;
+    const key = JSON.stringify({ source, mtime: statSync(source).mtimeMs, total: t.total, lufs });
+    const stamp = `${target}.key`;
+    if (existsSync(target) && existsSync(stamp) && readFileSync(stamp, 'utf8') === key) {
+        return true;
+    }
+    const filters = [
+        `atrim=0:${t.total}`,
+        `loudnorm=I=${lufs}:TP=-3:LRA=9`,
+        'afade=t=in:st=0:d=0.8',
+        `afade=t=out:st=${round(t.total - fadeOut)}:d=${fadeOut}`,
+    ].join(',');
+    const render = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', source, '-vn', '-af', filters, '-c:a', 'aac', '-b:a', '160k', target], { stdio: 'inherit' });
+    if (render.status !== 0) {
+        throw new ReelsonError('ffmpeg could not render the music bed');
+    }
+    writeFileSync(stamp, key);
+    log(`  music bed: ${basename(source)} → assets/music.m4a (${lufs} LUFS, fades 0.8s/${fadeOut}s)`);
+    return true;
+}