@softure-ai/marketing-kit 0.1.8 → 0.1.9
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/CHANGELOG.md +23 -0
- package/README.md +28 -4
- package/dist/config/actions-schema.d.ts +7 -1
- package/dist/config/actions-schema.d.ts.map +1 -1
- package/dist/config/actions-schema.js +18 -3
- package/dist/config/actions-schema.js.map +1 -1
- package/dist/config/config.js +1 -1
- package/dist/config/config.js.map +1 -1
- package/dist/config/schema.d.ts +8 -1
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/config/schema.js +13 -4
- package/dist/config/schema.js.map +1 -1
- package/dist/film.d.ts +20 -5
- package/dist/film.d.ts.map +1 -1
- package/dist/film.js.map +1 -1
- package/dist/record/actions.d.ts.map +1 -1
- package/dist/record/actions.js +6 -1
- package/dist/record/actions.js.map +1 -1
- package/dist/record/record.d.ts.map +1 -1
- package/dist/record/record.js +51 -17
- package/dist/record/record.js.map +1 -1
- package/dist/record/screen-guard.d.ts +13 -0
- package/dist/record/screen-guard.d.ts.map +1 -0
- package/dist/record/screen-guard.js +27 -0
- package/dist/record/screen-guard.js.map +1 -0
- package/package.json +2 -1
- package/schema/marketing.schema.json +49 -6
- package/src/config/actions-schema.ts +18 -3
- package/src/config/config.ts +1 -1
- package/src/config/schema.ts +19 -5
- package/src/film.ts +15 -5
- package/src/record/actions.ts +6 -1
- package/src/record/record.ts +53 -19
- package/src/record/screen-guard.ts +37 -0
package/src/film.ts
CHANGED
|
@@ -12,6 +12,11 @@ import type { LayoutOverride, Transition, VideoFormat, Viewport } from "./compos
|
|
|
12
12
|
export interface Beat {
|
|
13
13
|
id: string;
|
|
14
14
|
text: string;
|
|
15
|
+
/**
|
|
16
|
+
* Phrases this sentence says that the screen must show while it is spoken: checked at a `checkScreen` inside the
|
|
17
|
+
* sentence, or when it ends. Never on the opening sentence.
|
|
18
|
+
*/
|
|
19
|
+
screenGuard?: string[];
|
|
15
20
|
}
|
|
16
21
|
|
|
17
22
|
export interface Persona {
|
|
@@ -89,8 +94,8 @@ export interface FilmScript {
|
|
|
89
94
|
/** The opening: its still, the camera shots over it, and how it hands over to the scene. */
|
|
90
95
|
hook: { still: string; shots: HookShot[]; transition: Transition };
|
|
91
96
|
/**
|
|
92
|
-
* Phrases the voiceover says that the app's screen must show
|
|
93
|
-
* stops and the render never starts.
|
|
97
|
+
* Phrases the voiceover says that the app's screen must show at every `checkScreen`. If any is missing the
|
|
98
|
+
* recording stops and the render never starts. Empty when every phrase lives on its sentence (`Beat.screenGuard`).
|
|
94
99
|
*/
|
|
95
100
|
screenGuard: string[];
|
|
96
101
|
endCard: EndCard;
|
|
@@ -116,8 +121,13 @@ export interface Director {
|
|
|
116
121
|
/** Touch the element on a phone, click it on a desktop. */
|
|
117
122
|
tap(target: Locator, options?: { after?: number }): Promise<void>;
|
|
118
123
|
type(text: string, options?: { perChar?: number }): Promise<void>;
|
|
119
|
-
/**
|
|
120
|
-
|
|
124
|
+
/** Press a key (a Playwright key name such as `Backspace` or `ControlOrMeta+A`) `times` times, holding `perKey` after each. */
|
|
125
|
+
press(key: string, options?: { times?: number; perKey?: number }): Promise<void>;
|
|
126
|
+
/**
|
|
127
|
+
* Tap the `input[name=…]` field, move the camera onto it and type the value. A value already in the field is
|
|
128
|
+
* selected and deleted first, on screen; `clear: false` types after it instead.
|
|
129
|
+
*/
|
|
130
|
+
fill(name: string, value: string, options?: { clear?: boolean }): Promise<void>;
|
|
121
131
|
blur(): Promise<void>;
|
|
122
132
|
/** Camera on an element (or on the rectangle that encloses several). */
|
|
123
133
|
focus(target: Locator | Locator[], options?: { scale?: number; height?: number }): Promise<void>;
|
|
@@ -129,7 +139,7 @@ export interface Director {
|
|
|
129
139
|
still(name: string): Promise<void>;
|
|
130
140
|
/** An event on the film's timeline: a sound effect or the persona card leaving. */
|
|
131
141
|
cue(name: CueName): Promise<void>;
|
|
132
|
-
/** The screen guard:
|
|
142
|
+
/** The screen guard: the video's phrases and the current sentence's, checked now, before the recording goes on. */
|
|
133
143
|
checkScreen(): Promise<void>;
|
|
134
144
|
}
|
|
135
145
|
|
package/src/record/actions.ts
CHANGED
|
@@ -55,8 +55,13 @@ export async function runAction(director: Director, action: SceneAction): Promis
|
|
|
55
55
|
return director.tap(getLocator(page, action.target), action.after === undefined ? undefined : { after: action.after });
|
|
56
56
|
case "type":
|
|
57
57
|
return director.type(action.text, action.perChar === undefined ? undefined : { perChar: action.perChar });
|
|
58
|
+
case "press":
|
|
59
|
+
return director.press(action.key, {
|
|
60
|
+
...(action.times === undefined ? {} : { times: action.times }),
|
|
61
|
+
...(action.perKey === undefined ? {} : { perKey: action.perKey }),
|
|
62
|
+
});
|
|
58
63
|
case "fill":
|
|
59
|
-
return director.fill(action.input, action.value);
|
|
64
|
+
return director.fill(action.input, action.value, action.clear === undefined ? undefined : { clear: action.clear });
|
|
60
65
|
case "blur":
|
|
61
66
|
return director.blur();
|
|
62
67
|
case "focus":
|
package/src/record/record.ts
CHANGED
|
@@ -5,8 +5,9 @@ import { chromium, type Locator } from "playwright";
|
|
|
5
5
|
|
|
6
6
|
import { fitScale, getGeometry, unionRect, type Rect } from "../compose/timeline.js";
|
|
7
7
|
import type { ColorTheme } from "../config/colors.js";
|
|
8
|
-
import {
|
|
8
|
+
import { sceneBeats, type Beat, type CueName, type Director, type Film } from "../film.js";
|
|
9
9
|
import type { BeatVoice } from "../voice/voiceover.js";
|
|
10
|
+
import { describeCheckScreenFailure, describeSentenceFailure, findMissingPhrases, getCheckScreenPhrases } from "./screen-guard.js";
|
|
10
11
|
|
|
11
12
|
/**
|
|
12
13
|
* Recording of the real app **frame by frame**, with the page clock frozen.
|
|
@@ -26,6 +27,8 @@ export const FPS = 30;
|
|
|
26
27
|
const DT = 1000 / FPS;
|
|
27
28
|
/** Limit of one scene action: longer means the app looks different from what the scene expects. */
|
|
28
29
|
const ACTION_TIMEOUT_MS = 5000;
|
|
30
|
+
/** How long one typed character or pressed key stays on screen before the next. */
|
|
31
|
+
const KEY_SECONDS = 0.13;
|
|
29
32
|
|
|
30
33
|
export interface CameraCue {
|
|
31
34
|
f: number;
|
|
@@ -96,7 +99,8 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
96
99
|
mkdirSync(framesDir, { recursive: true });
|
|
97
100
|
|
|
98
101
|
const voiceById = new Map(voices.map((voice) => [voice.id, voice]));
|
|
99
|
-
const
|
|
102
|
+
const sentenceById = new Map(sceneBeats(film).map((beat) => [beat.id, beat]));
|
|
103
|
+
const expectedBeats = [...sentenceById.keys()];
|
|
100
104
|
const log: RecordingLog = {
|
|
101
105
|
voiceoverKey: options.voiceoverKey,
|
|
102
106
|
beatIds: expectedBeats,
|
|
@@ -157,7 +161,8 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
157
161
|
|
|
158
162
|
let virtualMs = 0;
|
|
159
163
|
let frame = 0;
|
|
160
|
-
|
|
164
|
+
/** The sentence being recorded; `isGuardChecked` once a checkScreen inside it checked its own phrases. */
|
|
165
|
+
let current: { id: string; f0: number; sentence: Beat; isGuardChecked: boolean } | null = null;
|
|
161
166
|
let guardChecked = false;
|
|
162
167
|
|
|
163
168
|
const where = (): string => (current === null ? "before the first sentence" : `sentence "${current.id}"`);
|
|
@@ -196,6 +201,10 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
196
201
|
for (let i = 0, count = Math.round(seconds * FPS); i < count; i += 1) await shoot();
|
|
197
202
|
}
|
|
198
203
|
|
|
204
|
+
async function readScreenText(): Promise<string> {
|
|
205
|
+
return (await page.locator(settings.screenGuardSelector).first().innerText()).replace(/\s+/g, " ");
|
|
206
|
+
}
|
|
207
|
+
|
|
199
208
|
async function rectOf(target: Locator): Promise<Rect> {
|
|
200
209
|
try {
|
|
201
210
|
// "visible", not "attached": a hidden element has a 0×0 rectangle and a tap would miss.
|
|
@@ -249,13 +258,21 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
249
258
|
);
|
|
250
259
|
}
|
|
251
260
|
const voice = voiceById.get(id);
|
|
252
|
-
|
|
253
|
-
|
|
261
|
+
const sentence = sentenceById.get(id);
|
|
262
|
+
if (voice === undefined || sentence === undefined) throw new Error(`No voiceover for sentence "${id}".`);
|
|
263
|
+
const state = { id, f0: frame, sentence, isGuardChecked: false };
|
|
264
|
+
current = state;
|
|
254
265
|
await actions();
|
|
255
266
|
const minFrames = Math.round((voice.end - voice.start + (beatOptions?.pad ?? 0.35)) * FPS);
|
|
256
|
-
const missing = minFrames - (frame -
|
|
267
|
+
const missing = minFrames - (frame - state.f0);
|
|
257
268
|
if (missing > 0) await hold(missing / FPS);
|
|
258
|
-
|
|
269
|
+
// The sentence's own phrases, on its last frame, unless a checkScreen inside it already checked them.
|
|
270
|
+
const phrases = sentence.screenGuard ?? [];
|
|
271
|
+
if (!state.isGuardChecked && phrases.length > 0) {
|
|
272
|
+
const absent = findMissingPhrases(await readScreenText(), phrases);
|
|
273
|
+
if (absent.length > 0) throw new ScreenGuardError(describeSentenceFailure(id, absent, filmPath));
|
|
274
|
+
}
|
|
275
|
+
log.beats.push({ id, f0: state.f0, f1: frame });
|
|
259
276
|
},
|
|
260
277
|
|
|
261
278
|
async until(word) {
|
|
@@ -290,11 +307,19 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
290
307
|
for (const character of text) {
|
|
291
308
|
log.keys.push(frame);
|
|
292
309
|
await page.keyboard.type(character);
|
|
293
|
-
await hold(typeOptions?.perChar ??
|
|
310
|
+
await hold(typeOptions?.perChar ?? KEY_SECONDS);
|
|
294
311
|
}
|
|
295
312
|
},
|
|
296
313
|
|
|
297
|
-
async
|
|
314
|
+
async press(key, pressOptions) {
|
|
315
|
+
for (let i = 0, times = pressOptions?.times ?? 1; i < times; i += 1) {
|
|
316
|
+
log.keys.push(frame);
|
|
317
|
+
await page.keyboard.press(key);
|
|
318
|
+
await hold(pressOptions?.perKey ?? KEY_SECONDS);
|
|
319
|
+
}
|
|
320
|
+
},
|
|
321
|
+
|
|
322
|
+
async fill(name, value, fillOptions) {
|
|
298
323
|
const input = page.locator(`input[name=${name}]`);
|
|
299
324
|
await ensureVisible(input);
|
|
300
325
|
const rect = await rectOf(input);
|
|
@@ -302,6 +327,19 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
302
327
|
const scale = isDesktop ? Math.min(1.55, fitScale(geometry, rect)) : 1.55;
|
|
303
328
|
log.camera.push({ f: frame, kind: "focus", rect, scale, whoosh: false });
|
|
304
329
|
await director.tap(input, { after: 0.2 });
|
|
330
|
+
// A tap leaves the caret where the finger landed and selects nothing: typed keys would join the old value.
|
|
331
|
+
// An empty field presses nothing, so it records frame for frame as before.
|
|
332
|
+
if (fillOptions?.clear !== false && (await input.inputValue()) !== "") {
|
|
333
|
+
await director.press("ControlOrMeta+A");
|
|
334
|
+
await director.press("Backspace");
|
|
335
|
+
const left = await input.inputValue();
|
|
336
|
+
if (left !== "") {
|
|
337
|
+
throw new Error(
|
|
338
|
+
`${where()}: ${String(input)} still holds "${left}" after select all and Backspace; ` +
|
|
339
|
+
`the app puts a value back. Set "clear": false or fix the scene: ${filmPath}`,
|
|
340
|
+
);
|
|
341
|
+
}
|
|
342
|
+
}
|
|
305
343
|
await director.type(value);
|
|
306
344
|
},
|
|
307
345
|
|
|
@@ -341,16 +379,10 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
341
379
|
},
|
|
342
380
|
|
|
343
381
|
async checkScreen() {
|
|
344
|
-
const
|
|
345
|
-
|
|
346
|
-
if (missing.length > 0) {
|
|
347
|
-
throw new ScreenGuardError(
|
|
348
|
-
`The screen does not say what the voiceover says: missing ${missing.map((p) => `"${p}"`).join(", ")}. ` +
|
|
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
|
-
);
|
|
352
|
-
}
|
|
382
|
+
const missing = findMissingPhrases(await readScreenText(), getCheckScreenPhrases(film.screenGuard, current?.sentence ?? null));
|
|
383
|
+
if (missing.length > 0) throw new ScreenGuardError(describeCheckScreenFailure(missing, filmPath));
|
|
353
384
|
guardChecked = true;
|
|
385
|
+
if (current !== null) current.isGuardChecked = true;
|
|
354
386
|
},
|
|
355
387
|
};
|
|
356
388
|
|
|
@@ -362,7 +394,9 @@ export async function recordFilm(options: RecordOptions): Promise<RecordingLog>
|
|
|
362
394
|
`The scene recorded ${log.beats.length} of ${expectedBeats.length} sentences; "${expectedBeats[log.beats.length]}" is missing.`,
|
|
363
395
|
);
|
|
364
396
|
}
|
|
365
|
-
if (!guardChecked
|
|
397
|
+
if (!guardChecked && film.screenGuard.length > 0) {
|
|
398
|
+
throw new Error("The scene never called checkScreen(): the video's screenGuard phrases were never checked, so the film could say what the screen does not show.");
|
|
399
|
+
}
|
|
366
400
|
if (log.stills[film.hook.still] === undefined) {
|
|
367
401
|
throw new Error(`The scene did not save the opening frame "${film.hook.still}" (still).`);
|
|
368
402
|
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { containsPhrase, type Beat } from "../film.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The screen guard's rules, apart from the browser: which phrases a check covers and what a failure says. The
|
|
5
|
+
* video's `screenGuard` is checked at every `checkScreen`; a sentence's own `screenGuard` at a `checkScreen` inside
|
|
6
|
+
* that sentence, or, without one, when the sentence ends, so each number is proven on screen while it is spoken.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** The phrases a `checkScreen` covers: the video's, plus the current sentence's own (none before the first sentence). */
|
|
10
|
+
export function getCheckScreenPhrases(videoPhrases: readonly string[], sentence: Beat | null): string[] {
|
|
11
|
+
return [...videoPhrases, ...(sentence?.screenGuard ?? [])];
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** The phrases the screen's text does not contain as whole words, in their order. */
|
|
15
|
+
export function findMissingPhrases(text: string, phrases: readonly string[]): string[] {
|
|
16
|
+
return phrases.filter((phrase) => !containsPhrase(text, phrase));
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const quote = (phrases: readonly string[]): string => phrases.map((phrase) => `"${phrase}"`).join(", ");
|
|
20
|
+
|
|
21
|
+
function describeFix(filmPath: string): string {
|
|
22
|
+
return (
|
|
23
|
+
`The app counts from the recording day: if the voiceover was paid for on another day, pin that day in the video's ` +
|
|
24
|
+
`"today" (or pass --today=YYYY-MM-DD); otherwise fix the sentences and phrases in ${filmPath}.`
|
|
25
|
+
);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function describeCheckScreenFailure(missing: readonly string[], filmPath: string): string {
|
|
29
|
+
return `The screen does not say what the voiceover says: missing ${quote(missing)}. ${describeFix(filmPath)}`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function describeSentenceFailure(sentenceId: string, missing: readonly string[], filmPath: string): string {
|
|
33
|
+
return (
|
|
34
|
+
`Sentence "${sentenceId}" ended without its screenGuard phrases on screen: missing ${quote(missing)}. ` +
|
|
35
|
+
`Reveal them before the sentence ends, or check them where they show with a checkScreen inside the sentence. ${describeFix(filmPath)}`
|
|
36
|
+
);
|
|
37
|
+
}
|