@glissade/narrate 0.5.0 → 0.6.0-pre.1

package/dist/index.d.ts

@@ -51,6 +51,15 @@ interface NarrationScript {
    * segments word-less. Providers that supply their own words ignore this.
    */
   align?: string;
+  /**
+   * Split long caption segments into timed sub-cues at ~`maxChars` (on word
+   * boundaries, using per-word timings when present). Persisted into the timing
+   * manifest so the burned track and the .srt/.vtt sidecars split identically.
+   * Omit for no split (the default).
+   */
+  captionSplit?: {
+    maxChars: number;
+  };
   /** spoken segments and explicit pause beats, in playback order */
   segments: NarrationElement[];
 }
@@ -85,6 +94,10 @@ interface NarrationTiming {
   segments: TimedSegment[];
   /** explicit pause windows, addressable like segments; omitted when none */
   pauses?: TimedPause[];
+  /** caption split budget, committed so burned + sidecar split identically */
+  captionSplit?: {
+    maxChars: number;
+  };
 }
 declare class NarrationError extends Error {
   constructor(message: string);
@@ -118,6 +131,20 @@ interface CaptionTrackOptions {
   /** v1 granularity is per segment; 'word' is reserved (karaoke highlight, later) */
   granularity?: 'segment';
 }
+/** One caption cue within a segment's window. */
+interface CaptionCue {
+  text: string;
+  start: number;
+  end: number;
+}
+/**
+ * Split a segment's caption into timed sub-cues at ~`maxChars` (word-boundary).
+ * With per-word timings, each sub-cue is timed from its first word; without
+ * them, the segment window is divided evenly. No budget (or a short segment)
+ * yields a single cue — so the default is byte-identical. The SAME function
+ * drives the burned track AND the .srt/.vtt sidecars, so they match.
+ */
+declare function splitCaption(segment: TimedSegment, maxChars?: number): CaptionCue[];
 declare function captionTrack(timing: NarrationTiming, opts?: CaptionTrackOptions): Track<string>;
 interface CaptionStyle {
   fontFamily?: string;
@@ -239,4 +266,4 @@ declare function music(timing: MusicTiming, at?: number): MusicAnchors;
 declare function toSrt(timing: NarrationTiming): string;
 declare function toVtt(timing: NarrationTiming): string;
 //#endregion
-export { BedMode, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, captionNode, captionTrack, duckEnvelope, isPause, music, narration, toSrt, toVtt, validateMusicTiming };
+export { BedMode, CaptionCue, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, captionNode, captionTrack, duckEnvelope, isPause, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };

package/dist/index.js

@@ -76,16 +76,72 @@ function narration(timing) {
 	};
 	return anchors;
 }
+/**
+* Split a segment's caption into timed sub-cues at ~`maxChars` (word-boundary).
+* With per-word timings, each sub-cue is timed from its first word; without
+* them, the segment window is divided evenly. No budget (or a short segment)
+* yields a single cue — so the default is byte-identical. The SAME function
+* drives the burned track AND the .srt/.vtt sidecars, so they match.
+*/
+function splitCaption(segment, maxChars) {
+	const end = segment.start + segment.duration;
+	if (!maxChars || segment.text.length <= maxChars) return [{
+		text: segment.text,
+		start: segment.start,
+		end
+	}];
+	if (segment.words && segment.words.length > 0) {
+		const cues = [];
+		let words = [];
+		let start = segment.words[0].start;
+		for (const w of segment.words) {
+			if (words.length > 0 && [...words, w.word].join(" ").length > maxChars) {
+				cues.push({
+					text: words.join(" "),
+					start,
+					end: w.start
+				});
+				words = [];
+				start = w.start;
+			}
+			words.push(w.word);
+		}
+		if (words.length > 0) cues.push({
+			text: words.join(" "),
+			start,
+			end
+		});
+		return cues;
+	}
+	const tokens = segment.text.split(/\s+/).filter(Boolean);
+	const chunks = [];
+	let cur = "";
+	for (const t of tokens) {
+		const candidate = cur ? `${cur} ${t}` : t;
+		if (cur && candidate.length > maxChars) {
+			chunks.push(cur);
+			cur = t;
+		} else cur = candidate;
+	}
+	if (cur) chunks.push(cur);
+	const span = segment.duration / chunks.length;
+	return chunks.map((text, i) => ({
+		text,
+		start: segment.start + i * span,
+		end: segment.start + (i + 1) * span
+	}));
+}
 function captionTrack(timing, opts = {}) {
 	const target = opts.target ?? "captions/text";
+	const budget = timing.captionSplit?.maxChars;
 	const keys = [key(0, "", { interp: "hold" })];
 	let cursor = 0;
 	for (const s of timing.segments) {
 		if (s.start > cursor + 1e-9) {
 			if (keys[keys.length - 1].value !== "") keys.push(key(cursor, "", { interp: "hold" }));
 		}
-		if (s.start <= 1e-9) keys[0] = key(0, s.text, { interp: "hold" });
-		else keys.push(key(s.start, s.text, { interp: "hold" }));
+		for (const cue of splitCaption(s, budget)) if (cue.start <= 1e-9) keys[0] = key(0, cue.text, { interp: "hold" });
+		else keys.push(key(cue.start, cue.text, { interp: "hold" }));
 		cursor = s.start + s.duration;
 	}
 	keys.push(key(cursor, "", { interp: "hold" }));
@@ -128,16 +184,18 @@ function captionNode(size, style = {}) {
 				weight: node.fontWeight
 			}, width > 0 ? width : void 0, m).length;
 		};
-		node.fontSize.bindSource(() => {
-			const m = node.measurerSource?.() ?? estimatingMeasurer;
+		const fit = (m) => {
 			let font = baseFont;
 			while (font > minFont && lineCountAt(font, m) > maxLines) font -= 1;
-			return font;
-		});
+			return {
+				font,
+				lines: Math.max(1, lineCountAt(font, m))
+			};
+		};
+		node.fontSize.bindSource(() => fit(node.measurerSource?.() ?? estimatingMeasurer).font);
 		node.position.bindSource(() => {
-			const m = node.measurerSource?.() ?? estimatingMeasurer;
-			const lines = Math.max(1, lineCountAt(node.fontSize(), m));
-			const step = quantize(node.fontSize() * lineHeight);
+			const { font, lines } = fit(node.measurerSource?.() ?? estimatingMeasurer);
+			const step = quantize(font * lineHeight);
 			return [size.w / 2, bottomY - (lines - 1) * step];
 		});
 	}
@@ -295,10 +353,10 @@ function srtTime(t, sep) {
 	return `${p(h, 2)}:${p(m, 2)}:${p(s, 2)}${sep}${p(f, 3)}`;
 }
 function toSrt(timing) {
-	return timing.segments.map((s, i) => `${i + 1}\n${srtTime(s.start, ",")} --> ${srtTime(s.start + s.duration, ",")}\n${s.text}`).join("\n\n") + "\n";
+	return timing.segments.flatMap((s) => splitCaption(s, timing.captionSplit?.maxChars)).map((c, i) => `${i + 1}\n${srtTime(c.start, ",")} --> ${srtTime(c.end, ",")}\n${c.text}`).join("\n\n") + "\n";
 }
 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";
+	return "WEBVTT\n\n" + timing.segments.flatMap((s) => splitCaption(s, timing.captionSplit?.maxChars)).map((c) => `${srtTime(c.start, ".")} --> ${srtTime(c.end, ".")}\n${c.text}`).join("\n\n") + "\n";
 }
 //#endregion
-export { NarrationError, captionNode, captionTrack, duckEnvelope, isPause, music, narration, toSrt, toVtt, validateMusicTiming };
+export { NarrationError, captionNode, captionTrack, duckEnvelope, isPause, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };

package/dist/providers.js

@@ -510,7 +510,8 @@ async function synthesizeScript(scriptPath, opts = {}) {
 		providerVersion,
 		totalDuration: ends.length > 0 ? Math.max(...ends) : 0,
 		segments,
-		...pauses.length > 0 ? { pauses } : {}
+		...pauses.length > 0 ? { pauses } : {},
+		...raw.captionSplit ? { captionSplit: raw.captionSplit } : {}
 	};
 	const timingPath = `${base}.narration.timing.json`;
 	writeFileSync(timingPath, JSON.stringify(timing, null, 2) + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.5.0",
+  "version": "0.6.0-pre.1",
   "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.5.0",
-    "@glissade/scene": "0.5.0"
+    "@glissade/core": "0.6.0-pre.1",
+    "@glissade/scene": "0.6.0-pre.1"
   },
   "repository": {
     "type": "git",