@anvpx/motion-build 0.1.0 → 0.1.1

package/dist/audio/mix.d.ts

@@ -9,6 +9,11 @@ export interface MixClip {
     readonly duration: number;
     readonly wav: string;
 }
+/** Final-timeline placement for one scene id (start/duration after overlaps). */
+export interface MixPlacement {
+    readonly start: number;
+    readonly duration: number;
+}
 /** Opt-in build input: which manifest to mix and where its wavs live. */
 export interface AudioManifestRef {
     readonly manifest: TimingManifest;
@@ -25,8 +30,8 @@ export type AudioManifestResult = {
 };
 /** Wav path for one scene id inside the manifest's audio directory. */
 export declare const wavPathFor: (audioDir: string, id: string) => string;
-/** Manifest scenes in order, each resolved to its wav path. */
-export declare const clipsFromManifest: (manifest: TimingManifest, audioDir: string) => MixClip[];
+/** Manifest scenes in order, each resolved to its wav path and, when given, the final timeline placement. */
+export declare const clipsFromManifest: (manifest: TimingManifest, audioDir: string, placements?: ReadonlyMap<string, MixPlacement>) => MixClip[];
 /** Clips whose wav is absent; non-empty means refuse to mix (fail closed). */
 export declare const missingClips: (clips: readonly MixClip[], exists: (path: string) => boolean) => MixClip[];
 /** Whole seconds to integer ffmpeg milliseconds; refuses nonsense. */
@@ -45,8 +50,9 @@ export declare const isContiguous: (scenes: readonly {
 export declare const buildFilterGraph: (clips: readonly MixClip[]) => string;
 /**
  * Deterministic ffmpeg argv: silent video plus one `-i` per wav, video passed
- * through (`-c:v copy`), narration mixed to aac, `-shortest` trimming any
- * sub-frame tail so the output never outruns the picture.
+ * through (`-c:v copy`), narration mixed to aac. No `-shortest`: the picture is
+ * the timing authority, and a scene may hold silent after its narration ends.
+ * Trimming to the last wav would cut the authored tail (and the video with it).
  */
 export declare const buildMixArgs: (videoIn: string, clips: readonly MixClip[], out: string) => string[];
 /** Validates an unknown document as a mixable TimingManifest (fail closed). */
@@ -136,7 +142,8 @@ export declare const musicLoopFor: (bedDuration: number, clips: readonly MixClip
 /**
  * Deterministic ffmpeg argv with a ducked bed: silent video plus one `-i`
  * per narration wav plus the bed wav last, video passed through
- * (`-c:v copy`), bed ducked under narration and mixed to aac, `-shortest`.
+ * (`-c:v copy`), bed ducked under narration and mixed to aac. No `-shortest`;
+ * the picture keeps its authored tail after the last word.
  */
 export declare const buildMusicMixArgs: (videoIn: string, clips: readonly MixClip[], music: MusicBed, out: string) => string[];
 /**

package/dist/audio/mix.js

@@ -20,13 +20,19 @@ import { MIX_TRUE_PEAK_DBTP, SIDECHAIN_ATTACK_MS, SIDECHAIN_RATIO, SIDECHAIN_REL
 export const AUDIO_DIR_NAME = "audio";
 /** Wav path for one scene id inside the manifest's audio directory. */
 export const wavPathFor = (audioDir, id) => join(audioDir, `${id}.wav`);
-/** Manifest scenes in order, each resolved to its wav path. */
-export const clipsFromManifest = (manifest, audioDir) => manifest.scenes.map((scene) => ({
-    id: scene.id,
-    start: scene.start,
-    duration: scene.duration,
-    wav: wavPathFor(audioDir, scene.id),
-}));
+/** Manifest scenes in order, each resolved to its wav path and, when given, the final timeline placement. */
+export const clipsFromManifest = (manifest, audioDir, placements) => manifest.scenes.map((scene) => {
+    const placed = placements?.get(scene.id);
+    return {
+        id: scene.id,
+        // The voice manifest is a non-overlapping audio sequence; the film
+        // timeline may start scenes 0.5 s early for a transition. The mix must
+        // follow the picture, not the voice sequence.
+        start: placed?.start ?? scene.start,
+        duration: placed?.duration ?? scene.duration,
+        wav: wavPathFor(audioDir, scene.id),
+    };
+});
 /** Clips whose wav is absent; non-empty means refuse to mix (fail closed). */
 export const missingClips = (clips, exists) => clips.filter((clip) => !exists(clip.wav));
 /** Whole seconds to integer ffmpeg milliseconds; refuses nonsense. */
@@ -78,8 +84,9 @@ const narrationGraph = (clips, outLabel) => {
 };
 /**
  * Deterministic ffmpeg argv: silent video plus one `-i` per wav, video passed
- * through (`-c:v copy`), narration mixed to aac, `-shortest` trimming any
- * sub-frame tail so the output never outruns the picture.
+ * through (`-c:v copy`), narration mixed to aac. No `-shortest`: the picture is
+ * the timing authority, and a scene may hold silent after its narration ends.
+ * Trimming to the last wav would cut the authored tail (and the video with it).
  */
 export const buildMixArgs = (videoIn, clips, out) => [
     "-y",
@@ -98,7 +105,6 @@ export const buildMixArgs = (videoIn, clips, out) => [
     "aac",
     "-movflags",
     "+faststart",
-    "-shortest",
     out,
 ];
 /** Validates an unknown document as a mixable TimingManifest (fail closed). */
@@ -167,7 +173,7 @@ export const buildMusicFilterGraph = (clips, music) => {
     const sidechain = `sidechaincompress=threshold=${SIDECHAIN_THRESHOLD}:ratio=${SIDECHAIN_RATIO}` +
         `:attack=${SIDECHAIN_ATTACK_MS}:release=${SIDECHAIN_RELEASE_MS}`;
     return (`[${musicIndex}:a]volume=${volume},aloop=loop=-1:size=2e9,atrim=duration=${total}[mbed];` +
-        `${narr};[narr]asplit[nkey][nmix];` +
+        `${narr};[narr]apad=whole_dur=${total},asplit[nkey][nmix];` +
         `[mbed][nkey]${sidechain}[ducked];` +
         `[nmix][ducked]amix=inputs=2:normalize=0[aout]`);
 };
@@ -264,7 +270,8 @@ export const musicLoopFor = (bedDuration, clips) => {
 /**
  * Deterministic ffmpeg argv with a ducked bed: silent video plus one `-i`
  * per narration wav plus the bed wav last, video passed through
- * (`-c:v copy`), bed ducked under narration and mixed to aac, `-shortest`.
+ * (`-c:v copy`), bed ducked under narration and mixed to aac. No `-shortest`;
+ * the picture keeps its authored tail after the last word.
  */
 export const buildMusicMixArgs = (videoIn, clips, music, out) => [
     "-y",
@@ -285,7 +292,6 @@ export const buildMusicMixArgs = (videoIn, clips, music, out) => [
     "aac",
     "-movflags",
     "+faststart",
-    "-shortest",
     out,
 ];
 /**

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { CUSTOM_SCENE_TYPE, type CustomSceneFile, type CustomSceneSource, collec
 export { bundledThemeDocs } from "@anvpx/motion-themes";
 export { type AssetCollector, type CopiedAsset, copyAssets, createAssetCollector, normaliseRef, sha256Of, } from "./assets.ts";
 export { type FrozenCopyCheck, frozenCopyProblems, } from "./audio/approval.ts";
-export { AT_TARGET_TOLERANCE_LU, AUDIO_DIR_NAME, type AudioManifestRef, type AudioManifestResult, buildFilterGraph, buildLoudnessMeasureArgs, buildLoudnessNormalizeArgs, buildLoudnessNormalizeFilter, buildMixArgs, buildMusicFilterGraph, buildMusicMixArgs, clipsFromManifest, DEFAULT_MUSIC_VOLUME, frozenClips, frozenMusic, frozenWavFor, isContiguous, LOUDNORM_MEASURE_FILTER, type LoudnessMeasurement, type MixClip, type MixDelivery, type MixDeliveryPlan, type MixRunner, type MixRunResult, type MusicBed, missingClips, missingMusic, mixAtDeliveryLevel, needsNormalization, parseAudioManifest, parseLoudnessMeasurement, resolveMusicVolume, TARGET_LRA, TARGET_LUFS, TARGET_TRUE_PEAK_DB, toDelayMs, wavPathFor, } from "./audio/mix.ts";
+export { AT_TARGET_TOLERANCE_LU, AUDIO_DIR_NAME, type AudioManifestRef, type AudioManifestResult, buildFilterGraph, buildLoudnessMeasureArgs, buildLoudnessNormalizeArgs, buildLoudnessNormalizeFilter, buildMixArgs, buildMusicFilterGraph, buildMusicMixArgs, clipsFromManifest, DEFAULT_MUSIC_VOLUME, frozenClips, frozenMusic, frozenWavFor, isContiguous, LOUDNORM_MEASURE_FILTER, type LoudnessMeasurement, type MixClip, type MixDelivery, type MixDeliveryPlan, type MixPlacement, type MixRunner, type MixRunResult, type MusicBed, missingClips, missingMusic, mixAtDeliveryLevel, needsNormalization, parseAudioManifest, parseLoudnessMeasurement, resolveMusicVolume, TARGET_LRA, TARGET_LUFS, TARGET_TRUE_PEAK_DB, toDelayMs, wavPathFor, } from "./audio/mix.ts";
 export { type BuildOptions, type BuildResult, buildProject, tryResolveTheme, } from "./build.ts";
 export { type CacheStats, clearCache } from "./cache.ts";
 export { CSP } from "./emit/index-html.ts";
@@ -14,6 +14,6 @@ export { WORDS_PER_SECOND } from "./lint/reading-time.ts";
 export { type BuildManifest, type CompiledAssetView, compiledAssetMismatches, } from "./manifest.ts";
 export { createRenderManifest, type RenderManifest, type RenderManifestInput, renderRenderManifest, } from "./render-manifest.ts";
 export * from "./templates/index.ts";
-export { autoDuration, resolveTimeline, type TimedScene, type Timeline, } from "./timing.ts";
+export { autoDuration, placementsFromTimeline, resolveTimeline, type ScenePlacement, type TimedScene, type Timeline, } from "./timing.ts";
 export { validateStoryboardFull } from "./validate-full.ts";
 export { type FindingLevel, type MediaExpectation, type VerifyFinding, type VerifyInput, type VerifyReport, type VerifyStatus, verifyMedia, } from "./verify.ts";

package/dist/index.js

@@ -14,6 +14,6 @@ export { WORDS_PER_SECOND } from "./lint/reading-time.js";
 export { compiledAssetMismatches, } from "./manifest.js";
 export { createRenderManifest, renderRenderManifest, } from "./render-manifest.js";
 export * from "./templates/index.js";
-export { autoDuration, resolveTimeline, } from "./timing.js";
+export { autoDuration, placementsFromTimeline, resolveTimeline, } from "./timing.js";
 export { validateStoryboardFull } from "./validate-full.js";
 export { verifyMedia, } from "./verify.js";

package/dist/timing.d.ts

@@ -32,6 +32,13 @@ export interface Timeline {
     readonly overlays: readonly TimedOverlay[];
     readonly total: number;
 }
+/** One scene's placement on the final (overlap-aware) timeline. */
+export interface ScenePlacement {
+    readonly start: number;
+    readonly duration: number;
+}
+/** Map a resolved timeline to the placement a narration clip must use. */
+export declare const placementsFromTimeline: (timeline: Timeline) => Map<string, ScenePlacement>;
 export declare const autoDuration: (words: number) => number;
 export declare const isOverlay: (entry: SceneEntry) => boolean;
 /** Authored durations, optionally overridden per base scene id by a voice TimingManifest. */

package/dist/timing.js

@@ -8,10 +8,20 @@ export const IMPLEMENTED_TRANSITIONS = [
     "wipe",
     "zoom-through",
 ];
+/** Map a resolved timeline to the placement a narration clip must use. */
+export const placementsFromTimeline = (timeline) => new Map(timeline.scenes.map((scene) => [scene.id, { start: scene.start, duration: scene.duration }]));
 const round3 = (value) => Math.round(value * 1000) / 1000;
 export const autoDuration = (words) => Math.max(MIN_AUTO_SECONDS, Math.ceil(words / 3 + 1.5));
 export const isOverlay = (entry) => entry.layer === "overlay";
-const durationOf = (entry, voice) => round3(voice.get(entry.id) ?? entry.duration ?? autoDuration(sceneWords(entry.props, entry.type)));
+const durationOf = (entry, voice) => {
+    const authored = entry.duration ?? autoDuration(sceneWords(entry.props, entry.type));
+    const voiced = voice.get(entry.id);
+    // Voice is a floor on the spoken scene, never a reason to cut the authored
+    // picture shorter. `mk voice` preflights narration against the authored
+    // duration, so this normally keeps the authored value and leaves the tail of
+    // the scene silent; a longer manifest wins so narration can never clip.
+    return round3(voiced === undefined ? authored : Math.max(authored, voiced));
+};
 const overlapOf = (entry, prev, own) => entry.transition === "crossfade" ||
     entry.transition === "push" ||
     entry.transition === "wipe" ||

package/dist/verify.js

@@ -27,6 +27,7 @@ const videoOf = (stream) => ({
         ? { fps: parseRate(stream.r_frame_rate) }
         : {}),
     ...(count(stream.nb_frames) !== undefined ? { frames: count(stream.nb_frames) } : {}),
+    ...(count(stream.duration) !== undefined ? { duration: count(stream.duration) } : {}),
 });
 const readProbe = (probe) => {
     const root = asRecord(probe);
@@ -67,13 +68,16 @@ function checkFrame(video, expected, add) {
 function checkTiming(probed, expected, add) {
     const { video, duration } = probed;
     const fps = video?.fps;
-    if (expected.duration !== undefined && duration !== undefined) {
+    // Measure the picture. The container can be ~0.17 s longer than the video
+    // because AAC adds encoder priming/padding; that is not a timing failure.
+    const measured = video?.duration ?? duration;
+    if (expected.duration !== undefined && measured !== undefined) {
         const tolerance = Math.max(DURATION_TOLERANCE_SECONDS, fps ? 1 / fps : 0);
-        if (Math.abs(duration - expected.duration) > tolerance) {
-            add("duration-mismatch", "fatal", `Duration is ${duration.toFixed(2)}s, expected ${expected.duration.toFixed(2)}s.`);
+        if (Math.abs(measured - expected.duration) > tolerance) {
+            add("duration-mismatch", "fatal", `Duration is ${measured.toFixed(2)}s, expected ${expected.duration.toFixed(2)}s.`);
         }
     }
-    const reference = expected.duration ?? duration;
+    const reference = expected.duration ?? video?.duration ?? duration;
     if (video?.frames === undefined || fps === undefined || reference === undefined)
         return;
     const wanted = Math.round(reference * fps);
@@ -136,8 +140,9 @@ function checkPlatform(probed, template, add) {
     if (video)
         checkPlatformFrame(video, template, add);
     const cap = template.maxDurationSec;
-    if (cap !== undefined && duration !== undefined && duration > cap) {
-        add("platform-duration", "fatal", `Duration ${duration.toFixed(1)}s exceeds the ${id} cap ${cap}s.`);
+    const measured = video?.duration ?? duration;
+    if (cap !== undefined && measured !== undefined && measured > cap) {
+        add("platform-duration", "fatal", `Duration ${measured.toFixed(1)}s exceeds the ${id} cap ${cap}s.`);
     }
     if (!template.verified) {
         add("platform-unverified", "info", `Template ${id} has verified: false; its limits are approximations. Check the platform's current specs.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvpx/motion-build",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Storyboard compiler for @anvpx/motion: validation, scene emission and HyperFrames project output.",
   "license": "MIT",
   "author": "anvpx",
@@ -31,9 +31,9 @@
     "@fontsource/jetbrains-mono": "5.3.0",
     "@fontsource/source-serif-4": "5.3.1",
     "@fontsource/space-grotesk": "5.3.0",
-    "@anvpx/motion-scenes": "0.1.0",
-    "@anvpx/motion-schema": "0.1.0",
-    "@anvpx/motion-themes": "0.1.0",
+    "@anvpx/motion-scenes": "0.1.1",
+    "@anvpx/motion-schema": "0.1.1",
+    "@anvpx/motion-themes": "0.1.1",
     "postprocessing": "6.39.5",
     "three": "0.186.0"
   },