@bitmagic/cli 0.1.61-dev.0 → 0.1.61-dev.1

package/dist/trailer/synth.js

@@ -0,0 +1,120 @@
+/**
+ * Pure-TypeScript sound synthesizer for timeline synth recipes.
+ *
+ * Renders a SynthRecipe to 48kHz mono 16-bit PCM WAV: layers are summed,
+ * [start, end] freq/gain values ramp linearly, the mix is clamped to [-1, 1]
+ * and a ~5ms linear fade-in/out avoids clicks. No audio libraries; the WAV
+ * header is written by hand. Output is fully deterministic (seeded noise) so
+ * recipe-hash-named cache files are reproducible.
+ */
+import { createHash } from 'crypto';
+export const SYNTH_SAMPLE_RATE = 48000;
+const FADE_SEC = 0.005;
+const NOISE_SEED = 0x9e3779b9;
+/** Deterministic PRNG (mulberry32) so noise layers render identically every run. */
+function mulberry32(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function interp(value, fallback, progress) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'number')
+        return value;
+    return value[0] + (value[1] - value[0]) * progress;
+}
+function layerSamples(layer, sampleCount) {
+    const buf = new Float64Array(sampleCount);
+    const wave = layer.wave;
+    const rand = mulberry32(NOISE_SEED);
+    // Phase in cycles, accumulated per sample so frequency ramps chirp smoothly.
+    let phase = 0;
+    for (let i = 0; i < sampleCount; i++) {
+        const progress = sampleCount > 1 ? i / (sampleCount - 1) : 0;
+        const gain = interp(layer.gain, 1, progress);
+        let value;
+        if (wave === 'noise') {
+            value = rand() * 2 - 1;
+        }
+        else {
+            const frac = phase - Math.floor(phase);
+            switch (wave) {
+                case 'sine':
+                    value = Math.sin(2 * Math.PI * phase);
+                    break;
+                case 'square':
+                    value = frac < 0.5 ? 1 : -1;
+                    break;
+                case 'sawtooth':
+                    value = 2 * frac - 1;
+                    break;
+                case 'triangle':
+                    value = 1 - 4 * Math.abs(frac - 0.5);
+                    break;
+            }
+            phase += interp(layer.freq, 440, progress) / SYNTH_SAMPLE_RATE;
+        }
+        buf[i] = value * gain;
+    }
+    return buf;
+}
+/** Render a recipe to mono float samples in [-1, 1], faded at both ends. */
+export function synthesizeSamples(recipe) {
+    const sampleCount = Math.max(1, Math.round(recipe.dur * SYNTH_SAMPLE_RATE));
+    const mix = new Float64Array(sampleCount);
+    for (const layer of recipe.layers) {
+        const layerBuf = layerSamples(layer, sampleCount);
+        for (let i = 0; i < sampleCount; i++)
+            mix[i] += layerBuf[i];
+    }
+    const fadeSamples = Math.min(Math.round(FADE_SEC * SYNTH_SAMPLE_RATE), Math.floor(sampleCount / 2));
+    const result = new Float32Array(sampleCount);
+    for (let i = 0; i < sampleCount; i++) {
+        let v = Math.max(-1, Math.min(1, mix[i]));
+        if (fadeSamples > 0) {
+            if (i < fadeSamples)
+                v *= i / fadeSamples;
+            const fromEnd = sampleCount - 1 - i;
+            if (fromEnd < fadeSamples)
+                v *= fromEnd / fadeSamples;
+        }
+        result[i] = v;
+    }
+    return result;
+}
+/** Encode mono float samples as a 48kHz 16-bit PCM WAV file. */
+export function samplesToWav(samples) {
+    const dataSize = samples.length * 2;
+    const buffer = Buffer.alloc(44 + dataSize);
+    buffer.write('RIFF', 0, 'ascii');
+    buffer.writeUInt32LE(36 + dataSize, 4);
+    buffer.write('WAVE', 8, 'ascii');
+    buffer.write('fmt ', 12, 'ascii');
+    buffer.writeUInt32LE(16, 16); // fmt chunk size
+    buffer.writeUInt16LE(1, 20); // PCM
+    buffer.writeUInt16LE(1, 22); // mono
+    buffer.writeUInt32LE(SYNTH_SAMPLE_RATE, 24);
+    buffer.writeUInt32LE(SYNTH_SAMPLE_RATE * 2, 28); // byte rate
+    buffer.writeUInt16LE(2, 32); // block align
+    buffer.writeUInt16LE(16, 34); // bits per sample
+    buffer.write('data', 36, 'ascii');
+    buffer.writeUInt32LE(dataSize, 40);
+    for (let i = 0; i < samples.length; i++) {
+        buffer.writeInt16LE(Math.round(samples[i] * 32767), 44 + i * 2);
+    }
+    return buffer;
+}
+export function synthesizeWav(recipe) {
+    return samplesToWav(synthesizeSamples(recipe));
+}
+/** Stable cache key for a recipe (16 hex chars of sha256 over its JSON). */
+export function recipeHash(recipe) {
+    return createHash('sha256').update(JSON.stringify(recipe)).digest('hex').slice(0, 16);
+}
+//# sourceMappingURL=synth.js.map

package/dist/trailer/synth.js.map

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

package/dist/trailer/timeline-types.d.ts

@@ -0,0 +1,176 @@
+import type { TitleCue } from './titles.js';
+export interface FrameClockEntry {
+    frame: number;
+    wallMs: number;
+}
+export interface TimelineRecording {
+    /** Frame files are named `<name>_%06d.png`, indexed from 0. */
+    name: string;
+    gameId?: string;
+    genre?: string;
+    width: number;
+    height: number;
+    fps: number;
+    frameCount: number;
+    /** Frame indices whose PNG failed to save; may be absent or empty. */
+    missingFrames?: number[];
+    /** Ignored in v1. */
+    frameClock?: FrameClockEntry[];
+}
+export interface TimelineEvent {
+    frame: number;
+    type: string;
+    intensity?: number;
+    position?: number[];
+    actor?: string;
+    data?: Record<string, unknown>;
+}
+export type SynthWave = 'sine' | 'square' | 'sawtooth' | 'triangle' | 'noise';
+export interface SynthLayer {
+    wave: SynthWave;
+    /** Constant Hz or [start, end] linear ramp. Ignored for 'noise'. */
+    freq?: number | [number, number];
+    /** Constant gain or [start, end] linear ramp. Default 1. */
+    gain?: number | [number, number];
+}
+export interface SynthRecipe {
+    /** Duration in seconds. */
+    dur: number;
+    layers: SynthLayer[];
+}
+export interface AssetSound {
+    frame: number;
+    kind: 'asset';
+    assetId: string;
+    url: string;
+    volume?: number;
+}
+export interface SynthSound {
+    frame: number;
+    kind: 'synth';
+    name?: string;
+    recipe: SynthRecipe;
+    volume?: number;
+}
+export type TimelineSound = AssetSound | SynthSound;
+export type HudElementKind = 'counter' | 'progress' | 'icon-text' | 'timer' | 'custom';
+/**
+ * Recorded HUD state changes (the engine's `TimelineHudOp`). Frames use the
+ * recording's source clock. Elements that existed before the recording started
+ * are emitted as frame-0 `create` ops, so frame 0 is always a complete
+ * snapshot, and array order within a frame is stacking order in an anchor.
+ *
+ * `update` carries already-rendered text, so the replay never applies a game's
+ * `format` callback. Timers are the exception — they log start/pause/reset
+ * only and the displayed value is derived (see hud-state.ts).
+ */
+export type HudOp = {
+    frame: number;
+    op: 'create';
+    id: string;
+    elType: HudElementKind;
+    params: Record<string, unknown>;
+} | {
+    frame: number;
+    op: 'update';
+    id: string;
+    text?: string;
+    icon?: string;
+    percent?: number;
+} | {
+    frame: number;
+    op: 'custom-html';
+    id: string;
+    html: string;
+} | {
+    frame: number;
+    op: 'timer';
+    id: string;
+    action: 'start' | 'pause' | 'reset';
+    seconds?: number;
+} | {
+    frame: number;
+    op: 'show' | 'hide' | 'remove';
+    id: string;
+} | {
+    frame: number;
+    op: 'health';
+    current: number;
+    max: number;
+} | {
+    frame: number;
+    op: 'health-visible';
+    visible: boolean;
+} | {
+    frame: number;
+    op: 'toast';
+    message: string;
+    variant?: string;
+    durationMs?: number;
+} | {
+    frame: number;
+    op: 'hud-visible';
+    visible: boolean;
+} | {
+    frame: number;
+    op: 'theme';
+    theme: unknown;
+};
+export interface Timeline {
+    version: number;
+    recording: TimelineRecording;
+    events: TimelineEvent[];
+    sounds: TimelineSound[];
+    /** HUD state changes; absent/empty when the recording captured no HUD. */
+    hud: HudOp[];
+}
+export interface EdlClip {
+    /** Source frame index, inclusive. */
+    in: number;
+    /** Source frame index, exclusive. */
+    out: number;
+    /** Playback speed 0.25–2.0; default 1.0 (0.5 = slow-mo). */
+    speed?: number;
+    /** Transition between the PREVIOUS clip and this one; first clip's is ignored. */
+    transition?: 'cut' | 'crossfade';
+    /** Crossfade length in seconds; default 0.25. */
+    transitionDuration?: number;
+    label?: string;
+    /** Draw the recorded HUD over this clip. Overrides the global --ui flag. */
+    ui?: boolean;
+}
+export interface Edl {
+    version: number;
+    /** Informational only. */
+    targetDuration?: number;
+    clips: EdlClip[];
+    /** Burned-in title cards, timed in OUTPUT seconds. */
+    titles?: TitleCue[];
+}
+export interface AnalysisWindow {
+    startFrame: number;
+    endFrame: number;
+    score: number;
+    /** Compact digest lines, e.g. "f3121 explosion i0.9". */
+    events: string[];
+    /** Path relative to the recording dir, e.g. "sheets/window_00.png". */
+    sheet: string;
+}
+export interface Analysis {
+    version: number;
+    fps: number;
+    frameCount: number;
+    windows: AnalysisWindow[];
+}
+export declare function frameFileName(recordingName: string, frame: number): string;
+export declare function frameFilePath(recordingDir: string, recordingName: string, frame: number): string;
+export declare function parseRecipe(raw: unknown, ctx: string): SynthRecipe;
+/**
+ * Parse the hud[] track. Skipped entries are reported (grouped by op name) so
+ * a forward-compatible skip is never silent.
+ */
+export declare function parseHudOps(raw: unknown, source: string): HudOp[];
+export declare function parseTimeline(raw: unknown, source: string): Timeline;
+export declare function loadTimeline(recordingDir: string): Timeline;
+export declare function parseEdl(raw: unknown, source: string): Edl;
+export declare function loadEdl(filePath: string): Edl;

package/dist/trailer/timeline-types.js

@@ -0,0 +1,379 @@
+/**
+ * Stable JSON contracts for the trailer pipeline plus validating loaders.
+ *
+ * timeline.json / edl.json are inputs written by the game engine and an AI
+ * editor respectively; analysis.json is our output. Loaders validate with
+ * type guards and throw descriptive errors — never silently coerce.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+import { warn } from './io.js';
+// ---------------------------------------------------------------------------
+// Frame file naming
+// ---------------------------------------------------------------------------
+export function frameFileName(recordingName, frame) {
+    return `${recordingName}_${String(frame).padStart(6, '0')}.png`;
+}
+export function frameFilePath(recordingDir, recordingName, frame) {
+    return path.join(recordingDir, frameFileName(recordingName, frame));
+}
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asNumber(value, ctx) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`${ctx}: expected a finite number, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function asString(value, ctx) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${ctx}: expected a non-empty string, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseNumOrRamp(value, ctx) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value) && value.length === 2) {
+        const [a, b] = value;
+        if (typeof a === 'number' && Number.isFinite(a) && typeof b === 'number' && Number.isFinite(b)) {
+            return [a, b];
+        }
+    }
+    throw new Error(`${ctx}: expected a number or a [start, end] pair`);
+}
+function readJson(filePath) {
+    if (!fs.existsSync(filePath))
+        throw new CliError(`File not found: ${filePath}`);
+    const text = fs.readFileSync(filePath, 'utf-8');
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new CliError(`Invalid JSON in ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// timeline.json parsing
+// ---------------------------------------------------------------------------
+const SYNTH_WAVES = ['sine', 'square', 'sawtooth', 'triangle', 'noise'];
+function isSynthWave(value) {
+    return typeof value === 'string' && SYNTH_WAVES.includes(value);
+}
+export function parseRecipe(raw, ctx) {
+    if (!isRecord(raw))
+        throw new Error(`${ctx}: expected an object`);
+    const dur = asNumber(raw.dur, `${ctx}.dur`);
+    if (dur <= 0)
+        throw new Error(`${ctx}.dur: must be > 0, got ${dur}`);
+    if (!Array.isArray(raw.layers) || raw.layers.length === 0) {
+        throw new Error(`${ctx}.layers: expected a non-empty array`);
+    }
+    const layers = raw.layers.map((layerRaw, i) => parseLayer(layerRaw, `${ctx}.layers[${i}]`));
+    return { dur, layers };
+}
+function parseLayer(raw, ctx) {
+    if (!isRecord(raw))
+        throw new Error(`${ctx}: expected an object`);
+    if (!isSynthWave(raw.wave)) {
+        throw new Error(`${ctx}.wave: expected one of ${SYNTH_WAVES.join(', ')}, got ${JSON.stringify(raw.wave)}`);
+    }
+    const layer = { wave: raw.wave };
+    if (raw.freq !== undefined)
+        layer.freq = parseNumOrRamp(raw.freq, `${ctx}.freq`);
+    if (raw.gain !== undefined)
+        layer.gain = parseNumOrRamp(raw.gain, `${ctx}.gain`);
+    return layer;
+}
+function parseEvent(raw, ctx) {
+    if (!isRecord(raw))
+        throw new Error(`${ctx}: expected an object`);
+    const event = {
+        frame: asNumber(raw.frame, `${ctx}.frame`),
+        type: asString(raw.type, `${ctx}.type`)
+    };
+    if (raw.intensity !== undefined)
+        event.intensity = asNumber(raw.intensity, `${ctx}.intensity`);
+    if (Array.isArray(raw.position) && raw.position.every((v) => typeof v === 'number')) {
+        event.position = raw.position;
+    }
+    if (typeof raw.actor === 'string')
+        event.actor = raw.actor;
+    if (isRecord(raw.data))
+        event.data = raw.data;
+    return event;
+}
+function parseSound(raw, ctx) {
+    if (!isRecord(raw))
+        throw new Error(`${ctx}: expected an object`);
+    const frame = asNumber(raw.frame, `${ctx}.frame`);
+    const volume = raw.volume !== undefined ? asNumber(raw.volume, `${ctx}.volume`) : undefined;
+    if (raw.kind === 'asset') {
+        const sound = {
+            frame,
+            kind: 'asset',
+            assetId: asString(raw.assetId, `${ctx}.assetId`),
+            url: asString(raw.url, `${ctx}.url`)
+        };
+        if (volume !== undefined)
+            sound.volume = volume;
+        return sound;
+    }
+    if (raw.kind === 'synth') {
+        const sound = {
+            frame,
+            kind: 'synth',
+            recipe: parseRecipe(raw.recipe, `${ctx}.recipe`)
+        };
+        if (typeof raw.name === 'string')
+            sound.name = raw.name;
+        if (volume !== undefined)
+            sound.volume = volume;
+        return sound;
+    }
+    throw new Error(`${ctx}.kind: expected "asset" or "synth", got ${JSON.stringify(raw.kind)}`);
+}
+const HUD_ELEMENT_KINDS = ['counter', 'progress', 'icon-text', 'timer', 'custom'];
+function isHudElementKind(value) {
+    return typeof value === 'string' && HUD_ELEMENT_KINDS.includes(value);
+}
+function optString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function optFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Parse one hud[] entry. Returns null for a malformed entry or an op name this
+ * build predates — the track is forward-compatible by design, so an unknown op
+ * is skipped (and counted by the caller), never fatal.
+ */
+function parseHudOp(raw) {
+    if (!isRecord(raw))
+        return null;
+    const frame = optFiniteNumber(raw.frame);
+    if (frame === undefined)
+        return null;
+    const id = optString(raw.id);
+    switch (raw.op) {
+        case 'create': {
+            if (id === undefined || !isHudElementKind(raw.elType))
+                return null;
+            return { frame, op: 'create', id, elType: raw.elType, params: isRecord(raw.params) ? raw.params : {} };
+        }
+        case 'update': {
+            if (id === undefined)
+                return null;
+            const op = { frame, op: 'update', id };
+            const text = optString(raw.text);
+            const icon = optString(raw.icon);
+            const percent = optFiniteNumber(raw.percent);
+            if (text !== undefined)
+                op.text = text;
+            if (icon !== undefined)
+                op.icon = icon;
+            if (percent !== undefined)
+                op.percent = percent;
+            return op;
+        }
+        case 'custom-html': {
+            const html = optString(raw.html);
+            if (id === undefined || html === undefined)
+                return null;
+            return { frame, op: 'custom-html', id, html };
+        }
+        case 'timer': {
+            if (id === undefined)
+                return null;
+            if (raw.action !== 'start' && raw.action !== 'pause' && raw.action !== 'reset')
+                return null;
+            const op = { frame, op: 'timer', id, action: raw.action };
+            const seconds = optFiniteNumber(raw.seconds);
+            if (seconds !== undefined)
+                op.seconds = seconds;
+            return op;
+        }
+        case 'show':
+        case 'hide':
+        case 'remove':
+            return id === undefined ? null : { frame, op: raw.op, id };
+        case 'health': {
+            const current = optFiniteNumber(raw.current);
+            const max = optFiniteNumber(raw.max);
+            if (current === undefined || max === undefined)
+                return null;
+            return { frame, op: 'health', current, max };
+        }
+        case 'health-visible':
+        case 'hud-visible':
+            return typeof raw.visible === 'boolean' ? { frame, op: raw.op, visible: raw.visible } : null;
+        case 'toast': {
+            const message = optString(raw.message);
+            if (message === undefined)
+                return null;
+            const op = { frame, op: 'toast', message };
+            const variant = optString(raw.variant);
+            const durationMs = optFiniteNumber(raw.durationMs);
+            if (variant !== undefined)
+                op.variant = variant;
+            if (durationMs !== undefined)
+                op.durationMs = durationMs;
+            return op;
+        }
+        case 'theme':
+            return { frame, op: 'theme', theme: raw.theme };
+        default:
+            return null;
+    }
+}
+/**
+ * Parse the hud[] track. Skipped entries are reported (grouped by op name) so
+ * a forward-compatible skip is never silent.
+ */
+export function parseHudOps(raw, source) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error(`${source}: "hud" must be an array`);
+    const ops = [];
+    const skipped = new Map();
+    for (const entry of raw) {
+        const parsed = parseHudOp(entry);
+        if (parsed === null) {
+            const name = isRecord(entry) && typeof entry.op === 'string' ? entry.op : '<malformed>';
+            skipped.set(name, (skipped.get(name) ?? 0) + 1);
+            continue;
+        }
+        ops.push(parsed);
+    }
+    if (skipped.size > 0) {
+        const detail = [...skipped.entries()].map(([name, count]) => `${name} x${count}`).join(', ');
+        warn(`${source}: skipped ${[...skipped.values()].reduce((a, b) => a + b, 0)} unsupported hud op(s): ${detail}`);
+    }
+    return ops;
+}
+export function parseTimeline(raw, source) {
+    if (!isRecord(raw))
+        throw new Error(`${source}: expected a JSON object`);
+    if (!isRecord(raw.recording))
+        throw new Error(`${source}: missing "recording" object`);
+    const rec = raw.recording;
+    const recording = {
+        name: asString(rec.name, `${source}: recording.name`),
+        width: asNumber(rec.width, `${source}: recording.width`),
+        height: asNumber(rec.height, `${source}: recording.height`),
+        fps: asNumber(rec.fps, `${source}: recording.fps`),
+        frameCount: asNumber(rec.frameCount, `${source}: recording.frameCount`)
+    };
+    if (recording.fps <= 0)
+        throw new Error(`${source}: recording.fps must be > 0`);
+    if (recording.frameCount <= 0)
+        throw new Error(`${source}: recording.frameCount must be > 0`);
+    if (typeof rec.gameId === 'string')
+        recording.gameId = rec.gameId;
+    if (typeof rec.genre === 'string')
+        recording.genre = rec.genre;
+    if (rec.missingFrames !== undefined) {
+        if (!Array.isArray(rec.missingFrames) || !rec.missingFrames.every((v) => Number.isInteger(v))) {
+            throw new Error(`${source}: recording.missingFrames must be an array of integers`);
+        }
+        recording.missingFrames = rec.missingFrames;
+    }
+    const eventsRaw = raw.events ?? [];
+    if (!Array.isArray(eventsRaw))
+        throw new Error(`${source}: "events" must be an array`);
+    const events = eventsRaw.map((e, i) => parseEvent(e, `${source}: events[${i}]`));
+    const soundsRaw = raw.sounds ?? [];
+    if (!Array.isArray(soundsRaw))
+        throw new Error(`${source}: "sounds" must be an array`);
+    const sounds = soundsRaw.map((s, i) => parseSound(s, `${source}: sounds[${i}]`));
+    return {
+        version: typeof raw.version === 'number' ? raw.version : 1,
+        recording,
+        events,
+        sounds,
+        hud: parseHudOps(raw.hud, source)
+    };
+}
+export function loadTimeline(recordingDir) {
+    const filePath = path.join(recordingDir, 'timeline.json');
+    return parseTimeline(readJson(filePath), filePath);
+}
+// ---------------------------------------------------------------------------
+// edl.json parsing
+// ---------------------------------------------------------------------------
+function parseClip(raw, ctx) {
+    if (!isRecord(raw))
+        throw new Error(`${ctx}: expected an object`);
+    const clip = {
+        in: asNumber(raw.in, `${ctx}.in`),
+        out: asNumber(raw.out, `${ctx}.out`)
+    };
+    if (raw.speed !== undefined)
+        clip.speed = asNumber(raw.speed, `${ctx}.speed`);
+    if (raw.transition !== undefined) {
+        if (raw.transition !== 'cut' && raw.transition !== 'crossfade') {
+            throw new Error(`${ctx}.transition: expected "cut" or "crossfade", got ${JSON.stringify(raw.transition)}`);
+        }
+        clip.transition = raw.transition;
+    }
+    if (raw.transitionDuration !== undefined) {
+        clip.transitionDuration = asNumber(raw.transitionDuration, `${ctx}.transitionDuration`);
+    }
+    if (typeof raw.label === 'string')
+        clip.label = raw.label;
+    if (raw.ui !== undefined) {
+        if (typeof raw.ui !== 'boolean')
+            throw new Error(`${ctx}.ui: expected a boolean, got ${JSON.stringify(raw.ui)}`);
+        clip.ui = raw.ui;
+    }
+    return clip;
+}
+function parseTitle(raw, source) {
+    if (!isRecord(raw))
+        throw new Error(`${source}: expected an object`);
+    if (typeof raw.at !== 'number' || raw.at < 0)
+        throw new Error(`${source}: "at" must be a non-negative number of seconds`);
+    if (typeof raw.dur !== 'number' || raw.dur <= 0)
+        throw new Error(`${source}: "dur" must be a positive number of seconds`);
+    if (typeof raw.text !== 'string' || raw.text.length === 0)
+        throw new Error(`${source}: "text" must be a non-empty string`);
+    const cue = { at: raw.at, dur: raw.dur, text: raw.text };
+    if (typeof raw.sub === 'string')
+        cue.sub = raw.sub;
+    if (typeof raw.note === 'string')
+        cue.note = raw.note;
+    if (raw.style !== undefined) {
+        if (raw.style !== 'title' && raw.style !== 'line' && raw.style !== 'card') {
+            throw new Error(`${source}: "style" must be title, line or card`);
+        }
+        cue.style = raw.style;
+    }
+    return cue;
+}
+export function parseEdl(raw, source) {
+    if (!isRecord(raw))
+        throw new Error(`${source}: expected a JSON object`);
+    if (!Array.isArray(raw.clips) || raw.clips.length === 0) {
+        throw new Error(`${source}: "clips" must be a non-empty array`);
+    }
+    const clips = raw.clips.map((c, i) => parseClip(c, `${source}: clips[${i}]`));
+    const edl = { version: typeof raw.version === 'number' ? raw.version : 1, clips };
+    if (typeof raw.targetDuration === 'number')
+        edl.targetDuration = raw.targetDuration;
+    if (raw.titles !== undefined) {
+        if (!Array.isArray(raw.titles))
+            throw new Error(`${source}: "titles" must be an array`);
+        edl.titles = raw.titles.map((t, i) => parseTitle(t, `${source}: titles[${i}]`));
+    }
+    return edl;
+}
+export function loadEdl(filePath) {
+    return parseEdl(readJson(filePath), filePath);
+}
+//# sourceMappingURL=timeline-types.js.map