@m0saic/templates 0.2.0

package/dist/m0saic/media/qr/stamp-video/v1/gleamBand.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Diagonal "gleam band" PNG — a soft white stripe at an angle on a
+ * transparent canvas. The QR-stamp video template overlays this on
+ * top of the QR with `blendMode: "screen"` and animates its
+ * x-position so the band sweeps across the QR every `gleamPeriodSec` —
+ * matching the production-feel shimmer used by the render-hero M.
+ *
+ * Generated inline per render via the shared resvg rasterizer. Cheap
+ * (~30 ms on a tiny SVG) — orders of magnitude smaller than the
+ * stamp wrap's re-encode pass, so prebuilding the PNG into a shipped
+ * asset is not worth the build-step complexity.
+ *
+ * Pure procedural; deterministic given inputs.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateGleamBandPng = generateGleamBandPng;
+exports.buildGleamSweepXExpr = buildGleamSweepXExpr;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const svgRaster_1 = require("../../../../_shared/svgRaster");
+const DEFAULTS = {
+    outputName: "qr-stamp-gleam.png",
+    angleDeg: 20,
+    bandWidthFrac: 0.018,
+    peakAlpha: 0.4,
+};
+function buildGleamSvg(opts) {
+    const { sizePx, angleDeg, bandWidthFrac, peakAlpha } = opts;
+    const half = bandWidthFrac;
+    const mid = 0.5;
+    // Peaked falloff: thin bright core at the center, soft halo around
+    // it. This is the visual difference between "premium specular
+    // highlight on glass" and "PowerPoint shine transition." The
+    // previous gradient was a 3-stop linear triangle (0 → peak → 0
+    // straight ramp) — which reads as a wide soft wash, not a real
+    // reflection. The shape we want is closer to a Lorentzian peak:
+    // nearly invisible at the band edges, a soft halo through the
+    // middle, then a sharp bright crest right at the center.
+    //
+    // Six interior stops give us:
+    //   - Band-edge anchor at alpha 0 (outer 100% of bandWidthFrac)
+    //   - Halo shoulder at alpha = peakAlpha * 0.18 (at 60% inset)
+    //   - Inner shoulder at alpha = peakAlpha * 0.5 (at 30% inset)
+    //   - Crest at alpha = peakAlpha (center)
+    //   - Mirror on the right side
+    //
+    // The two-step shoulder (0 → 0.18 → 0.5 → 1.0 normalized) makes
+    // the alpha curve steepen as you approach the center. Linear
+    // interpolation between these stops approximates the shape of a
+    // real specular reflection without needing an SVG <filter>.
+    const shoulderOffsetOuter = (mid - half) * 100; // alpha 0
+    const shoulderOffsetMid = (mid - half * 0.6) * 100; // alpha 0.18*peak
+    const shoulderOffsetInner = (mid - half * 0.3) * 100; // alpha 0.5*peak
+    const peakOffset = mid * 100; // alpha peak
+    const shoulderOffsetInnerR = (mid + half * 0.3) * 100;
+    const shoulderOffsetMidR = (mid + half * 0.6) * 100;
+    const shoulderOffsetOuterR = (mid + half) * 100;
+    const haloAlpha = peakAlpha * 0.18;
+    const midAlpha = peakAlpha * 0.5;
+    return `
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${sizePx} ${sizePx}">
+  <defs>
+    <linearGradient id="gleam" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="white" stop-opacity="0"/>
+      <stop offset="${shoulderOffsetOuter.toFixed(3)}%" stop-color="white" stop-opacity="0"/>
+      <stop offset="${shoulderOffsetMid.toFixed(3)}%" stop-color="white" stop-opacity="${haloAlpha.toFixed(3)}"/>
+      <stop offset="${shoulderOffsetInner.toFixed(3)}%" stop-color="white" stop-opacity="${midAlpha.toFixed(3)}"/>
+      <stop offset="${peakOffset.toFixed(3)}%" stop-color="white" stop-opacity="${peakAlpha.toFixed(3)}"/>
+      <stop offset="${shoulderOffsetInnerR.toFixed(3)}%" stop-color="white" stop-opacity="${midAlpha.toFixed(3)}"/>
+      <stop offset="${shoulderOffsetMidR.toFixed(3)}%" stop-color="white" stop-opacity="${haloAlpha.toFixed(3)}"/>
+      <stop offset="${shoulderOffsetOuterR.toFixed(3)}%" stop-color="white" stop-opacity="0"/>
+      <stop offset="100%" stop-color="white" stop-opacity="0"/>
+    </linearGradient>
+  </defs>
+  <g transform="rotate(${angleDeg.toFixed(2)} ${sizePx / 2} ${sizePx / 2})">
+    <rect x="${-sizePx}" y="${-sizePx}" width="${sizePx * 3}" height="${sizePx * 3}" fill="url(#gleam)"/>
+  </g>
+</svg>`.trim();
+}
+async function generateGleamBandPng(opts) {
+    var _a, _b, _c, _d;
+    const outputName = (_a = opts.outputName) !== null && _a !== void 0 ? _a : DEFAULTS.outputName;
+    const angleDeg = (_b = opts.angleDeg) !== null && _b !== void 0 ? _b : DEFAULTS.angleDeg;
+    const bandWidthFrac = (_c = opts.bandWidthFrac) !== null && _c !== void 0 ? _c : DEFAULTS.bandWidthFrac;
+    const peakAlpha = (_d = opts.peakAlpha) !== null && _d !== void 0 ? _d : DEFAULTS.peakAlpha;
+    const sizePx = Math.max(16, Math.round(opts.sizePx));
+    const svg = buildGleamSvg({ sizePx, angleDeg, bandWidthFrac, peakAlpha });
+    fs.mkdirSync(opts.workspaceDir, { recursive: true });
+    const pngPath = path.join(opts.workspaceDir, outputName);
+    // High-quality rasterization with a bumped density. The band has soft
+    // gradient edges so antialiasing matters more than the QR's hard
+    // module edges — render at 2× and downsample for a clean falloff.
+    const density = Math.max(72, Math.round((72 * sizePx * 2) / sizePx));
+    // The SVG's viewBox is 0 0 sizePx sizePx, so fitting the width to sizePx is
+    // exactly 1:1 — resvg antialiases analytically, so the old
+    // render-at-density-then-lanczos-downscale step is unnecessary.
+    await (0, svgRaster_1.renderSvgToPngFile)(svg, pngPath, sizePx);
+    return { pngPath };
+}
+/**
+ * Build the ffmpeg overlay xExpr for a periodic gleam sweep.
+ *
+ * The band PNG is the same natural size as the QR (so `w` in the
+ * expression equals the band layer's width, which equals the QR's
+ * width). The sweep traverses the band from offscreen-left to
+ * offscreen-right over `sweepSec`, then the enable-gate on the
+ * overlay (set in qr-stamp.ts) hides the layer for the remaining
+ * `periodSec - sweepSec` — periodic rather than continuous.
+ *
+ * # Eased traversal
+ *
+ * The previous formula was linear (`min(1, mod(t,p)/sweep)`) — the
+ * band moved at constant velocity then snapped park at +0.35w. The
+ * constant velocity + hard park is what reads as "PowerPoint shine
+ * transition." Real reflections accelerate from rest, blow through
+ * the middle, decelerate at the other side — a cosine ease curve.
+ *
+ *   x_offset(t) = -X + X * (1 - cos(PI * t_norm))
+ *
+ *   where X = 0.7 * w
+ *   and   t_norm = clamp(mod(t, periodSec) / sweepSec, 0, 1)
+ *
+ * Endpoint check:
+ *   t_norm = 0    → cos(0)  =  1  → x = -X + X*(1-1)  = -X    (offscreen left)
+ *   t_norm = 0.5  → cos(PI/2) = 0 → x = -X + X*(1-0)  =  0    (centered)
+ *   t_norm = 1    → cos(PI) = -1  → x = -X + X*(1-(-1)) = +X  (offscreen right)
+ *
+ * Velocity (derivative of x w.r.t. t_norm):
+ *   v = X * PI * sin(PI * t_norm)
+ *   sin(0) = sin(PI) = 0 → v = 0 at the endpoints (smooth start / stop)
+ *   sin(PI/2) = 1        → v = X*PI at center (peak speed)
+ *
+ * # Why X = 0.7w (offscreen entry / exit is safe)
+ *
+ * `overlay.xExpr` is an OFFSET on the destination — ffmpeg's overlay
+ * filter does NOT clip the layer to its destination rect. For a
+ * naive flat composition that would mean any sweep wider than the
+ * band's footprint paints onto surrounding canvas content.
+ *
+ * BUT — the gleam in qr-stamp.ts is wrapped in a **nested mosaic**
+ * (see `children["qr_stamp_gleam"]`), so the engine renders the
+ * sweep into an intermediate framebuffer sized exactly to the QR
+ * cell. The framebuffer's finite extent does the clipping for us:
+ * any pixels the band tries to paint past the QR's bounds simply
+ * have no buffer to land in. That makes ±0.7w safe — the band can
+ * enter from fully offscreen-left and exit fully offscreen-right
+ * without leaking onto canvas content.
+ *
+ * At 20° tilt + bandWidthFrac=0.018, the band's full horizontal
+ * footprint is ~80% of sizePx (tilt's `sin(20°)` component dominates).
+ * X=0.7 plus that half-footprint (~0.4) means the band is fully
+ * offscreen at both extremes — clean enter, clean exit, no visible
+ * pop at the enable-gate boundary.
+ *
+ * # Footgun if you copy this pattern elsewhere
+ *
+ * The ±0.7w range is ONLY safe because of the nested-mosaic wrap.
+ * If you remove the nested mosaic and use a flat overlay, the band
+ * will bleed onto surrounding content at the sweep extremes. See
+ * the internal nested-mosaic-clip-pattern notes for the
+ * general pattern.
+ */
+function buildGleamSweepXExpr(periodSec, sweepSec) {
+    const p = periodSec > 0 ? periodSec : 6;
+    const s = sweepSec > 0 ? sweepSec : 0.9;
+    // `min(1, mod(t,p)/s)` clamps t_norm into [0, 1] across the sweep
+    // window. After the sweep ends the enable-gate hides the layer
+    // anyway, but the clamp keeps cos(PI*t_norm) well-defined even if
+    // the gate is bypassed in a future caller.
+    const tNorm = `min(1,mod(t,${p.toFixed(3)})/${s.toFixed(3)})`;
+    return `(-0.7*w)+(0.7*w)*(1-cos(PI*${tNorm}))`;
+}

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

@@ -0,0 +1,2 @@
+export { QrStampVideo, default } from "./qr-stamp";
+export type { QrStampVideoProps, QrStampMode } from "./qr-stamp";

package/dist/m0saic/media/qr/stamp-video/v1/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.QrStampVideo = void 0;
+var qr_stamp_1 = require("./qr-stamp");
+Object.defineProperty(exports, "QrStampVideo", { enumerable: true, get: function () { return qr_stamp_1.QrStampVideo; } });
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(qr_stamp_1).default; } });

package/dist/m0saic/media/qr/stamp-video/v1/qr-stamp.d.ts

@@ -0,0 +1,82 @@
+import type { LuminanceBucket } from "@m0saic/types";
+/**
+ * Adaptive M0saic QR watermark for video.
+ *
+ * Overlays a M0saic QR code in the bottom-right corner of an input video.
+ * When `mode === "auto"` and luminance buckets are provided, the template
+ * crossfades between a light-bg and dark-bg variant per the underlying
+ * video's brightness — bright scenes get the light-bg variant (cohesive
+ * tonal match) and dark scenes get the dark-bg variant. The orange QR
+ * modules contrast against both backgrounds, so the QR stays scannable
+ * either way.
+ *
+ * This is the engine-pure half of the free-tier watermark feature:
+ * the template accepts pre-computed `luminanceBuckets` so the render
+ * stays deterministic. The CLI runs the actual ffmpeg luminance probe
+ * (see `@m0saic/core/probe/luminanceProbe`) and passes the buckets in.
+ */
+export type QrStampMode = "auto" | "light" | "dark" | "transparent";
+export type QrStampVideoProps = {
+    /**
+     * Path to the base video file the QR will be stamped onto.
+     * Required at render time; optional in the type so `defaultProps` doesn't
+     * have to seed a fake placeholder. `render` throws if missing.
+     */
+    videoPath?: string;
+    /** Text encoded into the QR (URL, plain string, or structured payload). */
+    text?: string;
+    /** Gutter between the QR and the bottom-right canvas edges, in pixels. */
+    cornerInsetPx?: number;
+    /** Stamp size as a percent of min(W, H). */
+    stampSizePct?: number;
+    /** Play a polished entrance animation (scale-bounce + fade-in). */
+    entrance?: boolean;
+    /** Entrance duration, ms. */
+    entranceDurMs?: number;
+    /**
+     * Periodic diagonal shine sweep — premium production polish. Renders
+     * a soft white diagonal band overlay with `blendMode: "screen"` that
+     * sweeps across the QR every `gleamPeriodSec`. Matches the render-hero
+     * M shimmer aesthetic. On by default.
+     */
+    gleam?: boolean;
+    /** Time between gleam sweeps, in seconds (cycle period). */
+    gleamPeriodSec?: number;
+    /** Duration of each sweep in seconds — band traverses left-to-right over this time. Short = quick flash. */
+    gleamSweepSec?: number;
+    /** Band angle in degrees clockwise from vertical (0 = horizontal sweep, 20 = mild diagonal). */
+    gleamAngleDeg?: number;
+    /** Peak alpha of the band (0..1). 0.4 reads as a clear specular highlight against the new peaked-falloff gradient; 0.7+ overwhelms. */
+    gleamPeakAlpha?: number;
+    /** QR adaptation mode. "auto" requires `luminanceBuckets` to be provided. */
+    mode?: QrStampMode;
+    /** Pre-computed luminance series for mode === "auto" — the CLI hook fills this in. */
+    luminanceBuckets?: LuminanceBucket[];
+    /**
+     * Auto-mode adaptive band, low end. Each bucket picks the dark-bg
+     * variant when its avgLuma is at or below the midpoint of
+     * `[adaptiveLowLuma, adaptiveHighLuma]`, otherwise the light-bg
+     * variant. Both knobs stay for backward-compat; today the only
+     * thing the band determines is the midpoint threshold.
+     */
+    adaptiveLowLuma?: number;
+    /** Auto-mode adaptive band, high end. See {@link adaptiveLowLuma}. */
+    adaptiveHighLuma?: number;
+    /**
+     * Crossfade duration in ms for auto-mode variant transitions at
+     * scene boundaries. Smoothstep ramp centered on the boundary,
+     * half-width each side. Default 400ms — short enough to feel
+     * snappy, long enough to avoid a flicker.
+     */
+    crossfadeDurMs?: number;
+    /**
+     * Opacity of the QR's solid background, 0..1. Default 0.92 — subtle
+     * bleed-through that softens the "sticker" look without compromising
+     * scanability (the orange modules + center logo stay fully opaque).
+     * Set to 1 for the classic opaque-sticker look. Ignored for
+     * `mode: "transparent"`.
+     */
+    bgOpacity?: number;
+};
+export declare const QrStampVideo: import("@m0saic/types").MosaicTemplate<QrStampVideoProps, import("@m0saic/types").MosaicTemplateOutputs, import("@m0saic/types").MosaicTemplateUpstreamVariables, import("@m0saic/types").MosaicTemplateUpstreamData, import("@m0saic/types").MosaicTemplateSidecars>;
+export default QrStampVideo;