@softure-ai/marketing-kit 0.1.5 → 0.1.6

package/dist/render/render.js

@@ -3,7 +3,7 @@ import { cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, extname, join } from "node:path";
 import { composeFilm, filmTimes } from "../compose/compose.js";
-import { getGeometry, getLayoutName, rewindFrames } from "../compose/timeline.js";
+import { crossfadeArgs, getGeometry, getLayoutName, getTransitionSeconds, transitionFrames } from "../compose/timeline.js";
 import { runHyperframes } from "./hyperframes.js";
 const require = createRequire(import.meta.url);
 function run(command, args) {
@@ -47,18 +47,18 @@ export function buildComposition(input) {
     mkdirSync(assetsDir, { recursive: true });
     const ff = (args) => run("ffmpeg", ["-v", "error", "-y", ...args]);
     ff(["-framerate", String(log.fps), "-i", join(dir, "frames", "f%05d.jpg"), "-c:v", "libx264", "-preset", "slow", "-crf", "14", "-pix_fmt", "yuv420p", join(assetsDir, "screen.mp4")]);
-    // Rewind: 24 frames from the opening frame back to the start of the scene (0.8 s), with motion blur.
+    // The transition from the opening frame into the scene: stills joined by dissolves (none for a cut).
     const still = log.stills[film.hook.still];
     const firstBeat = log.beats[0];
     if (still === undefined || firstBeat === undefined)
         throw new Error(`The recording of ${film.id} has no opening frame or no sentences: record it again.`);
-    const rewindDir = join(dir, "rewind");
-    rmSync(rewindDir, { recursive: true, force: true });
-    mkdirSync(rewindDir, { recursive: true });
-    rewindFrames(firstBeat.f0, still).forEach((index, k) => {
-        cpSync(getFramePath(dir, index), join(rewindDir, `r${String(k).padStart(5, "0")}.jpg`));
-    });
-    ff(["-framerate", String(log.fps), "-i", join(rewindDir, "r%05d.jpg"), "-vf", "tmix=frames=3", "-c:v", "libx264", "-crf", "16", "-pix_fmt", "yuv420p", join(assetsDir, "rewind.mp4")]);
+    const transitionPath = join(assetsDir, "transition.mp4");
+    rmSync(transitionPath, { force: true });
+    const frames = transitionFrames(film.hook.transition, firstBeat.f0, still);
+    if (frames.length > 0) {
+        const inputs = frames.map((index) => getFramePath(dir, index));
+        ff(crossfadeArgs({ inputs, fps: log.fps, seconds: getTransitionSeconds(film.hook.transition), output: transitionPath }));
+    }
     cpSync(getFramePath(dir, still), join(assetsDir, "hook.jpg"));
     cpSync(getFramePath(dir, log.frames - 1), join(assetsDir, "last.jpg"));
     ff(["-i", input.voiceoverAudio, "-filter:a", `atempo=${film.voice.tempo}`, "-c:a", "libmp3lame", "-q:a", "2", join(assetsDir, "voiceover.mp3")]);
@@ -87,7 +87,7 @@ export function buildComposition(input) {
         fonts,
         assets: {
             screen: "assets/screen.mp4",
-            rewind: "assets/rewind.mp4",
+            transition: frames.length > 0 ? "assets/transition.mp4" : null,
             hookStill: "assets/hook.jpg",
             lastFrame: "assets/last.jpg",
             voiceover: "assets/voiceover.mp3",

package/dist/render/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/render/render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/render/render.ts"],"names":[],"mappings":"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"}

package/dist/voice/cache.d.ts

@@ -4,14 +4,23 @@ export interface VoiceoverPaths {
     key: string;
     audio: string;
     words: string;
+    /** `video`: in the video's own folder; `flat`: `<key>.*` in the cache root, the layout before 0.1.6, still read. */
+    layout: "video" | "flat";
 }
 /** A voiceover on disk: the audio file's path and the timed words. */
 export interface Voiceover {
     audio: string;
     words: TimedWord[];
 }
-/** Where a recording of this input lives in the cache: `<key>.mp3` and `<key>.json`. */
-export declare function getVoiceoverPaths(cacheDir: string, input: TtsInput): VoiceoverPaths;
+/**
+ * Where a recording of this input lives in the cache. With a video id: `<cacheDir>/<video-id>/<key>.mp3|json`, so
+ * a reader sees which film a paid file belongs to; a recording saved flat by an earlier version
+ * (`<cacheDir>/<key>.*`) is still found when the video's folder has none, so no paid file is recorded twice.
+ * Without a video id: the flat layout. The key (text, voice, model, language) is the same in both.
+ */
+export declare function getVoiceoverPaths(cacheDir: string, input: TtsInput, videoId?: string): VoiceoverPaths;
+/** Recordings in the video's folder other than `key`: what an earlier script of the film paid for. Sorted file names. */
+export declare function findStaleVoiceovers(cacheDir: string, videoId: string, key: string): string[];
 /** The cached voiceover, null when either file is missing, or an error naming a broken words file. */
 export declare function readCachedVoiceover(paths: VoiceoverPaths): TtsResult<Voiceover | null>;
 /** Writes a recording in FIRE_TRACKER's format, so files recorded there stay byte-identical. */

package/dist/voice/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/voice/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,cAAc,CAGnF;AAaD,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC,CAUtF;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,GAAG,SAAS,CAK1G"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/voice/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,oHAAoH;IACpH,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CAMrG;AAED,yHAAyH;AACzH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5F;AAaD,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC,CAUtF;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,GAAG,SAAS,CAM1G"}

package/dist/voice/cache.js

@@ -1,11 +1,35 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { err, ok } from "./provider.js";
 import { voiceoverKey } from "./voiceover.js";
-/** Where a recording of this input lives in the cache: `<key>.mp3` and `<key>.json`. */
-export function getVoiceoverPaths(cacheDir, input) {
+function getPathsIn(dir, key, layout) {
+    return { key, audio: join(dir, `${key}.mp3`), words: join(dir, `${key}.json`), layout };
+}
+function hasRecording(paths) {
+    return existsSync(paths.audio) && existsSync(paths.words);
+}
+/**
+ * Where a recording of this input lives in the cache. With a video id: `<cacheDir>/<video-id>/<key>.mp3|json`, so
+ * a reader sees which film a paid file belongs to; a recording saved flat by an earlier version
+ * (`<cacheDir>/<key>.*`) is still found when the video's folder has none, so no paid file is recorded twice.
+ * Without a video id: the flat layout. The key (text, voice, model, language) is the same in both.
+ */
+export function getVoiceoverPaths(cacheDir, input, videoId) {
     const key = voiceoverKey(input.text, input.voiceId, input.model, input.language);
-    return { key, audio: join(cacheDir, `${key}.mp3`), words: join(cacheDir, `${key}.json`) };
+    const flat = getPathsIn(cacheDir, key, "flat");
+    if (videoId === undefined)
+        return flat;
+    const own = getPathsIn(join(cacheDir, videoId), key, "video");
+    return hasRecording(own) || !hasRecording(flat) ? own : flat;
+}
+/** Recordings in the video's folder other than `key`: what an earlier script of the film paid for. Sorted file names. */
+export function findStaleVoiceovers(cacheDir, videoId, key) {
+    const dir = join(cacheDir, videoId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.endsWith(".mp3") && name !== `${key}.mp3`)
+        .sort();
 }
 function isTimedWords(value) {
     return (Array.isArray(value) &&
@@ -34,6 +58,7 @@ export function readCachedVoiceover(paths) {
 /** Writes a recording in FIRE_TRACKER's format, so files recorded there stay byte-identical. */
 export function writeVoiceover(cacheDir, paths, recording) {
     mkdirSync(cacheDir, { recursive: true });
+    mkdirSync(dirname(paths.audio), { recursive: true });
     writeFileSync(paths.audio, recording.audio);
     writeFileSync(paths.words, `${JSON.stringify(recording.words, null, 1)}\n`);
     return { audio: paths.audio, words: recording.words };

package/dist/voice/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/voice/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAoD,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAkB,MAAM,gBAAgB,CAAC;AAc9D,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAe;IACjE,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjF,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACpB,KAAK,CAAC,KAAK,CAAC,CAAC,IAAa,EAAE,EAAE;YAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YAC5D,MAAM,IAAI,GAAG,IAA+B,CAAC;YAC7C,OAAO,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC;QACzG,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,mBAAmB,CAAC,KAAqB;IACvD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1E,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAY,CAAC;IACnE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,eAAe,KAAK,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,gCAAgC,CAAC,CAAC;IACrF,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAqB,EAAE,SAAuB;IAC7F,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5C,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/voice/cache.ts"],"names":[],"mappings":"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"}

package/dist/voice/produce.d.ts

@@ -3,6 +3,8 @@ import { type TtsEstimate, type TtsInput, type TtsProvider, type TtsResult } fro
 export interface ProduceVoiceoverOptions {
     cacheDir: string;
     input: TtsInput;
+    /** The film the voiceover belongs to: its recordings live in `<cacheDir>/<videoId>/`. Without it, the flat layout. */
+    videoId?: string;
     provider: TtsProvider;
     /** Only `true` lets the provider spend money. */
     isCommit: boolean;

package/dist/voice/produce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"produce.d.ts","sourceRoot":"","sources":["../../src/voice/produce.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0D,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACpG,OAAO,EAAW,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3G,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC;IACtB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM,CAErF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAoB7G"}
+{"version":3,"file":"produce.d.ts","sourceRoot":"","sources":["../../src/voice/produce.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+E,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EAAW,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3G,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,sHAAsH;IACtH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,WAAW,CAAC;IACtB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM,CAErF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CA6B7G"}

package/dist/voice/produce.js

@@ -1,4 +1,5 @@
-import { getVoiceoverPaths, readCachedVoiceover, writeVoiceover } from "./cache.js";
+import { dirname, join } from "node:path";
+import { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoiceover } from "./cache.js";
 import { err, ok } from "./provider.js";
 export function describeEstimate(provider, estimate) {
     return `voiceover estimate (${provider.id}): ${estimate.characters} characters, at most ${estimate.maxCost} ${estimate.unit}.`;
@@ -8,13 +9,22 @@ export function describeEstimate(provider, estimate) {
  * run and before every paid call; without `isCommit` the provider is never called.
  */
 export async function produceVoiceover(options) {
-    const { cacheDir, input, provider, isCommit, log } = options;
-    const paths = getVoiceoverPaths(cacheDir, input);
+    const { cacheDir, input, videoId, provider, isCommit, log } = options;
+    const paths = getVoiceoverPaths(cacheDir, input, videoId);
     const cached = readCachedVoiceover(paths);
     if (!cached.ok)
         return cached;
+    if (videoId !== undefined) {
+        const stale = findStaleVoiceovers(cacheDir, videoId, paths.key);
+        if (stale.length > 0) {
+            log(`voiceover: ${join(cacheDir, videoId)} also holds ${stale.join(", ")}, which the current script does not use; delete them once no film needs them.`);
+        }
+    }
     if (cached.value !== null) {
         log(`voiceover: from the cache ${paths.key}, nothing spent.`);
+        if (videoId !== undefined && paths.layout === "flat") {
+            log(`voiceover: ${paths.key}.mp3 and .json sit in the cache root (the layout before 0.1.6); move them into ${join(cacheDir, videoId)}/ to keep them with their film.`);
+        }
         return ok({ kind: "cached", key: paths.key, voiceover: cached.value });
     }
     const estimate = provider.estimate(input);
@@ -27,7 +37,7 @@ export async function produceVoiceover(options) {
     if (!recording.ok)
         return err(recording.error);
     const voiceover = writeVoiceover(cacheDir, paths, recording.value);
-    log(`voiceover: recorded ${estimate.characters} characters, saved ${paths.key}.{mp3,json} in ${cacheDir} (commit them).`);
+    log(`voiceover: recorded ${estimate.characters} characters, saved ${paths.key}.{mp3,json} in ${dirname(paths.audio)} (commit them).`);
     return ok({ kind: "recorded", key: paths.key, voiceover, estimate });
 }
 //# sourceMappingURL=produce.js.map

package/dist/voice/produce.js.map

@@ -1 +1 @@
-{"version":3,"file":"produce.js","sourceRoot":"","sources":["../../src/voice/produce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,cAAc,EAAkB,MAAM,YAAY,CAAC;AACpG,OAAO,EAAE,GAAG,EAAE,EAAE,EAAqE,MAAM,eAAe,CAAC;AAgB3G,MAAM,UAAU,gBAAgB,CAAC,QAAqB,EAAE,QAAqB;IAC3E,OAAO,uBAAuB,QAAQ,CAAC,EAAE,MAAM,QAAQ,CAAC,UAAU,wBAAwB,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC;AACjI,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgC;IACrE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC7D,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,GAAG,CAAC,6BAA6B,KAAK,CAAC,GAAG,kBAAkB,CAAC,CAAC;QAC9D,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,GAAG,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,GAAG,CAAC,4BAA4B,KAAK,CAAC,OAAO,2DAA2D,CAAC,CAAC;QAC1G,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACnD,IAAI,CAAC,SAAS,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACnE,GAAG,CAAC,uBAAuB,QAAQ,CAAC,UAAU,sBAAsB,KAAK,CAAC,GAAG,kBAAkB,QAAQ,iBAAiB,CAAC,CAAC;IAC1H,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;AACvE,CAAC"}
+{"version":3,"file":"produce.js","sourceRoot":"","sources":["../../src/voice/produce.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/marketing-kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "SOFTURE AI marketing kit: a CLI that turns a project's real app into a vertical film (cached voiceover, frame-by-frame recording, HTML composition, hyperframes render) plus per-platform post copy and OG images.",
   "license": "MIT",
   "type": "module",

package/schema/marketing.schema.json

@@ -2374,6 +2374,16 @@
                   "additionalProperties": false
                 },
                 "description": "Camera moves over the opening frame, at least one."
+              },
+              "transition": {
+                "default": "fade",
+                "description": "How the opening frame hands over to the scene: fade (a 0.8 s cross-fade), rewind (0.8 s back through the scene in five dissolving frames) or cut.",
+                "type": "string",
+                "enum": [
+                  "fade",
+                  "rewind",
+                  "cut"
+                ]
               }
             },
             "required": [
@@ -2383,6 +2393,11 @@
             "additionalProperties": false,
             "description": "The opening: the result frame the first sentence plays over."
           },
+          "today": {
+            "description": "The day the app is recorded as of (YYYY-MM-DD): pin it once the voiceover is paid for, so the numbers it says still match the screen in a later month. --today overrides it; without either, the day of the run.",
+            "type": "string",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+          },
           "screenGuard": {
             "minItems": 1,
             "type": "array",

package/src/cli/main.ts

@@ -16,7 +16,7 @@ import { splitIntoBeats } from "../voice/voiceover.js";
 import { CliFailure, fail } from "./failure.js";
 import { loadFilm, type LoadedFilm } from "./films.js";
 import { writeOgImages } from "./og.js";
-import { readOptions, type FilmOptions, type ShotsOptions } from "./options.js";
+import { getRecordingDay, readOptions, type FilmOptions, type ShotsOptions } from "./options.js";
 import { ensureServer } from "./server.js";
 import { getVoiceoverPaths, produceVoiceover, readJson, requireVoiceover } from "./voice.js";
 
@@ -25,7 +25,7 @@ import { getVoiceoverPaths, produceVoiceover, readJson, requireVoiceover } from
  *
  *   all <film>                 voiceover from the cache -> recording -> render -> post copy
  *   voice <film> [--commit]    voiceover (paid only with --commit)
- *   record <film> [--today=YYYY-MM-DD] [--url=...]
+ *   record <film> [--today=YYYY-MM-DD] [--url=...]   (--today overrides the video's today)
  *   render <film> [--quality=draft|standard|high]
  *   preview <film>
  *   posts <film>
@@ -48,16 +48,17 @@ async function record(config: MarketingConfig, film: LoadedFilm, options: FilmOp
   const voices = splitIntoBeats(voiceover.words, film.beats, film.voice.tempo);
   const server = await ensureServer(config, film, options.url);
   mkdirSync(getBuildDir(config, film), { recursive: true });
+  const recordingDay = getRecordingDay(options.today, film.today);
   let log: RecordingLog;
   try {
-    console.log(`recording: ${server.url} frame by frame; this takes a few minutes.`);
+    console.log(`recording: ${server.url} frame by frame, the app as of ${recordingDay.day ?? "today"} (${recordingDay.source}); this takes a few minutes.`);
     log = await recordFilm({
       film,
       url: server.url,
       outDir: getBuildDir(config, film),
       voices,
       voiceoverKey: getVoiceoverPaths(config, film).key,
-      today: options.today,
+      today: recordingDay.day ?? undefined,
       filmPath: film.scenePath,
       executablePath: process.env.PLAYWRIGHT_CHROMIUM_PATH || undefined,
       browser: {

package/src/cli/options.ts

@@ -1,3 +1,4 @@
+import { isCalendarDay } from "../config/day.js";
 import { DEFAULT_CONFIG_FILE, QUALITIES, type Quality } from "../config/schema.js";
 
 /**
@@ -20,7 +21,7 @@ export interface FilmOptions {
   filmId: string;
   /** `voice` really pays for the voiceover only with `--commit`. */
   isCommit: boolean;
-  /** The day the app counts from, only to reproduce an old film. */
+  /** The day the app counts from; overrides the video's `today` for one run. */
   today?: string;
   /** Another address of the recorded page. */
   url?: string;
@@ -56,7 +57,7 @@ export const USAGE = [
   "",
   "  all <film>                      voiceover from the cache -> recording -> render -> post copy",
   "  voice <film> [--commit]         voiceover; without --commit it only counts the characters",
-  "  record <film> [--today=YYYY-MM-DD] [--url=...]",
+  "  record <film> [--today=YYYY-MM-DD] [--url=...]   --today overrides the video's \"today\"",
   "  render <film> [--quality=draft|standard|high]",
   "  preview <film>                  open the composition in the hyperframes preview",
   "  posts <film>                    post copy for the configured platforms",
@@ -100,7 +101,7 @@ export function readOptions(argv: string[]): ReadOptionsResult {
   if (positional.length > 1) return { ok: false, error: `one film at a time, got ${positional.join(", ")}.` };
   if (!FILM_ID.test(filmId)) return { ok: false, error: `film name "${filmId}": lowercase letters, digits and hyphens only.` };
   const today = flags.get("today");
-  if (today !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(today)) return { ok: false, error: `--today=${today}: expected YYYY-MM-DD.` };
+  if (today !== undefined && !isCalendarDay(today)) return { ok: false, error: `--today=${today}: expected a real day as YYYY-MM-DD.` };
   const quality = flags.get("quality");
   if (quality !== undefined && !isQuality(quality)) return { ok: false, error: `--quality=${quality}: expected ${QUALITIES.join(" | ")}.` };
   const commit = flags.get("commit");
@@ -141,3 +142,13 @@ function readShotsOptions(positional: string[], flags: Map<string, string>, conf
   if (url !== undefined && !isHttpAddress(url)) return { ok: false, error: `--url=${url}: expected an address such as http://localhost:3000.` };
   return { ok: true, options: { command: "shots", shotId, url, configPath } };
 }
+
+/** The day a recording starts its page clock at, and where it came from. */
+export type RecordingDay = { day: string; source: "--today" | "videos[].today" } | { day: null; source: "the day of the run" };
+
+/** `--today` wins over the video's `today`; without either, the page clock starts now. */
+export function getRecordingDay(flag: string | undefined, configured: string | null): RecordingDay {
+  if (flag !== undefined) return { day: flag, source: "--today" };
+  if (configured !== null) return { day: configured, source: "videos[].today" };
+  return { day: null, source: "the day of the run" };
+}

package/src/cli/voice.ts

@@ -16,7 +16,7 @@ function getTtsInput(film: Film): TtsInput {
 }
 
 export function getVoiceoverPaths(config: MarketingConfig, film: Film): VoiceoverPaths {
-  return getCachePaths(config.voice.cacheDir, getTtsInput(film));
+  return getCachePaths(config.voice.cacheDir, getTtsInput(film), film.id);
 }
 
 /** JSON from disk with the file name in the error, not a bare "Unexpected token". */
@@ -43,6 +43,7 @@ export async function produceVoiceover(config: MarketingConfig, film: Film, isCo
   const result = await produce({
     cacheDir: config.voice.cacheDir,
     input: getTtsInput(film),
+    videoId: film.id,
     provider: createTtsProvider(config.voice.provider, { env: process.env }),
     isCommit,
     log: (line) => console.log(line),

package/src/compose/compose.ts

@@ -3,13 +3,13 @@ import type { SfxEvent } from "../config/schema.js";
 import type { Film } from "../film.js";
 import { formatMessage, type MarketingMessages } from "../messages/index.js";
 import type { RecordingLog } from "../record/record.js";
-import { BROWSER_BAR_HEIGHT, cameraPose, captionChunks, widePose, type CameraPose, type Geometry } from "./timeline.js";
+import { BROWSER_BAR_HEIGHT, cameraPose, captionChunks, getTransitionSeconds, widePose, type CameraPose, type Geometry } from "./timeline.js";
 import type { BeatVoice } from "../voice/voiceover.js";
 
 /**
  * HyperFrames composition from the recording: the phone (or, for a desktop recording, a browser window) with the real screen, a camera that follows
  * the thumb, a touch marker, captions in one place, the persona card, an opening from the result
- * frame with a rewind, the end card and sounds.
+ * frame with its transition into the scene (fade, rewind or cut), the end card and sounds.
  *
  * HyperFrames 0.8.85 contract: a root with `data-composition-id`, clips with
  * `data-start`/`data-duration`, `<audio>` with an `id`, a GSAP timeline `{ paused: true }` under
@@ -21,15 +21,14 @@ const COMPOSITION_ID = "film";
 /** Pause before the first word of the opening. */
 const HOOK_LEAD = 0.3;
 const HOOK_MIN = 3.8;
-const REWIND = 0.8;
 const END_TAIL = 1.6;
 /** The end card enters this long after the start of the last sentence. */
 const END_CARD_DELAY = 0.9;
 
 export interface ComposeAssets {
-  /** Screen recording (mp4 from frames), the rewind clip, the opening frame, the last frame, the tempo-shifted voiceover. */
+  /** Screen recording (mp4 from frames), the transition clip (null for a cut), the opening frame, the last frame, the tempo-shifted voiceover. */
   screen: string;
-  rewind: string;
+  transition: string | null;
   hookStill: string;
   lastFrame: string;
   voiceover: string;
@@ -186,7 +185,8 @@ export function filmTimes(film: Film, log: RecordingLog, voices: BeatVoice[]) {
   const last = log.beats.at(-1);
   if (firstBeat === undefined || last === undefined) throw new Error("The recording has no sentences: record the film again (softure-marketing record).");
   const firstFrame = firstBeat.f0;
-  const offset = hook + REWIND - firstFrame / log.fps;
+  const transition = getTransitionSeconds(film.hook.transition);
+  const offset = hook + transition - firstFrame / log.fps;
   const at = (frame: number): number => r3(frame / log.fps + offset);
   const lastVoice = voice.get(last.id);
   if (lastVoice === undefined) throw new Error(`No voiceover for sentence "${last.id}".`);
@@ -198,7 +198,7 @@ export function filmTimes(film: Film, log: RecordingLog, voices: BeatVoice[]) {
   if (unplaced.length > 0) {
     throw new Error(`The recording has no sentences ${unplaced.join(", ")}: record the film again (softure-marketing record).`);
   }
-  return { hook, rewind: REWIND, firstFrame, at, endCard, end, screenEnd: at(log.frames), voiceStart };
+  return { hook, transition, firstFrame, at, endCard, end, screenEnd: at(log.frames), voiceStart };
 }
 
 export function composeFilm(input: ComposeInput): string {
@@ -314,7 +314,7 @@ export function composeFilm(input: ComposeInput): string {
     .join("\n  ");
 
   const personaOut = log.cues.find((cue) => cue.name === "persona-out");
-  const screenStart = r3(times.hook + times.rewind);
+  const screenStart = r3(times.hook + times.transition);
   const screenDuration = r3(times.screenEnd - screenStart);
   const tail = r3(Math.max(0.04, times.end - times.screenEnd));
   const c = colors;
@@ -375,7 +375,7 @@ ${windowParts.css}
     ${windowParts.open}
       <div class="screen">
         <img id="hook" class="clip" src="${assets.hookStill}" data-start="0" data-duration="${times.hook}" />
-        <video id="rewind" class="clip" src="${assets.rewind}" data-start="${times.hook}" data-duration="${times.rewind}" muted playsinline></video>
+        ${assets.transition === null || times.transition === 0 ? "" : `<video id="transition" class="clip" src="${assets.transition}" data-start="${times.hook}" data-duration="${times.transition}" muted playsinline></video>`}
         <video id="recording" class="clip" src="${assets.screen}" data-start="${screenStart}" data-media-start="${r3(times.firstFrame / log.fps)}" data-duration="${screenDuration}" muted playsinline></video>
         <img id="last" class="clip" src="${assets.lastFrame}" data-start="${times.screenEnd}" data-duration="${tail}" />
         ${taps.map((tap) => `<div class="touch" style="left:${tap.x}px;top:${tap.y}px"><div class="dot" id="td${tap.i}"></div><div class="ring" id="tr${tap.i}"></div></div>`).join("\n        ")}

package/src/compose/timeline.ts

@@ -327,3 +327,58 @@ export function rewindFrames(first: number, still: number, count = 24): number[]
   if (count < 2) throw new Error("A rewind needs at least two frames.");
   return Array.from({ length: count }, (_, k) => Math.round(still - ((still - first) * k) / (count - 1)));
 }
+
+/** How the opening frame hands over to the scene: a cross-fade, a rewind through the scene, or a hard cut. */
+export const TRANSITIONS = ["fade", "rewind", "cut"] as const;
+
+export type Transition = (typeof TRANSITIONS)[number];
+
+const TRANSITION_SECONDS = 0.8;
+/** Key frames of a rewind: few enough that each screen reads, joined by dissolves (24 blended frames flickered in FIRE). */
+const REWIND_KEY_FRAMES = 5;
+/** One dissolve between two key frames of a rewind. */
+const REWIND_DISSOLVE = 0.2;
+
+export function getTransitionSeconds(transition: Transition): number {
+  return transition === "cut" ? 0 : TRANSITION_SECONDS;
+}
+
+/** The recording frames the transition clip is made of, from the opening frame (`still`) to the scene's first (`first`). */
+export function transitionFrames(transition: Transition, first: number, still: number): number[] {
+  if (still < first) throw new Error(`The opening frame (${still}) is before the start of the scene (${first}).`);
+  if (transition === "cut") return [];
+  if (transition === "fade") return [still, first];
+  return rewindFrames(first, still, REWIND_KEY_FRAMES);
+}
+
+export interface CrossfadeInput {
+  /** Still images in order, at least two. */
+  inputs: string[];
+  fps: number;
+  /** The clip's length. */
+  seconds: number;
+  output: string;
+}
+
+const r3 = (value: number) => Math.round(value * 1000) / 1000;
+
+/**
+ * ffmpeg arguments of a clip that dissolves from still to still and lasts exactly `seconds`. Two stills fade over
+ * the whole clip; more are joined by `REWIND_DISSOLVE` dissolves, each still shown for the same time.
+ */
+export function crossfadeArgs(input: CrossfadeInput): string[] {
+  const { inputs, fps, seconds, output } = input;
+  const count = inputs.length;
+  if (count < 2) throw new Error(`A cross-fade needs at least two stills, got ${count}.`);
+  const dissolve = count === 2 ? seconds : REWIND_DISSOLVE;
+  // count × each - (count - 1) × dissolve = seconds
+  const each = r3((seconds + (count - 1) * dissolve) / count);
+  const step = r3(each - dissolve);
+  const sources = inputs.flatMap((path) => ["-loop", "1", "-framerate", String(fps), "-t", String(each), "-i", path]);
+  const filters = inputs.slice(1).map((_, k) => {
+    const from = k === 0 ? "[0:v]" : `[v${k}]`;
+    const last = k === count - 2 ? ",format=yuv420p" : "";
+    return `${from}[${k + 1}:v]xfade=transition=fade:duration=${dissolve}:offset=${r3((k + 1) * step)}${last}[v${k + 1}]`;
+  });
+  return [...sources, "-filter_complex", filters.join(";"), "-map", `[v${count - 1}]`, "-t", String(seconds), "-r", String(fps), "-c:v", "libx264", "-crf", "16", "-pix_fmt", "yuv420p", output];
+}

package/src/config/config.ts

@@ -67,6 +67,8 @@ export interface VideoConfig extends FilmScript {
   sceneSource: SceneSource;
   /** The post copy, or null when `social.posts` has no entry for this video. */
   post: VideoPost | null;
+  /** `videos[].today`: the day the app is recorded as of, or null for the day of the run. */
+  today: string | null;
 }
 
 export interface MarketingConfig {
@@ -143,6 +145,7 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
       beats: video.beats.map((beat) => ({ id: beat.id, text: beat.text })),
       hook: video.hook,
       screenGuard: video.screenGuard,
+      today: video.today ?? null,
       endCard: video.endCard,
       url: new URL(video.path, data.app.baseUrl).href,
       ownUrl: `http://localhost:${data.app.port}${video.path}`,

package/src/config/day.ts

@@ -0,0 +1,9 @@
+/** A day as `YYYY-MM-DD`, the form of `--today` and `videos[].today`. */
+export const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/** True for a `YYYY-MM-DD` that names a real calendar day (not 2026-02-30): the page clock would start at Invalid Date. */
+export function isCalendarDay(value: string): boolean {
+  if (!DAY_PATTERN.test(value)) return false;
+  const date = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
+}

package/src/config/schema.ts

@@ -5,6 +5,7 @@ import {
   LAYOUTS,
   LAYOUT_NAMES,
   MIN_DESKTOP_WIDTH,
+  TRANSITIONS,
   VIDEO_FORMATS,
   fitsFrame,
   isDesktopViewport,
@@ -17,6 +18,7 @@ import { CHANNEL_CODE_MAX_LENGTH, CHANNEL_CODE_PATTERN, DEFAULT_LINK_IN_BIO, PLA
 import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
 import { actionSchema, type SceneAction } from "./actions-schema.js";
 import { COLOR_ROLES, COLOR_THEMES, isHexColor, type ColorRole } from "./colors.js";
+import { DAY_PATTERN, isCalendarDay } from "./day.js";
 import { getScreenshotNames } from "./screenshot-names.js";
 
 /**
@@ -241,7 +243,7 @@ type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?:
 
 interface SceneShape {
   beats: VideoBeat[];
-  hook: { still: string; shots: { mark: string }[] };
+  hook: { still: string; shots: { mark: string }[]; transition: string };
   sceneModule?: string | undefined;
 }
 
@@ -346,8 +348,20 @@ const videoSchema = z
           )
           .min(1, "the opening needs at least one shot")
           .describe("Camera moves over the opening frame, at least one."),
+        transition: z
+          .enum(TRANSITIONS)
+          .default("fade")
+          .describe("How the opening frame hands over to the scene: fade (a 0.8 s cross-fade), rewind (0.8 s back through the scene in five dissolving frames) or cut."),
       })
       .describe("The opening: the result frame the first sentence plays over."),
+    today: z
+      .string()
+      .regex(DAY_PATTERN, "must be a day as YYYY-MM-DD")
+      .refine(isCalendarDay, "is not a day of the calendar")
+      .optional()
+      .describe(
+        "The day the app is recorded as of (YYYY-MM-DD): pin it once the voiceover is paid for, so the numbers it says still match the screen in a later month. --today overrides it; without either, the day of the run.",
+      ),
     screenGuard: z
       .array(nonBlank)
       .min(1, "the screen guard needs at least one phrase")

package/src/film.ts

@@ -1,6 +1,6 @@
 import type { Locator, Page } from "playwright";
 
-import type { LayoutOverride, VideoFormat, Viewport } from "./compose/timeline.js";
+import type { LayoutOverride, Transition, VideoFormat, Viewport } from "./compose/timeline.js";
 
 /**
  * Film = script (data from `marketing.json`) + scene: the beats' `actions` in the same file
@@ -86,7 +86,8 @@ export interface FilmScript {
    * scene records the rest, and the **last** ends with the end card.
    */
   beats: Beat[];
-  hook: { still: string; shots: HookShot[] };
+  /** The opening: its still, the camera shots over it, and how it hands over to the scene. */
+  hook: { still: string; shots: HookShot[]; transition: Transition };
   /**
    * Phrases the voiceover says that the app's screen must show. If any is missing the recording
    * stops and the render never starts.