@clipwright/core 0.35.0 → 0.37.0

package/dist/ugc-interview.js

@@ -0,0 +1,260 @@
+import { lexicalTokens, quoteOccurrences } from "./semantic-inserts.js";
+import { defaultVoiceOf } from "./voices.js";
+import { layerWordRange } from "./ugc-layers.js";
+// An interview (#972): an off-screen speaker's words inside the script, the presenter answering on screen and holding still while they speak.
+export const INTERVIEW_GAZES = ["camera", "left", "right"];
+export const INTERVIEW_LISTENING = ["freeze", "live"];
+export const MAX_INTERVIEW_TURNS = 12;
+/** The presenter's takes in one interview: one per answer, and one more at each change of gaze. */
+export const MAX_INTERVIEW_TAKES = 10;
+export const MAX_PRESENTER_GAZE = 6;
+/** Past this the presenter holds still long enough to name it. */
+export const INTERVIEW_FREEZE_WARN_SEC = 6;
+/** An off-screen line's length before synthesis, at a conversation's 19 characters a second. */
+export const INTERVIEW_CHARS_PER_SEC = 19;
+/** The conversation's pauses, cut down to a tenth of a second unless pause_trim names others: an interview answers without waiting. */
+export const INTERVIEW_PAUSE_TRIM = Object.freeze({ sentence_end_s: 0.1, comma_s: 0.1, mid_phrase_s: 0.1 });
+/** The off-screen voice when none is named, never the presenter's own. */
+export const DEFAULT_INTERVIEW_VOICE = "en_male_mark";
+export const SECOND_INTERVIEW_VOICE = "en_female_cassidy";
+/** The off-screen speaker's word ranges in script order, adjacent turns joined; a string names the first turn that does not resolve or overlaps. */
+export function interviewTurnRanges(script, turns) {
+    const tokens = lexicalTokens(script), ranges = [];
+    for (const [index, turn] of turns.entries()) {
+        const range = layerWordRange(tokens, { id: "turn", anchor: turn.anchor, cover_words: turn.cover_words });
+        if (typeof range === "string")
+            return { index, message: range };
+        const other = ranges.find(item => item.startWord < range.coverWord && range.startWord < item.coverWord);
+        if (other)
+            return { index, message: `overlaps turn ${other.index}` };
+        ranges.push({ ...range, index });
+    }
+    const sorted = ranges.sort((a, b) => a.startWord - b.startWord), joined = [];
+    for (const { startWord, coverWord } of sorted) {
+        const last = joined.at(-1);
+        if (last && last.coverWord === startWord)
+            last.coverWord = coverWord;
+        else
+            joined.push({ startWord, coverWord });
+    }
+    return joined;
+}
+/** The script cut into the lines of the conversation, at word boundaries with each word's punctuation kept, in order. */
+export function interviewTexts(script, turns) {
+    const total = lexicalTokens(script).length, cuts = new Set();
+    for (const turn of turns) {
+        cuts.add(turn.startWord);
+        cuts.add(turn.coverWord);
+    }
+    const boundaries = [...cuts].filter(word => word > 0 && word < total).sort((a, b) => a - b);
+    const pieces = splitAtWords(script, boundaries);
+    let at = 0;
+    return pieces.map((text, index) => {
+        const startWord = at, coverWord = boundaries[index] ?? total;
+        at = coverWord;
+        const speaker = turns.some(turn => turn.startWord <= startWord && startWord < turn.coverWord) ? "off_screen" : "presenter";
+        return { speaker, text, startWord, coverWord };
+    });
+}
+/** A conversation's pace before synthesis (#991): each line takes a start and a time per word, a short answer reading slower than narration. */
+export const INTERVIEW_LINE_SEC = 0.43;
+export const INTERVIEW_WORD_SEC = 0.39;
+/** An interview's estimated length and the presenter's share of it, line by line. */
+export function interviewSecondsEstimate(script, turns) {
+    let totalSec = 0, presenterSec = 0;
+    for (const line of interviewTexts(script, turns)) {
+        const seconds = INTERVIEW_LINE_SEC + INTERVIEW_WORD_SEC * (line.coverWord - line.startWord);
+        totalSec += seconds;
+        if (line.speaker === "presenter")
+            presenterSec += seconds;
+    }
+    return { totalSec, presenterSec };
+}
+/** The script split before each lexical word in `boundaries`: whole whitespace chunks where possible, else inside one at the shortest prefix
+ *  that holds exactly the words before the cut. */
+function splitAtWords(script, boundaries) {
+    const chunks = script.split(/(\s+)/u), pieces = [];
+    let current = "", words = 0, next = 0;
+    for (const chunk of chunks) {
+        if (/^\s*$/u.test(chunk)) {
+            current += chunk;
+            continue;
+        }
+        let rest = chunk;
+        let count = lexicalTokens(rest).length;
+        while (next < boundaries.length && words + count > boundaries[next]) {
+            const need = boundaries[next] - words;
+            if (need <= 0) {
+                pieces.push(current);
+                current = "";
+            }
+            else {
+                // The longest such prefix, so the punctuation after the last word stays with it.
+                const cut = [...Array(rest.length).keys()].map(i => i + 1).findLast(p => lexicalTokens(rest.slice(0, p)).length === need &&
+                    lexicalTokens(rest.slice(p)).length === count - need);
+                pieces.push(current + rest.slice(0, cut));
+                current = "";
+                rest = rest.slice(cut);
+                words += need;
+                count -= need;
+            }
+            next++;
+        }
+        current += rest;
+        words += count;
+    }
+    pieces.push(current);
+    return pieces.map(piece => piece.trim());
+}
+/** Each lexical word's speaker. */
+export function wordSpeakers(total, turns) {
+    return Array.from({ length: total }, (_, word) => turns.some(turn => turn.startWord <= word && word < turn.coverWord) ? "off_screen" : "presenter");
+}
+/** The presenter's gaze on each lexical word: the interview's own, else camera, then each presenter_gaze item on its words. */
+export function wordGazes(script, input) {
+    const tokens = lexicalTokens(script), gazes = tokens.map(() => input.interview?.gaze ?? "camera");
+    for (const item of input.presenter_gaze ?? []) {
+        const range = layerWordRange(tokens, { id: "gaze", anchor: item.anchor, cover_words: item.cover_words });
+        if (typeof range === "string")
+            continue;
+        for (let word = range.startWord; word < range.coverWord; word++)
+            gazes[word] = item.gaze;
+    }
+    return gazes;
+}
+/** Every view of the actor the run needs, the main one first. */
+export function gazesNeeded(input) {
+    return [...new Set([input.interview?.gaze ?? "camera", ...(input.presenter_gaze ?? []).map(item => item.gaze)])];
+}
+/** The presenter's takes before timing: each run of words on screen is one, and a change of gaze inside a run starts another. */
+export function presenterTakeCount(script, input) {
+    const tokens = lexicalTokens(script), turns = input.interview ? interviewTurnRanges(script, input.interview.turns) : [];
+    if (!Array.isArray(turns))
+        return 0;
+    const covered = new Set();
+    for (const insert of input.inserts ?? []) {
+        const range = layerWordRange(tokens, insert);
+        if (typeof range !== "string")
+            for (let word = range.startWord; word < range.coverWord; word++)
+                covered.add(word);
+    }
+    const speakers = wordSpeakers(tokens.length, turns), gazes = wordGazes(script, input);
+    let takes = 0;
+    for (let word = 0; word < tokens.length; word++) {
+        const shown = speakers[word] === "presenter" && !covered.has(word);
+        const before = word > 0 && speakers[word - 1] === "presenter" && !covered.has(word - 1);
+        if (shown && (!before || gazes[word] !== gazes[word - 1]))
+            takes++;
+    }
+    return takes;
+}
+/** The one model that speaks a conversation in one request. */
+export const INTERVIEW_TTS_MODEL = "eleven_v4";
+/** Every refusal of `interview` and `presenter_gaze` before money, named by path. */
+export function interviewRefusals(input) {
+    const { interview } = input;
+    if (interview === undefined && input.presenter_gaze === undefined)
+        return [];
+    if (input.script === undefined || input.segments !== undefined || input.call !== undefined) {
+        const field = interview ? "interview" : "presenter_gaze";
+        return [{ path: [field], message: `${field} needs script and cannot be combined with segments or call` }];
+    }
+    const refusals = [], tokens = lexicalTokens(input.script);
+    let turns = [];
+    if (interview) {
+        const ranges = interviewTurnRanges(input.script, interview.turns);
+        if (!Array.isArray(ranges))
+            refusals.push({ path: ["interview", "turns", ranges.index, "anchor"], message: ranges.message });
+        else {
+            turns = ranges;
+            if (turns.reduce((sum, turn) => sum + turn.coverWord - turn.startWord, 0) === tokens.length) {
+                refusals.push({ path: ["interview", "turns"], message: "every word is the off-screen speaker's: the presenter needs words" });
+            }
+        }
+        // An actor_id's gender is the pin's, so admission checks its default voice (#972 I2); an unknown gender speaks the default actor's voice.
+        const presenter = input.actor_id === undefined || input.voice !== undefined
+            ? interviewPresenterVoice(input, input.image === undefined ? undefined : input.actor_gender) : undefined;
+        if (interview.off_screen?.voice !== undefined && interview.off_screen.voice === presenter) {
+            refusals.push({ path: ["interview", "off_screen", "voice"], message: INTERVIEW_SHARED_VOICE_REFUSAL });
+        }
+        if (input.tts_model !== undefined && input.tts_model !== INTERVIEW_TTS_MODEL) {
+            refusals.push({ path: ["tts_model"], message: `an interview speaks both voices as one conversation on ${INTERVIEW_TTS_MODEL}: omit tts_model or pass ${INTERVIEW_TTS_MODEL}` });
+        }
+        if (interview.listening === "live") {
+            refusals.push({ path: ["interview", "listening"], message: "listening live is not offered yet: omit listening, and the presenter holds still while the off-screen speaker talks" });
+        }
+        if (interview.off_screen?.caption !== undefined && input.captions !== true) {
+            refusals.push({ path: ["interview", "off_screen", "caption"], message: "interview.off_screen.caption requires captions=true: it styles the off-screen speaker's captions" });
+        }
+        if (interview.gaze !== undefined && interview.gaze !== "camera" && input.actor_id === undefined) {
+            refusals.push({ path: ["interview", "gaze"], message: "interview.gaze needs actor_id; list_actors shows each actor's views" });
+        }
+    }
+    const off = wordSpeakers(tokens.length, turns), gazed = [];
+    for (const [index, item] of (input.presenter_gaze ?? []).entries()) {
+        if (input.actor_id === undefined) {
+            refusals.push({ path: ["presenter_gaze", index], message: `presenter_gaze[${index}]: needs actor_id; list_actors shows each actor's views` });
+            continue;
+        }
+        const range = layerWordRange(tokens, { id: "gaze", anchor: item.anchor, cover_words: item.cover_words });
+        if (typeof range === "string") {
+            refusals.push({ path: ["presenter_gaze", index, "anchor"], message: range });
+            continue;
+        }
+        if (off.slice(range.startWord, range.coverWord).includes("off_screen")) {
+            refusals.push({ path: ["presenter_gaze", index, "anchor"], message: "the presenter looks where they speak: these words are the off-screen speaker's" });
+        }
+        if (gazed.some(other => other.startWord < range.coverWord && range.startWord < other.coverWord)) {
+            refusals.push({ path: ["presenter_gaze", index, "anchor"], message: "overlaps an earlier presenter_gaze item: one gaze holds a word" });
+        }
+        gazed.push(range);
+    }
+    if (interview && input.captions === true) {
+        for (const [index, item] of (input.caption_emphasis ?? []).entries()) {
+            const quote = typeof item === "string" ? item : item.quote;
+            if (quoteOccurrences(tokens, quote).some(match => off.slice(match.startWord, match.endWord).includes("off_screen"))) {
+                refusals.push({ path: ["caption_emphasis", index], message: `"${quote}" is spoken off screen; emphasis marks the presenter's words` });
+            }
+        }
+    }
+    if (!refusals.length) {
+        const takes = presenterTakeCount(input.script, input), cap = interview ? MAX_INTERVIEW_TAKES : undefined;
+        if (cap !== undefined && takes > cap) {
+            refusals.push({ path: ["interview"], message: `the presenter appears in ${takes} takes, more than ${cap}; merge answers or drop a change of gaze` });
+        }
+    }
+    return refusals;
+}
+/** What an interview does differently from what was asked, named before money (rule 3). */
+export function interviewWarnings(input) {
+    const interview = input.interview;
+    if (typeof input.script !== "string" || !interview || !Array.isArray(interview.turns))
+        return [];
+    const turns = interviewTurnRanges(input.script, interview.turns);
+    if (!Array.isArray(turns))
+        return [];
+    const warnings = [];
+    const lines = interviewTexts(input.script, turns).filter(line => line.speaker === "off_screen");
+    const longest = Math.max(0, ...lines.map(line => line.text.length / INTERVIEW_CHARS_PER_SEC));
+    if (longest > INTERVIEW_FREEZE_WARN_SEC) {
+        warnings.push(`the presenter holds still for about ${longest.toFixed(1)} s while the off-screen speaker talks`);
+    }
+    if (turns[0]?.startWord === 0)
+        warnings.push("the opening question freezes the presenter on the first frame of their first answer");
+    if (input.voice_pace !== undefined) {
+        warnings.push("voice_pace does not change an interview: both voices speak as one conversation at their own pace; list_voices names each voice's words_per_second");
+    }
+    return warnings;
+}
+export const INTERVIEW_SHARED_VOICE_REFUSAL = "the off-screen speaker needs a voice other than the presenter's";
+/** The presenter's voice by name: the named one, else its model's default for the gender; a raw voice_id has no name. */
+export function interviewPresenterVoice(input, gender) {
+    if (input.voice_id !== undefined)
+        return undefined;
+    return input.voice ?? defaultVoiceOf(input.tts_model, gender).name;
+}
+/** The off-screen voice: the named one, else the default, kept off the presenter's voice; the server compares by vendor id (#987). */
+export function interviewOffScreenVoice(interview, speaksPresenterVoice) {
+    return interview.off_screen?.voice ?? (speaksPresenterVoice(DEFAULT_INTERVIEW_VOICE) ? SECOND_INTERVIEW_VOICE : DEFAULT_INTERVIEW_VOICE);
+}
+//# sourceMappingURL=ugc-interview.js.map

package/dist/ugc-interview.js.map

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

package/dist/ugc-layers.d.ts

@@ -1,8 +1,15 @@
+import { CAPTION_POSITION_VERTICAL } from "./caption-geometry.js";
+import { type CaptionPlace, type Place, type PresenterPlace } from "./scene-place.js";
 import type { WordTiming } from "./tts-backend.js";
 export declare const OVERLAY_POSITIONS: readonly ["top_left", "top_right", "bottom_left", "bottom_right", "top", "bottom"];
 export type OverlayPosition = (typeof OVERLAY_POSITIONS)[number];
-export declare const LAYER_ENTERS: readonly ["cut", "fade", "slide", "tilt_in"];
+export declare const LAYER_ENTERS: readonly ["cut", "fade", "slide", "tilt_in", "pop", "scale_up"];
 export type LayerEnter = (typeof LAYER_ENTERS)[number];
+/** How an overlay leaves (#973 S3); absent is a cut, as every overlay before it. */
+export declare const LAYER_EXITS: readonly ["cut", "fade", "pop_out", "slide"];
+export type LayerExit = (typeof LAYER_EXITS)[number];
+/** The most an overlay's appearance moves off its first word, in seconds. */
+export declare const MAX_ENTER_OFFSET_S = 0.5;
 export declare const LAYOUT_WINDOW_KINDS: readonly ["split", "card"];
 export type LayoutWindowKind = (typeof LAYOUT_WINDOW_KINDS)[number];
 export declare const INSERT_TRANSITIONS: readonly ["cut", "wipe", "flash", "zoom"];
@@ -57,24 +64,99 @@ export interface LayerRefusal {
     path: (string | number)[];
     message: string;
 }
+/** An overlay at a preset position or at a place: exactly one of the two. */
+/** A template drawn over the presenter carries `own`, the rect its kind draws (#973 S4): its box without a place, its shape scaled whole with one. */
+export type PlaceableOverlay = AnchoredItem & {
+    position?: OverlayPosition | undefined;
+    place?: Place | undefined;
+    own?: LayerRect | undefined;
+};
+/** The templates a scene adds to the overlays for one framing; templates/index.ts gives them, which this module cannot import. */
+export type SceneExtras = (framing: PresenterFraming) => readonly PlaceableOverlay[];
 export interface LayerCheckInput {
     script: string;
     aspect_ratio?: string | undefined;
+    presenter_framing?: PresenterFraming | undefined;
+    actor_id?: string | undefined;
     inserts?: readonly AnchoredItem[] | undefined;
-    overlays?: readonly (AnchoredItem & {
-        position: OverlayPosition;
-    })[] | undefined;
+    overlays?: readonly PlaceableOverlay[] | undefined;
     layout_windows?: readonly (AnchoredItem & {
         layout: LayoutWindowKind;
     })[] | undefined;
+    captions?: boolean | undefined;
+    caption_style?: string | undefined;
+    caption_position?: keyof typeof CAPTION_POSITION_VERTICAL | undefined;
+    caption_place?: CaptionPlace | undefined;
+    presenter_place?: PresenterPlace | undefined;
+}
+/** What a placed overlay may stand by at admission: the planned face and, with captions, the tallest page's box where they sit (#973 S2). */
+export interface AdmissionScene {
+    face: LayerRect;
+    captions?: LayerRect | undefined;
 }
-/** Every refusal of overlays and layout windows against the script, named by path; empty when they render. */
-export declare function layerRefusals(input: LayerCheckInput): LayerRefusal[];
+export declare function admissionScene(input: Pick<LayerCheckInput, "captions" | "caption_style" | "caption_position" | "caption_place" | "presenter_place">, aspectRatio: string, framing: PresenterFraming): AdmissionScene;
+/** The sides a place may take next to the captions: a page grows sideways with its words. */
+export declare const CAPTION_SIDES: readonly string[];
+/** The framings an admitted run may render: a wide request may render close when the actor has no wide view; wide needs an actor and 9:16. */
+export declare function admissionFramings(input: {
+    aspect_ratio?: string | undefined;
+    presenter_framing?: unknown;
+    actor_id?: unknown;
+}): PresenterFraming[];
+/** How many layers a place leans on through `{ layer }`, Infinity in a loop or past a missing or preset anchor; a template is an anchor as drawn. */
+export declare function placeDepth(overlays: readonly PlaceableOverlay[], id: string, seen?: ReadonlySet<string>): number;
+/** A template's own rect in pixels: the shape its place scales it to. */
+export declare const ownPixels: (own: LayerRect, canvas: {
+    width: number;
+    height: number;
+}) => {
+    width: number;
+    height: number;
+};
+/** Each layer's box at admission, by id: a preset's footprint, a template's own rect, a place resolved on the usual face (a template's shape scaled
+ *  whole into it); a place on a broken chain has none. */
+export declare function overlayFootprints(overlays: readonly PlaceableOverlay[], aspectRatio: string, framing: PresenterFraming, scene?: AdmissionScene): Map<string, LayerRect>;
+/** Over this share of the face's box a placed overlay covers the face; under it, it touches the edge (#973 S1). */
+export declare const FACE_COVER_SHARE = 0.1;
+/** Under this share of the frame's short side an overlay would not read. */
+export declare const OVERLAY_MIN_SIDE = 0.03;
+/** Over this share of the frame an overlay hides a presenter who is still billed. */
+export declare const OVERLAY_COVERED_PRESENTER = 0.6;
+/** Admission warnings for placed overlays and templates: a box at the face's edge, and a box that hides most of a billed presenter. */
+export declare function placeWarnings(input: {
+    overlays?: unknown;
+    aspect_ratio?: unknown;
+    presenter_framing?: unknown;
+    actor_id?: unknown;
+}, extras?: SceneExtras): string[];
+/** The refusals a placed overlay or template meets on its anchor and on its box in every framing, at the path `at` names (#973 S1, S4). */
+export declare function placedRefusals(what: "overlay" | "template", item: PlaceableOverlay & {
+    place: Place;
+}, range: WordRange, at: (...rest: string[]) => (string | number)[], scene: {
+    items: readonly PlaceableOverlay[];
+    tokens: readonly string[];
+    footprints: readonly {
+        boxes: ReadonlyMap<string, LayerRect>;
+        face: LayerRect;
+    }[];
+    canvas: {
+        width: number;
+        height: number;
+    };
+}): LayerRefusal[];
+/** Every refusal of overlays and layout windows against the script, named by path; empty when they render. `extras` adds the run's templates. */
+export declare function layerRefusals(input: LayerCheckInput, extras?: SceneExtras): LayerRefusal[];
 export interface LayerFrames {
     id: string;
     startFrame: number;
     endFrame: number;
 }
+/** Each overlay's first frame moved by its enter_offset_s (#973 S3), inside its own frames and the video. Overlays that left on or before its first */
+/** word and still show then leave as it enters, so no more overlays share the screen than their words allow. */
+export declare function offsetOverlayFrames(frames: readonly LayerFrames[], overlays: readonly {
+    id: string;
+    enter_offset_s?: number | undefined;
+}[], fps: number, warnings: string[]): LayerFrames[];
 /** Frames of each word range on the run's narration, by the rule inserts follow: a range ends where its first uncovered word starts. */
 export declare function resolveLayerFrames(input: {
     tokens: readonly string[];