@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.
- package/README.md +49 -12
- package/dist/cli/main.js +15 -9
- package/dist/cli/main.js.map +1 -1
- package/dist/cli/options.d.ts +14 -1
- package/dist/cli/options.d.ts.map +1 -1
- package/dist/cli/options.js +22 -9
- package/dist/cli/options.js.map +1 -1
- package/dist/cli/voice.d.ts +5 -0
- package/dist/cli/voice.d.ts.map +1 -1
- package/dist/cli/voice.js +28 -8
- package/dist/cli/voice.js.map +1 -1
- package/dist/compose/compose.d.ts +3 -3
- package/dist/compose/compose.d.ts.map +1 -1
- package/dist/compose/compose.js +7 -7
- package/dist/compose/compose.js.map +1 -1
- package/dist/compose/timeline.d.ts +19 -0
- package/dist/compose/timeline.d.ts.map +1 -1
- package/dist/compose/timeline.js +42 -0
- package/dist/compose/timeline.js.map +1 -1
- package/dist/config/config.d.ts +5 -0
- package/dist/config/config.d.ts.map +1 -1
- package/dist/config/config.js +3 -1
- package/dist/config/config.js.map +1 -1
- package/dist/config/day.d.ts +5 -0
- package/dist/config/day.d.ts.map +1 -0
- package/dist/config/day.js +10 -0
- package/dist/config/day.js.map +1 -0
- package/dist/config/schema.d.ts +9 -0
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/config/schema.js +22 -1
- package/dist/config/schema.js.map +1 -1
- package/dist/film.d.ts +3 -1
- package/dist/film.d.ts.map +1 -1
- package/dist/film.js.map +1 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -3
- package/dist/index.js.map +1 -1
- package/dist/posts/posts.d.ts +2 -1
- package/dist/posts/posts.d.ts.map +1 -1
- package/dist/posts/posts.js +1 -1
- package/dist/posts/posts.js.map +1 -1
- package/dist/record/record.d.ts +1 -1
- package/dist/record/record.d.ts.map +1 -1
- package/dist/record/record.js +2 -2
- package/dist/record/record.js.map +1 -1
- package/dist/render/render.js +10 -10
- package/dist/render/render.js.map +1 -1
- package/dist/voice/batch.d.ts +28 -0
- package/dist/voice/batch.d.ts.map +1 -0
- package/dist/voice/batch.js +46 -0
- package/dist/voice/batch.js.map +1 -0
- package/dist/voice/cache.d.ts +11 -2
- package/dist/voice/cache.d.ts.map +1 -1
- package/dist/voice/cache.js +30 -5
- package/dist/voice/cache.js.map +1 -1
- package/dist/voice/elevenlabs.d.ts.map +1 -1
- package/dist/voice/elevenlabs.js +11 -1
- package/dist/voice/elevenlabs.js.map +1 -1
- package/dist/voice/pace.d.ts +22 -0
- package/dist/voice/pace.d.ts.map +1 -0
- package/dist/voice/pace.js +39 -0
- package/dist/voice/pace.js.map +1 -0
- package/dist/voice/produce.d.ts +8 -0
- package/dist/voice/produce.d.ts.map +1 -1
- package/dist/voice/produce.js +26 -5
- package/dist/voice/produce.js.map +1 -1
- package/dist/voice/provider.d.ts +2 -0
- package/dist/voice/provider.d.ts.map +1 -1
- package/dist/voice/provider.js.map +1 -1
- package/package.json +1 -1
- package/schema/marketing.schema.json +31 -0
- package/src/cli/main.ts +14 -9
- package/src/cli/options.ts +24 -7
- package/src/cli/voice.ts +28 -9
- package/src/compose/compose.ts +9 -9
- package/src/compose/timeline.ts +55 -0
- package/src/config/config.ts +9 -2
- package/src/config/day.ts +9 -0
- package/src/config/schema.ts +25 -1
- package/src/film.ts +3 -2
- package/src/index.ts +10 -2
- package/src/posts/posts.ts +3 -2
- package/src/record/record.ts +3 -3
- package/src/render/render.ts +10 -10
- package/src/voice/batch.ts +65 -0
- package/src/voice/cache.ts +33 -5
- package/src/voice/elevenlabs.ts +11 -1
- package/src/voice/pace.ts +55 -0
- package/src/voice/produce.ts +31 -6
- package/src/voice/provider.ts +2 -0
package/src/config/config.ts
CHANGED
|
@@ -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
|
+
}
|
package/src/config/schema.ts
CHANGED
|
@@ -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
|
-
|
|
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,
|
package/src/posts/posts.ts
CHANGED
|
@@ -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
|
};
|
package/src/record/record.ts
CHANGED
|
@@ -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
|
|
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
|
|
350
|
-
|
|
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;
|
package/src/render/render.ts
CHANGED
|
@@ -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,
|
|
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
|
-
//
|
|
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
|
|
87
|
-
rmSync(
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
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
|
+
}
|
package/src/voice/cache.ts
CHANGED
|
@@ -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
|
-
|
|
20
|
-
|
|
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
|
-
|
|
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 };
|
package/src/voice/elevenlabs.ts
CHANGED
|
@@ -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
|
+
}
|
package/src/voice/produce.ts
CHANGED
|
@@ -1,19 +1,32 @@
|
|
|
1
|
-
import {
|
|
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
|
-
|
|
45
|
-
|
|
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
|
}
|
package/src/voice/provider.ts
CHANGED
|
@@ -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. */
|