@glissade/narrate 0.4.3 → 0.4.4

package/dist/index.d.ts

@@ -118,7 +118,63 @@ interface DuckOptions {
 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, DuckOptions, NarrationAnchors, NarrationError, NarrationScript, NarrationSegment, NarrationTiming, TimedSegment, TimedWord, captionNode, captionTrack, duckEnvelope, 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

@@ -126,6 +126,55 @@ function duckEnvelope(timing, opts = {}) {
 	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);
@@ -142,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, duckEnvelope, 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.3",
+  "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/scene": "0.4.3",
-    "@glissade/core": "0.4.3"
+    "@glissade/core": "0.4.4",
+    "@glissade/scene": "0.4.4"
   },
   "repository": {
     "type": "git",