@glissade/narrate 0.4.2 → 0.4.4

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AssetRef, AudioClip, Track } from "@glissade/core";
+import { AssetRef, AudioClip, Key, Track } from "@glissade/core";
 import { FilterSpec, Text } from "@glissade/scene";
 
 //#region src/index.d.ts
@@ -92,7 +92,89 @@ declare function captionNode(size: {
   w: number;
   h: number;
 }, style?: CaptionStyle): Text;
+interface DuckOptions {
+  /** gain while narration speaks; default 0.25 */
+  duck?: number;
+  /** gain elsewhere; default 1 */
+  base?: number;
+  /** ramp-down seconds before a segment starts; default 0.15 */
+  attack?: number;
+  /** ramp-up seconds after a segment ends; default 0.4 */
+  release?: number;
+  /**
+   * Windows whose gap (after attack/release) is smaller than this stay
+   * ducked through — no pumping between close segments. Default 0.5.
+   */
+  mergeGap?: number;
+  /** the music clip's `at` on the timeline; gain keys are CLIP-local. Default 0. */
+  clipAt?: number;
+}
+/**
+ * The bed-ducking envelope every narrated video needs: duck windows are the
+ * narration segments, with attack/release ramps and near-window merging.
+ * Pure function of the committed manifest — re-narrate and the ducking
+ * re-flows. Returns a keys-only gain envelope for AudioClip.gain.
+ */
+declare function duckEnvelope(timing: NarrationTiming, opts?: DuckOptions): {
+  keys: Key<number>[];
+};
+/**
+ * `<name>.music.timing.json` — committed next to its stem. The load-bearing
+ * invariant: BEAT 0 IS SAMPLE 0 of the stem (the prepare step trims the
+ * recording to the downbeat); `offsetSec` exists for stems that can't be
+ * trimmed (count-ins). Everything derives from bpm/beatsPerCycle — no
+ * per-beat marker arrays. Shape blessed from downstream production
+ * (TidalCycles render step), where `cps` is the native unit: when present it
+ * must agree with bpm/beatsPerCycle.
+ */
+interface MusicTiming {
+  musicVersion: 1;
+  name?: string;
+  bpm: number;
+  beatsPerCycle: number;
+  cycles?: number;
+  /** cycles per second — TidalCycles-native; must equal bpm / (60 · beatsPerCycle) */
+  cps?: number;
+  durationSec: number;
+  /** seconds into the stem where beat 0 sits; default 0 (trimmed-to-downbeat) */
+  offsetSec?: number;
+  /** stem audio file, relative to the manifest — required for render auto-mix */
+  stem?: string;
+  /** bed level in dB applied to the clip gain (auto-mix and clip()); default 0 */
+  gainDb?: number;
+  /** provenance (e.g. the .tidal pattern source) */
+  source?: string;
+}
+interface MusicClipOptions {
+  /** bed level in dB; overrides the manifest's gainDb */
+  gainDb?: number;
+  /** auto-duck under this narration (windows from its segments) */
+  duckUnder?: NarrationTiming;
+  duckOpts?: Omit<DuckOptions, 'clipAt'>;
+}
+interface MusicAnchors {
+  /** timeline second of beat n (beat 0 = clip at + offsetSec) */
+  beat(n: number): number;
+  /** timeline second of cycle n (beatsPerCycle beats each) */
+  cycle(n: number): number;
+  /** quantize t to the closest beat */
+  nearestBeat(t: number): number;
+  /** quantize t forward to the next beat (what choreography reaches for) */
+  nextBeat(t: number): number;
+  readonly beatLen: number;
+  readonly durationSec: number;
+  /** the grid parameters, for external quantizers */
+  grid(): {
+    bpm: number;
+    offsetSec: number;
+  };
+  /** the stem as an AudioClip, with bed gain and optional narration ducking composed */
+  clip(url?: string, opts?: MusicClipOptions): AudioClip;
+}
+declare function validateMusicTiming(timing: MusicTiming): void;
+/** Beat-grid anchors over a music manifest; `at` places the clip on the timeline. */
+declare function music(timing: MusicTiming, at?: number): MusicAnchors;
 declare function toSrt(timing: NarrationTiming): string;
 declare function toVtt(timing: NarrationTiming): string;
 //#endregion
-export { CaptionStyle, CaptionTrackOptions, NarrationAnchors, NarrationError, NarrationScript, NarrationSegment, NarrationTiming, TimedSegment, TimedWord, captionNode, captionTrack, narration, toSrt, toVtt };
+export { CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationError, NarrationScript, NarrationSegment, NarrationTiming, TimedSegment, TimedWord, captionNode, captionTrack, duckEnvelope, music, narration, toSrt, toVtt, validateMusicTiming };

package/dist/index.js

@@ -87,6 +87,94 @@ function captionNode(size, style = {}) {
 		filters: style.filters ?? glow("#000000cc", 3, 1)
 	});
 }
+/**
+* The bed-ducking envelope every narrated video needs: duck windows are the
+* narration segments, with attack/release ramps and near-window merging.
+* Pure function of the committed manifest — re-narrate and the ducking
+* re-flows. Returns a keys-only gain envelope for AudioClip.gain.
+*/
+function duckEnvelope(timing, opts = {}) {
+	const duck = opts.duck ?? .25;
+	const base = opts.base ?? 1;
+	const attack = opts.attack ?? .15;
+	const release = opts.release ?? .4;
+	const mergeGap = opts.mergeGap ?? .5;
+	const clipAt = opts.clipAt ?? 0;
+	const windows = [];
+	for (const s of [...timing.segments].sort((a, b) => a.start - b.start)) {
+		const last = windows[windows.length - 1];
+		if (last && s.start - last.end < attack + release + mergeGap) last.end = Math.max(last.end, s.start + s.duration);
+		else windows.push({
+			start: s.start,
+			end: s.start + s.duration
+		});
+	}
+	const keys = [];
+	for (const w of windows) {
+		const rampStart = w.start - attack - clipAt;
+		const down = w.start - clipAt;
+		const up = w.end - clipAt;
+		const rampEnd = w.end + release - clipAt;
+		if (rampEnd <= 0) continue;
+		if (rampStart > 0) keys.push(key(rampStart, base));
+		if (down > 0) keys.push(key(down, duck));
+		else if (keys.length === 0) keys.push(key(0, duck));
+		keys.push(key(Math.max(up, 1e-6), duck));
+		keys.push(key(rampEnd, base));
+	}
+	if (keys.length === 0) keys.push(key(0, base));
+	if (keys[0].t > 0) keys.unshift(key(0, base));
+	return { keys };
+}
+function validateMusicTiming(timing) {
+	if (timing.musicVersion !== 1) throw new NarrationError(`unsupported musicVersion ${String(timing.musicVersion)}`);
+	if (!(timing.bpm > 0) || !(timing.beatsPerCycle > 0)) throw new NarrationError("music timing needs bpm > 0 and beatsPerCycle > 0");
+	if (timing.cps !== void 0) {
+		const expected = timing.bpm / (60 * timing.beatsPerCycle);
+		if (Math.abs(timing.cps - expected) > 1e-9) throw new NarrationError(`music timing cps (${timing.cps}) disagrees with bpm/beatsPerCycle (expected ${expected})`);
+	}
+}
+/** Beat-grid anchors over a music manifest; `at` places the clip on the timeline. */
+function music(timing, at = 0) {
+	validateMusicTiming(timing);
+	const beatLen = 60 / timing.bpm;
+	const beat0 = at + (timing.offsetSec ?? 0);
+	return {
+		beat: (n) => beat0 + n * beatLen,
+		cycle: (n) => beat0 + n * timing.beatsPerCycle * beatLen,
+		nearestBeat: (t) => beat0 + Math.round((t - beat0) / beatLen) * beatLen,
+		nextBeat: (t) => beat0 + Math.ceil((t - beat0 - 1e-9) / beatLen) * beatLen,
+		beatLen,
+		durationSec: timing.durationSec,
+		grid: () => ({
+			bpm: timing.bpm,
+			offsetSec: beat0
+		}),
+		clip: (url, opts = {}) => {
+			const src = url ?? timing.stem;
+			if (!src) throw new NarrationError("music clip needs a url (or a stem field in the manifest)");
+			const gainDb = opts.gainDb ?? timing.gainDb ?? 0;
+			const scale = Math.pow(10, gainDb / 20);
+			let keys = null;
+			if (opts.duckUnder) keys = duckEnvelope(opts.duckUnder, {
+				...opts.duckOpts,
+				clipAt: at
+			}).keys;
+			else if (gainDb !== 0) keys = [key(0, 1)];
+			return {
+				asset: {
+					kind: "audio",
+					url: src
+				},
+				at,
+				...keys !== null ? { gain: { keys: keys.map((k) => ({
+					...k,
+					value: k.value * scale
+				})) } } : {}
+			};
+		}
+	};
+}
 function srtTime(t, sep) {
 	const ms = Math.round(t * 1e3);
 	const h = Math.floor(ms / 36e5);
@@ -103,4 +191,4 @@ function toVtt(timing) {
 	return "WEBVTT\n\n" + timing.segments.map((s) => `${srtTime(s.start, ".")} --> ${srtTime(s.start + s.duration, ".")}\n${s.text}`).join("\n\n") + "\n";
 }
 //#endregion
-export { NarrationError, captionNode, captionTrack, narration, toSrt, toVtt };
+export { NarrationError, captionNode, captionTrack, duckEnvelope, music, narration, toSrt, toVtt, validateMusicTiming };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "glissade narration + captions: TTS at prepare time (gs narrate), deterministic caching, narration-anchored timeline beats, and captions as plain tracks. Render stays offline.",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,8 +19,8 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.4.2",
-    "@glissade/scene": "0.4.2"
+    "@glissade/core": "0.4.4",
+    "@glissade/scene": "0.4.4"
   },
   "repository": {
     "type": "git",