@m0saic/templates 0.2.0

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

@@ -0,0 +1,51 @@
+/**
+ * Per-input step builder for the trickplay pipeline.
+ *
+ * One input fans out to one pipeline step PER SHEET (long content
+ * overflows a sheet's cols·rowsPerSheet capacity). Every cell is the
+ * same video asset seeked to its own timestamp — screencap-grid's
+ * frame-at-timestamp mechanism (`clipStartMs` + freeze) with the
+ * proportional math swapped for the fixed cadence in `plan.ts`.
+ *
+ * The per-input index sidecars (WebVTT storyboard + JSON manifest)
+ * ride the FIRST sheet step, image modes only — the engine writes them
+ * next to that sheet's deliverable and resolves the step-output tokens
+ * to final basenames. The mp4 mode (animated contact-sheet preview)
+ * emits no sidecars: index files only make sense against image sheets.
+ */
+import type { MosaicEngineContext, MosaicPipelineStep } from "@m0saic/types";
+/** Fixed duration for image sheet steps — a single-frame render. */
+export declare const IMAGE_STEP_MS = 40;
+/** Duration used for error-mosaic steps (input problems). */
+export declare const ERROR_STEP_MS = 1000;
+export type TrickplayOutputFormat = "png" | "jpeg" | "mp4";
+/** Resolved knobs a step needs (validated once by the template). */
+export type TrickplayStepKnobs = {
+    intervalSec: number;
+    tileWidth: number;
+    cols: number;
+    rowsPerSheet: number;
+    outputFormat: TrickplayOutputFormat;
+};
+/** Step name for input `stepBaseName`'s sheet `sheetIndex` (0-based → `__sheet_01`). */
+export declare function sheetStepName(stepBaseName: string, sheetIndex: number): string;
+/**
+ * The m0 for one sheet: `rows` stacked rows of `cols` cells, with the
+ * trailing cells of a partial last row as null tiles (`-` holes — they
+ * consume no source; the doc's black background shows through).
+ * Produces the identical string to `grid({rows, cols}).m0` when the
+ * sheet is full (locked by a unit test).
+ */
+export declare function buildSheetM0(rows: number, cols: number, thumbCount: number): string;
+/**
+ * Build the pipeline steps for one input: one step per sheet, plus the
+ * per-input index sidecars on the first sheet step. Input problems
+ * degrade to a single error-mosaic step so one bad file never kills a
+ * batch.
+ */
+export declare function buildTrickplayStepsForInput(args: {
+    inputPath: string;
+    stepBaseName: string;
+    knobs: TrickplayStepKnobs;
+    ctx: MosaicEngineContext;
+}): MosaicPipelineStep[];

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

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Per-input step builder for the trickplay pipeline.
+ *
+ * One input fans out to one pipeline step PER SHEET (long content
+ * overflows a sheet's cols·rowsPerSheet capacity). Every cell is the
+ * same video asset seeked to its own timestamp — screencap-grid's
+ * frame-at-timestamp mechanism (`clipStartMs` + freeze) with the
+ * proportional math swapped for the fixed cadence in `plan.ts`.
+ *
+ * The per-input index sidecars (WebVTT storyboard + JSON manifest)
+ * ride the FIRST sheet step, image modes only — the engine writes them
+ * next to that sheet's deliverable and resolves the step-output tokens
+ * to final basenames. The mp4 mode (animated contact-sheet preview)
+ * emits no sidecars: index files only make sense against image sheets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_STEP_MS = exports.IMAGE_STEP_MS = void 0;
+exports.sheetStepName = sheetStepName;
+exports.buildSheetM0 = buildSheetM0;
+exports.buildTrickplayStepsForInput = buildTrickplayStepsForInput;
+const types_1 = require("@m0saic/types");
+const dsl_stdlib_1 = require("@m0saic/dsl-stdlib");
+const template_utils_1 = require("@m0saic/template-utils");
+const plan_1 = require("./plan");
+const sidecars_1 = require("./sidecars");
+/** Fixed duration for image sheet steps — a single-frame render. */
+exports.IMAGE_STEP_MS = 40;
+/** Duration used for error-mosaic steps (input problems). */
+exports.ERROR_STEP_MS = 1000;
+const ERROR_TITLE = "Trickplay";
+/** Step name for input `stepBaseName`'s sheet `sheetIndex` (0-based → `__sheet_01`). */
+function sheetStepName(stepBaseName, sheetIndex) {
+    return `${stepBaseName}__sheet_${String(sheetIndex + 1).padStart(2, "0")}`;
+}
+/** Input basename without directory or extension — the step label.
+ * Local (not node:path) so the template stays web-bundle clean. */
+function inputLabel(p) {
+    var _a;
+    const base = (_a = p.split(/[\\/]/).pop()) !== null && _a !== void 0 ? _a : p;
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+/**
+ * The m0 for one sheet: `rows` stacked rows of `cols` cells, with the
+ * trailing cells of a partial last row as null tiles (`-` holes — they
+ * consume no source; the doc's black background shows through).
+ * Produces the identical string to `grid({rows, cols}).m0` when the
+ * sheet is full (locked by a unit test).
+ */
+function buildSheetM0(rows, cols, thumbCount) {
+    const rowStrs = [];
+    for (let r = 0; r < rows; r++) {
+        const tokens = [];
+        for (let c = 0; c < cols; c++) {
+            tokens.push(r * cols + c < thumbCount ? "1" : "-");
+        }
+        rowStrs.push(cols === 1 ? tokens[0] : `${cols}(${tokens.join(",")})`);
+    }
+    return rows === 1 ? rowStrs[0] : `${rows}[${rowStrs.join(",")}]`;
+}
+function errorStep(stepName, label, message, ctx) {
+    return {
+        name: stepName,
+        label,
+        durationMs: exports.ERROR_STEP_MS,
+        file: (0, template_utils_1.makeErrorMosaic)(message, {
+            title: ERROR_TITLE,
+            width: ctx.target.width,
+            height: ctx.target.height,
+        }),
+    };
+}
+/**
+ * Build the pipeline steps for one input: one step per sheet, plus the
+ * per-input index sidecars on the first sheet step. Input problems
+ * degrade to a single error-mosaic step so one bad file never kills a
+ * batch.
+ */
+function buildTrickplayStepsForInput(args) {
+    var _a, _b, _c;
+    const { inputPath, stepBaseName, knobs, ctx } = args;
+    const label = inputLabel(inputPath);
+    const firstStepName = sheetStepName(stepBaseName, 0);
+    const meta = ctx.media[(0, types_1.asAssetId)(inputPath)];
+    if (!meta || !(meta.width > 0) || !(meta.height > 0)) {
+        return [errorStep(firstStepName, label, `No probed dimensions for input: ${inputPath}`, ctx)];
+    }
+    if (meta.kind !== "video") {
+        return [
+            errorStep(firstStepName, label, `Trickplay needs a video input (kind: ${meta.kind}): ${inputPath}`, ctx),
+        ];
+    }
+    if (!(meta.durationMs != null && meta.durationMs > 0)) {
+        return [errorStep(firstStepName, label, `Video input has no probed duration: ${inputPath}`, ctx)];
+    }
+    try {
+        const frameMs = Math.max(1, Math.round(1000 / ((_b = (_a = meta.fps) !== null && _a !== void 0 ? _a : ctx.target.fps) !== null && _b !== void 0 ? _b : 30)));
+        const plan = (0, plan_1.planTrickplay)({
+            durationMs: meta.durationMs,
+            srcWidth: meta.width,
+            srcHeight: meta.height,
+            frameMs,
+            intervalSec: knobs.intervalSec,
+            tileWidth: knobs.tileWidth,
+            cols: knobs.cols,
+            rowsPerSheet: knobs.rowsPerSheet,
+        });
+        const isImage = knobs.outputFormat !== "mp4";
+        const format = isImage
+            ? { kind: "image", container: knobs.outputFormat }
+            : { kind: "video", container: "mp4" };
+        const stepDurationMs = isImage ? exports.IMAGE_STEP_MS : ((_c = ctx.target.durationMs) !== null && _c !== void 0 ? _c : 5000);
+        const assetId = (0, types_1.asAssetId)((0, template_utils_1.slugifyAssetKeyFromPath)(inputPath));
+        const assets = {
+            [assetId]: { kind: "file", path: inputPath, mediaType: "video" },
+        };
+        return plan.sheets.map((sheet) => {
+            const sources = [];
+            for (let j = 0; j < sheet.thumbCount; j++) {
+                const t = plan.timestampsMs[sheet.firstThumbIndex + j];
+                sources.push({
+                    type: "media",
+                    mediaType: "video",
+                    assetId,
+                    // Cell aspect == source aspect up to even-rounding, so cover
+                    // is an exact fit (no visible crop).
+                    placement: { fit: "cover" },
+                    playback: isImage
+                        ? { clipStartMs: t, clipDurationMs: frameMs, loopMode: "freeze" }
+                        : { clipStartMs: t },
+                    audio: { enabled: false },
+                    editor: { owner: "template" },
+                });
+            }
+            const doc = {
+                kind: "mosaic_document",
+                version: 1,
+                m0: (0, dsl_stdlib_1.toM0String)(buildSheetM0(sheet.rows, sheet.cols, sheet.thumbCount), "Trickplay"),
+                assets,
+                sources,
+                size: { width: sheet.width, height: sheet.height },
+                backgroundColor: "#000000",
+                format,
+                ...(isImage && sheet.index === 0
+                    ? { sidecars: buildIndexSidecars(plan, inputPath, meta.durationMs, knobs, stepBaseName) }
+                    : {}),
+            };
+            return {
+                name: sheetStepName(stepBaseName, sheet.index),
+                label: plan.sheets.length > 1 ? `${label} (sheet ${sheet.index + 1}/${plan.sheets.length})` : label,
+                durationMs: stepDurationMs,
+                file: doc,
+            };
+        });
+    }
+    catch (err) {
+        return [
+            errorStep(firstStepName, label, `Trickplay step failed for ${inputPath}: ${err instanceof Error ? err.message : String(err)}`, ctx),
+        ];
+    }
+}
+function buildIndexSidecars(plan, inputPath, durationMs, knobs, stepBaseName) {
+    const sheetRef = (sheetIndex) => (0, types_1.stepOutputToken)(sheetStepName(stepBaseName, sheetIndex));
+    return {
+        trickplay: (0, sidecars_1.buildTrickplayManifest)({
+            plan,
+            inputPath,
+            durationMs,
+            cols: knobs.cols,
+            rowsPerSheet: knobs.rowsPerSheet,
+            sheetRef,
+        }),
+        storyboard: {
+            kind: "text",
+            ext: "vtt",
+            content: (0, sidecars_1.buildStoryboardVtt)(plan, sheetRef),
+        },
+    };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Pure trickplay math: fixed-interval seek timestamps, sheet
+ * partitioning, and per-thumb cue rectangles.
+ *
+ * This is the fixed-cadence counterpart of screencap-grid's
+ * proportional `computeTimestamps` (`(i+1)/(n+1)·d`): trickplay
+ * players expect one thumbnail per `interval`, placed row-major into
+ * fixed-capacity sheets — thumb `i` covers the timeline range
+ * `[i·interval, (i+1)·interval)` and lives at a coordinate derivable
+ * from `i` alone. Everything here is a pure function of its inputs.
+ */
+export type TrickplayKnobs = {
+    /** Seconds between thumbnails. */
+    intervalSec: number;
+    /** Thumbnail width in px (even-rounded; height derives from source aspect). */
+    tileWidth: number;
+    /** Tiles per sheet row. */
+    cols: number;
+    /** Max tile rows per sheet. */
+    rowsPerSheet: number;
+};
+export type TrickplayCue = {
+    /** Timeline range this thumb previews. `endMs` is exclusive; the last cue ends at the media duration. */
+    startMs: number;
+    endMs: number;
+    /** Which sheet the thumb lives in. */
+    sheetIndex: number;
+    /** Pixel rect within the sheet (the WebVTT `#xywh` values). */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type TrickplaySheet = {
+    index: number;
+    /** Tile rows actually present (the last sheet is trimmed). */
+    rows: number;
+    cols: number;
+    /** Sheet canvas dims in px — exactly cols·tileWidth × rows·tileHeight. */
+    width: number;
+    height: number;
+    /** Thumbs on this sheet (< rows·cols only on the last sheet). */
+    thumbCount: number;
+    /** Global index of this sheet's first thumb. */
+    firstThumbIndex: number;
+};
+export type TrickplayPlan = {
+    intervalMs: number;
+    tileWidth: number;
+    tileHeight: number;
+    thumbnailCount: number;
+    /** Seek time per thumb, clamped so the last seek still yields a frame. */
+    timestampsMs: number[];
+    sheets: TrickplaySheet[];
+    cues: TrickplayCue[];
+};
+/** Round to the nearest even integer, floored at 2 (encoder-safe tile dims). */
+export declare function evenRound(v: number): number;
+export declare function planTrickplay(args: {
+    durationMs: number;
+    srcWidth: number;
+    srcHeight: number;
+    /** One source frame's duration in ms (seek clamp headroom). */
+    frameMs: number;
+} & TrickplayKnobs): TrickplayPlan;

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

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Pure trickplay math: fixed-interval seek timestamps, sheet
+ * partitioning, and per-thumb cue rectangles.
+ *
+ * This is the fixed-cadence counterpart of screencap-grid's
+ * proportional `computeTimestamps` (`(i+1)/(n+1)·d`): trickplay
+ * players expect one thumbnail per `interval`, placed row-major into
+ * fixed-capacity sheets — thumb `i` covers the timeline range
+ * `[i·interval, (i+1)·interval)` and lives at a coordinate derivable
+ * from `i` alone. Everything here is a pure function of its inputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evenRound = evenRound;
+exports.planTrickplay = planTrickplay;
+/** Round to the nearest even integer, floored at 2 (encoder-safe tile dims). */
+function evenRound(v) {
+    return Math.max(2, 2 * Math.round(v / 2));
+}
+function planTrickplay(args) {
+    const { durationMs, srcWidth, srcHeight, frameMs } = args;
+    if (!(durationMs > 0)) {
+        throw new Error(`planTrickplay: durationMs must be > 0 (got ${durationMs})`);
+    }
+    if (!(srcWidth > 0) || !(srcHeight > 0)) {
+        throw new Error(`planTrickplay: source dims must be > 0 (got ${srcWidth}×${srcHeight})`);
+    }
+    const intervalMs = Math.max(1, Math.round(args.intervalSec * 1000));
+    const cols = Math.max(1, Math.round(args.cols));
+    const rowsPerSheet = Math.max(1, Math.round(args.rowsPerSheet));
+    const tileWidth = evenRound(args.tileWidth);
+    const tileHeight = evenRound(tileWidth * (srcHeight / srcWidth));
+    const thumbnailCount = Math.max(1, Math.ceil(durationMs / intervalMs));
+    // Seek at each interval start; clamp so the final seek lands at least
+    // one frame before EOF (a seek at/past EOF yields no frame). t_0 stays 0.
+    const maxSeek = Math.max(0, Math.round(durationMs - frameMs));
+    const timestampsMs = Array.from({ length: thumbnailCount }, (_, i) => Math.min(i * intervalMs, maxSeek));
+    const capacity = cols * rowsPerSheet;
+    const sheetCount = Math.ceil(thumbnailCount / capacity);
+    const sheets = Array.from({ length: sheetCount }, (_, s) => {
+        const firstThumbIndex = s * capacity;
+        const thumbCount = Math.min(capacity, thumbnailCount - firstThumbIndex);
+        const rows = Math.ceil(thumbCount / cols);
+        return {
+            index: s,
+            rows,
+            cols,
+            width: cols * tileWidth,
+            height: rows * tileHeight,
+            thumbCount,
+            firstThumbIndex,
+        };
+    });
+    const cues = Array.from({ length: thumbnailCount }, (_, i) => {
+        const sheetIndex = Math.floor(i / capacity);
+        const j = i - sheetIndex * capacity;
+        return {
+            startMs: i * intervalMs,
+            endMs: Math.min((i + 1) * intervalMs, Math.round(durationMs)),
+            sheetIndex,
+            x: (j % cols) * tileWidth,
+            y: Math.floor(j / cols) * tileHeight,
+            w: tileWidth,
+            h: tileHeight,
+        };
+    });
+    return {
+        intervalMs,
+        tileWidth,
+        tileHeight,
+        thumbnailCount,
+        timestampsMs,
+        sheets,
+        cues,
+    };
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Trickplay index-file builders: the WebVTT storyboard and the JSON
+ * manifest. Both reference sheet images via `{{stepOutput:<stepName>}}`
+ * tokens (see `@m0saic/types` `stepOutputToken`) — the engine's sidecar
+ * writer substitutes each token with the sheet deliverable's final
+ * on-disk basename, so the emitted references are valid relative URLs
+ * next to the index files.
+ *
+ * Conventions covered:
+ *  - WebVTT storyboard (`#xywh=x,y,w,h` media fragments) — the
+ *    de-facto web-player format (Video.js, JW, Bitmovin, THEO, hls.js UIs).
+ *  - Jellyfin trickplay fields (Width/Height = per-thumb px,
+ *    TileWidth/TileHeight = tiles per row/column, ThumbnailCount,
+ *    Interval in ms). Bandwidth is omitted — sheet byte sizes are
+ *    unknowable at make-time.
+ *  - DASH-IF thumbnail tiles (`thumbnail_tile` EssentialProperty,
+ *    value "HxV") — ready to lift into an MPD.
+ */
+import type { TrickplayPlan } from "./plan";
+export type TrickplayManifest = {
+    version: 1;
+    input: string;
+    durationMs: number;
+    intervalMs: number;
+    tileWidth: number;
+    tileHeight: number;
+    cols: number;
+    rowsPerSheet: number;
+    thumbnailCount: number;
+    sheets: Array<{
+        /** Sheet image file reference (step-output token → final basename). */
+        file: string;
+        width: number;
+        height: number;
+        rows: number;
+        cols: number;
+        thumbCount: number;
+        firstThumbIndex: number;
+    }>;
+    cues: Array<{
+        startMs: number;
+        endMs: number;
+        /** Sheet image file reference (step-output token → final basename). */
+        sheet: string;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+    jellyfin: {
+        Width: number;
+        Height: number;
+        TileWidth: number;
+        TileHeight: number;
+        ThumbnailCount: number;
+        Interval: number;
+    };
+    dashIf: {
+        schemeIdUri: "http://dashif.org/guidelines/thumbnail_tile";
+        value: string;
+    };
+};
+/** Format milliseconds as a WebVTT timestamp (`HH:MM:SS.mmm`). */
+export declare function formatVttTimestamp(ms: number): string;
+/**
+ * Build the WebVTT storyboard. `sheetRef(sheetIndex)` supplies the
+ * sheet-image reference for each cue's payload (a step-output token in
+ * production; tests may pass literal names).
+ */
+export declare function buildStoryboardVtt(plan: TrickplayPlan, sheetRef: (sheetIndex: number) => string): string;
+/** Build the JSON manifest (Jellyfin + DASH-IF blocks + full cue list). */
+export declare function buildTrickplayManifest(args: {
+    plan: TrickplayPlan;
+    inputPath: string;
+    durationMs: number;
+    cols: number;
+    rowsPerSheet: number;
+    sheetRef: (sheetIndex: number) => string;
+}): TrickplayManifest;

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

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Trickplay index-file builders: the WebVTT storyboard and the JSON
+ * manifest. Both reference sheet images via `{{stepOutput:<stepName>}}`
+ * tokens (see `@m0saic/types` `stepOutputToken`) — the engine's sidecar
+ * writer substitutes each token with the sheet deliverable's final
+ * on-disk basename, so the emitted references are valid relative URLs
+ * next to the index files.
+ *
+ * Conventions covered:
+ *  - WebVTT storyboard (`#xywh=x,y,w,h` media fragments) — the
+ *    de-facto web-player format (Video.js, JW, Bitmovin, THEO, hls.js UIs).
+ *  - Jellyfin trickplay fields (Width/Height = per-thumb px,
+ *    TileWidth/TileHeight = tiles per row/column, ThumbnailCount,
+ *    Interval in ms). Bandwidth is omitted — sheet byte sizes are
+ *    unknowable at make-time.
+ *  - DASH-IF thumbnail tiles (`thumbnail_tile` EssentialProperty,
+ *    value "HxV") — ready to lift into an MPD.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatVttTimestamp = formatVttTimestamp;
+exports.buildStoryboardVtt = buildStoryboardVtt;
+exports.buildTrickplayManifest = buildTrickplayManifest;
+/** Format milliseconds as a WebVTT timestamp (`HH:MM:SS.mmm`). */
+function formatVttTimestamp(ms) {
+    const clamped = Math.max(0, Math.round(ms));
+    const msPart = clamped % 1000;
+    const totalSec = Math.floor(clamped / 1000);
+    const sec = totalSec % 60;
+    const min = Math.floor(totalSec / 60) % 60;
+    const hr = Math.floor(totalSec / 3600);
+    const pad = (n, w) => String(n).padStart(w, "0");
+    return `${pad(hr, 2)}:${pad(min, 2)}:${pad(sec, 2)}.${pad(msPart, 3)}`;
+}
+/**
+ * Build the WebVTT storyboard. `sheetRef(sheetIndex)` supplies the
+ * sheet-image reference for each cue's payload (a step-output token in
+ * production; tests may pass literal names).
+ */
+function buildStoryboardVtt(plan, sheetRef) {
+    const cues = plan.cues.map((c) => `${formatVttTimestamp(c.startMs)} --> ${formatVttTimestamp(c.endMs)}\n` +
+        `${sheetRef(c.sheetIndex)}#xywh=${c.x},${c.y},${c.w},${c.h}`);
+    return `WEBVTT\n\n${cues.join("\n\n")}\n`;
+}
+/** Build the JSON manifest (Jellyfin + DASH-IF blocks + full cue list). */
+function buildTrickplayManifest(args) {
+    const { plan, inputPath, durationMs, cols, rowsPerSheet, sheetRef } = args;
+    return {
+        version: 1,
+        input: inputPath,
+        durationMs: Math.round(durationMs),
+        intervalMs: plan.intervalMs,
+        tileWidth: plan.tileWidth,
+        tileHeight: plan.tileHeight,
+        cols,
+        rowsPerSheet,
+        thumbnailCount: plan.thumbnailCount,
+        sheets: plan.sheets.map((s) => ({
+            file: sheetRef(s.index),
+            width: s.width,
+            height: s.height,
+            rows: s.rows,
+            cols: s.cols,
+            thumbCount: s.thumbCount,
+            firstThumbIndex: s.firstThumbIndex,
+        })),
+        cues: plan.cues.map((c) => ({
+            startMs: c.startMs,
+            endMs: c.endMs,
+            sheet: sheetRef(c.sheetIndex),
+            x: c.x,
+            y: c.y,
+            w: c.w,
+            h: c.h,
+        })),
+        jellyfin: {
+            Width: plan.tileWidth,
+            Height: plan.tileHeight,
+            TileWidth: cols,
+            TileHeight: rowsPerSheet,
+            ThumbnailCount: plan.thumbnailCount,
+            Interval: plan.intervalMs,
+        },
+        dashIf: {
+            schemeIdUri: "http://dashif.org/guidelines/thumbnail_tile",
+            value: `${cols}x${rowsPerSheet}`,
+        },
+    };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Trickplay sheet generator — `@m0saic/media/trickplay/v1`.
+ *
+ * Renders the seek-preview artifacts video players use while scrubbing:
+ * sprite sheets of video thumbnails at a fixed interval, placed at
+ * known row-major grid coordinates, plus the player-consumable index
+ * files (WebVTT storyboard with `#xywh` cues; JSON manifest carrying
+ * Jellyfin-compatible fields and DASH-IF `thumbnail_tile` grid info).
+ *
+ * One template covers every output shape via the `outputFormat` knob
+ * (watermark's per-step-format precedent): `png` (default) / `jpeg`
+ * emit static sheets + index sidecars; `mp4` emits an animated
+ * contact-sheet preview (no sidecars). `outputHints` deliberately
+ * carries NO `format` — a template-level container hint would override
+ * the user's `-o` extension in `resolveOutputFormat`; each pipeline
+ * step declares its own format instead.
+ *
+ * Always returns an `emit:"multi"` pipeline (watermark precedent):
+ * per-step canvases are the only vehicle for probed-dims sheet sizing,
+ * and long inputs fan out to multiple sheet steps.
+ */
+import type { MosaicTemplate } from "@m0saic/types";
+import { type TrickplayOutputFormat, type TrickplayStepKnobs } from "./pipeline";
+export type TrickplayV1Props = {
+    /** Video(s) to index — a folder, one or more files, or drag-and-drop. One sheet set per input. */
+    sourceIds?: string[];
+    /** Seconds between thumbnails. Default 10 (Jellyfin parity). */
+    intervalSec?: number;
+    /** Thumbnail width in px (even-rounded; height derives from source aspect). Default 320. */
+    tileWidth?: number;
+    /** Thumbnails per sheet row. Default 10. */
+    cols?: number;
+    /** Max thumbnail rows per sheet; longer content spills to more sheets. Default 10. */
+    rowsPerSheet?: number;
+    /** Sheet output: png/jpeg static sheets + index sidecars, or an animated mp4 preview. Default "png". */
+    outputFormat?: TrickplayOutputFormat;
+};
+/** Resolve + clamp props to deterministic step knobs. */
+export declare function resolveTrickplayKnobs(props: TrickplayV1Props): TrickplayStepKnobs;
+export declare const Trickplay: MosaicTemplate<TrickplayV1Props>;