@softure-ai/marketing-kit 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/README.md +49 -12
  2. package/dist/cli/main.js +15 -9
  3. package/dist/cli/main.js.map +1 -1
  4. package/dist/cli/options.d.ts +14 -1
  5. package/dist/cli/options.d.ts.map +1 -1
  6. package/dist/cli/options.js +22 -9
  7. package/dist/cli/options.js.map +1 -1
  8. package/dist/cli/voice.d.ts +5 -0
  9. package/dist/cli/voice.d.ts.map +1 -1
  10. package/dist/cli/voice.js +28 -8
  11. package/dist/cli/voice.js.map +1 -1
  12. package/dist/compose/compose.d.ts +3 -3
  13. package/dist/compose/compose.d.ts.map +1 -1
  14. package/dist/compose/compose.js +7 -7
  15. package/dist/compose/compose.js.map +1 -1
  16. package/dist/compose/timeline.d.ts +19 -0
  17. package/dist/compose/timeline.d.ts.map +1 -1
  18. package/dist/compose/timeline.js +42 -0
  19. package/dist/compose/timeline.js.map +1 -1
  20. package/dist/config/config.d.ts +5 -0
  21. package/dist/config/config.d.ts.map +1 -1
  22. package/dist/config/config.js +3 -1
  23. package/dist/config/config.js.map +1 -1
  24. package/dist/config/day.d.ts +5 -0
  25. package/dist/config/day.d.ts.map +1 -0
  26. package/dist/config/day.js +10 -0
  27. package/dist/config/day.js.map +1 -0
  28. package/dist/config/schema.d.ts +9 -0
  29. package/dist/config/schema.d.ts.map +1 -1
  30. package/dist/config/schema.js +22 -1
  31. package/dist/config/schema.js.map +1 -1
  32. package/dist/film.d.ts +3 -1
  33. package/dist/film.d.ts.map +1 -1
  34. package/dist/film.js.map +1 -1
  35. package/dist/index.d.ts +5 -3
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +5 -3
  38. package/dist/index.js.map +1 -1
  39. package/dist/posts/posts.d.ts +2 -1
  40. package/dist/posts/posts.d.ts.map +1 -1
  41. package/dist/posts/posts.js +1 -1
  42. package/dist/posts/posts.js.map +1 -1
  43. package/dist/record/record.d.ts +1 -1
  44. package/dist/record/record.d.ts.map +1 -1
  45. package/dist/record/record.js +2 -2
  46. package/dist/record/record.js.map +1 -1
  47. package/dist/render/render.js +10 -10
  48. package/dist/render/render.js.map +1 -1
  49. package/dist/voice/batch.d.ts +28 -0
  50. package/dist/voice/batch.d.ts.map +1 -0
  51. package/dist/voice/batch.js +46 -0
  52. package/dist/voice/batch.js.map +1 -0
  53. package/dist/voice/cache.d.ts +11 -2
  54. package/dist/voice/cache.d.ts.map +1 -1
  55. package/dist/voice/cache.js +30 -5
  56. package/dist/voice/cache.js.map +1 -1
  57. package/dist/voice/elevenlabs.d.ts.map +1 -1
  58. package/dist/voice/elevenlabs.js +11 -1
  59. package/dist/voice/elevenlabs.js.map +1 -1
  60. package/dist/voice/pace.d.ts +22 -0
  61. package/dist/voice/pace.d.ts.map +1 -0
  62. package/dist/voice/pace.js +39 -0
  63. package/dist/voice/pace.js.map +1 -0
  64. package/dist/voice/produce.d.ts +8 -0
  65. package/dist/voice/produce.d.ts.map +1 -1
  66. package/dist/voice/produce.js +26 -5
  67. package/dist/voice/produce.js.map +1 -1
  68. package/dist/voice/provider.d.ts +2 -0
  69. package/dist/voice/provider.d.ts.map +1 -1
  70. package/dist/voice/provider.js.map +1 -1
  71. package/package.json +1 -1
  72. package/schema/marketing.schema.json +31 -0
  73. package/src/cli/main.ts +14 -9
  74. package/src/cli/options.ts +24 -7
  75. package/src/cli/voice.ts +28 -9
  76. package/src/compose/compose.ts +9 -9
  77. package/src/compose/timeline.ts +55 -0
  78. package/src/config/config.ts +9 -2
  79. package/src/config/day.ts +9 -0
  80. package/src/config/schema.ts +25 -1
  81. package/src/film.ts +3 -2
  82. package/src/index.ts +10 -2
  83. package/src/posts/posts.ts +3 -2
  84. package/src/record/record.ts +3 -3
  85. package/src/render/render.ts +10 -10
  86. package/src/voice/batch.ts +65 -0
  87. package/src/voice/cache.ts +33 -5
  88. package/src/voice/elevenlabs.ts +11 -1
  89. package/src/voice/pace.ts +55 -0
  90. package/src/voice/produce.ts +31 -6
  91. package/src/voice/provider.ts +2 -0
@@ -41,6 +41,8 @@ export interface PlatformChannel {
41
41
 
42
42
  export interface VideoPost {
43
43
  caption: string;
44
+ /** `social.disclosure` with the persona's name; null or absent when none is configured or the post opts out. */
45
+ disclosure?: string | null;
44
46
  hashtags: string[];
45
47
  /** The configured platforms in `PLATFORMS` order, with this video's codes. */
46
48
  channels: PlatformChannel[];
@@ -67,6 +69,8 @@ export interface VideoConfig extends FilmScript {
67
69
  sceneSource: SceneSource;
68
70
  /** The post copy, or null when `social.posts` has no entry for this video. */
69
71
  post: VideoPost | null;
72
+ /** `videos[].today`: the day the app is recorded as of, or null for the day of the run. */
73
+ today: string | null;
70
74
  }
71
75
 
72
76
  export interface MarketingConfig {
@@ -92,7 +96,7 @@ export interface MarketingConfig {
92
96
  hideSelectors: string[];
93
97
  screenGuardSelector: string;
94
98
  };
95
- voice: { provider: "elevenlabs"; cacheDir: string };
99
+ voice: { provider: "elevenlabs"; cacheDir: string; minIntervalSeconds: number };
96
100
  videos: VideoConfig[];
97
101
  social: { linkTemplate: string } | null;
98
102
  screenshots: MarketingJson["screenshots"];
@@ -143,6 +147,7 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
143
147
  beats: video.beats.map((beat) => ({ id: beat.id, text: beat.text })),
144
148
  hook: video.hook,
145
149
  screenGuard: video.screenGuard,
150
+ today: video.today ?? null,
146
151
  endCard: video.endCard,
147
152
  url: new URL(video.path, data.app.baseUrl).href,
148
153
  ownUrl: `http://localhost:${data.app.port}${video.path}`,
@@ -159,6 +164,8 @@ function resolveVideos(data: MarketingJson, at: (relative: string) => string): V
159
164
  ? null
160
165
  : {
161
166
  caption: post.caption,
167
+ disclosure:
168
+ post.disclosure && data.social?.disclosure !== undefined ? data.social.disclosure.replaceAll("{persona}", video.persona.name).trim() : null,
162
169
  hashtags: post.hashtags,
163
170
  channels: PLATFORMS.flatMap((platform) => {
164
171
  const channel = platforms[platform];
@@ -215,7 +222,7 @@ export function loadMarketingConfig(path: string): LoadConfigResult {
215
222
  hideSelectors: data.app.hideSelectors,
216
223
  screenGuardSelector: data.app.screenGuardSelector,
217
224
  },
218
- voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir) },
225
+ voice: { provider: data.voice.provider, cacheDir: at(data.voice.cacheDir), minIntervalSeconds: data.voice.minIntervalSeconds },
219
226
  videos: resolveVideos(data, at),
220
227
  social: data.social === undefined ? null : { linkTemplate: data.social.linkTemplate },
221
228
  screenshots: data.screenshots,
@@ -0,0 +1,9 @@
1
+ /** A day as `YYYY-MM-DD`, the form of `--today` and `videos[].today`. */
2
+ export const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
3
+
4
+ /** True for a `YYYY-MM-DD` that names a real calendar day (not 2026-02-30): the page clock would start at Invalid Date. */
5
+ export function isCalendarDay(value: string): boolean {
6
+ if (!DAY_PATTERN.test(value)) return false;
7
+ const date = new Date(`${value}T00:00:00Z`);
8
+ return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
9
+ }
@@ -5,6 +5,7 @@ import {
5
5
  LAYOUTS,
6
6
  LAYOUT_NAMES,
7
7
  MIN_DESKTOP_WIDTH,
8
+ TRANSITIONS,
8
9
  VIDEO_FORMATS,
9
10
  fitsFrame,
10
11
  isDesktopViewport,
@@ -17,6 +18,7 @@ import { CHANNEL_CODE_MAX_LENGTH, CHANNEL_CODE_PATTERN, DEFAULT_LINK_IN_BIO, PLA
17
18
  import { ELEVENLABS_DEFAULT_MODEL } from "../voice/voiceover.js";
18
19
  import { actionSchema, type SceneAction } from "./actions-schema.js";
19
20
  import { COLOR_ROLES, COLOR_THEMES, isHexColor, type ColorRole } from "./colors.js";
21
+ import { DAY_PATTERN, isCalendarDay } from "./day.js";
20
22
  import { getScreenshotNames } from "./screenshot-names.js";
21
23
 
22
24
  /**
@@ -234,6 +236,12 @@ const voiceSchema = z.strictObject({
234
236
  .regex(LANGUAGE_PATTERN, "must be an ISO 639 language code such as en")
235
237
  .describe("ISO 639 code the voice speaks (en, pl); part of the voiceover cache key."),
236
238
  tempo: tempo.default(1).describe("Speed-up (0.8-1.3) applied at build time, not in the API, so the paid cache stays valid."),
239
+ minIntervalSeconds: z
240
+ .number()
241
+ .min(0)
242
+ .max(3600)
243
+ .default(60)
244
+ .describe("Least seconds between two paid recordings (0-3600, default 60; 0 turns it off), counted from the newest file in cacheDir, so separate runs are spaced too."),
237
245
  cacheDir: relativePath.default("marketing/voiceover").describe("The paid voiceover cache (<key>.mp3 and <key>.json), relative to the folder of marketing.json; commit it."),
238
246
  });
239
247
 
@@ -241,7 +249,7 @@ type VideoBeat = { id: string; text: string; pad?: number | undefined; actions?:
241
249
 
242
250
  interface SceneShape {
243
251
  beats: VideoBeat[];
244
- hook: { still: string; shots: { mark: string }[] };
252
+ hook: { still: string; shots: { mark: string }[]; transition: string };
245
253
  sceneModule?: string | undefined;
246
254
  }
247
255
 
@@ -346,8 +354,20 @@ const videoSchema = z
346
354
  )
347
355
  .min(1, "the opening needs at least one shot")
348
356
  .describe("Camera moves over the opening frame, at least one."),
357
+ transition: z
358
+ .enum(TRANSITIONS)
359
+ .default("fade")
360
+ .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."),
349
361
  })
350
362
  .describe("The opening: the result frame the first sentence plays over."),
363
+ today: z
364
+ .string()
365
+ .regex(DAY_PATTERN, "must be a day as YYYY-MM-DD")
366
+ .refine(isCalendarDay, "is not a day of the calendar")
367
+ .optional()
368
+ .describe(
369
+ "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.",
370
+ ),
351
371
  screenGuard: z
352
372
  .array(nonBlank)
353
373
  .min(1, "the screen guard needs at least one phrase")
@@ -411,6 +431,7 @@ const socialSchema = z.strictObject({
411
431
  video: id.describe("The id of the film in videos this post is for."),
412
432
  caption: z.string().describe("The post's text."),
413
433
  hashtags: z.array(z.string()).default([]).describe("Hashtags appended to the caption."),
434
+ disclosure: z.boolean().default(true).describe("Whether social.disclosure follows this post's caption (default true)."),
414
435
  codes: z
415
436
  .partialRecord(z.enum(PLATFORMS), channelCode.describe("The platform's channel code for this film."))
416
437
  .optional()
@@ -419,6 +440,9 @@ const socialSchema = z.strictObject({
419
440
  )
420
441
  .default([])
421
442
  .describe("Post copy per film; a film without a post gets no posts.md."),
443
+ disclosure: nonBlank
444
+ .optional()
445
+ .describe("A paragraph after every post's caption, e.g. that the persona is an example and the voice is AI-generated; {persona} becomes the film's persona name. A post opts out with disclosure: false."),
422
446
  });
423
447
 
424
448
  const screenshotSchema = z.strictObject({
package/src/film.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { Locator, Page } from "playwright";
2
2
 
3
- import type { LayoutOverride, VideoFormat, Viewport } from "./compose/timeline.js";
3
+ import type { LayoutOverride, Transition, VideoFormat, Viewport } from "./compose/timeline.js";
4
4
 
5
5
  /**
6
6
  * Film = script (data from `marketing.json`) + scene: the beats' `actions` in the same file
@@ -86,7 +86,8 @@ export interface FilmScript {
86
86
  * scene records the rest, and the **last** ends with the end card.
87
87
  */
88
88
  beats: Beat[];
89
- hook: { still: string; shots: HookShot[] };
89
+ /** The opening: its still, the camera shots over it, and how it hands over to the scene. */
90
+ hook: { still: string; shots: HookShot[]; transition: Transition };
90
91
  /**
91
92
  * Phrases the voiceover says that the app's screen must show. If any is missing the recording
92
93
  * stops and the render never starts.
package/src/index.ts CHANGED
@@ -83,29 +83,36 @@ export type { TtsEstimate, TtsInput, TtsProvider, TtsRecording, TtsResult } from
83
83
  export { ELEVENLABS_API_KEY_ENV, ELEVENLABS_PROVIDER_ID, createElevenLabsProvider, type ElevenLabsOptions } from "./voice/elevenlabs.js";
84
84
  export { createFakeTtsProvider, type FakeTtsOptions, type FakeTtsProvider } from "./voice/fake.js";
85
85
  export { createTtsProvider, type CreateTtsProviderOptions, type TtsProviderId } from "./voice/providers.js";
86
- export { getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover, type VoiceoverPaths } from "./voice/cache.js";
87
- export { describeEstimate, produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./voice/produce.js";
86
+ export { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover, type VoiceoverPaths } from "./voice/cache.js";
87
+ export { describeCharge, describeEstimate, produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./voice/produce.js";
88
+ export { findLastRecordingTime, waitForPace, type PaceOptions } from "./voice/pace.js";
89
+ export { describeVoiceoverBatch, produceVoiceovers, type VoiceoverBatchItem, type VoiceoverBatchResult } from "./voice/batch.js";
88
90
  export {
89
91
  BROWSER_BAR_HEIGHT,
90
92
  DEVICE_KINDS,
91
93
  LAYOUTS,
92
94
  LAYOUT_NAMES,
93
95
  MIN_DESKTOP_WIDTH,
96
+ TRANSITIONS,
94
97
  VIDEO_FORMATS,
95
98
  cameraPose,
96
99
  captionChunks,
100
+ crossfadeArgs,
97
101
  fitScale,
98
102
  fitsFrame,
99
103
  getGeometry,
100
104
  getLayoutName,
105
+ getTransitionSeconds,
101
106
  isDesktopViewport,
102
107
  resolveLayout,
103
108
  rewindFrames,
109
+ transitionFrames,
104
110
  unionRect,
105
111
  widePose,
106
112
  type CameraPose,
107
113
  type CaptionChunk,
108
114
  type CaptionLayout,
115
+ type CrossfadeInput,
109
116
  type DeviceKind,
110
117
  type EndCardLayout,
111
118
  type Geometry,
@@ -114,6 +121,7 @@ export {
114
121
  type LayoutOverride,
115
122
  type Point,
116
123
  type Rect,
124
+ type Transition,
117
125
  type TextBox,
118
126
  type VideoFormat,
119
127
  type Viewport,
@@ -4,7 +4,8 @@ import { channelLink, type Platform } from "../platforms.js";
4
4
 
5
5
  /**
6
6
  * Post copy for a film: one `posts.md` with ready text for every configured platform and a link
7
- * carrying the platform's channel code, so a visit from the film can be counted.
7
+ * carrying the platform's channel code, so a visit from the film can be counted. The text is the
8
+ * caption, the disclosure (`social.disclosure`), the link or the link-in-bio line, and the hashtags.
8
9
  *
9
10
  * Where a link in the caption is not clickable (Instagram, TikTok by default) the link goes to the
10
11
  * bio and the caption says so; elsewhere it is in the post.
@@ -38,7 +39,7 @@ export function buildPosts(input: PostsInput): PlatformPost[] {
38
39
  return {
39
40
  platform,
40
41
  label: copy.platforms[platform],
41
- text: [input.post.caption.trim(), call, hashtags].filter((part) => part.length > 0).join("\n\n"),
42
+ text: [input.post.caption.trim(), input.post.disclosure ?? "", call, hashtags].filter((part) => part.length > 0).join("\n\n"),
42
43
  link,
43
44
  linkInBio,
44
45
  };
@@ -60,7 +60,7 @@ export interface RecordOptions {
60
60
  outDir: string;
61
61
  voices: BeatVoice[];
62
62
  voiceoverKey: string;
63
- /** The day the app counts from: today by default; another day only to reproduce an old film. */
63
+ /** The day the app counts from (`--today` or the video's `today`); the day of the run without one. */
64
64
  today?: string;
65
65
  /** The file that holds the scene (its module, or marketing.json for actions), named in errors that ask for a scene fix. */
66
66
  filmPath: string;
@@ -346,8 +346,8 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
346
346
  if (missing.length > 0) {
347
347
  throw new ScreenGuardError(
348
348
  `The screen does not say what the voiceover says: missing ${missing.map((p) => `"${p}"`).join(", ")}. ` +
349
- `The app counts from the recording day, so fix the sentences and phrases in ${filmPath}. ` +
350
- `--today=YYYY-MM-DD only reproduces an old film; it is not a way around this refusal.`,
349
+ `The app counts from the recording day: if the voiceover was paid for on another day, pin that day in the video's ` +
350
+ `"today" (or pass --today=YYYY-MM-DD); otherwise fix the sentences and phrases in ${filmPath}.`,
351
351
  );
352
352
  }
353
353
  guardChecked = true;
@@ -4,7 +4,7 @@ import { createRequire } from "node:module";
4
4
  import { dirname, extname, join } from "node:path";
5
5
 
6
6
  import { composeFilm, filmTimes, type ComposeFont } from "../compose/compose.js";
7
- import { getGeometry, getLayoutName, rewindFrames } from "../compose/timeline.js";
7
+ import { crossfadeArgs, getGeometry, getLayoutName, getTransitionSeconds, transitionFrames } from "../compose/timeline.js";
8
8
  import type { BrandColors } from "../config/colors.js";
9
9
  import type { BrandFont } from "../config/config.js";
10
10
  import type { SfxEvent } from "../config/schema.js";
@@ -79,17 +79,17 @@ export function buildComposition(input: RenderInput): string {
79
79
 
80
80
  const ff = (args: string[]) => run("ffmpeg", ["-v", "error", "-y", ...args]);
81
81
  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")]);
82
- // Rewind: 24 frames from the opening frame back to the start of the scene (0.8 s), with motion blur.
82
+ // The transition from the opening frame into the scene: stills joined by dissolves (none for a cut).
83
83
  const still = log.stills[film.hook.still];
84
84
  const firstBeat = log.beats[0];
85
85
  if (still === undefined || firstBeat === undefined) throw new Error(`The recording of ${film.id} has no opening frame or no sentences: record it again.`);
86
- const rewindDir = join(dir, "rewind");
87
- rmSync(rewindDir, { recursive: true, force: true });
88
- mkdirSync(rewindDir, { recursive: true });
89
- rewindFrames(firstBeat.f0, still).forEach((index, k) => {
90
- cpSync(getFramePath(dir, index), join(rewindDir, `r${String(k).padStart(5, "0")}.jpg`));
91
- });
92
- 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")]);
86
+ const transitionPath = join(assetsDir, "transition.mp4");
87
+ rmSync(transitionPath, { force: true });
88
+ const frames = transitionFrames(film.hook.transition, firstBeat.f0, still);
89
+ if (frames.length > 0) {
90
+ const inputs = frames.map((index) => getFramePath(dir, index));
91
+ ff(crossfadeArgs({ inputs, fps: log.fps, seconds: getTransitionSeconds(film.hook.transition), output: transitionPath }));
92
+ }
93
93
  cpSync(getFramePath(dir, still), join(assetsDir, "hook.jpg"));
94
94
  cpSync(getFramePath(dir, log.frames - 1), join(assetsDir, "last.jpg"));
95
95
  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 {
120
120
  fonts,
121
121
  assets: {
122
122
  screen: "assets/screen.mp4",
123
- rewind: "assets/rewind.mp4",
123
+ transition: frames.length > 0 ? "assets/transition.mp4" : null,
124
124
  hookStill: "assets/hook.jpg",
125
125
  lastFrame: "assets/last.jpg",
126
126
  voiceover: "assets/voiceover.mp3",
@@ -0,0 +1,65 @@
1
+ import { produceVoiceover, type ProduceVoiceoverOptions, type VoiceoverOutcome } from "./produce.js";
2
+
3
+ /**
4
+ * Voiceovers of several films in one run, in order. The first failure stops the batch: nothing after it reaches the
5
+ * provider, so a refusal (a bad key, an exhausted balance, a policy block) is never answered with more calls.
6
+ */
7
+
8
+ export interface VoiceoverBatchItem {
9
+ /** The film the voiceover belongs to, for the summary. */
10
+ id: string;
11
+ options: ProduceVoiceoverOptions;
12
+ }
13
+
14
+ export interface VoiceoverBatchResult {
15
+ /** Films that finished, in order, with what happened to each. */
16
+ done: { id: string; outcome: VoiceoverOutcome }[];
17
+ /** The film that failed, or null when every film finished. */
18
+ failed: { id: string; error: string } | null;
19
+ /** Films after the failure, never sent. */
20
+ notAttempted: string[];
21
+ }
22
+
23
+ export async function produceVoiceovers(items: VoiceoverBatchItem[]): Promise<VoiceoverBatchResult> {
24
+ const done: VoiceoverBatchResult["done"] = [];
25
+ for (const [index, item] of items.entries()) {
26
+ const result = await produceVoiceover(item.options);
27
+ if (!result.ok) {
28
+ return { done, failed: { id: item.id, error: result.error }, notAttempted: items.slice(index + 1).map((rest) => rest.id) };
29
+ }
30
+ done.push({ id: item.id, outcome: result.value });
31
+ }
32
+ return { done, failed: null, notAttempted: [] };
33
+ }
34
+
35
+ /** The batch in a few lines: what was recorded, from the cache or only estimated, the totals, and where it stopped. */
36
+ export function describeVoiceoverBatch(result: VoiceoverBatchResult): string[] {
37
+ const byKind = (kind: VoiceoverOutcome["kind"]) => result.done.filter((entry) => entry.outcome.kind === kind).map((entry) => entry.id);
38
+ const lines: string[] = [];
39
+ for (const [label, ids] of [
40
+ ["recorded", byKind("recorded")],
41
+ ["from the cache", byKind("cached")],
42
+ ["estimated only (dry run)", byKind("dry-run")],
43
+ ] as const) {
44
+ if (ids.length > 0) lines.push(`voiceovers ${label}: ${ids.length} (${ids.join(", ")})`);
45
+ }
46
+ const priced = result.done.flatMap((entry) => (entry.outcome.kind === "cached" ? [] : [entry.outcome]));
47
+ const [first] = priced;
48
+ if (first !== undefined) {
49
+ const characters = priced.reduce((sum, outcome) => sum + outcome.estimate.characters, 0);
50
+ const maxCost = priced.reduce((sum, outcome) => sum + outcome.estimate.maxCost, 0);
51
+ lines.push(`total: ${characters} characters, at most ${maxCost} ${first.estimate.unit}.`);
52
+ const recorded = priced.flatMap((outcome) => (outcome.kind === "recorded" ? [outcome] : []));
53
+ const charges = recorded.flatMap((outcome) => (outcome.charged === null ? [] : [outcome.charged]));
54
+ if (recorded.length > 0) {
55
+ const unreported = recorded.length - charges.length;
56
+ const total = Math.round(charges.reduce((sum, charge) => sum + charge, 0) * 1000) / 1000;
57
+ lines.push(`charged: ${total} ${first.estimate.unit}${unreported > 0 ? ` (${unreported} ${unreported === 1 ? "recording" : "recordings"} did not report a charge)` : ""}.`);
58
+ }
59
+ }
60
+ if (result.failed !== null) {
61
+ lines.push(`stopped at ${result.failed.id}: ${result.failed.error}`);
62
+ if (result.notAttempted.length > 0) lines.push(`not attempted: ${result.notAttempted.join(", ")}.`);
63
+ }
64
+ return lines;
65
+ }
@@ -1,5 +1,5 @@
1
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import { join } from "node:path";
1
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { dirname, join } from "node:path";
3
3
 
4
4
  import { err, ok, type TtsInput, type TtsRecording, type TtsResult } from "./provider.js";
5
5
  import { voiceoverKey, type TimedWord } from "./voiceover.js";
@@ -8,6 +8,8 @@ export interface VoiceoverPaths {
8
8
  key: string;
9
9
  audio: string;
10
10
  words: string;
11
+ /** `video`: in the video's own folder; `flat`: `<key>.*` in the cache root, the layout before 0.1.6, still read. */
12
+ layout: "video" | "flat";
11
13
  }
12
14
 
13
15
  /** A voiceover on disk: the audio file's path and the timed words. */
@@ -16,10 +18,35 @@ export interface Voiceover {
16
18
  words: TimedWord[];
17
19
  }
18
20
 
19
- /** Where a recording of this input lives in the cache: `<key>.mp3` and `<key>.json`. */
20
- export function getVoiceoverPaths(cacheDir: string, input: TtsInput): VoiceoverPaths {
21
+ function getPathsIn(dir: string, key: string, layout: VoiceoverPaths["layout"]): VoiceoverPaths {
22
+ return { key, audio: join(dir, `${key}.mp3`), words: join(dir, `${key}.json`), layout };
23
+ }
24
+
25
+ function hasRecording(paths: VoiceoverPaths): boolean {
26
+ return existsSync(paths.audio) && existsSync(paths.words);
27
+ }
28
+
29
+ /**
30
+ * Where a recording of this input lives in the cache. With a video id: `<cacheDir>/<video-id>/<key>.mp3|json`, so
31
+ * a reader sees which film a paid file belongs to; a recording saved flat by an earlier version
32
+ * (`<cacheDir>/<key>.*`) is still found when the video's folder has none, so no paid file is recorded twice.
33
+ * Without a video id: the flat layout. The key (text, voice, model, language) is the same in both.
34
+ */
35
+ export function getVoiceoverPaths(cacheDir: string, input: TtsInput, videoId?: string): VoiceoverPaths {
21
36
  const key = voiceoverKey(input.text, input.voiceId, input.model, input.language);
22
- return { key, audio: join(cacheDir, `${key}.mp3`), words: join(cacheDir, `${key}.json`) };
37
+ const flat = getPathsIn(cacheDir, key, "flat");
38
+ if (videoId === undefined) return flat;
39
+ const own = getPathsIn(join(cacheDir, videoId), key, "video");
40
+ return hasRecording(own) || !hasRecording(flat) ? own : flat;
41
+ }
42
+
43
+ /** Recordings in the video's folder other than `key`: what an earlier script of the film paid for. Sorted file names. */
44
+ export function findStaleVoiceovers(cacheDir: string, videoId: string, key: string): string[] {
45
+ const dir = join(cacheDir, videoId);
46
+ if (!existsSync(dir)) return [];
47
+ return readdirSync(dir)
48
+ .filter((name) => name.endsWith(".mp3") && name !== `${key}.mp3`)
49
+ .sort();
23
50
  }
24
51
 
25
52
  function isTimedWords(value: unknown): value is TimedWord[] {
@@ -49,6 +76,7 @@ export function readCachedVoiceover(paths: VoiceoverPaths): TtsResult<Voiceover
49
76
  /** Writes a recording in FIRE_TRACKER's format, so files recorded there stay byte-identical. */
50
77
  export function writeVoiceover(cacheDir: string, paths: VoiceoverPaths, recording: TtsRecording): Voiceover {
51
78
  mkdirSync(cacheDir, { recursive: true });
79
+ mkdirSync(dirname(paths.audio), { recursive: true });
52
80
  writeFileSync(paths.audio, recording.audio);
53
81
  writeFileSync(paths.words, `${JSON.stringify(recording.words, null, 1)}\n`);
54
82
  return { audio: paths.audio, words: recording.words };
@@ -4,6 +4,8 @@ import { buildTtsRequest, readTimestampsResponse, wordsFromAlignment } from "./v
4
4
  export const ELEVENLABS_PROVIDER_ID = "elevenlabs";
5
5
  export const ELEVENLABS_API_KEY_ENV = "ELEVENLABS_API_KEY";
6
6
  const ERROR_DETAIL_LENGTH = 300;
7
+ /** The response header with the credits the generation cost (API reference, "Response headers"). */
8
+ const CHARGE_HEADER = "character-cost";
7
9
 
8
10
  export interface ElevenLabsOptions {
9
11
  /** The API key; a missing one fails `synthesize`, not the estimate. */
@@ -20,6 +22,14 @@ function estimate(input: TtsInput): TtsEstimate {
20
22
  return { characters: input.text.length, maxCost: input.text.length, unit: "ElevenLabs credits" };
21
23
  }
22
24
 
25
+ /** The credits ElevenLabs reports for the call; null when the header is missing or not a non-negative number. */
26
+ function readCharge(response: Response): number | null {
27
+ const header = response.headers.get(CHARGE_HEADER)?.trim() ?? "";
28
+ if (header.length === 0) return null;
29
+ const charged = Number(header);
30
+ return Number.isFinite(charged) && charged >= 0 ? charged : null;
31
+ }
32
+
23
33
  async function readBody(response: Response): Promise<TtsResult<unknown>> {
24
34
  try {
25
35
  return ok((await response.json()) as unknown);
@@ -55,7 +65,7 @@ export function createElevenLabsProvider(options: ElevenLabsOptions): TtsProvide
55
65
  if (!body.ok) return body;
56
66
  try {
57
67
  const parsed = readTimestampsResponse(body.value);
58
- return ok({ audio: parsed.audio, words: wordsFromAlignment(parsed.alignment) });
68
+ return ok({ audio: parsed.audio, words: wordsFromAlignment(parsed.alignment), charged: readCharge(response) });
59
69
  } catch (error) {
60
70
  // The parsers throw on a malformed body; for a caller it is an expected failure of the call.
61
71
  return err(error instanceof Error ? error.message : String(error));
@@ -0,0 +1,55 @@
1
+ import { existsSync, readdirSync, statSync } from "node:fs";
2
+ import { join } from "node:path";
3
+
4
+ /**
5
+ * Paid calls are spaced so a batch of films never reaches the provider as a burst (FIRE_TRACKER sent 26 in about ten
6
+ * minutes from a shell loop and drew an ElevenLabs policy warning). The time of the last paid call is read from the
7
+ * cache itself: every paid call writes `<key>.json` right after the response, so pacing also holds across separate
8
+ * runs of the CLI and needs no state file.
9
+ */
10
+
11
+ export interface PaceOptions {
12
+ /** The voiceover cache: recordings at its root (the flat layout) and in one folder per video. */
13
+ cacheDir: string;
14
+ /** The least time between two paid calls; 0 turns pacing off. */
15
+ minIntervalSeconds: number;
16
+ /** Injected in tests; `Date.now` otherwise. */
17
+ now?: () => number;
18
+ /** Injected in tests; a timer otherwise. */
19
+ sleep?: (milliseconds: number) => Promise<void>;
20
+ log: (line: string) => void;
21
+ }
22
+
23
+ const sleepFor = (milliseconds: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, milliseconds));
24
+
25
+ function listWordFiles(dir: string): string[] {
26
+ return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
27
+ const path = join(dir, entry.name);
28
+ if (entry.isFile() && entry.name.endsWith(".json")) return [path];
29
+ if (!entry.isDirectory()) return [];
30
+ return readdirSync(path, { withFileTypes: true })
31
+ .filter((inner) => inner.isFile() && inner.name.endsWith(".json"))
32
+ .map((inner) => join(path, inner.name));
33
+ });
34
+ }
35
+
36
+ /** When the newest recording in the cache was written, in epoch milliseconds; null for an empty or missing cache. */
37
+ export function findLastRecordingTime(cacheDir: string): number | null {
38
+ if (!existsSync(cacheDir)) return null;
39
+ const times = listWordFiles(cacheDir).map((path) => statSync(path).mtimeMs);
40
+ return times.length === 0 ? null : Math.max(...times);
41
+ }
42
+
43
+ /** Waits until `minIntervalSeconds` have passed since the newest recording in the cache; returns the seconds waited. */
44
+ export async function waitForPace(options: PaceOptions): Promise<number> {
45
+ const { cacheDir, minIntervalSeconds, log } = options;
46
+ if (minIntervalSeconds <= 0) return 0;
47
+ const last = findLastRecordingTime(cacheDir);
48
+ if (last === null) return 0;
49
+ const now = (options.now ?? Date.now)();
50
+ const remaining = Math.ceil((last + minIntervalSeconds * 1000 - now) / 1000);
51
+ if (remaining <= 0) return 0;
52
+ log(`voiceover: the last paid recording in ${cacheDir} is under ${minIntervalSeconds} s old (voice.minIntervalSeconds); waiting ${remaining} s before the next call.`);
53
+ await (options.sleep ?? sleepFor)(remaining * 1000);
54
+ return remaining;
55
+ }
@@ -1,19 +1,32 @@
1
- import { getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover } from "./cache.js";
1
+ import { dirname, join } from "node:path";
2
+
3
+ import { findStaleVoiceovers, getVoiceoverPaths, readCachedVoiceover, writeVoiceover, type Voiceover } from "./cache.js";
4
+ import { waitForPace, type PaceOptions } from "./pace.js";
2
5
  import { err, ok, type TtsEstimate, type TtsInput, type TtsProvider, type TtsResult } from "./provider.js";
3
6
 
4
7
  export interface ProduceVoiceoverOptions {
5
8
  cacheDir: string;
6
9
  input: TtsInput;
10
+ /** The film the voiceover belongs to: its recordings live in `<cacheDir>/<videoId>/`. Without it, the flat layout. */
11
+ videoId?: string;
7
12
  provider: TtsProvider;
8
13
  /** Only `true` lets the provider spend money. */
9
14
  isCommit: boolean;
15
+ /** Spacing of paid calls (`voice.minIntervalSeconds`); without it, no wait. Never applies to a cache hit or a dry run. */
16
+ pace?: Omit<PaceOptions, "cacheDir" | "log">;
10
17
  log: (line: string) => void;
11
18
  }
12
19
 
13
20
  export type VoiceoverOutcome =
14
21
  | { kind: "cached"; key: string; voiceover: Voiceover }
15
22
  | { kind: "dry-run"; key: string; estimate: TtsEstimate }
16
- | { kind: "recorded"; key: string; voiceover: Voiceover; estimate: TtsEstimate };
23
+ | { kind: "recorded"; key: string; voiceover: Voiceover; estimate: TtsEstimate; charged: number | null };
24
+
25
+ /** The charge the provider reported, next to the estimate; the estimate stays an upper bound. */
26
+ export function describeCharge(provider: TtsProvider, estimate: TtsEstimate, charged: number | null): string {
27
+ if (charged === null) return `voiceover: ${provider.id} did not report the charge; the estimate was at most ${estimate.maxCost} ${estimate.unit}.`;
28
+ return `voiceover: ${provider.id} charged ${charged} ${estimate.unit} for ${estimate.characters} characters (the estimate was at most ${estimate.maxCost}).`;
29
+ }
17
30
 
18
31
  export function describeEstimate(provider: TtsProvider, estimate: TtsEstimate): string {
19
32
  return `voiceover estimate (${provider.id}): ${estimate.characters} characters, at most ${estimate.maxCost} ${estimate.unit}.`;
@@ -24,12 +37,21 @@ export function describeEstimate(provider: TtsProvider, estimate: TtsEstimate):
24
37
  * run and before every paid call; without `isCommit` the provider is never called.
25
38
  */
26
39
  export async function produceVoiceover(options: ProduceVoiceoverOptions): Promise<TtsResult<VoiceoverOutcome>> {
27
- const { cacheDir, input, provider, isCommit, log } = options;
28
- const paths = getVoiceoverPaths(cacheDir, input);
40
+ const { cacheDir, input, videoId, provider, isCommit, pace, log } = options;
41
+ const paths = getVoiceoverPaths(cacheDir, input, videoId);
29
42
  const cached = readCachedVoiceover(paths);
30
43
  if (!cached.ok) return cached;
44
+ if (videoId !== undefined) {
45
+ const stale = findStaleVoiceovers(cacheDir, videoId, paths.key);
46
+ if (stale.length > 0) {
47
+ log(`voiceover: ${join(cacheDir, videoId)} also holds ${stale.join(", ")}, which the current script does not use; delete them once no film needs them.`);
48
+ }
49
+ }
31
50
  if (cached.value !== null) {
32
51
  log(`voiceover: from the cache ${paths.key}, nothing spent.`);
52
+ if (videoId !== undefined && paths.layout === "flat") {
53
+ 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.`);
54
+ }
33
55
  return ok({ kind: "cached", key: paths.key, voiceover: cached.value });
34
56
  }
35
57
  const estimate = provider.estimate(input);
@@ -38,9 +60,12 @@ export async function produceVoiceover(options: ProduceVoiceoverOptions): Promis
38
60
  log(`voiceover DRY RUN (voice ${input.voiceId}): nothing was sent. Run with --commit to pay and record.`);
39
61
  return ok({ kind: "dry-run", key: paths.key, estimate });
40
62
  }
63
+ if (pace !== undefined) await waitForPace({ ...pace, cacheDir, log });
41
64
  const recording = await provider.synthesize(input);
42
65
  if (!recording.ok) return err(recording.error);
43
66
  const voiceover = writeVoiceover(cacheDir, paths, recording.value);
44
- log(`voiceover: recorded ${estimate.characters} characters, saved ${paths.key}.{mp3,json} in ${cacheDir} (commit them).`);
45
- return ok({ kind: "recorded", key: paths.key, voiceover, estimate });
67
+ const charged = recording.value.charged ?? null;
68
+ log(describeCharge(provider, estimate, charged));
69
+ log(`voiceover: recorded ${estimate.characters} characters, saved ${paths.key}.{mp3,json} in ${dirname(paths.audio)} (commit them).`);
70
+ return ok({ kind: "recorded", key: paths.key, voiceover, estimate, charged });
46
71
  }
@@ -13,6 +13,8 @@ export interface TtsInput {
13
13
  export interface TtsRecording {
14
14
  audio: Buffer;
15
15
  words: TimedWord[];
16
+ /** What the provider says it charged, in the estimate's unit; null or absent when it does not say. */
17
+ charged?: number | null;
16
18
  }
17
19
 
18
20
  /** What a recording would cost, shown before anything is spent. */