@softure-ai/marketing-kit 0.1.5 → 0.1.6

package/src/index.ts

@@ -83,7 +83,7 @@ export type { TtsEstimate, TtsInput, TtsProvider, TtsRecording, TtsResult } from
 export { ELEVENLABS_API_KEY_ENV, ELEVENLABS_PROVIDER_ID, createElevenLabsProvider, type ElevenLabsOptions } from "./voice/elevenlabs.js";
 export { createFakeTtsProvider, type FakeTtsOptions, type FakeTtsProvider } from "./voice/fake.js";
 export { createTtsProvider, type CreateTtsProviderOptions, type TtsProviderId } from "./voice/providers.js";
-export { getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover, type VoiceoverPaths } from "./voice/cache.js";
+export { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover, type VoiceoverPaths } from "./voice/cache.js";
 export { describeEstimate, produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./voice/produce.js";
 export {
   BROWSER_BAR_HEIGHT,
@@ -91,21 +91,26 @@ export {
   LAYOUTS,
   LAYOUT_NAMES,
   MIN_DESKTOP_WIDTH,
+  TRANSITIONS,
   VIDEO_FORMATS,
   cameraPose,
   captionChunks,
+  crossfadeArgs,
   fitScale,
   fitsFrame,
   getGeometry,
   getLayoutName,
+  getTransitionSeconds,
   isDesktopViewport,
   resolveLayout,
   rewindFrames,
+  transitionFrames,
   unionRect,
   widePose,
   type CameraPose,
   type CaptionChunk,
   type CaptionLayout,
+  type CrossfadeInput,
   type DeviceKind,
   type EndCardLayout,
   type Geometry,
@@ -114,6 +119,7 @@ export {
   type LayoutOverride,
   type Point,
   type Rect,
+  type Transition,
   type TextBox,
   type VideoFormat,
   type Viewport,

package/src/record/record.ts

@@ -60,7 +60,7 @@ export interface RecordOptions {
   outDir: string;
   voices: BeatVoice[];
   voiceoverKey: string;
-  /** The day the app counts from: today by default; another day only to reproduce an old film. */
+  /** The day the app counts from (`--today` or the video's `today`); the day of the run without one. */
   today?: string;
   /** The file that holds the scene (its module, or marketing.json for actions), named in errors that ask for a scene fix. */
   filmPath: string;
@@ -346,8 +346,8 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
         if (missing.length > 0) {
           throw new ScreenGuardError(
             `The screen does not say what the voiceover says: missing ${missing.map((p) => `"${p}"`).join(", ")}. ` +
-              `The app counts from the recording day, so fix the sentences and phrases in ${filmPath}. ` +
-              `--today=YYYY-MM-DD only reproduces an old film; it is not a way around this refusal.`,
+              `The app counts from the recording day: if the voiceover was paid for on another day, pin that day in the video's ` +
+              `"today" (or pass --today=YYYY-MM-DD); otherwise fix the sentences and phrases in ${filmPath}.`,
           );
         }
         guardChecked = true;

package/src/render/render.ts

@@ -4,7 +4,7 @@ import { createRequire } from "node:module";
 import { dirname, extname, join } from "node:path";
 
 import { composeFilm, filmTimes, type ComposeFont } from "../compose/compose.js";
-import { getGeometry, getLayoutName, rewindFrames } from "../compose/timeline.js";
+import { crossfadeArgs, getGeometry, getLayoutName, getTransitionSeconds, transitionFrames } from "../compose/timeline.js";
 import type { BrandColors } from "../config/colors.js";
 import type { BrandFont } from "../config/config.js";
 import type { SfxEvent } from "../config/schema.js";
@@ -79,17 +79,17 @@ export function buildComposition(input: RenderInput): string {
 
   const ff = (args: string[]) => 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")]);
@@ -120,7 +120,7 @@ export function buildComposition(input: RenderInput): string {
       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/src/voice/cache.ts

@@ -1,5 +1,5 @@
-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, type TtsInput, type TtsRecording, type TtsResult } from "./provider.js";
 import { voiceoverKey, type TimedWord } from "./voiceover.js";
@@ -8,6 +8,8 @@ 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. */
@@ -16,10 +18,35 @@ export interface Voiceover {
   words: TimedWord[];
 }
 
-/** Where a recording of this input lives in the cache: `<key>.mp3` and `<key>.json`. */
-export function getVoiceoverPaths(cacheDir: string, input: TtsInput): VoiceoverPaths {
+function getPathsIn(dir: string, key: string, layout: VoiceoverPaths["layout"]): VoiceoverPaths {
+  return { key, audio: join(dir, `${key}.mp3`), words: join(dir, `${key}.json`), layout };
+}
+
+function hasRecording(paths: VoiceoverPaths): boolean {
+  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: string, input: TtsInput, videoId?: string): VoiceoverPaths {
   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: string, videoId: string, key: string): string[] {
+  const dir = join(cacheDir, videoId);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".mp3") && name !== `${key}.mp3`)
+    .sort();
 }
 
 function isTimedWords(value: unknown): value is TimedWord[] {
@@ -49,6 +76,7 @@ export function readCachedVoiceover(paths: VoiceoverPaths): TtsResult<Voiceover
 /** Writes a recording in FIRE_TRACKER's format, so files recorded there stay byte-identical. */
 export function writeVoiceover(cacheDir: string, paths: VoiceoverPaths, recording: TtsRecording): Voiceover {
   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/src/voice/produce.ts

@@ -1,9 +1,13 @@
-import { getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover } from "./cache.js";
+import { dirname, join } from "node:path";
+
+import { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover } from "./cache.js";
 import { err, ok, type TtsEstimate, type TtsInput, type TtsProvider, type TtsResult } from "./provider.js";
 
 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;
@@ -24,12 +28,21 @@ export function describeEstimate(provider: TtsProvider, estimate: TtsEstimate):
  * run and before every paid call; without `isCommit` the provider is never called.
  */
 export async function produceVoiceover(options: ProduceVoiceoverOptions): Promise<TtsResult<VoiceoverOutcome>> {
-  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);
@@ -41,6 +54,6 @@ export async function produceVoiceover(options: ProduceVoiceoverOptions): Promis
   const recording = await provider.synthesize(input);
   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 });
 }