videobook 0.0.0-stage → 0.2.0

package/dist/rhythm/music-analysis.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { findAudioFile, findPrimaryMediaFile } from "videobook-engine";
+import { musicAnalysisSchema, sectionLabelsSchema } from "./model.js";
+import { candidateSections } from "./energy.js";
+import { extractWaveform, FFMPEG } from "../ffmpeg.js";
+import { RHYTHM_ANALYZER_VERSION, RHYTHM_ANALYZER_ID, SECTION_LABELER_VERSION } from "./contract.js";
+import { runRhythmWorker } from "./run-worker.js";
+export async function musicSource(engine, artifactId, streamId) {
+    const artifact = engine.artifacts.get(artifactId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    if (!["audio", "video", "final"].includes(artifact.value.kind))
+        throw new Error("Choose an audio or video source");
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const file = artifact.value.kind === "audio"
+        ? findAudioFile(manifest.value.files, artifact.value.kind)
+        : findPrimaryMediaFile(manifest.value.files, artifact.value.kind);
+    const streams = engine.streams.list(artifactId);
+    if (!streams.ok)
+        throw new Error(streams.error.message);
+    const stream = streams.value.find((item) => item.kind === "audio" && item.sourcePath === file?.name
+        && item.objectHash === file.objectHash && (!streamId || item.streamId === streamId));
+    if (!stream || !file)
+        throw new Error("Wait for the current audio source to finish processing");
+    const durationSeconds = stream.durationTicks * stream.timeBase.numerator / stream.timeBase.denominator;
+    if (!(durationSeconds > 0) || durationSeconds > 3600)
+        throw new Error("Music analysis supports audio up to 60 minutes");
+    const analysisId = createHash("sha256").update(JSON.stringify([
+        file.objectHash, stream.streamIndex, RHYTHM_ANALYZER_ID, RHYTHM_ANALYZER_VERSION,
+    ])).digest("hex");
+    return { artifactId, objectHash: file.objectHash, streamId: stream.streamId, streamIndex: stream.streamIndex,
+        analysisId, durationSeconds, inputPath: join(manifest.value.path, file.name) };
+}
+export async function cachedMusicAnalysis(engine, source) {
+    const read = await engine.metadata.artifacts.read(source.artifactId, `music.analysis.${source.analysisId}`);
+    if (!read.ok)
+        return null;
+    const parsed = musicAnalysisSchema.safeParse(read.value);
+    if (!parsed.success || parsed.data.objectHash !== source.objectHash || parsed.data.streamId !== source.streamId)
+        return null;
+    return parsed.data;
+}
+export async function analyzeMusicSource(engine, artifactId, analysisId, streamId, signal) {
+    const source = await musicSource(engine, artifactId, streamId);
+    if (source.analysisId !== analysisId)
+        throw new Error("The audio source changed; analyze it again");
+    const analysis = await runRhythmWorker(FFMPEG, source.inputPath, signal, source.streamIndex);
+    signal.throwIfAborted();
+    const waveform = await extractWaveform(source.inputPath, 8192, source.streamIndex, signal);
+    signal.throwIfAborted();
+    if (!waveform.length)
+        throw new Error("The soundtrack waveform could not be decoded. Retry analysis.");
+    const current = await musicSource(engine, artifactId, streamId);
+    if (current.analysisId !== analysisId)
+        throw new Error("The audio source changed during analysis");
+    const withinSource = (beat) => beat.timeSeconds < source.durationSeconds;
+    const energy = analysis.energy;
+    const result = musicAnalysisSchema.parse({
+        analysisId, artifactId, objectHash: source.objectHash, streamId, durationSeconds: source.durationSeconds,
+        analyzerVersion: `${RHYTHM_ANALYZER_ID}@${RHYTHM_ANALYZER_VERSION}`,
+        beats: analysis.beats.filter(withinSource), bpm: analysis.bpm, confidence: analysis.bpmConfidence,
+        bars: analysis.bars?.filter(withinSource) ?? null, beatsPerBar: analysis.meter?.beatsPerBar ?? null,
+        barSource: analysis.barSource,
+        waveform, lowConfidence: analysis.lowConfidence,
+        energy: energy ?? null,
+        sections: energy ? candidateSections(energy, source.durationSeconds) : null,
+    });
+    const saved = await engine.metadata.artifacts.write(artifactId, `music.analysis.${analysisId}`, result);
+    if (!saved.ok)
+        throw new Error(saved.error.message);
+    return result;
+}
+export async function readMusicAnalysis(engine, artifactId, streamId) {
+    const source = await musicSource(engine, artifactId, streamId);
+    const analysis = await cachedMusicAnalysis(engine, source);
+    const jobs = engine.jobs.queue.list({ type: "analyze_music", limit: 500 });
+    const job = jobs.filter((item) => item.payload.musicArtifactId === artifactId && item.payload.analysisId === source.analysisId)
+        .sort((left, right) => right.id - left.id)[0];
+    const pending = job && ["queued", "running", "completing"].includes(job.state);
+    const status = pending ? job.state === "queued" ? "queued" : "analyzing"
+        : job?.state === "aborted" ? "cancelled" : job?.state === "failed" ? "failed"
+            : analysis ? analysis.beats.length ? "ready" : "no-beats" : "missing";
+    const sections = await readSectionState(engine, source, analysis);
+    return { status, analysisId: source.analysisId, jobId: job?.id ?? null, error: job?.error?.message ?? null, analysis, sections };
+}
+async function readSectionState(engine, source, analysis) {
+    if (!analysis?.energy || !analysis.sections)
+        return { status: "missing", jobId: null, error: null, labels: null };
+    const stored = await readSectionLabels(engine, source.artifactId, source.analysisId);
+    if (stored && sectionLabelsCurrent(stored, analysis)) {
+        return {
+            status: stored.status === "ready" ? "ready" : "unavailable",
+            jobId: null, error: stored.status === "ready" ? null : stored.reason,
+            labels: stored.status === "ready" ? stored : null,
+        };
+    }
+    const jobs = engine.jobs.queue.list({ type: "label_music_sections", limit: 500 });
+    const job = jobs.filter((item) => item.payload.analysisId === source.analysisId).sort((left, right) => right.id - left.id)[0];
+    const active = job && ["queued", "running", "completing"].includes(job.state);
+    const status = active ? job.state === "queued" ? "queued" : "labeling"
+        : job?.state === "aborted" ? "cancelled" : job?.state === "failed" ? "failed" : "missing";
+    return { status, jobId: job?.id ?? null, error: job?.error?.message ?? null, labels: null };
+}
+export async function readSectionLabels(engine, artifactId, analysisId) {
+    const read = await engine.metadata.artifacts.read(artifactId, `music.sections.${analysisId}`);
+    if (!read.ok)
+        return null;
+    const parsed = sectionLabelsSchema.safeParse(read.value);
+    return parsed.success ? parsed.data : null;
+}
+export function sectionLabelsCurrent(stored, analysis) {
+    const candidates = analysis.sections?.candidates ?? [];
+    const covered = stored.status === "ready"
+        && stored.labels.length === candidates.length
+        && stored.labels.every((label, index) => label.candidateId === candidates[index]?.id);
+    return stored.analysisId === analysis.analysisId && stored.objectHash === analysis.objectHash
+        && stored.streamId === analysis.streamId && stored.labeler.version === SECTION_LABELER_VERSION
+        && stored.boundaries.algorithmVersion === analysis.sections?.algorithmVersion
+        && stored.boundaries.algorithmId === analysis.sections?.algorithmId
+        && (stored.status === "unavailable" || covered);
+}

package/dist/rhythm/music-draft.js

@@ -0,0 +1,261 @@
+import { withNotebookMutation } from "../notebook-mutations.js";
+import { v5 as uuidv5 } from "uuid";
+import { findPrimaryMediaFile, MVP_CONTRACT_VERSION } from "videobook-engine";
+import { sequenceContinuationRevision } from "../tools/command-plan.js";
+import { MOMENTS_MAX_RANKED, readEditingMoments } from "../editing-moments.js";
+import { cachedMusicAnalysis, musicSource } from "./music-analysis.js";
+import { readSequenceRhythm } from "./sequence-rhythm.js";
+import { effectiveMarkers, frameAtSourceTime, soundtrackClip, timelineMarkers } from "./timing.js";
+import { musicDraftOptionsSchema } from "./draft-model.js";
+import { energySegments } from "./energy.js";
+import { fittedTransform } from "./visual-fit.js";
+const namespace = "5cc43cf4-f4bf-4dce-aa1e-a8105ae53087";
+const endOf = (clip) => clip.timelineStartFrame + clip.durationFrames;
+export async function planMusicVideo(engine, input, expectedSequence, expectedRhythm, actor, sourceSurface) {
+    const options = musicDraftOptionsSchema.parse(input);
+    const sequence = engine.sequences.getPrimary();
+    const contentRevision = sequenceContinuationRevision(sequence);
+    if (contentRevision !== expectedSequence && sequence.revision !== expectedSequence)
+        throw new Error("The timeline changed. Reload before making a draft.");
+    const rhythm = await readSequenceRhythm(engine, sequence.sequenceId);
+    if (rhythm.revision !== expectedRhythm)
+        throw new Error("The beat map changed. Reload before making a draft.");
+    const master = soundtrackClip(sequence, rhythm.settings);
+    if (!master)
+        throw new Error("Choose a master soundtrack before making a draft.");
+    const source = await musicSource(engine, master.source.artifactId, master.source.range.streamId);
+    if (source.objectHash !== master.source.range.objectHash)
+        throw new Error("The soundtrack source changed. Replace the timeline clip first.");
+    const analysis = await cachedMusicAnalysis(engine, source);
+    if (!rhythm.settings.correction && (!analysis || analysis.lowConfidence))
+        throw new Error("Analyze the song and confirm uncertain beats with a manual grid before making a draft.");
+    if (options.analysis && (!analysis || analysis.analysisId !== options.analysis.music_analysis_id)) {
+        throw new Error("The referenced music analysis is stale; analyze the current soundtrack before planning with it.");
+    }
+    const moments = await resolveMoments(engine, options);
+    const markers = timelineMarkers(master, effectiveMarkers(master, rhythm.settings, analysis), sequence);
+    const musical = markers.filter((marker) => options.unit === "beats" || marker.bar);
+    if (musical.length < 2)
+        throw new Error(options.unit === "bars" ? "Confirm bar starts in Soundtrack before using bars." : "Add at least two beat markers before making a draft.");
+    const track = sequence.tracks.find((item) => item.trackId === options.track_id);
+    if (!track || track.kind !== "video" || !track.enabled || track.locked)
+        throw new Error("Choose an enabled, unlocked video track.");
+    if (options.start_frame >= options.end_frame || options.start_frame < master.timelineStartFrame || options.end_frame > endOf(master))
+        throw new Error("Choose a nonempty range inside the master soundtrack.");
+    const touching = sequence.clips.filter((clip) => clip.trackId === track.trackId && clip.timelineStartFrame < options.end_frame && endOf(clip) > options.start_frame);
+    const preserved = touching.filter((clip) => options.preserve_existing || options.preserve_clip_ids.includes(clip.clipId) || clip.timelineStartFrame < options.start_frame || endOf(clip) > options.end_frame);
+    const removed = touching.filter((clip) => !preserved.includes(clip));
+    if (sequence.transitions.some((transition) => removed.some((clip) => transition.outgoingClipId === clip.clipId || transition.incomingClipId === clip.clipId)))
+        throw new Error("Remove transitions in the replacement range or keep the existing clips.");
+    const gaps = [];
+    let cursor = options.start_frame;
+    for (const clip of [...preserved].sort((a, b) => a.timelineStartFrame - b.timelineStartFrame)) {
+        if (clip.timelineStartFrame > cursor)
+            gaps.push({ start: cursor, end: Math.min(clip.timelineStartFrame, options.end_frame) });
+        cursor = Math.max(cursor, endOf(clip));
+    }
+    if (cursor < options.end_frame)
+        gaps.push({ start: cursor, end: options.end_frame });
+    if (!gaps.length)
+        throw new Error("This range is already filled. Turn off Keep existing clips to replace it, or choose an empty range.");
+    const fps = sequence.frameRate.numerator / sequence.frameRate.denominator;
+    const sources = await Promise.all(options.sources.map(async (selection) => {
+        const artifact = engine.artifacts.get(selection.artifact_id);
+        if (!artifact.ok || !["video", "final"].includes(artifact.value.kind))
+            throw new Error("Choose ready video sources.");
+        const manifest = await engine.files.manifest(selection.artifact_id);
+        const streams = engine.streams.list(selection.artifact_id);
+        if (!manifest.ok || !streams.ok)
+            throw new Error("A source is unavailable. Refresh media.");
+        const file = findPrimaryMediaFile(manifest.value.files, artifact.value.kind);
+        const stream = streams.value.find((item) => item.kind === "video" && item.objectHash === file?.objectHash && item.sourcePath === file.name);
+        if (!stream)
+            throw new Error(`Wait for ${artifact.value.label} to finish processing.`);
+        const tickSeconds = stream.timeBase.numerator / stream.timeBase.denominator;
+        const first = Math.round((selection.start_seconds ?? 0) / tickSeconds);
+        const last = selection.end_seconds === undefined ? stream.durationTicks : Math.round(selection.end_seconds / tickSeconds);
+        if (first < 0 || last > stream.durationTicks || first >= last)
+            throw new Error(`Source range is outside ${artifact.value.label}.`);
+        return { artifactId: selection.artifact_id, stream, tickSeconds, first, last, used: first };
+    }));
+    if (new Set(sources.map((item) => item.artifactId)).size !== sources.length)
+        throw new Error("Select each source once; enable source reuse to repeat footage.");
+    const snapshot = engine.head;
+    const currentRhythm = await readSequenceRhythm(engine, sequence.sequenceId);
+    if (snapshot !== engine.head || currentRhythm.revision !== rhythm.revision || sequenceContinuationRevision(engine.sequences.getPrimary()) !== contentRevision)
+        throw new Error("The timeline or beat map changed while planning. Try again.");
+    const commandId = uuidv5(JSON.stringify([snapshot, rhythm.revision, options, sources.map((item) => item.stream.objectHash)]), namespace);
+    const operations = removed.map((clip) => ({ kind: "remove-clip", clipId: clip.clipId, ripple: false }));
+    const inserted = [];
+    const shots = [];
+    const uncovered = [];
+    const warnings = new Set();
+    let sourceIndex = 0;
+    const energy = options.strategy === "follow_song_energy"
+        ? analysis?.energy?.values.length
+            ? { segments: energySegments(analysis.energy, analysis.sections, analysis.durationSeconds) }
+            : null
+        : null;
+    if (options.strategy === "follow_song_energy" && !energy) {
+        throw new Error("Follow-song-energy planning needs an analysis reference with an energy curve; run analyze_music on the current soundtrack first.");
+    }
+    if (energy && !analysis?.sections?.candidates.length)
+        warnings.add("The analysis has no section boundaries; the whole range keeps your base interval.");
+    const intervalFrames = energy
+        ? energyCutFrames(musical, energy.segments, options.interval)
+        : musical.filter((_, index) => index % options.interval === 0).map((marker) => marker.frame);
+    for (const gap of gaps) {
+        const boundaries = [gap.start];
+        for (const frame of intervalFrames) {
+            if (frame - boundaries[boundaries.length - 1] >= options.minimum_shot_frames && gap.end - frame >= options.minimum_shot_frames)
+                boundaries.push(frame);
+        }
+        boundaries.push(gap.end);
+        for (let index = 1; index < boundaries.length; index++) {
+            if (shots.length >= 1000)
+                throw new Error("Limit the draft to 1,000 shots; choose a longer interval or shorter range.");
+            const start = boundaries[index - 1];
+            const end = boundaries[index];
+            const seconds = (end - start) / fps;
+            let chosen;
+            let ticks = 0;
+            let retimed = false;
+            for (let attempt = 0; attempt < sources.length; attempt++) {
+                const candidate = sources[(sourceIndex + attempt) % sources.length];
+                const required = Math.ceil(seconds / candidate.tickSeconds - 1e-7);
+                if (candidate.last - candidate.used >= required) {
+                    chosen = candidate;
+                    ticks = required;
+                    sourceIndex = (sourceIndex + attempt + 1) % sources.length;
+                    break;
+                }
+                if (options.reuse_sources && candidate.last - candidate.first >= required) {
+                    chosen = candidate;
+                    chosen.used = chosen.first;
+                    ticks = required;
+                    sourceIndex = (sourceIndex + attempt + 1) % sources.length;
+                    warnings.add("Some source footage is repeated.");
+                    break;
+                }
+            }
+            if (!chosen && options.allow_retiming) {
+                const candidate = sources[sourceIndex % sources.length];
+                if (candidate.used === candidate.last && options.reuse_sources) {
+                    candidate.used = candidate.first;
+                    warnings.add("Some source footage is repeated.");
+                }
+                if (candidate.used < candidate.last) {
+                    chosen = candidate;
+                    ticks = candidate.last - candidate.used;
+                    retimed = true;
+                    sourceIndex = (sourceIndex + 1) % sources.length;
+                }
+            }
+            if (!chosen) {
+                uncovered.push({ startFrame: start, endFrame: end });
+                continue;
+            }
+            const clipId = uuidv5(`shot:${shots.length}`, commandId);
+            const nativeFrames = ticks * chosen.tickSeconds * fps;
+            const speed = retimed ? { numerator: Math.max(1, Math.round(nativeFrames * 1000)), denominator: (end - start) * 1000 } : { numerator: 1, denominator: 1 };
+            const clip = {
+                clipId, trackId: track.trackId, timelineStartFrame: start, durationFrames: end - start, enabled: true,
+                source: { kind: "timed", artifactId: chosen.artifactId, range: { streamId: chosen.stream.streamId, objectHash: chosen.stream.objectHash, timeBase: chosen.stream.timeBase, startTick: chosen.used, durationTicks: ticks } },
+                speed, reverse: false, audioPolicy: "mute", transform: fittedTransform(),
+            };
+            const { clipId: _id, enabled: _enabled, ...placement } = clip;
+            operations.push({ kind: "insert-clip", clipId, mode: "overwrite", placement });
+            inserted.push(clip);
+            shots.push({ clipId, artifactId: chosen.artifactId, startFrame: start, endFrame: end, sourceStartSeconds: chosen.used * chosen.tickSeconds, sourceEndSeconds: (chosen.used + ticks) * chosen.tickSeconds, speed: speed.numerator / speed.denominator });
+            chosen.used += ticks;
+            if (retimed)
+                warnings.add("Some shots change playback speed. Review each rate below.");
+        }
+    }
+    if (!shots.length)
+        throw new Error("No source is long enough for this interval. Choose shorter cuts, more footage, or explicitly allow retiming.");
+    if (uncovered.length)
+        warnings.add(`${uncovered.length} spans have no footage. Add footage, shorten the interval, or enable reuse before applying.`);
+    if (!markers.some((marker) => marker.frame === options.end_frame))
+        warnings.add("The range ends between beats; the last shot ends exactly at your selected out point.");
+    let energyPlan;
+    if (energy && analysis) {
+        const segments = [];
+        for (const segment of energy.segments) {
+            const start = Math.max(options.start_frame, frameAtSourceTime(master, segment.startSeconds, fps));
+            const end = Math.min(options.end_frame, frameAtSourceTime(master, segment.endSeconds, fps));
+            if (end <= start)
+                continue;
+            segments.push({ startFrame: start, endFrame: end, tier: segment.tier, interval: segmentInterval(segment.tier, options.interval, energy.segments.length) });
+        }
+        energyPlan = { strategy: "follow_song_energy", musicAnalysisId: analysis.analysisId, segments };
+    }
+    const intent = { intentVersion: MVP_CONTRACT_VERSION, commandId, sequenceId: sequence.sequenceId, baseRevision: snapshot, actor, sourceSurface, confirmationPolicy: "always", operations };
+    const preview = engine.edits.preview(intent);
+    if (!preview.ok)
+        throw new Error(preview.error.message);
+    if (!preview.value.valid)
+        throw new Error(preview.value.conflicts.map((conflict) => conflict.message).join("; "));
+    const summary = `${shots.length} shots across ${((options.end_frame - options.start_frame) / fps).toFixed(2)}s`;
+    return {
+        plan: { planVersion: 1, planId: commandId, sourceSurface, actor, bookId: engine.book.get().bookId, summary,
+            normalizedReferences: [{ kind: "sequence", targetId: sequence.sequenceId, revision: snapshot }, ...sources.map((item) => ({ kind: "artifact", targetId: item.artifactId, objectHash: item.stream.objectHash }))],
+            stages: [{ stageId: `${commandId}:edit:0`, kind: "edit", summary, intent }], confirmation: { required: true, policy: "always", reason: "Review the music-video draft before replacing footage" } },
+        preview: preview.value, sequence: { ...sequence, clips: [...sequence.clips.filter((clip) => !removed.includes(clip)), ...inserted] },
+        rhythmRevision: rhythm.revision, sequenceContentRevision: contentRevision, shots, uncovered, warnings: [...warnings, ...preview.value.warnings.map((warning) => warning.message)],
+        ...(energyPlan ? { energyPlan } : {}),
+        ...(moments.length ? { sourceMoments: moments } : {}),
+    };
+}
+function segmentInterval(tier, base, segmentCount) {
+    if (segmentCount <= 1)
+        return base;
+    const multiplier = tier === "high" ? 1 : tier === "mid" ? 2 : 4;
+    return Math.min(8, base * multiplier);
+}
+function energyCutFrames(markers, segments, base) {
+    const selected = [];
+    for (const segment of segments) {
+        const inside = markers.filter((marker) => marker.timeSeconds >= segment.startSeconds && marker.timeSeconds < segment.endSeconds);
+        const interval = segmentInterval(segment.tier, base, segments.length);
+        inside.forEach((marker, index) => {
+            if (index % interval === 0)
+                selected.push(marker.frame);
+        });
+    }
+    return [...new Set(selected)].sort((left, right) => left - right);
+}
+async function resolveMoments(engine, options) {
+    const ranked = [];
+    for (const ref of options.analysis?.moments ?? []) {
+        const doc = await readEditingMoments(engine, ref.artifact_id, ref.moments_id);
+        if (!doc)
+            throw new Error("A referenced moments analysis is stale or missing; analyze that footage again before planning with it.");
+        for (const moment of doc.moments) {
+            ranked.push({ artifactId: doc.artifactId, shotId: moment.shotId, startSeconds: moment.startSeconds, endSeconds: moment.endSeconds, score: moment.score, quality: moment.quality });
+        }
+    }
+    return ranked
+        .sort((left, right) => right.score - left.score || left.artifactId.localeCompare(right.artifactId) || left.startSeconds - right.startSeconds)
+        .slice(0, MOMENTS_MAX_RANKED);
+}
+export async function commitMusicVideo(engine, intent, previewHash, rhythmRevision, sequenceContentRevision) {
+    return withNotebookMutation(`rhythm:${engine.book.get().bookId}:${intent.sequenceId}`, async () => {
+        const previous = engine.history.revisions(Number.MAX_SAFE_INTEGER).find((revision) => revision.operation === "commit_edit" && revision.details?.commandId === intent.commandId);
+        if (previous) {
+            if (previous.details?.previewHash !== previewHash)
+                throw new Error("This draft ID was already applied with a different preview.");
+            return { commandId: intent.commandId, actionId: String(previous.details.actionId), revision: engine.head,
+                sequence: engine.sequences.getPrimary(), previewHash };
+        }
+        const rhythm = await readSequenceRhythm(engine, intent.sequenceId);
+        if (rhythm.revision !== rhythmRevision)
+            throw new Error("The beat map changed. Preview a new draft before applying.");
+        if (sequenceContinuationRevision(engine.sequences.getPrimary()) !== sequenceContentRevision)
+            throw new Error("The timeline changed. Preview a new draft before applying.");
+        const committed = await engine.edits.commit(intent, previewHash);
+        if (!committed.ok)
+            throw new Error(committed.error.message);
+        return committed.value;
+    });
+}

package/dist/rhythm/onset.js

@@ -0,0 +1,101 @@
+import { fftInPlace } from "./fft.js";
+import { RHYTHM_HOP_SAMPLES, RHYTHM_LATENCY_SAMPLES, RHYTHM_MAX_RETAINED_SAMPLES, RHYTHM_SAMPLE_RATE, RHYTHM_WINDOW_SAMPLES, } from "./contract.js";
+const HANN = new Float64Array(RHYTHM_WINDOW_SAMPLES);
+for (let index = 0; index < RHYTHM_WINDOW_SAMPLES; index += 1) {
+    HANN[index] = 0.5 * (1 - Math.cos((2 * Math.PI * index) / (RHYTHM_WINDOW_SAMPLES - 1)));
+}
+export function createOnsetAccumulator(sampleRate = RHYTHM_SAMPLE_RATE) {
+    if (sampleRate !== RHYTHM_SAMPLE_RATE) {
+        throw new Error(`Rhythm analysis requires ${RHYTHM_SAMPLE_RATE} Hz mono PCM`);
+    }
+    const window = new Float32Array(RHYTHM_WINDOW_SAMPLES);
+    let filled = RHYTHM_LATENCY_SAMPLES;
+    const previous = new Float64Array(RHYTHM_WINDOW_SAMPLES / 2);
+    const real = new Float64Array(RHYTHM_WINDOW_SAMPLES);
+    const imag = new Float64Array(RHYTHM_WINDOW_SAMPLES);
+    const strength = [];
+    const rms = [];
+    let incoming = new Float32Array(0);
+    const emitFrame = () => {
+        let squares = 0;
+        for (let index = 0; index < RHYTHM_WINDOW_SAMPLES; index += 1)
+            squares += window[index] * window[index];
+        rms.push(Math.sqrt(squares / RHYTHM_WINDOW_SAMPLES));
+        for (let index = 0; index < RHYTHM_WINDOW_SAMPLES; index += 1) {
+            real[index] = window[index] * HANN[index];
+            imag[index] = 0;
+        }
+        fftInPlace(real, imag);
+        let flux = 0;
+        const bins = RHYTHM_WINDOW_SAMPLES / 2;
+        for (let bin = 1; bin < bins; bin += 1) {
+            const magnitude = Math.hypot(real[bin], imag[bin]);
+            const rise = magnitude - previous[bin];
+            if (rise > 0)
+                flux += rise;
+            previous[bin] = magnitude;
+        }
+        strength.push(flux);
+        window.copyWithin(0, RHYTHM_HOP_SAMPLES);
+        filled = RHYTHM_WINDOW_SAMPLES - RHYTHM_HOP_SAMPLES;
+    };
+    const drain = () => {
+        let offset = 0;
+        while (offset < incoming.length) {
+            const needed = RHYTHM_WINDOW_SAMPLES - filled;
+            const take = Math.min(needed, incoming.length - offset);
+            window.set(incoming.subarray(offset, offset + take), filled);
+            filled += take;
+            offset += take;
+            if (filled === RHYTHM_WINDOW_SAMPLES)
+                emitFrame();
+        }
+        incoming = new Float32Array(0);
+    };
+    return {
+        push(chunk) {
+            incoming = chunk;
+            drain();
+        },
+        retainedSamples() {
+            return filled + incoming.length;
+        },
+        hopCount() {
+            return strength.length;
+        },
+        finish() {
+            const raw = Float32Array.from(strength);
+            whitenFlux(raw);
+            return {
+                sampleRate,
+                hopSamples: RHYTHM_HOP_SAMPLES,
+                windowSamples: RHYTHM_WINDOW_SAMPLES,
+                strength: raw,
+                rms: Float32Array.from(rms),
+                frameCount: raw.length,
+            };
+        },
+    };
+}
+export function onsetRetainedLimit() {
+    return RHYTHM_MAX_RETAINED_SAMPLES;
+}
+function whitenFlux(strength) {
+    const width = 8;
+    const local = new Float32Array(strength.length);
+    for (let index = 0; index < strength.length; index += 1) {
+        const start = Math.max(0, index - width);
+        const end = Math.min(strength.length, index + width + 1);
+        let sum = 0;
+        for (let cursor = start; cursor < end; cursor += 1)
+            sum += strength[cursor];
+        local[index] = Math.max(0, strength[index] - sum / (end - start));
+    }
+    let peak = 0;
+    for (const value of local)
+        peak = Math.max(peak, value);
+    const scale = peak > 0 ? 1 / peak : 1;
+    for (let index = 0; index < strength.length; index += 1) {
+        strength[index] = local[index] * scale;
+    }
+}

package/dist/rhythm/run-worker.js

@@ -0,0 +1,51 @@
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+export async function runRhythmWorker(ffmpegPath, inputPath, signal, streamIndex) {
+    signal.throwIfAborted();
+    const development = import.meta.url.endsWith(".ts");
+    const child = fork(fileURLToPath(new URL(development ? "./worker.ts" : "./worker.js", import.meta.url)), [], {
+        execArgv: development ? ["--import", "tsx"] : [],
+        stdio: ["ignore", "ignore", "pipe", "ipc"],
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let stderr = "";
+        let killTimer;
+        const finish = (error, result) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", abort);
+            if (error)
+                reject(error);
+            else if (result)
+                resolve(result);
+        };
+        const abort = () => {
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => child.kill("SIGKILL"), 2000);
+            killTimer.unref();
+            finish(new Error("Music analysis cancelled"));
+        };
+        child.stderr?.on("data", (chunk) => { stderr = (stderr + chunk.toString()).slice(-8192); });
+        child.on("error", (error) => finish(error));
+        child.on("exit", (code) => {
+            if (killTimer)
+                clearTimeout(killTimer);
+            finish(new Error(`Music analysis stopped (${code}): ${stderr}`));
+        });
+        child.on("message", (message) => {
+            if (signal.aborted)
+                return;
+            if (message.analysis)
+                finish(undefined, message.analysis);
+            else
+                finish(new Error(message.error ?? "Music analyzer returned no result"));
+        });
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+        else
+            child.send({ ffmpegPath, inputPath, streamIndex });
+    });
+}

package/dist/rhythm/score.js

@@ -0,0 +1,47 @@
+export function scoreBeats(referenceSeconds, detectedSeconds, toleranceSeconds) {
+    const used = new Set();
+    const errors = [];
+    for (const reference of referenceSeconds) {
+        let best = -1;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        detectedSeconds.forEach((detected, index) => {
+            if (used.has(index))
+                return;
+            const distance = Math.abs(detected - reference);
+            if (distance <= toleranceSeconds && distance < bestDistance) {
+                best = index;
+                bestDistance = distance;
+            }
+        });
+        if (best >= 0) {
+            used.add(best);
+            errors.push(bestDistance);
+        }
+    }
+    const hits = errors.length;
+    const precision = detectedSeconds.length === 0
+        ? (referenceSeconds.length === 0 ? 1 : 0)
+        : hits / detectedSeconds.length;
+    const recall = referenceSeconds.length === 0
+        ? (detectedSeconds.length === 0 ? 1 : 0)
+        : hits / referenceSeconds.length;
+    const f1 = precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+    return {
+        precision,
+        recall,
+        f1,
+        medianAbsErrorSeconds: median(errors),
+        hits,
+        referenceCount: referenceSeconds.length,
+        detectedCount: detectedSeconds.length,
+    };
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2
+        : sorted[middle] ?? 0;
+}