videobook 0.0.0-stage → 0.2.0

package/dist/audio-cue.js

@@ -0,0 +1,71 @@
+function transcriptWords(transcript) {
+    if (Array.isArray(transcript.words))
+        return transcript.words;
+    const transcripts = transcript.transcripts;
+    if (!Array.isArray(transcripts) || transcripts.length === 0)
+        return undefined;
+    const first = transcripts[0];
+    return typeof first === "object" && first !== null
+        ? first.words
+        : undefined;
+}
+function cueTokens(value) {
+    return value
+        .normalize("NFKC")
+        .toLocaleLowerCase()
+        .replace(/[\u2019']/gu, "")
+        .split(/[^\p{L}\p{N}]+/gu)
+        .filter(Boolean);
+}
+export function timedSpeechWords(transcript) {
+    if (typeof transcript !== "object" || transcript === null) {
+        throw new Error("elevenlabs.json must contain a JSON object");
+    }
+    const words = transcriptWords(transcript);
+    if (!Array.isArray(words)) {
+        throw new Error("elevenlabs.json does not contain timed words");
+    }
+    const result = [];
+    for (const entry of words) {
+        if ((entry.type ?? "word") !== "word")
+            continue;
+        if (typeof entry.text !== "string")
+            continue;
+        if (typeof entry.start !== "number" || !Number.isFinite(entry.start) || entry.start < 0)
+            continue;
+        const tokens = cueTokens(entry.text);
+        for (const token of tokens)
+            result.push({ text: token, start: entry.start });
+    }
+    return result;
+}
+export function hasTimedSpeechWords(transcript) {
+    try {
+        return timedSpeechWords(transcript).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function timestampList(matches) {
+    return matches.map((seconds) => `${Number(seconds.toFixed(3))}s`).join(", ");
+}
+export function resolveAudioCue(transcript, cue) {
+    const query = cueTokens(cue);
+    if (query.length === 0)
+        throw new Error("Audio cue must contain a word or number");
+    const words = timedSpeechWords(transcript);
+    const matches = [];
+    for (let start = 0; start + query.length <= words.length; start++) {
+        const matchesPhrase = query.every((token, offset) => words[start + offset]?.text === token);
+        if (matchesPhrase)
+            matches.push(words[start].start);
+    }
+    if (matches.length === 0) {
+        throw new Error(`Audio cue "${cue}" was not found in elevenlabs.json. Use audio_seconds for a numeric target.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Audio cue "${cue}" is ambiguous; it matches at ${timestampList(matches)}. Use a longer phrase or audio_seconds.`);
+    }
+    return matches[0];
+}

package/dist/audio-encoding.js

@@ -0,0 +1,32 @@
+import { extname } from "node:path";
+import { AUDIO_OPTS } from "./ffmpeg.js";
+export function audioOnlyOutputOptions(outputPath) {
+    switch (extname(outputPath).toLowerCase()) {
+        case ".mp3":
+            return ["-c:a", "libmp3lame", "-q:a", "2", "-ac", "2"];
+        case ".wav":
+            return ["-c:a", "pcm_s16le", "-ac", "2"];
+        case ".ogg":
+            return ["-c:a", "libvorbis", "-q:a", "5", "-ac", "2"];
+        case ".flac":
+            return ["-c:a", "flac", "-compression_level", "5", "-ac", "2"];
+        case ".webm":
+        case ".opus":
+            return ["-c:a", "libopus", "-b:a", "160k", "-ac", "2"];
+        case ".weba":
+            return ["-f", "webm", "-c:a", "libopus", "-b:a", "160k", "-ac", "2"];
+        case ".aac":
+        case ".m4a":
+            return AUDIO_OPTS;
+        default:
+            throw new Error(`Unsupported target audio format: ${extname(outputPath) || "unknown"}`);
+    }
+}
+export function videoAudioOutputOptions(outputPath) {
+    const extension = extname(outputPath).toLowerCase();
+    if (extension === ".webm")
+        return ["-c:a", "libopus", "-b:a", "160k", "-ac", "2"];
+    if (extension === ".avi")
+        return ["-c:a", "libmp3lame", "-b:a", "192k", "-ac", "2"];
+    return AUDIO_OPTS;
+}

package/dist/audio-sync-request.js

@@ -0,0 +1 @@
+export {};

package/dist/audio-sync.js

@@ -0,0 +1,223 @@
+export const AUDIO_SYNC_STRETCH_MIN = 0.25;
+export const AUDIO_SYNC_STRETCH_MAX = 4;
+const EPSILON = 1e-9;
+function requireFinite(name, value) {
+    if (!Number.isFinite(value))
+        throw new Error(`${name} must be a finite number`);
+}
+function nearlyEqual(left, right) {
+    return Math.abs(left - right) <= EPSILON;
+}
+function endpointDerivative(firstInterval, secondInterval, firstSlope, secondSlope) {
+    const derivative = ((2 * firstInterval + secondInterval) * firstSlope
+        - firstInterval * secondSlope) / (firstInterval + secondInterval);
+    if (derivative <= 0)
+        return 0;
+    if (secondSlope <= 0 && derivative > 3 * firstSlope)
+        return 3 * firstSlope;
+    return derivative;
+}
+function pchipDerivatives(intervals, slopes) {
+    if (slopes.length === 1)
+        return [slopes[0], slopes[0]];
+    const derivatives = new Array(slopes.length + 1);
+    derivatives[0] = endpointDerivative(intervals[0], intervals[1], slopes[0], slopes[1]);
+    derivatives[slopes.length] = endpointDerivative(intervals.at(-1), intervals.at(-2), slopes.at(-1), slopes.at(-2));
+    for (let index = 1; index < slopes.length; index++) {
+        const previousSlope = slopes[index - 1];
+        const nextSlope = slopes[index];
+        if (previousSlope * nextSlope <= 0) {
+            derivatives[index] = 0;
+            continue;
+        }
+        const previousInterval = intervals[index - 1];
+        const nextInterval = intervals[index];
+        const firstWeight = 2 * nextInterval + previousInterval;
+        const secondWeight = nextInterval + 2 * previousInterval;
+        derivatives[index] = (firstWeight + secondWeight)
+            / (firstWeight / previousSlope + secondWeight / nextSlope);
+    }
+    return derivatives;
+}
+function segmentDerivative(segment, normalizedTime) {
+    const [cubic, quadratic, linear] = segment.coefficients;
+    const interval = segment.videoEndSeconds - segment.videoStartSeconds;
+    return (3 * cubic * normalizedTime * normalizedTime
+        + 2 * quadratic * normalizedTime
+        + linear) / interval;
+}
+function derivativeExtrema(segment) {
+    const [cubic, quadratic] = segment.coefficients;
+    const values = [segmentDerivative(segment, 0), segmentDerivative(segment, 1)];
+    if (Math.abs(cubic) <= EPSILON)
+        return values;
+    const criticalPoint = -quadratic / (3 * cubic);
+    if (criticalPoint > 0 && criticalPoint < 1) {
+        values.push(segmentDerivative(segment, criticalPoint));
+    }
+    return values;
+}
+function validateDerivativeBounds(segment, index) {
+    const extrema = derivativeExtrema(segment);
+    const minimum = Math.min(...extrema);
+    const maximum = Math.max(...extrema);
+    if (minimum < AUDIO_SYNC_STRETCH_MIN - EPSILON
+        || maximum > AUDIO_SYNC_STRETCH_MAX + EPSILON) {
+        throw new Error(`Smooth retiming rate in segment ${index + 1} must stay between ${AUDIO_SYNC_STRETCH_MIN} and ${AUDIO_SYNC_STRETCH_MAX}`);
+    }
+}
+function normalizedAnchors(input) {
+    const anchors = [{ videoSeconds: 0, audioSeconds: 0 }];
+    let suppliedStart = false;
+    for (const anchor of input.anchors) {
+        if (!suppliedStart && anchors.length === 1
+            && anchor.videoSeconds === 0 && anchor.audioSeconds === 0) {
+            suppliedStart = true;
+            continue;
+        }
+        anchors.push({ ...anchor });
+    }
+    const finalAnchor = anchors.at(-1);
+    if (finalAnchor.videoSeconds !== input.videoDuration
+        || finalAnchor.audioSeconds !== input.audioDuration) {
+        anchors.push({
+            videoSeconds: input.videoDuration,
+            audioSeconds: input.audioDuration,
+        });
+    }
+    return anchors;
+}
+export function createAudioSyncPlan(input) {
+    requireFinite("videoDuration", input.videoDuration);
+    requireFinite("audioDuration", input.audioDuration);
+    requireFinite("sourceFps", input.sourceFps);
+    if (input.videoDuration <= 0)
+        throw new Error("Video duration must be greater than zero");
+    if (input.audioDuration <= 0)
+        throw new Error("Audio duration must be greater than zero");
+    if (input.sourceFps <= 0)
+        throw new Error("Source frame rate must be greater than zero");
+    for (const [index, anchor] of input.anchors.entries()) {
+        requireFinite(`anchors[${index}].videoSeconds`, anchor.videoSeconds);
+        requireFinite(`anchors[${index}].audioSeconds`, anchor.audioSeconds);
+        if (anchor.videoSeconds < 0 || anchor.videoSeconds > input.videoDuration) {
+            throw new Error(`Video anchor ${index + 1} must be within the video duration`);
+        }
+        if (anchor.audioSeconds < 0 || anchor.audioSeconds > input.audioDuration) {
+            throw new Error(`Audio anchor ${index + 1} must be within the audio duration`);
+        }
+    }
+    const anchors = normalizedAnchors(input);
+    const frameDuration = 1 / input.sourceFps;
+    const intervals = [];
+    const slopes = [];
+    for (let index = 0; index < anchors.length - 1; index++) {
+        const current = anchors[index];
+        const next = anchors[index + 1];
+        const videoInterval = next.videoSeconds - current.videoSeconds;
+        const audioInterval = next.audioSeconds - current.audioSeconds;
+        if (videoInterval <= EPSILON || audioInterval <= EPSILON) {
+            throw new Error("Audio-sync anchors must be strictly increasing on both clocks");
+        }
+        if (videoInterval + EPSILON < frameDuration || audioInterval + EPSILON < frameDuration) {
+            throw new Error(`Audio-sync anchor intervals must be at least one source frame (${frameDuration.toFixed(6)}s)`);
+        }
+        const durationFactor = audioInterval / videoInterval;
+        if (durationFactor < AUDIO_SYNC_STRETCH_MIN - EPSILON
+            || durationFactor > AUDIO_SYNC_STRETCH_MAX + EPSILON) {
+            throw new Error(`Segment duration factor must be between ${AUDIO_SYNC_STRETCH_MIN} and ${AUDIO_SYNC_STRETCH_MAX}`);
+        }
+        intervals.push(videoInterval);
+        slopes.push(durationFactor);
+    }
+    if (anchors.every((anchor) => nearlyEqual(anchor.videoSeconds, anchor.audioSeconds))) {
+        throw new Error("Audio-sync map is a no-op");
+    }
+    const derivatives = pchipDerivatives(intervals, slopes);
+    const segments = slopes.map((durationFactor, index) => {
+        const start = anchors[index];
+        const end = anchors[index + 1];
+        const interval = intervals[index];
+        const startDerivative = derivatives[index];
+        const endDerivative = derivatives[index + 1];
+        const coefficients = [
+            2 * start.audioSeconds - 2 * end.audioSeconds
+                + interval * (startDerivative + endDerivative),
+            -3 * start.audioSeconds + 3 * end.audioSeconds
+                - interval * (2 * startDerivative + endDerivative),
+            interval * startDerivative,
+            start.audioSeconds,
+        ];
+        const segment = {
+            videoStartSeconds: start.videoSeconds,
+            videoEndSeconds: end.videoSeconds,
+            audioStartSeconds: start.audioSeconds,
+            audioEndSeconds: end.audioSeconds,
+            durationFactor,
+            startDerivative,
+            endDerivative,
+            coefficients,
+        };
+        validateDerivativeBounds(segment, index);
+        return segment;
+    });
+    return {
+        videoDuration: input.videoDuration,
+        audioDuration: input.audioDuration,
+        sourceFps: input.sourceFps,
+        frameDuration,
+        anchors,
+        segments,
+    };
+}
+function findSegment(plan, videoSeconds) {
+    return plan.segments.find((segment) => videoSeconds <= segment.videoEndSeconds + EPSILON)
+        ?? plan.segments.at(-1);
+}
+export function evaluateAudioSyncMap(plan, videoSeconds) {
+    requireFinite("videoSeconds", videoSeconds);
+    if (videoSeconds < -EPSILON || videoSeconds > plan.videoDuration + EPSILON) {
+        throw new Error("Video timestamp must be within the planned video duration");
+    }
+    const clamped = Math.min(plan.videoDuration, Math.max(0, videoSeconds));
+    const segment = findSegment(plan, clamped);
+    const interval = segment.videoEndSeconds - segment.videoStartSeconds;
+    const normalizedTime = (clamped - segment.videoStartSeconds) / interval;
+    const [cubic, quadratic, linear, constant] = segment.coefficients;
+    return ((cubic * normalizedTime + quadratic) * normalizedTime + linear)
+        * normalizedTime + constant;
+}
+export function evaluateAudioSyncDerivative(plan, videoSeconds) {
+    requireFinite("videoSeconds", videoSeconds);
+    if (videoSeconds < -EPSILON || videoSeconds > plan.videoDuration + EPSILON) {
+        throw new Error("Video timestamp must be within the planned video duration");
+    }
+    const clamped = Math.min(plan.videoDuration, Math.max(0, videoSeconds));
+    const segment = findSegment(plan, clamped);
+    const interval = segment.videoEndSeconds - segment.videoStartSeconds;
+    return segmentDerivative(segment, (clamped - segment.videoStartSeconds) / interval);
+}
+function filterNumber(value) {
+    return Number(value.toFixed(12)).toString();
+}
+function setptsPolynomial(segment) {
+    const sourceTime = "((PTS-STARTPTS)*TB)";
+    const start = filterNumber(segment.videoStartSeconds);
+    const interval = filterNumber(segment.videoEndSeconds - segment.videoStartSeconds);
+    const normalizedTime = `((${sourceTime}-${start})/${interval})`;
+    const [cubic, quadratic, linear, constant] = segment.coefficients.map(filterNumber);
+    return `(((${cubic}*${normalizedTime}+${quadratic})*${normalizedTime}+${linear})*${normalizedTime}+${constant})/TB`;
+}
+export function buildAudioSyncSetptsExpression(plan) {
+    let expression = setptsPolynomial(plan.segments.at(-1));
+    for (let index = plan.segments.length - 2; index >= 0; index--) {
+        const boundary = filterNumber(plan.segments[index].videoEndSeconds);
+        expression = `if(lte((PTS-STARTPTS)*TB,${boundary}),${setptsPolynomial(plan.segments[index])},${expression})`;
+    }
+    return expression;
+}
+export function buildAudioSyncVideoFilter(plan) {
+    const fps = filterNumber(plan.sourceFps);
+    const duration = filterNumber(plan.audioDuration);
+    return `[0:v:0]setpts='${buildAudioSyncSetptsExpression(plan)}',fps=fps=${fps},tpad=stop_mode=clone:stop_duration=${duration},trim=duration=${duration}[vout]`;
+}

package/dist/audio-trim-range.js

@@ -0,0 +1,31 @@
+export const AUDIO_TRIM_EPSILON_SECONDS = 0.05;
+function expectedAudioTrimDuration(sourceDuration, mode, trimStart, trimEnd, cutStart, cutEnd) {
+    if (mode === "keep") {
+        const start = trimStart ?? 0;
+        const end = trimEnd ?? sourceDuration;
+        if (start >= sourceDuration - AUDIO_TRIM_EPSILON_SECONDS) {
+            throw new Error(`trim_start ${start} must be before audio duration ${sourceDuration.toFixed(3)}`);
+        }
+        if (end > sourceDuration + AUDIO_TRIM_EPSILON_SECONDS) {
+            throw new Error(`trim_end ${end} exceeds audio duration ${sourceDuration.toFixed(3)}`);
+        }
+        return Math.min(end, sourceDuration) - start;
+    }
+    const start = cutStart ?? 0;
+    const end = cutEnd ?? sourceDuration;
+    if (start >= sourceDuration - AUDIO_TRIM_EPSILON_SECONDS) {
+        throw new Error(`cut_start ${start} must be before audio duration ${sourceDuration.toFixed(3)}`);
+    }
+    if (end > sourceDuration + AUDIO_TRIM_EPSILON_SECONDS) {
+        throw new Error(`cut_end ${end} exceeds audio duration ${sourceDuration.toFixed(3)}`);
+    }
+    return sourceDuration - (Math.min(end, sourceDuration) - start);
+}
+export function validateAudioTrimRange(sourceDuration, mode, trimStart, trimEnd, cutStart, cutEnd) {
+    if (!Number.isFinite(sourceDuration) || sourceDuration <= 0)
+        throw new Error("Audio file has no usable duration");
+    const duration = expectedAudioTrimDuration(sourceDuration, mode, trimStart, trimEnd, cutStart, cutEnd);
+    if (duration <= AUDIO_TRIM_EPSILON_SECONDS)
+        throw new Error("Trim would produce an empty audio file");
+    return duration;
+}

package/dist/book-context.js

@@ -0,0 +1,31 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const contexts = new AsyncLocalStorage();
+export function currentBookContext() {
+    return contexts.getStore();
+}
+function activeBookContext() {
+    const context = contexts.getStore();
+    if (!context)
+        throw new Error("A book context is required for this operation");
+    return context;
+}
+export function activeBookEngine() {
+    return activeBookContext().engine;
+}
+/**
+ * Tool and job code often holds `scopedBookEngine` rather than a concrete
+ * engine. Storing that proxy as a context's engine would make every property
+ * read resolve back to itself, so nested contexts inherit the enclosing book's
+ * concrete engine instead.
+ */
+function concreteEngine(engine) {
+    return engine === scopedBookEngine ? activeBookEngine() : engine;
+}
+export async function withBookContext(context, operation) {
+    return contexts.run({ ...context, engine: concreteEngine(context.engine) }, operation);
+}
+export const scopedBookEngine = new Proxy({}, {
+    get(_target, property) {
+        return Reflect.get(activeBookEngine(), property);
+    },
+});