@m0saic/templates 0.2.0

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

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSubtitleBurnCover = renderSubtitleBurnCover;
+const screencap_grid_cover_1 = require("../../screencap_grid/v2/screencap-grid-cover");
+const types_1 = require("@m0saic/types");
+const screencap_grid_tutorial_1 = require("../../screencap_grid/v2/screencap-grid-tutorial");
+const COVER_FRAME_ASSET_ID = (0, types_1.asAssetId)("subtitle-burn-cover-frame");
+/**
+ * The hero still: Big Buck Bunny's title card (~27s — founder-picked: "the
+ * big buck bunny logo part"), full 1080p. Node contexts read the bundled
+ * jpg via __dirname (the highlights web-safe pattern); the browser uses
+ * the copy served from the registered template-assets tree.
+ */
+function coverFrameAssets() {
+    var _a;
+    const isNode = typeof process !== "undefined" && !!((_a = process.versions) === null || _a === void 0 ? void 0 : _a.node);
+    const unpackedAsar = (p) => p.includes("/app.asar/")
+        ? p.split("/app.asar/").join("/app.asar.unpacked/")
+        : p.split("\\app.asar\\").join("\\app.asar.unpacked\\");
+    return {
+        [COVER_FRAME_ASSET_ID]: isNode
+            ? {
+                kind: "file",
+                path: unpackedAsar(`${__dirname}/assets/cover-frame.jpg`),
+                mediaType: "image",
+            }
+            : {
+                kind: "url",
+                url: "/template-assets/assets/templates/@m0saic__media__subtitle-burn__v1/cover-frame.jpg",
+                mediaType: "image",
+            },
+    };
+}
+function coverMessage(paneWidth, theme, type, label, body) {
+    const copy = (0, screencap_grid_cover_1.onboardingSplit)("row", [4, 11], [
+        (0, screencap_grid_cover_1.onboardingTextBlock)({
+            text: label,
+            fontSize: type.micro,
+            color: theme.accent,
+            cellWidthPx: paneWidth * 0.72,
+            hAlign: "left",
+            label: `cover ${label.toLowerCase()} label`,
+        }),
+        (0, screencap_grid_cover_1.onboardingTextBlock)({
+            text: body,
+            fontSize: type.label,
+            color: theme.textPrimary,
+            cellWidthPx: paneWidth * 0.72,
+            hAlign: "left",
+            widthFrac: 0.92,
+            label: `cover ${label.toLowerCase()} message`,
+        }),
+    ]);
+    const bubble = (0, screencap_grid_cover_1.onboardingOverlay)((0, screencap_grid_cover_1.onboardingSolid)(theme.surfaceRaised), (0, screencap_grid_cover_1.onboardingSplit)("col", [1, 18, 1], [null, copy, null]));
+    return (0, screencap_grid_cover_1.onboardingSplit)("col", [1, 19], [(0, screencap_grid_cover_1.onboardingSolid)(theme.accent), bubble]);
+}
+function coverTip(paneWidth, theme, type) {
+    const copy = (0, screencap_grid_cover_1.onboardingSplit)("row", [2, 5], [
+        (0, screencap_grid_cover_1.onboardingTextBlock)({
+            text: "START HERE",
+            fontSize: type.micro,
+            color: theme.accent,
+            cellWidthPx: paneWidth * 0.72,
+            hAlign: "left",
+            label: "cover start tip label",
+        }),
+        (0, screencap_grid_cover_1.onboardingTextBlock)({
+            text: "Drop a video with embedded subtitles into Source. The default track burns immediately.",
+            fontSize: type.label,
+            color: theme.textPrimary,
+            cellWidthPx: paneWidth * 0.72,
+            hAlign: "left",
+            widthFrac: 0.92,
+            label: "cover start tip",
+        }),
+    ]);
+    return (0, screencap_grid_cover_1.onboardingFrame)((0, screencap_grid_cover_1.onboardingOverlay)((0, screencap_grid_cover_1.onboardingSolid)(theme.surface), (0, screencap_grid_cover_1.onboardingSplit)("col", [1, 18, 1], [null, copy, null])), theme.borderStrong);
+}
+function coverChatPane(paneWidth, theme, type, compact) {
+    const brand = (0, screencap_grid_tutorial_1.tutorialBrand)(theme, type, "Subtitle Burn");
+    const title = (0, screencap_grid_cover_1.onboardingTextBlock)({
+        text: "Captions, burned in.",
+        fontSize: type.headline,
+        color: theme.textPrimary,
+        cellWidthPx: paneWidth * 0.83,
+        hAlign: "left",
+        widthFrac: 0.9,
+        label: "cover title",
+    });
+    const overview = (0, screencap_grid_cover_1.onboardingTextBlock)({
+        text: compact
+            ? "Reads the subtitle track inside your video and burns it onto the pixels."
+            : "Reads the subtitle track already inside your MKV/MP4 and burns it onto the pixels — no player settings, no sidecar files, plays everywhere.",
+        fontSize: type.callout,
+        color: theme.textSecondary,
+        cellWidthPx: paneWidth * 0.83,
+        hAlign: "left",
+        widthFrac: 0.9,
+        label: "cover overview",
+    });
+    const sourceMessage = coverMessage(paneWidth, theme, type, "ADD A SOURCE", compact
+        ? "The default-flagged track wins."
+        : "Drop a subbed video. The default-flagged track wins out of the box.");
+    const trackMessage = coverMessage(paneWidth, theme, type, "PICK THE TRACK", compact
+        ? "By language or exact index."
+        : "By language (\"eng\", \"spa\") or exact track index; strict or fallback.");
+    const clipMessage = coverMessage(paneWidth, theme, type, "CLIP + STYLE", compact
+        ? "Cue-aware trim; placement, size, colors."
+        : "Trim with the cue-aware range picker. Placement, size, and colors are yours.");
+    const tip = coverTip(paneWidth, theme, type);
+    const conversation = (0, screencap_grid_cover_1.onboardingSplit)("row", compact
+        ? [1, 6, 2, 9, 8, 2, 7, 1, 7, 1, 7, 2, 6, 1]
+        : [1, 6, 2, 10, 9, 2, 7, 1, 7, 1, 7, 2, 6, 1], [
+        null,
+        brand,
+        null,
+        title,
+        overview,
+        null,
+        sourceMessage,
+        null,
+        trackMessage,
+        null,
+        clipMessage,
+        null,
+        tip,
+        null,
+    ]);
+    const paddedConversation = (0, screencap_grid_cover_1.onboardingSplit)("col", [2, 26, 2], [null, conversation, null]);
+    return (0, screencap_grid_cover_1.onboardingFrame)((0, screencap_grid_cover_1.onboardingOverlay)((0, screencap_grid_cover_1.onboardingSolid)(theme.surfaceInset), paddedConversation), theme.border);
+}
+/**
+ * The hero: a real film frame with a subtitle burned onto it — white
+ * glyphs anchored to the lower quarter, exactly the template's default
+ * look. A second thin strip beneath shows the next cue arriving, hinting
+ * at the time axis without needing motion.
+ */
+function coverHero(theme, type) {
+    const subtitle = (0, screencap_grid_cover_1.onboardingLeaf)((0, screencap_grid_cover_1.onboardingTextSource)({
+        text: "Burned right onto the frame.",
+        fontSize: Math.round(type.headline * 0.62),
+        color: "#ffffff",
+        hAlign: "center",
+        label: "hero burned subtitle",
+    }));
+    const subtitleBand = (0, screencap_grid_cover_1.onboardingSplit)("row", [11, 3, 1], [null, subtitle, null]);
+    const frame = (0, screencap_grid_cover_1.onboardingOverlay)((0, screencap_grid_cover_1.onboardingLeaf)({
+        type: "media",
+        mediaType: "image",
+        assetId: COVER_FRAME_ASSET_ID,
+        placement: { fit: "cover" },
+        editor: { owner: "template", label: "hero film frame" },
+    }), subtitleBand);
+    const nextCue = (0, screencap_grid_cover_1.onboardingSplit)("col", [5, 8, 5], [
+        null,
+        (0, screencap_grid_cover_1.onboardingLeaf)((0, screencap_grid_cover_1.onboardingTextSource)({
+            text: "00:03 → 00:05   “the next cue is already timed”",
+            fontSize: type.micro,
+            color: theme.textSecondary,
+            hAlign: "center",
+            backgroundColor: theme.surfaceInset,
+            label: "hero cue strip",
+        })),
+        null,
+    ]);
+    return (0, screencap_grid_cover_1.onboardingFrame)((0, screencap_grid_cover_1.onboardingSplit)("row", [15, 1, 2], [frame, null, nextCue]), theme.borderStrong);
+}
+/** Production cover: the instruction pane beside a burned-subtitle frame. */
+function renderSubtitleBurnCover(ctx) {
+    const canvasW = ctx.target.width;
+    const canvasH = ctx.target.height;
+    const theme = (0, screencap_grid_cover_1.resolveScreencapOnboardingTheme)(ctx);
+    const type = (0, screencap_grid_cover_1.coverTypeRamp)(canvasW, canvasH);
+    const compact = Math.min(canvasW, canvasH) < 480;
+    const stacked = canvasH > canvasW * 1.05;
+    const paneWidth = stacked ? canvasW * 0.88 : canvasW * 0.3;
+    const pane = coverChatPane(paneWidth, theme, type, compact);
+    const hero = coverHero(theme, type);
+    const content = stacked
+        ? (0, screencap_grid_cover_1.onboardingSplit)("row", [47, 3, 50], [
+            (0, screencap_grid_cover_1.onboardingSplit)("col", [6, 88, 6], [null, pane, null]),
+            null,
+            (0, screencap_grid_cover_1.onboardingSplit)("col", [6, 88, 6], [null, hero, null]),
+        ])
+        : (0, screencap_grid_cover_1.onboardingSplit)("col", [4, 30, 3, 59, 4], [null, pane, null, hero, null]);
+    const page = (0, screencap_grid_cover_1.onboardingSplit)("row", [5, 90, 5], [null, content, null]);
+    return {
+        kind: "mosaic_document",
+        version: 1,
+        assets: { ...(0, screencap_grid_tutorial_1.tutorialAssets)(), ...coverFrameAssets() },
+        size: { width: canvasW, height: canvasH },
+        backgroundColor: theme.surfaceApp,
+        m0: page.m0,
+        sources: page.sources,
+    };
+}

package/dist/m0saic/media/subtitle-burn/v1/subtitle-burn.d.ts

@@ -0,0 +1,137 @@
+import type { LoopMode, MosaicLanguageCode, MosaicSubtitleCue, MosaicSubtitleTrack, MosaicTemplate } from "@m0saic/types";
+export type SubtitleBurnProps = {
+    /**
+     * Source id in `ctx.media` (e.g. an MKV/MP4 with embedded subtitle streams).
+     * When omitted, the first media entry with a populated subtitle track is used;
+     * if none has subtitles, the first video source is used as pass-through.
+     */
+    sourceId?: string;
+    /**
+     * Preferred subtitle language as an ISO 639-2/B 3-letter code (e.g. `"eng"`,
+     * `"spa"`) or any form `normalizeLanguageCode` can canonicalize (`"en"`,
+     * `"en-US"`, `"Eng"`). When set and a matching track exists, it wins over
+     * the default-flagged track. Use {@link MosaicLanguageCode} constants from
+     * `@m0saic/types` for readability.
+     */
+    languageCode?: MosaicLanguageCode;
+    /**
+     * When `languageCode` is set but no track matches, this controls whether
+     * the template falls back to the default-flagged track (then first track)
+     * or skips subtitles entirely (pass-through).
+     *
+     * Defaults to `true` — sensible because callers usually want subtitles
+     * when they exist, even if their preferred language isn't available.
+     * Set to `false` to enforce strict matching.
+     */
+    fallbackToDefault?: boolean;
+    /**
+     * Explicit subtitle track index (0-based). When set, this is the highest-
+     * priority selection signal and overrides `languageCode` / `fallbackToDefault`.
+     * Use this for fully deterministic selection regardless of language tags.
+     */
+    trackIndex?: number;
+    /**
+     * When `true`, the template publishes the extracted (window-clamped) cues
+     * via TWO additional channels alongside the rendered video:
+     *
+     * - **`MosaicDataSource`** with `alias: "subtitleCues"` — pipeline-readable
+     *   via `ctx.upstreamData.subtitleCues` in a downstream step.
+     * - **`doc.sidecars.cues`** — written to disk by the engine as
+     *   `{output-basename}.cues.json` next to the rendered video.
+     *
+     * Off by default. Free-of-cost when disabled (no extra sources, no disk write).
+     */
+    emitCues?: boolean;
+    /**
+     * Source-relative milliseconds at which the rendered segment begins.
+     * When set, the template trims the input video to `[clipStartMs, clipEndMs]`
+     * and offsets subtitle cue times to be output-relative (cue at source-time
+     * `clipStartMs + Δ` fires at output-time `Δ`).
+     *
+     * Omit (or set to `0`) to render from the start of the source.
+     */
+    clipStartMs?: number;
+    /**
+     * Source-relative milliseconds at which the rendered segment ends.
+     * Must be greater than `clipStartMs` when both are set; otherwise the
+     * template falls back to the error mosaic.
+     *
+     * Omit to render to the end of the source (subject to `ctx.target.durationMs`
+     * and `clipLoopMode`).
+     */
+    clipEndMs?: number;
+    /**
+     * How the clipped media source behaves when its length doesn't match
+     * `ctx.target.durationMs`. Defaults to `"cut"` (clip plays its real
+     * length, remainder transparent — best for subtitle work). Other options:
+     *
+     * - `"loop"` — repeat the clip seamlessly to fill the target duration
+     * - `"freeze"` — hold the final frame of the clip
+     *
+     * Surface of {@link MosaicPlaybackProps.loopMode}.
+     */
+    clipLoopMode?: LoopMode;
+    /** Where the burned subtitle text sits on the frame. Defaults to "bottom". */
+    placement?: "bottom" | "top";
+    /** Subtitle font size in pixels. Default scales from `ctx.target.height`. */
+    fontSize?: number;
+    /** Subtitle font color. Default `"#ffffff"`. */
+    fontColor?: string;
+    /** Outline / border color for legibility. Default `"#000000"`. */
+    borderColor?: string;
+    /** Outline width as a fraction of min(w,h). Default `0.003`. */
+    borderWidth?: number;
+};
+/**
+ * Names the algorithm path taken by {@link selectSubtitleTrack}. Surfaced
+ * via telemetry so consumers can attribute a render to its selection logic
+ * without reverse-engineering the props.
+ */
+export type SubtitleSelectionRule = "no-tracks" | "explicit-index" | "language-match" | "language-miss-strict" | "default-flagged" | "first-track";
+export type SelectSubtitleTrackResult = {
+    track: MosaicSubtitleTrack | undefined;
+    rule: SubtitleSelectionRule;
+};
+/**
+ * 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.
+ */
+export declare function selectSubtitleTrack(tracks: readonly MosaicSubtitleTrack[] | undefined, props: Pick<SubtitleBurnProps, "trackIndex" | "languageCode" | "fallbackToDefault">): SelectSubtitleTrackResult;
+/**
+ * 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
+ */
+export declare function offsetCuesToOutput(cues: readonly MosaicSubtitleCue[], clipStartMs: number, clipEndMs: number, durationMs: number): MosaicSubtitleCue[];
+/**
+ * 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.
+ */
+export declare function fitCueText(text: string, canvasW: number, fontSize: number): {
+    text: string;
+    fontSize: number;
+};
+export declare const SUBTITLE_BURN_TEMPLATE_ID: import("@m0saic/types").TemplateId;
+export declare const SubtitleBurn: MosaicTemplate<SubtitleBurnProps>;