@glissade/cli 0.7.0-pre.0 → 0.8.0-pre.0

package/dist/cli.js

@@ -51,7 +51,7 @@ render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
   --fps <n>        frames per second (default: timeline fps, else 60)
   --range <a..b>   integer FRAME indices to render, inclusive (default: whole timeline)
-  --frame <n>      render a single frame index (a still, through the same path)
+  --frame <n>      render a single frame; --out foo.png writes that one file, --out <dir> writes a PNG into it
   --format png-seq force a PNG sequence even when --out looks like a video
   --trace <file>   replay an InputTrace and bake it (machine scenes, §A.6)
   --state <name>   render one machine state's timeline linearly
@@ -60,6 +60,7 @@ render options:
   --narration <m>  auto (default): mix the voice from a sibling *.narration.timing.json | off
   --music <m>      auto (default): mix a sibling *.music.timing.json bed, ducked under narration | off
   --sfx <m>        auto (default): mix effect hits from a sibling *.sfx.timing.json | off
+  --chapters <m>   vtt: also write WebVTT chapters from cue markers (cues.json is always written when cues exist)
 
 dev options:
   --record         add a Record button; writes .trace.json sidecars next to the module
@@ -185,6 +186,7 @@ async function main() {
 			...frame !== void 0 ? { frame } : {},
 			...frameRange ? { frameRange } : {},
 			...formatFlag === "png-seq" ? { format: "png-seq" } : {},
+			...flags.get("chapters") === "vtt" ? { chapters: "vtt" } : {},
 			...flags.has("trace") ? { trace: flags.get("trace") } : {},
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},

package/dist/cues.js

@@ -0,0 +1,62 @@
+import { writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+//#region src/cues.ts
+/**
+* Composer cue signaling (§ad-break): cue markers (those carrying a `data.kind`)
+* are emitted at render as a deterministic `<stem>.cues.json` sidecar so a
+* downstream NLE / ad-insertion pipeline has machine-readable break points, and
+* optionally as WebVTT chapters. Mirrors the captions sidecar plumbing.
+*/
+/** Cue markers (those carrying a string `data.kind`) → a sorted cue list. */
+function collectCues(markers) {
+	const cues = [];
+	for (const m of markers) {
+		const data = m.data;
+		if (!data || typeof data !== "object" || typeof data.kind !== "string") continue;
+		cues.push({
+			t: m.t,
+			kind: data.kind,
+			name: m.name,
+			...typeof data.duration === "number" ? { duration: data.duration } : {}
+		});
+	}
+	return cues.sort((a, b) => a.t - b.t);
+}
+function vttTime(seconds) {
+	const ms = Math.round(seconds * 1e3);
+	const p = (n, w = 2) => String(n).padStart(w, "0");
+	return `${p(Math.floor(ms / 36e5))}:${p(Math.floor(ms % 36e5 / 6e4))}:${p(Math.floor(ms % 6e4 / 1e3))}.${p(ms % 1e3, 3)}`;
+}
+/** WebVTT chapters from cues; each runs until its duration or the next cue. */
+function cuesToVtt(cues, totalDuration) {
+	let out = "WEBVTT\n\n";
+	cues.forEach((c, i) => {
+		const end = c.duration !== void 0 ? c.t + c.duration : cues[i + 1]?.t ?? totalDuration;
+		out += `${c.name}\n${vttTime(c.t)} --> ${vttTime(end)}\n${c.kind}\n\n`;
+	});
+	return out;
+}
+/**
+* Write `<stem>.cues.json` (always, when cues exist) and, when `chaptersVtt`,
+* `<stem>.chapters.vtt`, next to the render output. Deterministic. Returns the
+* paths written.
+*/
+function writeCueSidecars(outPath, markers, totalDuration, chaptersVtt) {
+	const cues = collectCues(markers);
+	if (cues.length === 0) return [];
+	const isFile = /\.(mp4|webm)$/i.test(outPath);
+	const dir = isFile ? dirname(outPath) : outPath;
+	const prefix = isFile ? `${basename(outPath).replace(/\.(mp4|webm)$/i, "")}.` : "";
+	const written = [];
+	const jsonPath = join(dir, `${prefix}cues.json`);
+	writeFileSync(jsonPath, JSON.stringify({ cues }, null, 2) + "\n");
+	written.push(jsonPath);
+	if (chaptersVtt) {
+		const vttPath = join(dir, `${prefix}chapters.vtt`);
+		writeFileSync(vttPath, cuesToVtt(cues, totalDuration));
+		written.push(vttPath);
+	}
+	return written;
+}
+//#endregion
+export { writeCueSidecars };

package/dist/index.d.ts

@@ -30,6 +30,8 @@ interface RenderOptions {
   narration?: 'auto' | 'off';
   /** auto (default): mix effect hits from a sibling *.sfx.timing.json. */
   sfx?: 'auto' | 'off';
+  /** also write WebVTT chapters from cue markers ('vtt'); cues.json is always written when cues exist. */
+  chapters?: 'vtt' | 'off';
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {

package/dist/render.js

@@ -52,6 +52,7 @@ async function render(opts) {
 	const fps = opts.fps ?? doc.fps ?? 60;
 	const captionsMode = opts.captions ?? "burn";
 	const { hideCaptionsDoc, timingPathFor, writeCaptionSidecars } = await import("./captions.js").then((n) => n.t);
+	const { writeCueSidecars } = await import("./cues.js");
 	if (captionsMode !== "burn" && scene.resolveTarget("captions/opacity") !== void 0) doc = hideCaptionsDoc(doc);
 	const { compileTimeline } = await import("@glissade/core");
 	const compiled = compileTimeline(doc);
@@ -69,8 +70,9 @@ async function render(opts) {
 	}
 	const total = lastFrame - firstFrame + 1;
 	const isVideo = opts.format !== "png-seq" && /\.(mp4|webm)$/i.test(opts.out);
+	const singleFile = !isVideo && total === 1 && /\.png$/i.test(opts.out);
 	if (isVideo && !ffmpegAvailable()) throw new Error(`'${opts.out}' needs FFmpeg on PATH and none was found. Render a PNG sequence instead (--out <directory>) or install ffmpeg.`);
-	const framesDir = isVideo ? mkdtempSync(join(tmpdir(), "glissade-frames-")) : resolve(opts.out);
+	const framesDir = isVideo ? mkdtempSync(join(tmpdir(), "glissade-frames-")) : singleFile ? dirname(resolve(opts.out)) : resolve(opts.out);
 	mkdirSync(framesDir, { recursive: true });
 	const backend = new SkiaBackend(scene.size.w, scene.size.h);
 	scene.setTextMeasurer(backend);
@@ -98,7 +100,7 @@ async function render(opts) {
 	}
 	for (let f = firstFrame; f <= lastFrame; f++) {
 		backend.render(withDeterminismGuards("throw", () => evaluate(scene, doc, f / fps)));
-		writeFileSync(join(framesDir, `frame-${String(f).padStart(5, "0")}.png`), backend.encodePng());
+		writeFileSync(singleFile ? resolve(opts.out) : join(framesDir, `frame-${String(f).padStart(5, "0")}.png`), backend.encodePng());
 		opts.onProgress?.(f - firstFrame + 1, total);
 	}
 	backend.dispose();
@@ -113,9 +115,18 @@ async function render(opts) {
 		const { srt, vtt } = writeCaptionSidecars(timingPath, target);
 		process.stderr.write(`captions: ${srt}, ${vtt}\n`);
 	};
+	const emitCues = (target) => {
+		const written = writeCueSidecars(target, compiled.markers, duration, opts.chapters === "vtt");
+		if (written.length) process.stderr.write(`cues: ${written.join(", ")}\n`);
+	};
 	if (!isVideo) {
+		if (singleFile) return {
+			frames: 1,
+			out: resolve(opts.out)
+		};
 		if (compiled.audio.length > 0) process.stderr.write("note: PNG-sequence output ignores timeline audio; render to .mp4/.webm to mix it\n");
 		emitSidecars(framesDir);
+		emitCues(framesDir);
 		return {
 			frames: total,
 			out: framesDir
@@ -124,6 +135,7 @@ async function render(opts) {
 	const outAbs = resolve(opts.out);
 	mkdirSync(dirname(outAbs), { recursive: true });
 	emitSidecars(outAbs);
+	emitCues(outAbs);
 	const isWebm = /\.webm$/i.test(outAbs);
 	const container = isWebm ? "webm" : "mp4";
 	const { pickEncoder } = await import("./encoders.js").then((n) => n.r);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.7.0-pre.0",
+  "version": "0.8.0-pre.0",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,15 +20,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "^0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.7.0-pre.0",
-    "@glissade/core": "0.7.0-pre.0",
-    "@glissade/interact": "0.7.0-pre.0",
-    "@glissade/lottie": "0.7.0-pre.0",
-    "@glissade/svg": "0.7.0-pre.0",
-    "@glissade/narrate": "0.7.0-pre.0",
-    "@glissade/player": "0.7.0-pre.0",
-    "@glissade/scene": "0.7.0-pre.0",
-    "@glissade/sfx": "0.7.0-pre.0"
+    "@glissade/backend-skia": "0.8.0-pre.0",
+    "@glissade/core": "0.8.0-pre.0",
+    "@glissade/interact": "0.8.0-pre.0",
+    "@glissade/lottie": "0.8.0-pre.0",
+    "@glissade/svg": "0.8.0-pre.0",
+    "@glissade/narrate": "0.8.0-pre.0",
+    "@glissade/player": "0.8.0-pre.0",
+    "@glissade/scene": "0.8.0-pre.0",
+    "@glissade/sfx": "0.8.0-pre.0"
   },
   "repository": {
     "type": "git",