@glissade/narrate 0.4.2 → 0.4.3

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,33 @@ 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>[];
+};
 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, NarrationAnchors, NarrationError, NarrationScript, NarrationSegment, NarrationTiming, TimedSegment, TimedWord, captionNode, captionTrack, duckEnvelope, narration, toSrt, toVtt };

package/dist/index.js

@@ -87,6 +87,45 @@ 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 srtTime(t, sep) {
 	const ms = Math.round(t * 1e3);
 	const h = Math.floor(ms / 36e5);
@@ -103,4 +142,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, narration, toSrt, toVtt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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/scene": "0.4.3",
+    "@glissade/core": "0.4.3"
   },
   "repository": {
     "type": "git",