@m0saic/templates 0.2.0

package/dist/m0saic/media/metadata-stamp/v1/format-date.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Pure, machine-independent timestamp helpers for
+ * `@m0saic/media/metadata-stamp/v1`.
+ *
+ * Container creation tags arrive as ISO-8601 strings from the engine's
+ * ffprobe pass (`ctx.media[...]`). These helpers parse and format them
+ * WITHOUT `Date.parse`-on-naive-strings, `toLocale*`, or `Intl` — all of
+ * which read machine locale/timezone and would break byte-identical
+ * renders (agent contract §9). A wall time with no zone designator is
+ * treated as UTC, never as local time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAMP_DATE_FORMATS = exports.CREATION_TIME_TAG = exports.APPLE_CREATION_TAG = void 0;
+exports.extractCreationTimestampRaw = extractCreationTimestampRaw;
+exports.parseVideoTimestamp = parseVideoTimestamp;
+exports.formatVideoTimestamp = formatVideoTimestamp;
+/** Apple's QuickTime creation tag — carries the local UTC offset. */
+exports.APPLE_CREATION_TAG = "com.apple.quicktime.creationdate";
+/** The generic MP4/MOV creation tag — normalized to UTC by ffmpeg. */
+exports.CREATION_TIME_TAG = "creation_time";
+/** Date-format presets. English month names, fixed — no locale reads. */
+exports.STAMP_DATE_FORMATS = [
+    "YYYY-MM-DD",
+    "YYYY-MM-DD HH:mm",
+    "MMM D, YYYY",
+    "D MMM YYYY",
+    "MM/DD/YYYY",
+    "DD.MM.YYYY",
+];
+const MONTHS_EN = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+/**
+ * Pull the raw creation-timestamp string off probed metadata. Prefers
+ * the Apple key (it keeps the local UTC offset the camera stamped);
+ * falls back to `creation_time` (UTC). Returns null when neither tag is
+ * present — a common, normal case (transcoded or stripped files).
+ */
+function extractCreationTimestampRaw(meta) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    if (!meta)
+        return null;
+    const apple = (_c = (_b = (_a = meta.format) === null || _a === void 0 ? void 0 : _a.tags) === null || _b === void 0 ? void 0 : _b[exports.APPLE_CREATION_TAG]) !== null && _c !== void 0 ? _c : (_d = meta.tags) === null || _d === void 0 ? void 0 : _d[exports.APPLE_CREATION_TAG];
+    if (apple && apple.trim().length > 0)
+        return apple.trim();
+    const generic = (_f = (_e = meta.tags) === null || _e === void 0 ? void 0 : _e[exports.CREATION_TIME_TAG]) !== null && _f !== void 0 ? _f : (_h = (_g = meta.format) === null || _g === void 0 ? void 0 : _g.tags) === null || _h === void 0 ? void 0 : _h[exports.CREATION_TIME_TAG];
+    return generic && generic.trim().length > 0 ? generic.trim() : null;
+}
+// ISO-8601-ish: date, optional time (T or space), optional fraction,
+// optional zone (Z, ±hh:mm, ±hhmm). Covers ffprobe's
+// "2024-03-11T18:22:04.000000Z" and Apple's "2024-03-11T19:22:04+0100".
+const TS_RE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?\s*(Z|z|[+-]\d{2}:?\d{2})?$/;
+/**
+ * Parse a creation-tag string into an absolute instant + stated offset.
+ * Missing zone designator = UTC (deterministic; NEVER local time).
+ * Returns null for anything malformed or out of range.
+ */
+function parseVideoTimestamp(raw) {
+    if (!raw)
+        return null;
+    const m = TS_RE.exec(raw.trim());
+    if (!m)
+        return null;
+    const year = Number(m[1]);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    const hour = m[4] !== undefined ? Number(m[4]) : 0;
+    const minute = m[5] !== undefined ? Number(m[5]) : 0;
+    const second = m[6] !== undefined ? Number(m[6]) : 0;
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return null;
+    if (hour > 23 || minute > 59 || second > 60)
+        return null;
+    let offsetMinutes = null;
+    const zone = m[7];
+    if (zone !== undefined) {
+        if (zone === "Z" || zone === "z") {
+            offsetMinutes = 0;
+        }
+        else {
+            const sign = zone.startsWith("-") ? -1 : 1;
+            const hh = Number(zone.slice(1, 3));
+            const mm = Number(zone.slice(-2));
+            if (hh > 23 || mm > 59)
+                return null;
+            offsetMinutes = sign * (hh * 60 + mm);
+        }
+    }
+    const wallUtcMs = Date.UTC(year, month - 1, day, hour, minute, second);
+    // The wall-clock fields are local to `offsetMinutes`; subtract it to
+    // land on the absolute instant. No offset stated → wall time IS UTC.
+    const epochMs = offsetMinutes === null ? wallUtcMs : wallUtcMs - offsetMinutes * 60000;
+    return { epochMs, offsetMinutes };
+}
+/**
+ * Format a parsed timestamp. The rendered wall time uses, in order:
+ * the explicit `utcOffsetMinutes` override, the offset the tag carried,
+ * else UTC. `new Date(number)` + `getUTC*` only — pure epoch math.
+ */
+function formatVideoTimestamp(ts, format, utcOffsetMinutes) {
+    var _a;
+    const offset = (_a = utcOffsetMinutes !== null && utcOffsetMinutes !== void 0 ? utcOffsetMinutes : ts.offsetMinutes) !== null && _a !== void 0 ? _a : 0;
+    const t = new Date(ts.epochMs + offset * 60000);
+    const y = t.getUTCFullYear();
+    const mo = t.getUTCMonth() + 1;
+    const d = t.getUTCDate();
+    const p2 = (n) => String(n).padStart(2, "0");
+    switch (format) {
+        case "YYYY-MM-DD":
+            return `${y}-${p2(mo)}-${p2(d)}`;
+        case "YYYY-MM-DD HH:mm":
+            return `${y}-${p2(mo)}-${p2(d)} ${p2(t.getUTCHours())}:${p2(t.getUTCMinutes())}`;
+        case "MMM D, YYYY":
+            return `${MONTHS_EN[mo - 1]} ${d}, ${y}`;
+        case "D MMM YYYY":
+            return `${d} ${MONTHS_EN[mo - 1]} ${y}`;
+        case "MM/DD/YYYY":
+            return `${p2(mo)}/${p2(d)}/${y}`;
+        case "DD.MM.YYYY":
+            return `${p2(d)}.${p2(mo)}.${y}`;
+        default: {
+            const never = format;
+            throw new Error(`formatVideoTimestamp: unknown format ${String(never)}`);
+        }
+    }
+}

package/dist/m0saic/media/metadata-stamp/v1/index.d.ts

@@ -0,0 +1,4 @@
+export { MetadataStampV1 } from "./metadata-stamp";
+export type { MetadataStampV1Props, MetadataStampField } from "./metadata-stamp";
+export { STAMP_DATE_FORMATS, extractCreationTimestampRaw, formatVideoTimestamp, parseVideoTimestamp, } from "./format-date";
+export type { StampDateFormat, ParsedVideoTimestamp } from "./format-date";

package/dist/m0saic/media/metadata-stamp/v1/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVideoTimestamp = exports.formatVideoTimestamp = exports.extractCreationTimestampRaw = exports.STAMP_DATE_FORMATS = exports.MetadataStampV1 = void 0;
+var metadata_stamp_1 = require("./metadata-stamp");
+Object.defineProperty(exports, "MetadataStampV1", { enumerable: true, get: function () { return metadata_stamp_1.MetadataStampV1; } });
+var format_date_1 = require("./format-date");
+Object.defineProperty(exports, "STAMP_DATE_FORMATS", { enumerable: true, get: function () { return format_date_1.STAMP_DATE_FORMATS; } });
+Object.defineProperty(exports, "extractCreationTimestampRaw", { enumerable: true, get: function () { return format_date_1.extractCreationTimestampRaw; } });
+Object.defineProperty(exports, "formatVideoTimestamp", { enumerable: true, get: function () { return format_date_1.formatVideoTimestamp; } });
+Object.defineProperty(exports, "parseVideoTimestamp", { enumerable: true, get: function () { return format_date_1.parseVideoTimestamp; } });

package/dist/m0saic/media/metadata-stamp/v1/metadata-stamp.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @m0saic/media/metadata-stamp/v1 — "Metadata Stamp"
+ *
+ * Utility template: read each source video's creation timestamp from its
+ * container metadata (the engine's ffprobe pass already delivers the
+ * tags via `ctx.media` — no I/O here) and stamp it as a small text chip
+ * at one of the nine standard positions. Batch-first like the watermark:
+ * point it at a folder and every video gets stamped to its own output.
+ *
+ * When a file carries no creation tag (transcoded / stripped files — a
+ * normal case, not an edge case): `fallbackText` is stamped instead, and
+ * an EMPTY fallback means the video renders clean with no stamp at all —
+ * that's the configured no-op. `stampField` can also stamp the filename,
+ * or fixed custom text; other metadata fields are one enum value + one
+ * `ctx.media` read away.
+ *
+ * Always an `emit: "multi"` pipeline (watermark's convention, even for
+ * one input): pipeline steps are the only vehicle where each output's
+ * canvas tracks its input's probed dims (`step.file.size` wins; a plain
+ * top-level doc plans at the CLI `--width/--height`).
+ *
+ * Determinism: creation tags are properties of the input bytes —
+ * engine-provided metadata is an explicit input (knowledge:
+ * templates/philosophy-and-contract.md, "Core is dynamic — but pure").
+ * Formatting is pure UTC math in `format-date.ts`; no locale, no
+ * timezone, no wall clock. `meta.rawProbe` is never read.
+ */
+import { type StampPosition } from "@m0saic/template-utils";
+import { type StampDateFormat } from "./format-date";
+export type MetadataStampField = "creation-date" | "filename" | "custom";
+export type MetadataStampV1Props = {
+    /** Videos to stamp — a folder, one or more files, or drag-and-drop. One output per input. */
+    sourceIds?: string[];
+    /** What to stamp: the video's creation date, its filename, or fixed custom text. */
+    stampField?: MetadataStampField;
+    /** Fixed text to stamp (stampField: "custom"; in batch mode it applies to every file). */
+    customText?: string;
+    /** Stamped when a file has no creation tag. EMPTY = render that video with no stamp (the no-op). */
+    fallbackText?: string;
+    /** Date format preset (English month names; deterministic). */
+    dateFormat?: StampDateFormat;
+    /** Rendered UTC offset in minutes. Unset = the tag's own offset when present, else UTC. */
+    utcOffsetMinutes?: number;
+    /** Standard placement. */
+    position?: StampPosition;
+    /** Stamp chip height as a fraction of min(width, height). */
+    sizeRatio?: number;
+    /** Margin from the canvas edges, fraction of min(W, H). */
+    marginRatio?: number;
+    /** Stamp text color. */
+    fontColor?: string;
+    /** Chip (background pill behind the text) color. */
+    chipColor?: string;
+    /** Chip opacity; 0 removes the chip entirely. */
+    chipOpacity?: number;
+};
+export declare const MetadataStampV1: import("@m0saic/types").MosaicTemplate<MetadataStampV1Props, import("@m0saic/types").MosaicTemplateOutputs, import("@m0saic/types").MosaicTemplateUpstreamVariables, import("@m0saic/types").MosaicTemplateUpstreamData, import("@m0saic/types").MosaicTemplateSidecars>;
+export default MetadataStampV1;