@m0saic/templates 0.2.0

package/dist/m0saic/media/subtitle-burn/v1/subtitle-burn.js

@@ -0,0 +1,603 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubtitleBurn = exports.SUBTITLE_BURN_TEMPLATE_ID = void 0;
+exports.selectSubtitleTrack = selectSubtitleTrack;
+exports.offsetCuesToOutput = offsetCuesToOutput;
+exports.fitCueText = fitCueText;
+const types_1 = require("@m0saic/types");
+const platform_1 = require("@m0saic/platform");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+// Editor-only first-open cover (gate-25/26 founder ruling: "needs a cover" —
+// the missing-source first face was an error card). Sibling module keeps this
+// file about the burn itself.
+const subtitle_burn_cover_1 = require("./subtitle-burn-cover");
+const template_utils_1 = require("@m0saic/template-utils");
+const propsSchema = (0, template_utils_1.definePropsSchema)({
+    sourceId: {
+        type: "media",
+        required: false,
+        description: "Source id in ctx.media. Defaults to first video with subtitles.",
+        meta: { ui: { label: "Source" } },
+    },
+    languageCode: {
+        type: "string",
+        required: false,
+        description: 'Preferred subtitle language (e.g. "eng", "spa"). 2-letter and locale-suffix forms accepted.',
+        meta: { control: { placeholder: "first subtitle track" }, ui: { label: "Language" } },
+    },
+    fallbackToDefault: {
+        type: "boolean",
+        required: false,
+        description: "When languageCode misses, fall back to default-flagged or first track. Default true.",
+        meta: { ui: { label: "Fallback to default" } },
+    },
+    trackIndex: {
+        type: "number",
+        required: false,
+        description: "Explicit subtitle track index (overrides languageCode when set).",
+        meta: { control: { placeholder: "auto" }, constraints: { min: 0, max: 32 }, ui: { label: "Track" } },
+    },
+    emitCues: {
+        type: "boolean",
+        required: false,
+        description: "Publish extracted cues as a MosaicDataSource (pipeline-readable) AND doc.sidecars.cues (written to {basename}.cues.json).",
+        meta: { ui: { label: "Emit cues" } },
+    },
+    clipStartMs: {
+        type: "number",
+        required: false,
+        description: "Source-relative ms where the rendered segment starts. Paired with clipEndMs.",
+        meta: {
+            constraints: { min: 0 },
+            control: {
+                placeholder: "full video",
+                picker: "time-range",
+                videoFromProp: "sourceId",
+                unit: "ms",
+                markersProvider: {
+                    kind: "subtitles",
+                    videoFromProp: "sourceId",
+                    languageFromProp: "languageCode",
+                    trackIndexFromProp: "trackIndex",
+                },
+            },
+            ui: { label: "Clip start" },
+        },
+    },
+    clipEndMs: {
+        type: "number",
+        required: false,
+        description: "Source-relative ms where the rendered segment ends. Must be > clipStartMs.",
+        meta: {
+            constraints: { min: 0 },
+            control: {
+                placeholder: "full video",
+                picker: "time-range",
+                videoFromProp: "sourceId",
+                unit: "ms",
+                markersProvider: {
+                    kind: "subtitles",
+                    videoFromProp: "sourceId",
+                    languageFromProp: "languageCode",
+                    trackIndexFromProp: "trackIndex",
+                },
+            },
+            ui: { label: "Clip end" },
+        },
+    },
+    clipLoopMode: {
+        type: "string",
+        required: false,
+        description: "How the clipped source fills ctx.target.durationMs when shorter.",
+        meta: {
+            constraints: { oneOf: ["cut", "loop", "freeze"] },
+            control: {
+                options: [
+                    { value: "cut", label: "Cut (default)" },
+                    { value: "loop", label: "Loop" },
+                    { value: "freeze", label: "Freeze last frame" },
+                ],
+            },
+            ui: { label: "Clip loop mode" },
+        },
+    },
+    placement: {
+        type: "string",
+        required: false,
+        description: "Vertical placement of burned subtitles.",
+        meta: { ui: { label: "Placement" } },
+    },
+    fontSize: {
+        type: "number",
+        required: false,
+        description: "Subtitle font size in pixels.",
+        meta: { control: { placeholder: "auto (by height)" }, constraints: { min: 8, max: 200 }, ui: { label: "Font Size" } },
+    },
+    fontColor: {
+        type: "string",
+        required: false,
+        description: "Subtitle font color (hex or named).",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Font Color" } },
+    },
+    borderColor: {
+        type: "string",
+        required: false,
+        description: "Subtitle outline color (hex or named).",
+        meta: { constraints: { isColor: true }, control: { colorPicker: true }, ui: { label: "Border Color" } },
+    },
+    borderWidth: {
+        type: "number",
+        required: false,
+        description: "Outline width as a fraction of min(w,h).",
+        meta: { constraints: { min: 0, max: 0.05 }, ui: { label: "Border Width" } },
+    },
+});
+// ---- HELPERS ----
+const DEFAULT_FONT_COLOR = "#ffffff";
+const DEFAULT_BORDER_COLOR = "#000000";
+const DEFAULT_BORDER_WIDTH = 0.003;
+const DEFAULT_PLACEMENT = "bottom";
+function defaultFontSize(targetH) {
+    // Scale subtitle font from output height; matches conventions in info_pane.ts.
+    return Math.max(14, Math.min(72, Math.round(targetH * 0.045)));
+}
+/** Pick `props.sourceId` if set, else the first video source in ctx.media that has subtitles, else the first video. */
+function resolveSourceId(props, ctx) {
+    if (props.sourceId)
+        return props.sourceId;
+    const entries = Object.entries(ctx.media);
+    const withSubs = entries.find(([, m]) => { var _a, _b; return m.kind === "video" && ((_b = (_a = m.subtitles) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0; });
+    if (withSubs)
+        return withSubs[0];
+    const firstVideo = entries.find(([, m]) => m.kind === "video");
+    return firstVideo === null || firstVideo === void 0 ? void 0 : firstVideo[0];
+}
+/**
+ * Selection algorithm (in priority order):
+ *
+ *   1. `trackIndex` set → use that exact track (rule: `"explicit-index"`).
+ *   2. `languageCode` set → first track whose `stream.language` matches.
+ *      - match → rule: `"language-match"`
+ *      - miss + `fallbackToDefault: false` → rule: `"language-miss-strict"`, track: undefined
+ *      - miss + fallback → fall through to (3)
+ *   3. No preference (or fallthrough from 2) → default-flagged track if any
+ *      (rule: `"default-flagged"`), else first track (rule: `"first-track"`).
+ *
+ * Empty / undefined input → rule: `"no-tracks"`, track: undefined.
+ *
+ * Caller pass-through behavior: `track === undefined` means render the base
+ * video with no overlays. The `rule` lets the caller (and telemetry) explain
+ * *why* there's no track.
+ */
+function selectSubtitleTrack(tracks, props) {
+    if (!tracks || tracks.length === 0) {
+        return { track: undefined, rule: "no-tracks" };
+    }
+    if (typeof props.trackIndex === "number") {
+        const track = tracks[props.trackIndex];
+        return { track, rule: "explicit-index" };
+    }
+    if (props.languageCode) {
+        const matched = tracks.find((t) => (0, platform_1.matchesLanguageCode)(t.stream.language, props.languageCode));
+        if (matched)
+            return { track: matched, rule: "language-match" };
+        if (props.fallbackToDefault === false) {
+            return { track: undefined, rule: "language-miss-strict" };
+        }
+        // fall through to default/first below
+    }
+    const defaultFlagged = tracks.find((t) => t.stream.default === true);
+    if (defaultFlagged)
+        return { track: defaultFlagged, rule: "default-flagged" };
+    return { track: tracks[0], rule: "first-track" };
+}
+function filterCuesToWindow(cues, durationMs) {
+    const end = Math.max(0, durationMs);
+    return cues
+        .filter((c) => c.startMs < end && c.endMs > 0)
+        .map((c) => ({
+        startMs: Math.max(0, c.startMs),
+        endMs: Math.min(end, c.endMs),
+        text: c.text,
+    }))
+        .filter((c) => c.endMs > c.startMs && c.text.length > 0);
+}
+/**
+ * Remap source-relative cues to output-relative cues for a clipped segment.
+ *
+ * Source cues come from ffprobe in source-time. When the template renders
+ * `[clipStartMs, clipEndMs]` of the source, a cue with source-time
+ * `[cs, ce]` should appear at output-time `[cs - clipStartMs, ce - clipStartMs]`,
+ * intersected with the output's render window `[0, durationMs]`.
+ *
+ * Returns cues with:
+ *   - times offset by `-clipStartMs`
+ *   - intersected with the clip window AND `[0, durationMs]`
+ *   - empty / zero-length cues dropped
+ */
+function offsetCuesToOutput(cues, clipStartMs, clipEndMs, durationMs) {
+    const clipStart = Math.max(0, clipStartMs);
+    const clipEnd = Math.max(clipStart, clipEndMs);
+    const renderEnd = Math.max(0, durationMs);
+    // Effective output window: intersection of [0, clipEnd-clipStart] and [0, renderEnd].
+    const outputEnd = Math.min(clipEnd - clipStart, renderEnd);
+    const out = [];
+    for (const c of cues) {
+        // Drop cues that fall entirely outside the clip window in source-time.
+        if (c.endMs <= clipStart)
+            continue;
+        if (c.startMs >= clipEnd)
+            continue;
+        // Intersect with the clip window in source-time, then offset to output-time.
+        const localStart = Math.max(0, c.startMs - clipStart);
+        const localEnd = Math.min(outputEnd, c.endMs - clipStart);
+        if (localEnd <= localStart)
+            continue;
+        if (c.text.length === 0)
+            continue;
+        out.push({ startMs: localStart, endMs: localEnd, text: c.text });
+    }
+    return out;
+}
+// ── Cue text fit (gate 26) ────────────────────────────────────
+//
+// Cue layers draw LITERAL text at a fixed font, centered — a long single
+// line overflowed BOTH edges silently (the gate-16 CLI text-clip class,
+// pixel-confirmed on a 155-char cue). Subtitles must never lose words, so
+// the fit is WRAP-FIRST: greedy word-wrap each authored line to the em
+// budget; only when the wrapped cue still exceeds CUE_MAX_LINES does the
+// font step down (one bounded 0.75× step, floor 14px) and re-wrap.
+const CUE_EM_RATIO = 0.62;
+const CUE_PAD_X = 0.05;
+const CUE_MAX_LINES = 3;
+function cueLineBudget(canvasW, fontSize) {
+    return (canvasW * (1 - 2 * CUE_PAD_X)) / (fontSize * CUE_EM_RATIO);
+}
+/** Greedy word-wrap one authored line into chunks that fit the budget. */
+function wrapLineToBudget(line, budgetUnits) {
+    if ((0, template_utils_1.textEmUnits)(line) <= budgetUnits + 0.5)
+        return [line];
+    const words = line.split(/\s+/).filter(Boolean);
+    const out = [];
+    let cur = "";
+    for (const w of words) {
+        const cand = cur ? `${cur} ${w}` : w;
+        if (cur && (0, template_utils_1.textEmUnits)(cand) > budgetUnits) {
+            out.push(cur);
+            cur = w;
+        }
+        else {
+            cur = cand;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+/**
+ * Fit one cue's text to the frame width. Returns the (possibly re-wrapped)
+ * text and the (possibly stepped-down) font size. Cues that already fit
+ * pass through byte-identical.
+ */
+function fitCueText(text, canvasW, fontSize) {
+    const wrapAt = (font) => text
+        .split("\n")
+        .flatMap((line) => wrapLineToBudget(line, cueLineBudget(canvasW, font)));
+    const lines = wrapAt(fontSize);
+    if (lines.length <= CUE_MAX_LINES) {
+        const joined = lines.join("\n");
+        return { text: joined === text ? text : joined, fontSize };
+    }
+    const stepped = Math.max(14, Math.round(fontSize * 0.75));
+    return { text: wrapAt(stepped).join("\n"), fontSize: stepped };
+}
+function fmtSec(ms) {
+    // 3-decimal seconds is plenty for ffmpeg between() and stays deterministic.
+    return (ms / 1000).toFixed(3);
+}
+function buildCueLayer(cue, placement, fontSize, fontColor, borderColor, borderWidth) {
+    return {
+        content: { kind: "literal", text: cue.text },
+        style: { fontSize, fontColor, borderColor, borderWidth },
+        placement: {
+            hAlign: "center",
+            vAlign: placement === "top" ? "top" : "bottom",
+            padding: { x: 0.05, y: 0.05 },
+        },
+        overlay: { enable: `between(t,${fmtSec(cue.startMs)},${fmtSec(cue.endMs)})` },
+    };
+}
+// ---- RENDER ----
+exports.SUBTITLE_BURN_TEMPLATE_ID = (0, types_1.asTemplateId)("@m0saic/media/subtitle-burn/v1");
+exports.SubtitleBurn = {
+    id: exports.SUBTITLE_BURN_TEMPLATE_ID,
+    label: "Subtitle Burn",
+    version: 1,
+    // Forward-looking role assignment per the Phase 3j closed-union role
+    // formalization. Subtitle-burn produces pixels (base video + drawtext
+    // overlays); the optional MosaicDataSource it can emit on emitCues:true
+    // doesn't change its role — sources arrays can carry mixed kinds.
+    role: "renderable",
+    description: "Reads subtitle cues from an MKV/MP4's embedded subtitle stream (text-based codecs) and burns them onto the video as m0saic text overlays. Opt-in cue emission via MosaicDataSource + doc.sidecars.cues.",
+    capabilities: { tier: "core" },
+    tags: ["media", "subtitles", "captions", "creators", "educators", "animated", "accessibility", "video"],
+    propsSchema,
+    // Free-form schemas; the engine doesn't enforce shape yet, but declaring
+    // them documents the published contract for downstream consumers.
+    outputsSchema: {
+        subtitleCues: {
+            type: "object",
+            required: false,
+            description: "Selected subtitle track + window-clamped cues. Available to downstream pipeline steps via ctx.upstreamData.subtitleCues when emitCues:true.",
+        },
+    },
+    sidecarsSchema: {
+        cues: {
+            type: "object",
+            required: false,
+            description: "Written as {output-basename}.cues.json next to the rendered video when emitCues:true.",
+        },
+    },
+    outputHints: {
+        width: 1920,
+        height: 1080,
+        fps: 30,
+        durationMs: 10000,
+        format: { kind: "video", container: "mp4" },
+    },
+    defaultProps: {
+        placement: DEFAULT_PLACEMENT,
+        fallbackToDefault: true,
+        emitCues: false,
+        clipLoopMode: "cut",
+        fontColor: DEFAULT_FONT_COLOR,
+        borderColor: DEFAULT_BORDER_COLOR,
+        borderWidth: DEFAULT_BORDER_WIDTH,
+    },
+    renderCover(_props, ctx) {
+        return (0, subtitle_burn_cover_1.renderSubtitleBurnCover)(ctx);
+    },
+    render(props, ctx) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z;
+        const sourceId = resolveSourceId(props, ctx);
+        if (!sourceId) {
+            (0, types_1.emitTemplateLog)(ctx, {
+                templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+                level: "warn",
+                message: "Pass-through: no video source in ctx.media",
+                data: { event: "passthrough", reason: "no-video-source" },
+            });
+            return Promise.resolve((0, template_utils_1.makeErrorMosaic)('No video source found in ctx.media.', {
+                title: "Subtitle Burn",
+                width: ctx.target.width,
+                height: ctx.target.height,
+            }));
+        }
+        const meta = ctx.media[(0, types_1.asAssetId)(sourceId)];
+        const placement = (_a = props.placement) !== null && _a !== void 0 ? _a : DEFAULT_PLACEMENT;
+        const fontSize = (_b = props.fontSize) !== null && _b !== void 0 ? _b : defaultFontSize(ctx.target.height);
+        // User-supplied color strings are validated downstream by the engine;
+        // the union-typed MosaicColor doesn't accept arbitrary `string`, so cast
+        // at the prop boundary.
+        const fontColor = ((_c = props.fontColor) !== null && _c !== void 0 ? _c : DEFAULT_FONT_COLOR);
+        const borderColor = ((_d = props.borderColor) !== null && _d !== void 0 ? _d : DEFAULT_BORDER_COLOR);
+        const borderWidth = (_e = props.borderWidth) !== null && _e !== void 0 ? _e : DEFAULT_BORDER_WIDTH;
+        // Clip window: source-relative [clipStart, clipEnd]. When either prop is
+        // omitted we degrade gracefully — no clip is applied and the existing
+        // [0, ctx.target.durationMs] filter handles the render window.
+        const hasClipStart = typeof props.clipStartMs === "number";
+        const hasClipEnd = typeof props.clipEndMs === "number";
+        const clipActive = hasClipStart || hasClipEnd;
+        const clipStartMs = Math.max(0, (_f = props.clipStartMs) !== null && _f !== void 0 ? _f : 0);
+        const clipEndMs = hasClipEnd
+            ? Math.max(0, props.clipEndMs)
+            : ((_g = meta === null || meta === void 0 ? void 0 : meta.durationMs) !== null && _g !== void 0 ? _g : clipStartMs + ctx.target.durationMs);
+        if (clipActive && clipEndMs <= clipStartMs) {
+            (0, types_1.emitTemplateLog)(ctx, {
+                templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+                level: "warn",
+                message: "Invalid clip range: clipEndMs must be greater than clipStartMs",
+                data: { event: "passthrough", reason: "invalid-clip-range", clipStartMs, clipEndMs },
+            });
+            return Promise.resolve((0, template_utils_1.makeErrorMosaic)("clipEndMs must be greater than clipStartMs.", {
+                title: "Subtitle Burn",
+                width: ctx.target.width,
+                height: ctx.target.height,
+            }));
+        }
+        const clipDurationMs = clipEndMs - clipStartMs;
+        const clipLoopMode = (_h = props.clipLoopMode) !== null && _h !== void 0 ? _h : "cut";
+        // Telemetry event #1: tracks_discovered (count + language list).
+        const allTracks = (_j = meta === null || meta === void 0 ? void 0 : meta.subtitles) !== null && _j !== void 0 ? _j : [];
+        (0, types_1.emitTemplateLog)(ctx, {
+            templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+            message: "Subtitle tracks discovered in source",
+            data: {
+                event: "tracks_discovered",
+                sourceId,
+                count: allTracks.length,
+                languages: allTracks.map((t) => { var _a; return (_a = t.stream.language) !== null && _a !== void 0 ? _a : null; }),
+            },
+        });
+        const { track, rule } = selectSubtitleTrack(allTracks, {
+            trackIndex: props.trackIndex,
+            languageCode: props.languageCode,
+            fallbackToDefault: (_k = props.fallbackToDefault) !== null && _k !== void 0 ? _k : true,
+        });
+        // Telemetry event #2: track_selected — names which algorithm path won.
+        (0, types_1.emitTemplateLog)(ctx, {
+            templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+            message: `Subtitle track selection: ${rule}`,
+            data: {
+                event: "track_selected",
+                rule,
+                requestedLanguageCode: (_l = props.languageCode) !== null && _l !== void 0 ? _l : null,
+                requestedTrackIndex: (_m = props.trackIndex) !== null && _m !== void 0 ? _m : null,
+                trackIndex: (_o = track === null || track === void 0 ? void 0 : track.stream.streamIndex) !== null && _o !== void 0 ? _o : null,
+                language: (_p = track === null || track === void 0 ? void 0 : track.stream.language) !== null && _p !== void 0 ? _p : null,
+                codec: (_q = track === null || track === void 0 ? void 0 : track.stream.codecName) !== null && _q !== void 0 ? _q : null,
+                default: (_r = track === null || track === void 0 ? void 0 : track.stream.default) !== null && _r !== void 0 ? _r : null,
+                forced: (_s = track === null || track === void 0 ? void 0 : track.stream.forced) !== null && _s !== void 0 ? _s : null,
+            },
+        });
+        // ── Duration follow (gate 26 founder catch: "when i dropped big buck
+        // bunny, it defaulted to 10 seconds instead of the duration of the
+        // file"). The natural length of a subtitle burn is the SOURCE's (or
+        // the clip window's) — the 10s outputHints default is just a hint.
+        // The doc AUTHORS its duration below (authored declarations already
+        // out-rank hint-derived targets; Make's Duration override starts
+        // empty by design so the declaration reaches the planner untouched),
+        // and an EXPLICIT user duration (ctx.userIntent.durationMs — Make
+        // override / CLI --durationMs) still wins over the follow.
+        const userAskedDuration = typeof ((_t = ctx.userIntent) === null || _t === void 0 ? void 0 : _t.durationMs) === "number" && ctx.userIntent.durationMs > 0;
+        const followDurationMs = clipActive
+            ? clipDurationMs
+            : typeof (meta === null || meta === void 0 ? void 0 : meta.durationMs) === "number" && meta.durationMs > 0
+                ? meta.durationMs
+                : undefined;
+        const effectiveDurationMs = !userAskedDuration && followDurationMs != null
+            ? followDurationMs
+            : ctx.target.durationMs;
+        const rawCues = (_u = track === null || track === void 0 ? void 0 : track.cues) !== null && _u !== void 0 ? _u : [];
+        // When a clip window is set, offset cues to output-relative time AND
+        // intersect with both the clip window and the render duration. Otherwise
+        // the simple no-clip filter (assumes clip starts at 0) is sufficient.
+        // Both filter against the EFFECTIVE duration, so source-follow renders
+        // keep every cue instead of dropping everything past the 10s hint.
+        const cues = clipActive
+            ? offsetCuesToOutput(rawCues, clipStartMs, clipEndMs, effectiveDurationMs)
+            : filterCuesToWindow(rawCues, effectiveDurationMs);
+        // Telemetry event #3: cues_filtered — raw → window-clamped counts.
+        (0, types_1.emitTemplateLog)(ctx, {
+            templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+            message: "Cues filtered to ctx.target window",
+            data: {
+                event: "cues_filtered",
+                rawCount: rawCues.length,
+                windowedCount: cues.length,
+                durationMs: effectiveDurationMs,
+                clipActive,
+            },
+        });
+        // Telemetry event #5: clip_applied — emitted only when a clip window is active.
+        if (clipActive) {
+            (0, types_1.emitTemplateLog)(ctx, {
+                templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+                message: "Clip window applied to source",
+                data: {
+                    event: "clip_applied",
+                    clipStartMs,
+                    clipEndMs,
+                    clipDurationMs,
+                    clipLoopMode,
+                    sourceDurationMs: (_v = meta === null || meta === void 0 ? void 0 : meta.durationMs) !== null && _v !== void 0 ? _v : null,
+                    targetDurationMs: ctx.target.durationMs,
+                },
+            });
+        }
+        // Telemetry event #4: passthrough — when no track was selected.
+        if (!track) {
+            (0, types_1.emitTemplateLog)(ctx, {
+                templateId: exports.SUBTITLE_BURN_TEMPLATE_ID,
+                level: "warn",
+                message: `Pass-through: ${rule}`,
+                data: { event: "passthrough", reason: rule, sourceId },
+            });
+        }
+        const sourceAssetId = (0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(sourceId));
+        const assets = {
+            [sourceAssetId]: {
+                kind: "file",
+                path: sourceId,
+                mediaType: "video",
+            },
+        };
+        const sources = [
+            {
+                type: "media",
+                mediaType: "video",
+                assetId: sourceAssetId,
+                placement: { fit: "cover" },
+                ...(clipActive
+                    ? {
+                        playback: {
+                            clipStartMs,
+                            clipDurationMs,
+                            loopMode: clipLoopMode,
+                        },
+                    }
+                    : {}),
+                editor: { owner: "template" },
+            },
+        ];
+        if (cues.length > 0) {
+            const layers = cues.map((c) => {
+                const fit = fitCueText(c.text, ctx.target.width, fontSize);
+                return buildCueLayer({ ...c, text: fit.text }, placement, fit.fontSize, fontColor, borderColor, borderWidth);
+            });
+            sources.push({
+                type: "text",
+                renderMode: { kind: "video" },
+                layers,
+                visual: { backgroundColor: "none" },
+                editor: { owner: "template" },
+            });
+        }
+        // Cue emission: opt-in via emitCues, and only fires when we actually
+        // selected a track. The published shape is symmetric across the two
+        // channels (MosaicDataSource for pipelines, doc.sidecars for disk).
+        let sidecars;
+        if (props.emitCues === true && track) {
+            const cuesPayload = {
+                language: (_w = track.stream.language) !== null && _w !== void 0 ? _w : null,
+                codec: (_x = track.stream.codecName) !== null && _x !== void 0 ? _x : null,
+                streamIndex: track.stream.streamIndex,
+                default: (_y = track.stream.default) !== null && _y !== void 0 ? _y : false,
+                forced: (_z = track.stream.forced) !== null && _z !== void 0 ? _z : false,
+                selectionRule: rule,
+                // Clip context lets downstream consumers see whether cues are
+                // source-relative (no clip) or output-relative (clip active).
+                clip: clipActive
+                    ? { startMs: clipStartMs, endMs: clipEndMs, durationMs: clipDurationMs, loopMode: clipLoopMode }
+                    : null,
+                cues,
+            };
+            // Pipeline-readable channel: downstream step reads via
+            // ctx.upstreamData.subtitleCues.
+            sources.push({
+                type: "data",
+                alias: (0, types_1.asAliasId)("subtitleCues"),
+                variables: cuesPayload,
+                editor: { owner: "template" },
+            });
+            // Disk-side channel: engine's writeSidecars writes
+            // {output-basename}.cues.json next to the rendered video.
+            sidecars = { cues: cuesPayload };
+        }
+        // Pass-through when no cues: single full-frame tile. Otherwise stack a
+        // transparent overlay slot atop the base media so the text composites on top.
+        const m0 = cues.length > 0 ? (0, template_utils_1.buildOverlayStack)(2) : "F";
+        const doc = {
+            kind: "mosaic_document",
+            version: 1,
+            assets,
+            m0: (0, dsl_stdlib_1.toM0String)(m0, "SubtitleBurn"),
+            sources,
+            // Declared format (family convention — watermark/trickplay/screencap:
+            // each rendered doc declares its own). Without it, Make's Output Type
+            // has no ground truth for this doc and cannot preset/self-heal to
+            // Video — the gate-26 founder catch ("why is it trying to make my
+            // output an image").
+            format: { kind: "video", container: "mp4" },
+            // Authored duration: the source's (or clip window's) real length —
+            // see the duration-follow block above. Omitted only when nothing
+            // usable was probed (the target then rules as before).
+            ...(followDurationMs != null && !userAskedDuration
+                ? { durationMs: effectiveDurationMs }
+                : {}),
+            ...(sidecars ? { sidecars } : {}),
+        };
+        return Promise.resolve(doc);
+    },
+};
+(0, template_utils_1.registerTemplate)(exports.SubtitleBurn);

package/dist/m0saic/media/trickplay/index.d.ts

@@ -0,0 +1 @@
+export * from "./v1";

package/dist/m0saic/media/trickplay/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1"), exports);

package/dist/m0saic/media/trickplay/v1/index.d.ts

@@ -0,0 +1,4 @@
+export { Trickplay, resolveTrickplayKnobs, type TrickplayV1Props } from "./trickplay";
+export { buildSheetM0, buildTrickplayStepsForInput, sheetStepName, IMAGE_STEP_MS, type TrickplayOutputFormat, type TrickplayStepKnobs, } from "./pipeline";
+export { evenRound, planTrickplay, type TrickplayCue, type TrickplayKnobs, type TrickplayPlan, type TrickplaySheet } from "./plan";
+export { buildStoryboardVtt, buildTrickplayManifest, formatVttTimestamp, type TrickplayManifest, } from "./sidecars";

package/dist/m0saic/media/trickplay/v1/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatVttTimestamp = exports.buildTrickplayManifest = exports.buildStoryboardVtt = exports.planTrickplay = exports.evenRound = exports.IMAGE_STEP_MS = exports.sheetStepName = exports.buildTrickplayStepsForInput = exports.buildSheetM0 = exports.resolveTrickplayKnobs = exports.Trickplay = void 0;
+var trickplay_1 = require("./trickplay");
+Object.defineProperty(exports, "Trickplay", { enumerable: true, get: function () { return trickplay_1.Trickplay; } });
+Object.defineProperty(exports, "resolveTrickplayKnobs", { enumerable: true, get: function () { return trickplay_1.resolveTrickplayKnobs; } });
+var pipeline_1 = require("./pipeline");
+Object.defineProperty(exports, "buildSheetM0", { enumerable: true, get: function () { return pipeline_1.buildSheetM0; } });
+Object.defineProperty(exports, "buildTrickplayStepsForInput", { enumerable: true, get: function () { return pipeline_1.buildTrickplayStepsForInput; } });
+Object.defineProperty(exports, "sheetStepName", { enumerable: true, get: function () { return pipeline_1.sheetStepName; } });
+Object.defineProperty(exports, "IMAGE_STEP_MS", { enumerable: true, get: function () { return pipeline_1.IMAGE_STEP_MS; } });
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "evenRound", { enumerable: true, get: function () { return plan_1.evenRound; } });
+Object.defineProperty(exports, "planTrickplay", { enumerable: true, get: function () { return plan_1.planTrickplay; } });
+var sidecars_1 = require("./sidecars");
+Object.defineProperty(exports, "buildStoryboardVtt", { enumerable: true, get: function () { return sidecars_1.buildStoryboardVtt; } });
+Object.defineProperty(exports, "buildTrickplayManifest", { enumerable: true, get: function () { return sidecars_1.buildTrickplayManifest; } });
+Object.defineProperty(exports, "formatVttTimestamp", { enumerable: true, get: function () { return sidecars_1.formatVttTimestamp; } });