@bitmagic/cli 0.1.60 → 0.1.61-dev.1

package/dist/trailer/make.js

@@ -0,0 +1,205 @@
+/**
+ * `bitmagic trailer make` — one command from a recording to a rendered trailer, and the SAME
+ * command for every tuning loop after it.
+ *
+ * The pipeline is analyze → music → beats → shots → cut → render (→ publish). Every derived file
+ * lands in the recording's work dir under `.bitmagic/trailer/`; the one authored file is
+ * `trailer/shots.json` at the project root. The first run writes it (the auto cut in auto-edl.ts);
+ * every later run cuts and renders whatever the agent edited, so "make it faster" is: edit the
+ * shots, run `make` again, watch the new `-rN` render.
+ *
+ * Music is never generated silently: `--music-prompt` spends sparks, so it is opt-in, and a bed
+ * generated once is reused on the next run as long as the prompt is unchanged (music.json records
+ * what was asked for).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+import { aliasSourceDir } from '../scaffold/aliases.js';
+import { runAnalyze } from './analyze.js';
+import { buildAutoShots } from './auto-edl.js';
+import { cutShots, describeCut, loadShots } from './beat-cut.js';
+import { out, warn } from './io.js';
+import { analyzeBeats } from './music-beats.js';
+import { shotsPath, trailerSlug, workDir } from './paths.js';
+import { runRender } from './render.js';
+import { loadTimeline } from './timeline-types.js';
+export const DEFAULT_TRAILER_SECONDS = 30;
+/** Music runs a little past the cut so the fade-out has material. */
+export const MUSIC_TAIL_SEC = 4;
+/** The render's music/SFX balance the make-trailer skill settled on. */
+export const MAKE_MUSIC_GAIN_DB = -4;
+export const MAKE_SFX_GAIN_DB = -3;
+/** The game's name as the work copy knows it, for the end card and the file name. */
+export function gameNameFor(root) {
+    const gameJson = path.join(root, aliasSourceDir('work'), 'game.json');
+    try {
+        const parsed = JSON.parse(fs.readFileSync(gameJson, 'utf-8'));
+        if (typeof parsed === 'object' && parsed !== null) {
+            const name = parsed.name;
+            if (typeof name === 'string' && name.trim().length > 0)
+                return name.trim();
+        }
+    }
+    catch {
+        // No work copy or no name in it — the directory name is the honest fallback.
+    }
+    return path.basename(root);
+}
+function newerThan(a, b) {
+    return fs.existsSync(a) && fs.existsSync(b) && fs.statSync(a).mtimeMs >= fs.statSync(b).mtimeMs;
+}
+function readAnalysis(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (typeof parsed === 'object' && parsed !== null && Array.isArray(parsed.windows)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through: re-analyze.
+    }
+    return null;
+}
+/**
+ * The music bed: a file the creator supplied, a bed generated from a prompt (reused while the
+ * prompt is unchanged), or none.
+ */
+async function resolveMusic(options, work, seconds) {
+    if (options.music !== undefined) {
+        const resolved = path.resolve(options.music);
+        if (!fs.existsSync(resolved))
+            throw new CliError(`Music file not found: ${resolved}`);
+        return resolved;
+    }
+    if (options.musicPrompt === undefined)
+        return undefined;
+    if (options.generateMusic === undefined) {
+        throw new CliError('Music generation is not available in this build — pass --music <file> instead.');
+    }
+    const musicPath = path.join(work, 'music.mp3');
+    const recordPath = path.join(work, 'music.json');
+    const wanted = { prompt: options.musicPrompt, seconds: seconds + MUSIC_TAIL_SEC, at: '' };
+    if (fs.existsSync(musicPath) && fs.existsSync(recordPath)) {
+        try {
+            const previous = JSON.parse(fs.readFileSync(recordPath, 'utf-8'));
+            if (previous.prompt === wanted.prompt && previous.seconds === wanted.seconds) {
+                out(`music: reusing the bed generated earlier for this prompt (${path.basename(musicPath)})`);
+                return musicPath;
+            }
+        }
+        catch {
+            // Unreadable record: generate again.
+        }
+    }
+    out(`music: generating a ${wanted.seconds}s bed — "${wanted.prompt}"`);
+    await options.generateMusic(wanted.prompt, wanted.seconds, musicPath);
+    fs.writeFileSync(recordPath, `${JSON.stringify({ ...wanted, at: new Date().toISOString() }, null, 2)}\n`);
+    return musicPath;
+}
+/**
+ * The shots to cut: the committed file when it belongs to this recording, else a fresh auto cut.
+ * A file cut from ANOTHER recording is kept beside the new one rather than overwritten — its frame
+ * indices mean nothing here, but the labels, order and titles are the creator's work.
+ */
+function resolveShots(options, analysis, recordingName, beats, title) {
+    const file = shotsPath(options.root);
+    if (fs.existsSync(file) && options.resetShots !== true) {
+        const existing = loadShots(file);
+        if (existing.recording === undefined || existing.recording === recordingName) {
+            out(`shots: cutting ${path.relative(options.root, file)} (${existing.shots.length} shots)`);
+            return { shots: existing, written: false };
+        }
+        const kept = path.join(path.dirname(file), `shots.${trailerSlug(existing.recording)}.json`);
+        fs.copyFileSync(file, kept);
+        warn(`shots: ${path.relative(options.root, file)} was cut from recording "${existing.recording}", not this one — ` +
+            `kept it as ${path.relative(options.root, kept)} and writing a fresh first cut.`);
+    }
+    const auto = buildAutoShots({
+        analysis,
+        recordingName,
+        targetSeconds: options.seconds ?? DEFAULT_TRAILER_SECONDS,
+        beats,
+        title,
+        ...(options.sub !== undefined ? { sub: options.sub } : {}),
+        ...(options.ui === true ? { ui: true } : {}),
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(auto, null, 2)}\n`);
+    out(`shots: wrote a first cut to ${path.relative(options.root, file)} (${auto.shots.length} shots) — edit it and run make again to tune`);
+    return { shots: auto, written: true };
+}
+export async function makeTrailer(options) {
+    const recordingDir = options.recordingDir;
+    const timeline = loadTimeline(recordingDir);
+    const recordingName = path.basename(recordingDir);
+    const work = workDir(options.root, recordingName);
+    fs.mkdirSync(work, { recursive: true });
+    const seconds = options.seconds ?? DEFAULT_TRAILER_SECONDS;
+    const title = options.title ?? gameNameFor(options.root);
+    // 1. Analyze (cached while the recording is unchanged — contact sheets are the slow part).
+    const analysisPath = path.join(work, 'analysis.json');
+    let analysis = newerThan(analysisPath, path.join(recordingDir, 'timeline.json')) ? readAnalysis(analysisPath) : null;
+    if (analysis === null) {
+        analysis = await runAnalyze(recordingDir, 3, 24, work);
+    }
+    else {
+        out(`analysis: reusing ${path.relative(options.root, analysisPath)}`);
+    }
+    // 2. Music + beat grid.
+    const musicPath = await resolveMusic(options, work, seconds);
+    let beats = null;
+    let beatsPath;
+    if (musicPath !== undefined) {
+        beats = await analyzeBeats(musicPath);
+        beatsPath = path.join(work, 'beats.json');
+        fs.writeFileSync(beatsPath, `${JSON.stringify(beats, null, 2)}\n`);
+        out(`beats: ${beats.bpm.toFixed(1)} bpm, downbeat at ${beats.beatTimes[beats.downbeatIndex].toFixed(2)}s`);
+    }
+    // 3. Shots → EDL.
+    const { shots, written } = resolveShots(options, analysis, recordingName, beats, title);
+    const cut = cutShots(shots, beats, timeline.recording.fps, { frameCount: timeline.recording.frameCount });
+    if (cut.truncatedAt !== undefined) {
+        warn(`cut: the music ran out before "${cut.truncatedAt}" — the shots after it were dropped`);
+    }
+    const edlPath = path.join(work, 'edl.json');
+    fs.writeFileSync(edlPath, `${JSON.stringify(cut.edl, null, 2)}\n`);
+    out(`cut: ${describeCut(cut, beats)}`);
+    // 4. Render.
+    const render = await runRender(recordingDir, {
+        edlPath,
+        outPath: path.join(work, `${trailerSlug(title)}-trailer.mp4`),
+        ...(options.ui === true ? { ui: true } : {}),
+        ...(options.harnessUrl !== undefined ? { harnessUrl: options.harnessUrl } : {}),
+        ...(musicPath !== undefined && beats !== null
+            ? {
+                musicPath,
+                musicStartSec: beats.beatTimes[beats.downbeatIndex],
+                musicGainDb: MAKE_MUSIC_GAIN_DB,
+                sfxGainDb: MAKE_SFX_GAIN_DB,
+            }
+            : {}),
+    });
+    const result = {
+        recordingDir,
+        recordingName,
+        workDir: work,
+        analysisPath,
+        shotsPath: shotsPath(options.root),
+        shotsWritten: written,
+        edlPath,
+        mp4: render.outPath,
+        durationSec: render.durationSec,
+        clipCount: render.clipCount,
+    };
+    if (musicPath !== undefined)
+        result.musicPath = musicPath;
+    if (beatsPath !== undefined)
+        result.beatsPath = beatsPath;
+    // 5. Publish.
+    if (options.publish !== undefined) {
+        result.published = await options.publish(render.outPath);
+    }
+    return result;
+}
+//# sourceMappingURL=make.js.map

package/dist/trailer/make.js.map

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

package/dist/trailer/merge.d.ts

@@ -0,0 +1,7 @@
+export interface MergeOptions {
+    /** Directory to create. Default "<first>-merged" beside the first input. */
+    outDir?: string;
+    /** Allow inputs whose post-processing state differs. */
+    allowMixedPostFx?: boolean;
+}
+export declare function runMerge(dirs: string[], options?: MergeOptions): void;

package/dist/trailer/merge.js

@@ -0,0 +1,144 @@
+/**
+ * Join several recordings into one that the rest of the toolchain treats as
+ * normal.
+ *
+ * A session often spans multiple sittings — one run for the rain track, another
+ * for the rest — and a trailer wants to cut across all of them. Frames are just
+ * numbered PNGs and every timeline entry is frame-indexed, so merging is
+ * renumbering: run N's frames continue after run N-1's, and its events, sounds,
+ * HUD ops and frame clock shift by the same offset.
+ *
+ * Frames are hard-linked rather than copied, so merging a 30k-frame session
+ * costs kilobytes and leaves the originals untouched (copy is the
+ * cross-filesystem fallback).
+ *
+ * The merge walks the RAW timeline JSON rather than the parsed `Timeline`: the
+ * parser deliberately drops `music[]` and doesn't model the newer manifest
+ * fields, and a merge that silently discarded data would be worse than no
+ * merge. `loadTimeline` still runs first, purely to reject malformed input.
+ *
+ * The guards matter more than the mechanics. Mixing recordings of different
+ * sizes yields a trailer that changes resolution mid-cut; mixing
+ * post-processed footage with the pre-fix kind (no bloom, SSR or tone mapping)
+ * yields one that visibly changes look mid-cut. Both are refused by default.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+import { loadTimeline } from './timeline-types.js';
+import { out, warn } from './io.js';
+/** Frame-indexed arrays that must shift when a run is appended. */
+const FRAME_INDEXED_TRACKS = ['events', 'sounds', 'music', 'hud'];
+function shiftRows(rows, offset) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.map((row) => {
+        if (typeof row !== 'object' || row === null)
+            return row;
+        const entry = row;
+        if (typeof entry.frame !== 'number')
+            return row;
+        return { ...entry, frame: entry.frame + offset };
+    });
+}
+/** Hard-link when possible; copying is the cross-filesystem fallback. */
+function linkOrCopy(from, to) {
+    try {
+        fs.linkSync(from, to);
+    }
+    catch {
+        fs.copyFileSync(from, to);
+    }
+}
+export function runMerge(dirs, options = {}) {
+    if (dirs.length < 2)
+        throw new CliError('merge needs at least two recording dirs');
+    const runs = [];
+    let offset = 0;
+    for (const dir of dirs) {
+        const resolved = path.resolve(dir);
+        loadTimeline(resolved); // validation only — the merge uses the raw JSON
+        const raw = JSON.parse(fs.readFileSync(path.join(resolved, 'timeline.json'), 'utf8'));
+        runs.push({ dir: resolved, raw, offset });
+        offset += raw.recording.frameCount;
+    }
+    const totalFrames = offset;
+    const first = runs[0].raw.recording;
+    for (const run of runs.slice(1)) {
+        const rec = run.raw.recording;
+        if (rec.width !== first.width || rec.height !== first.height) {
+            throw new CliError(`resolution mismatch: ${path.basename(runs[0].dir)} is ${first.width}x${first.height}, ` +
+                `${path.basename(run.dir)} is ${rec.width}x${rec.height}`);
+        }
+        if (rec.fps !== first.fps) {
+            throw new CliError(`fps mismatch: ${first.fps} vs ${rec.fps} in ${path.basename(run.dir)}`);
+        }
+    }
+    // Footage recorded before the post-FX fix has no bloom/SSR/tone mapping and
+    // is visibly flatter; cutting it against fixed footage looks like a bug.
+    const postFx = runs.map((r) => r.raw.recording.postProcessing ?? 'unknown');
+    const distinct = Array.from(new Set(postFx));
+    if (distinct.length > 1) {
+        const detail = runs.map((r, i) => `${path.basename(r.dir)}=${postFx[i]}`).join(', ');
+        if (options.allowMixedPostFx !== true) {
+            throw new CliError(`post-processing mismatch (${detail}). These will not match visually — re-record ` +
+                `the odd one out, or pass --allow-mixed-postfx to override.`);
+        }
+        warn(`merging mismatched post-processing (${detail}) — the cut will change look between runs`);
+    }
+    else if (distinct[0] === 'unknown') {
+        warn('none of these recordings state their post-processing (recorded before that was tracked)');
+    }
+    const outDir = path.resolve(options.outDir ?? `${runs[0].dir}-merged`);
+    const name = path.basename(outDir);
+    fs.mkdirSync(outDir, { recursive: true });
+    let linked = 0;
+    const absent = [];
+    for (const run of runs) {
+        const srcName = run.raw.recording.name;
+        for (let i = 0; i < run.raw.recording.frameCount; i++) {
+            const src = path.join(run.dir, `${srcName}_${String(i).padStart(6, '0')}.png`);
+            if (!fs.existsSync(src)) {
+                absent.push(run.offset + i);
+                continue;
+            }
+            const dst = path.join(outDir, `${name}_${String(run.offset + i).padStart(6, '0')}.png`);
+            if (!fs.existsSync(dst))
+                linkOrCopy(src, dst);
+            linked++;
+        }
+    }
+    const merged = {
+        ...runs[0].raw,
+        version: 1,
+        recording: {
+            ...first,
+            name,
+            frameCount: totalFrames,
+            missingFrames: [
+                ...runs.flatMap((r) => (r.raw.recording.missingFrames ?? []).map((f) => f + r.offset)),
+                ...absent,
+            ].sort((a, b) => a - b),
+            frameClock: runs.flatMap((r) => (r.raw.recording.frameClock ?? []).map((s) => ({ ...s, frame: s.frame + r.offset }))),
+            // Where each source run begins, so a cut can avoid straddling a join.
+            mergedFrom: runs.map((r) => ({
+                name: r.raw.recording.name,
+                startFrame: r.offset,
+                frameCount: r.raw.recording.frameCount,
+            })),
+        },
+    };
+    for (const track of FRAME_INDEXED_TRACKS) {
+        merged[track] = runs.flatMap((r) => shiftRows(r.raw[track], r.offset));
+    }
+    fs.writeFileSync(path.join(outDir, 'timeline.json'), JSON.stringify(merged, null, 2));
+    const counts = FRAME_INDEXED_TRACKS.map((t) => `${t}: ${merged[t].length}`).join(', ');
+    const joins = runs.slice(1).map((r) => String(r.offset)).join(', ');
+    out(`merged ${runs.length} recordings -> ${outDir} | ${totalFrames} frames ` +
+        `(${(totalFrames / first.fps).toFixed(1)}s) | ${linked} frames linked | ${counts}` +
+        (joins ? ` | joins at frame ${joins}` : ''));
+    if (absent.length > 0) {
+        warn(`${absent.length} source frame(s) were absent and are listed in missingFrames`);
+    }
+}
+//# sourceMappingURL=merge.js.map

package/dist/trailer/merge.js.map

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

package/dist/trailer/music-beats.d.ts

@@ -0,0 +1,123 @@
+/** Analysis decode rate: covers kick through hat, and keeps the FFTs cheap. */
+export declare const BEAT_SAMPLE_RATE = 22050;
+export declare const FRAME_SIZE = 1024;
+export declare const HOP_SIZE = 512;
+export declare const BEATS_PER_BAR = 4;
+export interface BeatAnalysis {
+    /** Detected tempo, or the forced `opts.bpm`. */
+    bpm: number;
+    /** 0..1 — how strongly the beat grid matches the onset envelope. */
+    confidence: number;
+    /** Seconds, ascending, from the first beat to the end of the track. */
+    beatTimes: number[];
+    /** Every 4th beat starting at the detected downbeat. */
+    barTimes: number[];
+    /** Index into beatTimes of the first downbeat (0..3). */
+    downbeatIndex: number;
+    durationSec: number;
+    /** RMS in dBFS per bar — the structure hint for build/drop. */
+    energyPerBar: number[];
+}
+export interface BeatOptions {
+    /** Force the tempo (skips detection); the phase is still detected. */
+    bpm?: number;
+    /** Decode rate for analysis. Default BEAT_SAMPLE_RATE. */
+    sampleRate?: number;
+}
+/**
+ * Iterative in-place radix-2 Cooley-Tukey FFT. Power-of-two lengths only —
+ * the frame size is ours to choose, so there is no mixed-radix fallback.
+ */
+export declare function fftInPlace(re: Float64Array, im: Float64Array): void;
+/** Magnitude spectrum of a real frame: bins 0..n/2 inclusive. */
+export declare function fftMagnitudes(frame: ArrayLike<number>): Float64Array;
+export interface OnsetEnvelope {
+    /** Baseline-subtracted, half-wave-rectified spectral flux, one value per hop. */
+    strength: Float64Array;
+    /** The same measure over bins under LOW_BAND_HZ only (kick band). */
+    low: Float64Array;
+    /** Seconds per hop. Frame t is centred on t * hopSec. */
+    hopSec: number;
+}
+/**
+ * Spectral-flux onset envelope. Frames are centred (the signal is treated as
+ * zero-padded by frameSize/2 on the left) so frame t sits exactly on
+ * t * hopSec — the beat grid is built in that time base.
+ */
+export declare function computeOnsetEnvelope(samples: Float32Array, sampleRate: number, frameSize?: number, hopSize?: number): OnsetEnvelope;
+export interface TempoEstimate {
+    /** Tempo after octave correction. */
+    bpm: number;
+    /** Autocorrelation score of the chosen lag. */
+    score: number;
+    /** The raw autocorrelation peak, before octave correction. */
+    rawBpm: number;
+}
+/**
+ * Tempo from the onset envelope: autocorrelation peak over 60-200 BPM, refined
+ * to a fractional lag, then octave-corrected. The refinement matters — at a
+ * 23ms hop the integer lags around 120 BPM are 117.4 and 123.0 BPM, so an
+ * integer-lag answer alone cannot be within 1 BPM of the truth.
+ */
+export declare function detectTempo(env: OnsetEnvelope): TempoEstimate;
+/**
+ * With the period fixed, the offset within one period whose grid collects the
+ * most onset strength. Offsets are hop-sized; refineGrid takes it from there.
+ */
+export declare function detectPhase(env: OnsetEnvelope, periodSec: number, durationSec: number): number;
+/**
+ * Pull the grid onto the onsets it found. Each beat contributes the
+ * strength-weighted centroid of the envelope within a quarter beat of it, and
+ * a weighted least-squares line through those centroids gives period+phase at
+ * sub-hop resolution.
+ *
+ * This is not a nicety. The autocorrelation peak around the beat lag is a
+ * near-flat trapezoid — one beat of a 120 BPM track is 21.53 frames, and both
+ * lag 21 (123.0 BPM) and lag 22 (117.4 BPM) score about the same — so the
+ * tempo alone is only good to a couple of percent, and no hop-sized phase can
+ * be better than +-12ms.
+ *
+ * `lockPeriod` keeps a forced --bpm exactly as given and refines only the phase.
+ */
+export declare function refineGrid(env: OnsetEnvelope, periodSec: number, phaseSec: number, durationSec: number, lockPeriod: boolean): {
+    periodSec: number;
+    phaseSec: number;
+};
+/**
+ * Of the four candidate downbeat phases, the one whose beats carry the most
+ * kick-band onset energy. When the low band is flat (no drums, or a mix with
+ * nothing under 150Hz) the four scores are meaningless, so it falls back to
+ * total onset strength.
+ */
+export declare function pickDownbeat(env: OnsetEnvelope, beatTimes: number[]): number;
+/** The whole pipeline over decoded mono samples — no ffmpeg, no filesystem. */
+export declare function analyzeBeatsFromSamples(samples: Float32Array, sampleRate: number, opts?: BeatOptions): BeatAnalysis;
+/**
+ * Playable seconds in an audio file. Asks for the audio stream's own duration
+ * first and falls back to the container's; throws if neither is a number.
+ */
+export declare function probeAudioDurationSec(filePath: string): Promise<number>;
+/**
+ * Decode any audio file to mono float samples at `sampleRate`.
+ *
+ * `-vn` plus an explicit `-map 0:a:0` matter: music files routinely carry
+ * embedded cover art as a video stream, and without both, ffmpeg tries to push
+ * that image into a PCM stream and fails.
+ */
+export declare function decodeMonoPcm(audioPath: string, sampleRate: number): Promise<Float32Array>;
+export declare function analyzeBeats(audioPath: string, opts?: BeatOptions): Promise<BeatAnalysis>;
+/**
+ * The music with a click burst on every beat (downbeats an octave-ish up), as
+ * a 48kHz mono WAV. The grid is only verifiable by ear, so this file is the
+ * point of the whole `beats` command.
+ */
+export declare function renderClickTrack(audioPath: string, analysis: BeatAnalysis): Promise<Buffer>;
+export interface BeatsCommandOptions {
+    /** Where to write the BeatAnalysis JSON. */
+    jsonPath?: string;
+    /** Force the tempo instead of detecting it. */
+    bpm?: number;
+    /** Where to write the music+click verification WAV. */
+    clickPath?: string;
+}
+export declare function runBeats(audioPath: string, options?: BeatsCommandOptions): Promise<void>;