@allyhub/sdk 0.1.0-alpha.8 → 0.2.0-next.0

package/dist/parts.d.ts

@@ -1,8 +1,20 @@
-import { type FootageLayer, type FootageOptions, type LayerSpec, type MediaRef, type PartAnchors, type PartSpec, type RoomTone, type SaySpeech, type SoundSpec, type SpeechSpec, type TakeSpeech, type TransitionInput, type WordRef } from "@allyhub/engine/stage";
-export type { BoxKey, FootageBackground, FootageBox, PerOrient, PunchIn, Pullback, Reframe, FootageLayer, FootageOptions, GraphicLayer, LayerSpec, LayerTiming, PartAnchors, PartSpec, Rect, RoomTone, SaySpeech, SoundSpec, SpeechSpec, TakeSpeech, Direction, TransitionChannel, TransitionInput, TransitionPicture, TransitionSpec, TransitionType, WordRef, } from "@allyhub/engine/stage";
+import { type VoiceSetting, type FootageLayer, type FootageOptions, type LayerSpec, type MediaRef, type PartAnchors, type PartSpec, type RoomTone, type SaySpeech, type SoundSpec, type SpeechSpec, type TakeSpeech, type TransitionInput, type VideoSpeech, type WordRef } from "@allyhub-next/video-core";
+import type { Written } from "./written.js";
+import { type VideoItem } from "./piece.js";
+export type { BoxKey, FootageBackground, FootageBox, PerOrient, PunchIn, Pullback, Reframe, FootageLayer, FootageOptions, GraphicLayer, LayerSpec, LayerSpec as Layer, LayerTiming, PartAnchors, PartSpec, Rect, RoomTone, SaySpeech, SoundSpec, SpeechSpec, TakeSpeech, VideoSpeech, Direction, TransitionChannel, TransitionInput, TransitionPicture, TransitionSpec, TransitionType, WordRef, } from "@allyhub-next/video-core";
 export interface PartOptions {
-    /** Unique in the output; stable across combos and formats. */
+    /** Unique in the output; stable across combos. */
     key: string;
+    /**
+     * Its name for people: the timeline's scenes, a note's part. Default
+     * its largest text at its still (text every part shows left out).
+     */
+    title?: string;
+    /**
+     * The slot this part fills, when the piece has slots: default its key,
+     * when the key is the name of one of the combo's slots.
+     */
+    slot?: string;
     /** What the part says: take(file) or say(text). Without it the part is silent. */
     speech?: SpeechSpec;
     /**
@@ -27,7 +39,7 @@ export interface PartOptions {
      * before its end.
      */
     still?: WordRef | ((dur: number) => number);
-    /** Labels for the matrix's rules (P2). */
+    /** Words for the part beside its key: `allyhub reference compare` matches parts to a reference's sections by them. */
     tags?: string[];
     /**
      * J and L cuts: `before` seconds of the speech play under the previous
@@ -41,7 +53,8 @@ export interface PartOptions {
      * Sound effects: `[{ at: "free", sound: "pop" }, { at: 1.2, sound:
      * whoosh, gainDb: -4 }]`, each at a word reference or seconds, a name of
      * the look's sounds (or the built-in whoosh, tick, pop) or an audio
-     * file. Nothing plays unless it is placed.
+     * file. Nothing plays unless it is placed. `shape: { filter, eq,
+     * compress }` shapes one before it is levelled (as `music`'s).
      */
     sounds?: SoundSpec[];
     /**
@@ -65,9 +78,32 @@ export interface PartOptions {
      * only: place a sound with `sounds`.
      */
     transition?: TransitionInput;
+    /**
+     * How this part's speech was recorded, over the video's `mic`: a
+     * setup's name ("studio", "phone", "lav"), its options, or false for the
+     * voice as it is.
+     */
+    mic?: VoiceSetting;
+    /**
+     * The part's own grade, an ffmpeg filter chain on its picture before the
+     * camera's marks and the video's post: a clip's white balance and
+     * exposure (`{ filter: "colortemperature=temperature=4800,eq=brightness=0.03" }`).
+     * It is given the picture opaque, as planar RGB, its `t` the film's time.
+     */
+    post?: {
+        filter: string;
+    };
+    /**
+     * dB this part's speech is turned up (or down) after it is recorded, as
+     * an editor's clip volume: the recording's compressor does not even it
+     * out, and its room tone moves with it. From -40 to 24; default 0.
+     */
+    speechGainDb?: number;
 }
 /** A part of a video, or a page of a paged output. */
-export declare function part(opts: PartOptions): PartSpec;
+export type PartFn = (opts: PartOptions) => PartSpec;
+/** part() for the module `at` names: its sounds' paths are from its folder. */
+export declare const partFor: (at: Written) => PartFn;
 /** A take, narrowed with range() or saying(). */
 export interface Take extends TakeSpeech {
     /**
@@ -83,9 +119,10 @@ export interface Take extends TakeSpeech {
      */
     saying(text: string): Take;
     /**
-     * A cut list: a JSON file relative to the piece (`./edits/<name>.json`)
-     * removing word ranges, sounds and long pauses; the preview's
-     * transcript editor writes it. The file may not exist yet.
+     * A cut list: a JSON file relative to the file that names it
+     * (`./edits/<name>.json`) removing word ranges, sounds and long pauses;
+     * the preview's transcript editor writes it. One that is not there is
+     * AK-T005 (the take would play uncut): `{ "remove": [] }` removes nothing.
      */
     edits(path: string): Take;
     /**
@@ -106,28 +143,65 @@ export interface Take extends TakeSpeech {
      * as recorded, `gainDb` sets its gain yourself.
      */
     roomTone(tone: false | RoomTone): Take;
+    /**
+     * Plays it `times` as fast, its pitch kept (ffmpeg's atempo in the
+     * render, the browser's in the preview): 1.1 is 10 % faster, and its
+     * words, the part's length and everything timed by them follow. From
+     * 0.5 to 2. The file is not changed. A part showing the take's own
+     * picture (footage() without a file) plays at speed 1.
+     */
+    speed(times: number): Take;
+}
+export interface TakeFn {
+    /**
+     * Speech from a recording, audio or video, with its word times beside it
+     * (`<name>.words.json`: allyhub words <file> makes it). An import, or
+     * a path relative to the module that names it.
+     */
+    (file: MediaRef): Take;
+    /**
+     * A stretch of another video item of the project, a source with a clock
+     * of its own: `take(scene).range("@turn", "@press")` with the item's
+     * piece imported (`import scene from "../scene/video"`). The part lasts
+     * the stretch exactly, hears its sound and says its words; `footage()`
+     * draws its picture in sync, from `camera` when it shows a 3D scenery.
+     */
+    (video: VideoItem): VideoTake;
+}
+/** take() for the module `at` names: a path is from its folder. */
+export declare function takeFor(at: Written): TakeFn;
+/** A video item as a take, narrowed with range(). */
+export interface VideoTake extends VideoSpeech {
+    /**
+     * The stretch from `from` to `to`: seconds of its clock, an anchor of
+     * one of its parts ("@turn", "@/turn", "@turn+0.2") or a part's key;
+     * without `to`, to its end.
+     */
+    range(from: number | string, to?: number | string): VideoTake;
 }
-/**
- * Speech from a recording, audio or video, with its word times beside it
- * (`<name>.words.json`: allyhub transcribe <file> makes it). An import, or a
- * path relative to the piece's file.
- */
-export declare function take(file: MediaRef): Take;
 export interface SayOptions {
     /** The voice tool's voice id. */
     voice?: string;
     /** The voice tool; default tts-elevenlabs-multilingual-v2. */
     tool?: string;
     /**
-     * More input for the voice tool, as plain JSON (`allyhub tools describe
-     * <tool>` lists what it takes), such as { stability: 0.4 }. Passed with
-     * the text and voice; part of the file's hash, so changing it makes a
-     * new file.
+     * More input for the voice tool, as plain JSON: the fields its schema
+     * takes besides the text and the voice (`allyhub help ai <tool>`
+     * lists them; the ElevenLabs voices take `outputFormat`, such as
+     * "mp3_44100_128", and nothing else). The server refuses a field the
+     * schema does not have. Passed with the text and voice; part of the
+     * file's hash, so changing it makes a new file.
      */
     params?: Record<string, unknown>;
+    /**
+     * How fast the file plays, its pitch kept, as take(…).speed does: 1.1 is
+     * 10 % faster, from 0.5 to 2. AllyHub plays the same file faster; the
+     * voice tool is not asked, so it makes no new file.
+     */
+    speed?: number;
 }
 /**
- * Text to speech: `allyhub voice generate` makes the file
+ * Text to speech: `allyhub voice` makes the file
  * (assets/media/gen/say/<hash>) with its words; the check reports a say without
  * one (AK-T002). Text from s(key) is read aloud as the message's `speak`.
  */
@@ -136,5 +210,7 @@ export declare function say(text: string, opts?: SayOptions): SaySpeech;
  * A video on the part: footage("./broll.mp4", { at: "inbox", dur: 1.5 }).
  * Without a file it is the part's own take, in sync with its speech.
  */
-export declare function footage(file?: MediaRef | FootageOptions, opts?: FootageOptions): FootageLayer;
+export type FootageFn = (file?: MediaRef | VideoItem | FootageOptions, opts?: FootageOptions) => FootageLayer;
+/** footage() for the module `at` names: its paths are from its folder. */
+export declare const footageFor: (at: Written) => FootageFn;
 //# sourceMappingURL=parts.d.ts.map

package/dist/parts.js

@@ -1,414 +1,2 @@
-import { BACKDROP_BLUR_MAX, EASES, LAYER_BRAND, MATTE_FEATHER_MAX, MATTE_SHRINK_MAX, MEDIA_BRAND, ORIENT_KEYS, PART_BRAND, SPEECH_BRAND, isPerOrient, notJson, partAnchorsProblem, transitionProblem, } from "@allyhub/engine/stage";
-/** A part of a video, or a page of a paged output. */
-export function part(opts) {
-    const { key, layers, ...rest } = opts;
-    if (typeof key !== "string" || key === "") {
-        throw new Error("part: every part needs a key");
-    }
-    for (const side of ["before", "after"]) {
-        const x = opts.overlap?.[side];
-        if (x !== undefined && (!Number.isFinite(x) || x < 0 || x > 10)) {
-            throw new Error(`part ${key}: overlap.${side} is seconds from 0 to 10, not ${String(x)}`);
-        }
-    }
-    for (const [i, s] of (opts.sounds ?? []).entries()) {
-        const ok = typeof s === "object" &&
-            (typeof s.at === "string" || typeof s.at === "number") &&
-            (typeof s.sound === "string" ||
-                (typeof s.sound === "object" && "path" in s.sound));
-        if (!ok) {
-            throw new Error(`part ${key}: sounds[${String(i)}] is { at, sound, gainDb? }: at a word reference or seconds, sound a name or an audio file`);
-        }
-        if (s.gainDb !== undefined &&
-            (!Number.isFinite(s.gainDb) || s.gainDb < -60 || s.gainDb > 24)) {
-            throw new Error(`part ${key}: sounds[${String(i)}].gainDb is dB from -60 to 24, not ${String(s.gainDb)}`);
-        }
-    }
-    if (opts.anchors !== undefined) {
-        const bad = partAnchorsProblem(opts.anchors);
-        if (bad !== undefined) {
-            throw new Error(`part ${key}: anchors ${bad}`);
-        }
-    }
-    if (opts.transition !== undefined) {
-        const bad = transitionProblem(opts.transition);
-        if (bad !== undefined) {
-            throw new Error(`part ${key}: transition ${bad}`);
-        }
-    }
-    return { [PART_BRAND]: true, key, layers: layers ?? [], ...rest };
-}
-function makeTake(spec) {
-    const base = { [SPEECH_BRAND]: true, ...spec };
-    return {
-        ...base,
-        range(from, to) {
-            const { line: _line, from: _f, to: _t, ...rest } = spec;
-            return makeTake({ ...rest, from, ...(to === undefined ? {} : { to }) });
-        },
-        saying(text) {
-            const { from: _from, to: _to, ...rest } = spec;
-            return makeTake({ ...rest, line: text });
-        },
-        edits(path) {
-            if (typeof path !== "string" || !/\.json$/i.test(path)) {
-                throw new Error(`take(…).edits(path): a JSON file relative to the piece, such as "./edits/host.json" (not ${JSON.stringify(path)})`);
-            }
-            return makeTake({ ...spec, editsFile: path });
-        },
-        denoise(db = 12) {
-            if (!Number.isFinite(db) || db <= 0 || db > 97) {
-                throw new Error(`take(…).denoise(db): the noise reduction in dB, over 0 and up to 97 (not ${String(db)})`);
-            }
-            return makeTake({ ...spec, denoiseDb: db });
-        },
-        roomTone(tone) {
-            if (tone === false)
-                return makeTake({ ...spec, room: false });
-            const what = "take(…).roomTone(tone): false, or { from, to, match, gainDb, limitDb, fade }";
-            if (typeof tone !== "object" || Array.isArray(tone)) {
-                throw new Error(`${what} (not ${JSON.stringify(tone)})`);
-            }
-            const { from, to, match, gainDb, limitDb, fade } = tone;
-            const extra = Object.keys(tone).filter((k) => !["from", "to", "match", "gainDb", "limitDb", "fade"].includes(k));
-            if (extra.length > 0) {
-                throw new Error(`${what}: it has no ${extra.join(", ")}`);
-            }
-            if (from !== undefined || to !== undefined) {
-                if (from === undefined ||
-                    to === undefined ||
-                    !Number.isFinite(from) ||
-                    !Number.isFinite(to) ||
-                    from < 0 ||
-                    to - from < 0.05) {
-                    throw new Error(`${what}: from and to are seconds of the file, both given, at least 0.05 s apart`);
-                }
-            }
-            if (match !== undefined && typeof match !== "boolean") {
-                throw new Error(`${what}: match is true or false`);
-            }
-            if (gainDb !== undefined &&
-                (!Number.isFinite(gainDb) || gainDb < -60 || gainDb > 24)) {
-                throw new Error(`${what}: gainDb is dB from -60 to 24, not ${String(gainDb)}`);
-            }
-            if (limitDb !== undefined &&
-                (!Number.isFinite(limitDb) || limitDb < 0 || limitDb > 60)) {
-                throw new Error(`${what}: limitDb is dB from 0 to 60, not ${String(limitDb)}`);
-            }
-            if (fade !== undefined &&
-                (!Number.isFinite(fade) || fade < 0 || fade > 1)) {
-                throw new Error(`${what}: fade is seconds from 0 to 1, not ${String(fade)}`);
-            }
-            return makeTake({
-                ...spec,
-                room: {
-                    ...(from === undefined || to === undefined ? {} : { from, to }),
-                    ...(match === undefined ? {} : { match }),
-                    ...(gainDb === undefined ? {} : { gainDb }),
-                    ...(limitDb === undefined ? {} : { limitDb }),
-                    ...(fade === undefined ? {} : { fade }),
-                },
-            });
-        },
-    };
-}
-/**
- * Speech from a recording, audio or video, with its word times beside it
- * (`<name>.words.json`: allyhub transcribe <file> makes it). An import, or a
- * path relative to the piece's file.
- */
-export function take(file) {
-    return makeTake({ kind: "take", file });
-}
-/**
- * Text to speech: `allyhub voice generate` makes the file
- * (assets/media/gen/say/<hash>) with its words; the check reports a say without
- * one (AK-T002). Text from s(key) is read aloud as the message's `speak`.
- */
-export function say(text, opts = {}) {
-    const params = opts.params;
-    if (params !== undefined) {
-        if (typeof params !== "object" ||
-            params === null ||
-            Array.isArray(params)) {
-            throw new Error("say() params is not an object: give the voice tool's extra input as { name: value }.");
-        }
-        const bad = notJson(params, "params");
-        if (bad !== undefined) {
-            throw new Error(`say() ${bad} is not plain JSON: use strings, finite numbers, booleans, null, arrays and plain objects.`);
-        }
-        for (const [key, instead] of [
-            ["text", "say()'s text"],
-            ["voiceId", "the voice option"],
-        ]) {
-            if (key in params) {
-                throw new Error(`say() params.${key} is not allowed: give it as ${instead}.`);
-            }
-        }
-    }
-    return {
-        [SPEECH_BRAND]: true,
-        kind: "say",
-        text,
-        ...(opts.voice === undefined ? {} : { voice: opts.voice }),
-        ...(opts.tool === undefined ? {} : { tool: opts.tool }),
-        ...(params && Object.keys(params).length > 0
-            ? { params: structuredClone(params) }
-            : {}),
-    };
-}
-const isMediaRef = (v) => typeof v === "string" ||
-    (typeof v === "object" && v !== null && (MEDIA_BRAND in v || "sha256" in v));
-const isFraction = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
-/** A point as fractions (0–1), or a thrown error naming the option. */
-function checkPoint(name, p) {
-    if (p === undefined)
-        return;
-    const ok = typeof p === "object" &&
-        p !== null &&
-        isFraction(p.x) &&
-        isFraction(p.y);
-    if (!ok) {
-        throw new Error(`footage() ${name} ${JSON.stringify(p)} is not a point { x, y } with each from 0 to 1.`);
-    }
-}
-/** Seconds over 0 and up to 5, or a thrown error naming the option. */
-function checkSeconds(name, v) {
-    if (v === undefined)
-        return;
-    if (typeof v !== "number" || !(v > 0) || v > 30) {
-        throw new Error(`footage() ${name} ${JSON.stringify(v)} is not seconds over 0 and up to 30.`);
-    }
-}
-function checkEase(name, v) {
-    if (v === undefined || EASES.includes(v))
-        return;
-    throw new Error(`footage() ${name} ${JSON.stringify(v)} is not one of ${EASES.map((e) => `"${e}"`).join(", ")}.`);
-}
-function checkReframe(r) {
-    if (r === undefined || r === "face" || r === "center")
-        return;
-    if (typeof r === "object" && r !== null && "face" in r) {
-        const o = r;
-        if (o.face !== true) {
-            throw new Error(`footage() reframe ${JSON.stringify(r)}: face is true, as in { face: true, faceY: 0.4 }.`);
-        }
-        if (o.faceY !== undefined && !isFraction(o.faceY)) {
-            throw new Error(`footage() reframe faceY ${JSON.stringify(o.faceY)} is not from 0 (the crop's top) to 1 (its bottom); 0.4 is a little above the middle.`);
-        }
-        return;
-    }
-    if (typeof r === "object" && r !== null && "x" in r) {
-        checkPoint("reframe", r);
-        return;
-    }
-    throw new Error(`footage() reframe ${JSON.stringify(r)} is not "face", { face: true, faceY }, "center" or a point { x, y }.`);
-}
-/**
- * A layer's `background`: its numbers in range, and a colour or an image,
- * not both (a colour leaves nothing to blur, dim or desaturate).
- */
-function checkBackground(b) {
-    if (b === undefined)
-        return;
-    if (typeof b !== "object" || b === null || Array.isArray(b)) {
-        throw new Error(`footage() background ${JSON.stringify(b)} is not an object such as { blur: 24 }, { dim: 0.4, desaturate: 1 }, { color: "#101418" } or { image: "./backdrop.jpg" }.`);
-    }
-    const o = b;
-    const known = [
-        "blur",
-        "dim",
-        "desaturate",
-        "color",
-        "image",
-        "feather",
-        "shrink",
-    ];
-    const other = Object.keys(o).find((k) => !known.includes(k));
-    if (other !== undefined) {
-        throw new Error(`footage() background has no option "${other}": it takes ${known.join(", ")}.`);
-    }
-    const num = (v) => typeof v === "number" && Number.isFinite(v);
-    if (o["blur"] !== undefined &&
-        !(num(o["blur"]) && o["blur"] >= 0 && o["blur"] <= BACKDROP_BLUR_MAX)) {
-        throw new Error(`footage() background blur ${JSON.stringify(o["blur"])} is not a number from 0 to ${String(BACKDROP_BLUR_MAX)}: the blur's standard deviation in px at 1080p (24 is a soft room).`);
-    }
-    for (const k of ["dim", "desaturate"]) {
-        if (o[k] !== undefined && !isFraction(o[k])) {
-            throw new Error(`footage() background ${k} ${JSON.stringify(o[k])} is not a number from 0 (as it is) to 1.`);
-        }
-    }
-    if (o["color"] !== undefined &&
-        (typeof o["color"] !== "string" || o["color"].trim() === "")) {
-        throw new Error(`footage() background color ${JSON.stringify(o["color"])} is not a CSS colour such as "#101418", "var(--ak-color-bg)" or "transparent".`);
-    }
-    if (o["image"] !== undefined && !isMediaRef(o["image"])) {
-        throw new Error(`footage() background image ${JSON.stringify(o["image"])} is not an image: a path relative to the piece, or an imported file.`);
-    }
-    if (o["color"] !== undefined && o["image"] !== undefined) {
-        throw new Error("footage() background takes a color or an image, not both.");
-    }
-    if (o["color"] !== undefined) {
-        const over = ["blur", "dim", "desaturate"].find((k) => o[k] !== undefined);
-        if (over !== undefined) {
-            throw new Error(`footage() background ${over} does nothing with a color, which replaces the background: leave one out.`);
-        }
-    }
-    if (o["feather"] !== undefined &&
-        !(num(o["feather"]) &&
-            o["feather"] >= 0 &&
-            o["feather"] <= MATTE_FEATHER_MAX)) {
-        throw new Error(`footage() background feather ${JSON.stringify(o["feather"])} is not a number from 0 to ${String(MATTE_FEATHER_MAX)}: the softness of the person's edge in px at 1080p (2 by default).`);
-    }
-    if (o["shrink"] !== undefined &&
-        !(num(o["shrink"]) && Math.abs(o["shrink"]) <= MATTE_SHRINK_MAX)) {
-        throw new Error(`footage() background shrink ${JSON.stringify(o["shrink"])} is not a number from −${String(MATTE_SHRINK_MAX)} to ${String(MATTE_SHRINK_MAX)}: how far the person's edge is pulled in, px at 1080p (4 by default).`);
-    }
-}
-/**
- * A box, or each box key, lies in the frame: a box is the part of the
- * frame the picture shows in, so one reaching past it would be cut to the
- * frame and a push-in written as a box larger than the frame would not move.
- */
-function checkBoxes(box) {
-    if (box === undefined || box === "full" || !Array.isArray(box))
-        return;
-    const rects = box.length > 0 && typeof box[0] === "object"
-        ? box.map((k) => k.box)
-        : [box];
-    const e = 1e-6;
-    for (const r of rects) {
-        if (r === "full" || !Array.isArray(r) || r.length !== 4)
-            continue;
-        const [x, y, w, h] = r;
-        if ([x, y, w, h].every((v) => typeof v === "number" && Number.isFinite(v)) &&
-            (x ?? 0) >= -e &&
-            (y ?? 0) >= -e &&
-            (w ?? 0) > 0 &&
-            (h ?? 0) > 0 &&
-            (x ?? 0) + (w ?? 0) <= 1 + e &&
-            (y ?? 0) + (h ?? 0) <= 1 + e) {
-            continue;
-        }
-        throw new Error(`footage() box ${JSON.stringify(r)} is not inside the frame: [x, y, width, height] are fractions of it, with x + width and y + height at most 1. A box is where the picture shows, so it cannot grow past the frame; for a slow push in use punchIn, eased in over its \`in\` seconds centred on \`at\` ({ at: 4, in: 8, until: 8, scale: 1.07, ease: "linear" } pushes in over the first 8 s), and for a slow pull out pullback ({ scale: 1.07, dur: 8 }).`);
-    }
-}
-/**
- * The values an option holds: the one value, or a per-frame-shape
- * object's ({ landscape, portrait, square, default }), whose keys are
- * checked.
- */
-function perOrient(name, v) {
-    if (v === undefined)
-        return [];
-    if (!isPerOrient(v))
-        return [v];
-    const keys = ORIENT_KEYS;
-    const unknown = Object.keys(v).filter((k) => !keys.includes(k));
-    if (unknown.length > 0) {
-        throw new Error(`footage() ${name} has ${unknown.map((k) => JSON.stringify(k)).join(", ")}, which is not a frame shape: a per-shape ${name} is { ${ORIENT_KEYS.join(", ")} } (each optional; an output takes the one for its orientation, else default).`);
-    }
-    return Object.values(v).filter((x) => x !== undefined);
-}
-/** A crop is a part of the source: [x, y, width, height] as fractions of it. */
-function checkCrop(crop) {
-    const e = 1e-6;
-    const r = Array.isArray(crop) ? crop : [];
-    const [x, y, w, h] = r;
-    if (r.length === 4 &&
-        typeof x === "number" &&
-        typeof y === "number" &&
-        typeof w === "number" &&
-        typeof h === "number" &&
-        [x, y, w, h].every((v) => Number.isFinite(v)) &&
-        x >= -e &&
-        y >= -e &&
-        w > 0 &&
-        h > 0 &&
-        x + w <= 1 + e &&
-        y + h <= 1 + e) {
-        return;
-    }
-    throw new Error(`footage() crop ${JSON.stringify(crop)} is not a part of the source: [x, y, width, height] are fractions of it, with x + width and y + height at most 1.`);
-}
-/**
- * A video on the part: footage("./broll.mp4", { at: "inbox", dur: 1.5 }).
- * Without a file it is the part's own take, in sync with its speech.
- */
-export function footage(file, opts = {}) {
-    const o = file !== undefined && !isMediaRef(file) ? file : opts;
-    if (o.speed !== undefined &&
-        (!Number.isFinite(o.speed) || o.speed <= 0 || o.speed > 16)) {
-        throw new Error(`footage() speed ${String(o.speed)} is not a number over 0 and up to 16 (1 is normal speed).`);
-    }
-    if (o.sharpen !== undefined &&
-        (!Number.isFinite(o.sharpen) || o.sharpen < 0 || o.sharpen > 1)) {
-        throw new Error(`footage() sharpen ${String(o.sharpen)} is not a number from 0 to 1 (0.3 is gentle).`);
-    }
-    checkReframe(o.reframe);
-    if (o.speaker !== undefined &&
-        (!Number.isInteger(o.speaker) || o.speaker < 0)) {
-        throw new Error(`footage() speaker ${String(o.speaker)} is not a face id (a whole number from 0, as allyhub index lists them).`);
-    }
-    for (const p of o.punchIn ?? []) {
-        const scale = typeof p === "object"
-            ? p.scale
-            : /@(\d*\.\d+)$/.exec(String(p))?.[1] !== undefined
-                ? Number(/@(\d*\.\d+)$/.exec(String(p))?.[1])
-                : undefined;
-        if (scale !== undefined && (!(scale > 1) || scale > 3)) {
-            throw new Error(`footage() punchIn scale ${String(scale)} is not over 1 and up to 3 (1.12 is a gentle punch-in).`);
-        }
-        if (typeof p === "object") {
-            checkSeconds("punchIn in", p.in);
-            checkSeconds("punchIn out", p.out);
-            checkEase("punchIn ease", p.ease);
-            checkPoint("punchIn center", p.center);
-        }
-    }
-    if (typeof o.pullback === "object") {
-        const { scale, dur } = o.pullback;
-        if (scale !== undefined && (!(scale > 1) || scale > 3)) {
-            throw new Error(`footage() pullback scale ${String(scale)} is not over 1 and up to 3 (1.12 is a gentle pullback).`);
-        }
-        if (dur !== undefined && (!(dur > 0) || dur > 10)) {
-            throw new Error(`footage() pullback dur ${String(dur)} is not seconds over 0 and up to 10.`);
-        }
-        checkEase("pullback ease", o.pullback.ease);
-        checkPoint("pullback center", o.pullback.center);
-    }
-    if (o.shape !== undefined &&
-        o.shape !== "rect" &&
-        o.shape !== "circle") {
-        throw new Error(`footage() shape ${JSON.stringify(o.shape)} is not "rect" or "circle".`);
-    }
-    if (o.radius !== undefined &&
-        (typeof o.radius !== "number" || !Number.isFinite(o.radius) || o.radius < 0)) {
-        throw new Error(`footage() radius ${JSON.stringify(o.radius)} is not a number from 0: the corners' radius, px at 1080p (24 is a soft card corner).`);
-    }
-    if (o.radius !== undefined && o.radius > 0 && o.shape === "circle") {
-        throw new Error('footage(): radius rounds the corners of a rect; shape "circle" has none. Use one of them.');
-    }
-    const boxes = perOrient("box", o.box);
-    for (const b of boxes)
-        checkBoxes(b);
-    for (const c of perOrient("crop", o.crop))
-        checkCrop(c);
-    checkBackground(o.background);
-    if (boxes.some((b) => Array.isArray(b) && b.length > 0 && typeof b[0] === "object")) {
-        if (o.reframe !== undefined ||
-            o.punchIn?.length ||
-            (o.pullback !== undefined && o.pullback !== false)) {
-            throw new Error("footage(): a keyframed box cannot be reframed, punched in or pulled back; use a still box, or keyframes without reframe, punchIn and pullback.");
-        }
-    }
-    if (file !== undefined && !isMediaRef(file)) {
-        return { [LAYER_BRAND]: "footage", ...file };
-    }
-    return {
-        [LAYER_BRAND]: "footage",
-        ...(file === undefined ? {} : { file }),
-        ...opts,
-    };
-}
-//# sourceMappingURL=parts.js.map
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{shapeProblem as R,voiceProblem as T}from"@allyhub-next/audio";import{BACKDROP_BLUR_MAX as $,EASES as E,LAYER_BRAND as h,MATTE_FEATHER_MAX as S,MATTE_SHRINK_MAX as l,MEDIA_BRAND as _,ORIENT_KEYS as N,PART_BRAND as M,SPEECH_BRAND as g,isPerOrient as Y,notJson as G,partAnchorsProblem as C,speechSpeedProblem as O,transitionProblem as q}from"@allyhub-next/video-core";import{enginePiece as x,isItemPiece as j}from"./piece.js";export const partFor=r=>e=>{const{key:o,layers:n,...i}=e;if(typeof o!="string"||o==="")throw new Error("part: every part needs a key");if(i.title!==void 0&&(typeof i.title!="string"||i.title.trim()===""))throw new Error(`part ${o}: title is a name, not ${JSON.stringify(i.title)}`);for(const a of["before","after"]){const s=e.overlap?.[a];if(s!==void 0&&(!Number.isFinite(s)||s<0||s>10))throw new Error(`part ${o}: overlap.${a} is seconds from 0 to 10, not ${String(s)}`)}for(const[a,s]of(e.sounds??[]).entries()){if(!(typeof s=="object"&&(typeof s.at=="string"||typeof s.at=="number")&&(typeof s.sound=="string"||typeof s.sound=="object"&&"path"in s.sound)))throw new Error(`part ${o}: sounds[${String(a)}] is { at, sound, gainDb? }: at a word reference or seconds, sound a name or an audio file`);if(s.gainDb!==void 0&&(!Number.isFinite(s.gainDb)||s.gainDb<-60||s.gainDb>24))throw new Error(`part ${o}: sounds[${String(a)}].gainDb is dB from -60 to 24, not ${String(s.gainDb)}`);if(s.shape!==void 0){const f=R(s.shape);if(f!==void 0)throw new Error(`part ${o}: sounds[${String(a)}].shape: ${f}`)}}if(e.speechGainDb!==void 0&&(typeof e.speechGainDb!="number"||!Number.isFinite(e.speechGainDb)||e.speechGainDb<-40||e.speechGainDb>24))throw new Error(`part ${o}: speechGainDb is dB from -40 to 24, not ${String(e.speechGainDb)}`);if(e.anchors!==void 0){const a=C(e.anchors);if(a!==void 0)throw new Error(`part ${o}: anchors ${a}`)}if(e.transition!==void 0){const a=q(e.transition);if(a!==void 0)throw new Error(`part ${o}: transition ${a}`)}if(e.mic!==void 0){const a=T(e.mic);if(a!==void 0)throw new Error(`part ${o}: ${a}`)}if(e.post!==void 0){const a=e.post.filter;if(typeof a!="string"||a.trim()==="")throw new Error(`part ${o}: post: post is { filter: an ffmpeg filter chain }`)}const t=e.speech?.kind==="take"||e.speech?.kind==="say"?e.speech.tempo??1:1;if(t!==1&&(n??[]).some(a=>a[h]==="footage"&&a.file===void 0&&a.video===void 0))throw new Error(`part ${o}: footage() shows the part's take, which plays at speed ${String(t)}; a take's picture is drawn only at its own speed. Play the take at speed 1, or show other footage.`);return{[M]:!0,key:o,layers:n??[],...i,base:r.base}};function m(r,...e){const o={...r};for(const n of e)Reflect.deleteProperty(o,n);return o}function A(r,e){const o=i=>A(r,i);return{...{[g]:!0,...e},range(i,t){const a=m(e,"line","from","to");return o({...a,from:i,...t===void 0?{}:{to:t}})},saying(i){return o({...m(e,"from","to"),line:i})},edits(i){if(typeof i!="string"||!/\.json$/i.test(i))throw new Error(`take(…).edits(path): a JSON file relative to the file that names it, such as "./edits/host.json" (not ${JSON.stringify(i)})`);return o({...e,editsFile:i,editsBase:r.base})},speed(i){const t=O(i);if(t!==void 0)throw new Error(`take(…).speed(times): ${t}`);const a=m(e,"tempo");return o(i===1?a:{...a,tempo:i})},denoise(i=12){if(!Number.isFinite(i)||i<=0||i>97)throw new Error(`take(…).denoise(db): the noise reduction in dB, over 0 and up to 97 (not ${String(i)})`);return o({...e,denoiseDb:i})},roomTone(i){if(i===!1)return o({...e,room:!1});const t="take(…).roomTone(tone): false, or { from, to, match, gainDb, limitDb, fade }";if(typeof i!="object"||Array.isArray(i))throw new Error(`${t} (not ${JSON.stringify(i)})`);const{from:a,to:s,match:d,gainDb:f,limitDb:u,fade:c}=i,k=Object.keys(i).filter(P=>!["from","to","match","gainDb","limitDb","fade"].includes(P));if(k.length>0)throw new Error(`${t}: it has no ${k.join(", ")}`);if((a!==void 0||s!==void 0)&&(a===void 0||s===void 0||!Number.isFinite(a)||!Number.isFinite(s)||a<0||s-a<.05))throw new Error(`${t}: from and to are seconds of the file, both given, at least 0.05 s apart`);if(d!==void 0&&typeof d!="boolean")throw new Error(`${t}: match is true or false`);if(f!==void 0&&(!Number.isFinite(f)||f<-60||f>24))throw new Error(`${t}: gainDb is dB from -60 to 24, not ${String(f)}`);if(u!==void 0&&(!Number.isFinite(u)||u<0||u>60))throw new Error(`${t}: limitDb is dB from 0 to 60, not ${String(u)}`);if(c!==void 0&&(!Number.isFinite(c)||c<0||c>1))throw new Error(`${t}: fade is seconds from 0 to 1, not ${String(c)}`);return o({...e,room:{...a===void 0||s===void 0?{}:{from:a,to:s},...d===void 0?{}:{match:d},...f===void 0?{}:{gainDb:f},...u===void 0?{}:{limitDb:u},...c===void 0?{}:{fade:c}}})}}}export function takeFor(r){function e(o){return j(o)?J({kind:"video",piece:x(o)}):A(r,{kind:"take",file:o,...typeof o=="string"?{fileBase:r.base}:{}})}return e}const D=r=>typeof r=="number"&&Number.isFinite(r)&&r>=0||typeof r=="string"&&r.trim()!=="";function J(r){return{[g]:!0,...r,range(e,o){for(const[n,i]of[["from",e],["to",o]])if(i!==void 0&&!D(i))throw new Error(`take(video).range(from, to): ${n} is seconds from 0, an anchor ("@turn") or a part's key (not ${JSON.stringify(i)}).`);if(typeof e=="number"&&typeof o=="number"&&!(o>e))throw new Error(`take(video).range(${String(e)}, ${String(o)}): to comes after from.`);return J({...r,from:e,...o===void 0?{}:{to:o}})}}}export function say(r,e={}){if(e.speed!==void 0){const n=O(e.speed);if(n!==void 0)throw new Error(`say(): ${n}`)}const o=e.params;if(o!==void 0){if(typeof o!="object"||o===null||Array.isArray(o))throw new Error("say() params is not an object: give the voice tool's extra input as { name: value }.");const n=G(o,"params");if(n!==void 0)throw new Error(`say() ${n} is not plain JSON: use strings, finite numbers, booleans, null, arrays and plain objects.`);for(const[i,t]of[["text","say()'s text"],["voiceId","the voice option"]])if(i in o)throw new Error(`say() params.${i} is not allowed: give it as ${t}.`)}return{[g]:!0,kind:"say",text:r,...e.voice===void 0?{}:{voice:e.voice},...e.tool===void 0?{}:{tool:e.tool},...o&&Object.keys(o).length>0?{params:structuredClone(o)}:{},...e.speed===void 0||e.speed===1?{}:{tempo:e.speed}}}const b=r=>typeof r=="string"||typeof r=="object"&&r!==null&&(_ in r||"sha256"in r),p=r=>typeof r=="number"&&Number.isFinite(r)&&r>=0&&r<=1;function w(r,e){if(e===void 0)return;if(!(typeof e=="object"&&e!==null&&p(e.x)&&p(e.y)))throw new Error(`footage() ${r} ${JSON.stringify(e)} is not a point { x, y } with each from 0 to 1.`)}function F(r,e){if(e!==void 0&&(typeof e!="number"||!(e>0)||e>30))throw new Error(`footage() ${r} ${JSON.stringify(e)} is not seconds over 0 and up to 30.`)}function v(r,e){if(!(e===void 0||E.includes(e)))throw new Error(`footage() ${r} ${JSON.stringify(e)} is not one of ${E.map(o=>`"${o}"`).join(", ")}.`)}function H(r){if(!(r===void 0||r==="face"||r==="center")){if(typeof r=="object"&&r!==null&&"face"in r){const e=r;if(e.face!==!0)throw new Error(`footage() reframe ${JSON.stringify(r)}: face is true, as in { face: true, faceY: 0.4 }.`);if(e.faceY!==void 0&&!p(e.faceY))throw new Error(`footage() reframe faceY ${JSON.stringify(e.faceY)} is not from 0 (the crop's top) to 1 (its bottom); 0.4 is a little above the middle.`);return}if(typeof r=="object"&&r!==null&&"x"in r){w("reframe",r);return}throw new Error(`footage() reframe ${JSON.stringify(r)} is not "face", { face: true, faceY }, "center" or a point { x, y }.`)}}function K(r){if(r===void 0)return;if(typeof r!="object"||r===null||Array.isArray(r))throw new Error(`footage() background ${JSON.stringify(r)} is not an object such as { blur: 24 }, { dim: 0.4, desaturate: 1 }, { color: "#101418" } or { image: "./backdrop.jpg" }.`);const e=r,o=["blur","dim","desaturate","color","image","feather","shrink"],n=Object.keys(e).find(t=>!o.includes(t));if(n!==void 0)throw new Error(`footage() background has no option "${n}": it takes ${o.join(", ")}.`);const i=t=>typeof t=="number"&&Number.isFinite(t);if(e.blur!==void 0&&!(i(e.blur)&&e.blur>=0&&e.blur<=$))throw new Error(`footage() background blur ${JSON.stringify(e.blur)} is not a number from 0 to ${String($)}: the blur's standard deviation in px at 1080p (24 is a soft room).`);for(const t of["dim","desaturate"])if(e[t]!==void 0&&!p(e[t]))throw new Error(`footage() background ${t} ${JSON.stringify(e[t])} is not a number from 0 (as it is) to 1.`);if(e.color!==void 0&&(typeof e.color!="string"||e.color.trim()===""))throw new Error(`footage() background color ${JSON.stringify(e.color)} is not a CSS colour such as "#101418", "var(--ak-color-bg)" or "transparent".`);if(e.image!==void 0&&!b(e.image))throw new Error(`footage() background image ${JSON.stringify(e.image)} is not an image: a path relative to the piece, or an imported file.`);if(e.color!==void 0&&e.image!==void 0)throw new Error("footage() background takes a color or an image, not both.");if(e.color!==void 0){const t=["blur","dim","desaturate"].find(a=>e[a]!==void 0);if(t!==void 0)throw new Error(`footage() background ${t} does nothing with a color, which replaces the background: leave one out.`)}if(e.feather!==void 0&&!(i(e.feather)&&e.feather>=0&&e.feather<=S))throw new Error(`footage() background feather ${JSON.stringify(e.feather)} is not a number from 0 to ${String(S)}: the softness of the person's edge in px at 1080p (2 by default).`);if(e.shrink!==void 0&&!(i(e.shrink)&&Math.abs(e.shrink)<=l))throw new Error(`footage() background shrink ${JSON.stringify(e.shrink)} is not a number from −${String(l)} to ${String(l)}: how far the person's edge is pulled in, px at 1080p (4 by default).`)}function I(r){if(r===void 0||r==="full"||!Array.isArray(r))return;const e=r.length>0&&typeof r[0]=="object"?r.map(n=>n.box):[r],o=1e-6;for(const n of e){if(n==="full"||!Array.isArray(n)||n.length!==4)continue;const[i,t,a,s]=n;if(!([i,t,a,s].every(d=>typeof d=="number"&&Number.isFinite(d))&&(i??0)>=-o&&(t??0)>=-o&&(a??0)>0&&(s??0)>0&&(i??0)+(a??0)<=1+o&&(t??0)+(s??0)<=1+o))throw new Error(`footage() box ${JSON.stringify(n)} is not inside the frame: [x, y, width, height] are fractions of it, with x + width and y + height at most 1. A box is where the picture shows, so it cannot grow past the frame; for a slow push in use punchIn, eased in over its \`in\` seconds centred on \`at\` ({ at: 4, in: 8, until: 8, scale: 1.07, ease: "linear" } pushes in over the first 8 s), and for a slow pull out pullback ({ scale: 1.07, dur: 8 }).`)}}function y(r,e){if(e===void 0)return[];if(!Y(e))return[e];const o=N,n=Object.keys(e).filter(i=>!o.includes(i));if(n.length>0)throw new Error(`footage() ${r} has ${n.map(i=>JSON.stringify(i)).join(", ")}, which is not a frame shape: a per-shape ${r} is { ${N.join(", ")} } (each optional; an output takes the one for its orientation, else default).`);return Object.values(e).filter(i=>i!==void 0)}function X(r){const o=Array.isArray(r)?r:[],[n,i,t,a]=o;if(!(o.length===4&&typeof n=="number"&&typeof i=="number"&&typeof t=="number"&&typeof a=="number"&&[n,i,t,a].every(s=>Number.isFinite(s))&&n>=-1e-6&&i>=-1e-6&&t>0&&a>0&&n+t<=1+1e-6&&i+a<=1+1e-6))throw new Error(`footage() crop ${JSON.stringify(r)} is not a part of the source: [x, y, width, height] are fractions of it, with x + width and y + height at most 1.`)}function B(r){if(r===void 0)return;const e=r.scale;if(e!==void 0&&!(Number.isFinite(e)&&e>0&&e<=4))throw new Error(`footage() quality.scale ${String(e)} is outside (0, 4]: 0.5 is the fastest, 1 every pixel.`)}function L(r,e){const o=["crop","reframe","speaker","punchIn","sharpen","pullback","background","shape","radius"].filter(n=>e[n]!==void 0);if(o.length>0)throw new Error(`footage() of a video item takes at, until, dur, from, speed, box, fit, audio, gainDb, camera, cameras and quality; not ${o.join(", ")}.`);if(e.from!==void 0&&!D(e.from))throw new Error(`footage() from ${JSON.stringify(e.from)} is seconds from 0, an anchor ("@click") or a part's key of the video.`);if(e.speed!==void 0&&(!Number.isFinite(e.speed)||e.speed<=0||e.speed>16))throw new Error(`footage() speed ${String(e.speed)} is not a number over 0 and up to 16 (1 is normal speed).`);if(e.audio===!0&&e.speed!==void 0&&e.speed!==1)throw new Error("footage() of a video item plays its sound only at its own speed: speed 1, or audio off.");for(const n of y("box",e.box))I(n);return B(e.quality),{[h]:"footage",video:r,...e}}export const footageFor=r=>(e,o={})=>{if(j(e))return L(x(e),o);const n=e!==void 0&&!b(e)?e:o;if(typeof n.from=="string")throw new Error(`footage() from ${JSON.stringify(n.from)}: a file's from is seconds; a reference is a video item's.`);if(B(n.quality),n.speed!==void 0&&(!Number.isFinite(n.speed)||n.speed<=0||n.speed>16))throw new Error(`footage() speed ${String(n.speed)} is not a number over 0 and up to 16 (1 is normal speed).`);if(n.sharpen!==void 0&&(!Number.isFinite(n.sharpen)||n.sharpen<0||n.sharpen>1))throw new Error(`footage() sharpen ${String(n.sharpen)} is not a number from 0 to 1 (0.3 is gentle).`);if(H(n.reframe),n.speaker!==void 0&&(!Number.isInteger(n.speaker)||n.speaker<0))throw new Error(`footage() speaker ${String(n.speaker)} is not a face id (a whole number from 0, as allyhub frames --overlay labels them).`);for(const t of n.punchIn??[]){const a=typeof t=="object"?t.scale:/@(\d*\.\d+)$/.exec(String(t))?.[1]!==void 0?Number(/@(\d*\.\d+)$/.exec(String(t))?.[1]):void 0;if(a!==void 0&&(!(a>1)||a>3))throw new Error(`footage() punchIn scale ${String(a)} is not over 1 and up to 3 (1.12 is a gentle punch-in).`);typeof t=="object"&&(F("punchIn in",t.in),F("punchIn out",t.out),v("punchIn ease",t.ease),w("punchIn center",t.center))}if(typeof n.pullback=="object"){const{scale:t,dur:a}=n.pullback;if(t!==void 0&&(!(t>1)||t>3))throw new Error(`footage() pullback scale ${String(t)} is not over 1 and up to 3 (1.12 is a gentle pullback).`);if(a!==void 0&&(!(a>0)||a>10))throw new Error(`footage() pullback dur ${String(a)} is not seconds over 0 and up to 10.`);v("pullback ease",n.pullback.ease),w("pullback center",n.pullback.center)}if(n.shape!==void 0&&n.shape!=="rect"&&n.shape!=="circle")throw new Error(`footage() shape ${JSON.stringify(n.shape)} is not "rect" or "circle".`);if(n.radius!==void 0&&(typeof n.radius!="number"||!Number.isFinite(n.radius)||n.radius<0))throw new Error(`footage() radius ${JSON.stringify(n.radius)} is not a number from 0: the corners' radius, px at 1080p (24 is a soft card corner).`);if(n.radius!==void 0&&n.radius>0&&n.shape==="circle")throw new Error('footage(): radius rounds the corners of a rect; shape "circle" has none. Use one of them.');const i=y("box",n.box);for(const t of i)I(t);for(const t of y("crop",n.crop))X(t);if(K(n.background),i.some(t=>Array.isArray(t)&&t.length>0&&typeof t[0]=="object")&&(n.reframe!==void 0||n.punchIn?.length||n.pullback!==void 0&&n.pullback!==!1))throw new Error("footage(): a keyframed box cannot be reframed, punched in or pulled back; use a still box, or keyframes without reframe, punchIn and pullback.");return e!==void 0&&!b(e)?{[h]:"footage",...e,base:r.base}:{[h]:"footage",...e===void 0?{}:{file:e},...o,base:r.base}};

package/dist/paths.d.ts

@@ -61,7 +61,7 @@ export interface DrawOn {
 /**
  * The stroke-dash values that show the first `progress` (0–1, clamped) of
  * the path's stroke: 0 shows none of it, 1 all of it. Set them in render
- * from an eased progress: `css(path, drawOn(d, ease.out(progress(t, 0.2, 1))))`.
+ * from an eased progress: `css(path, { ...drawOn(d, ease.out(progress(t, 0.2, 1))) })`.
  * The gap is twice the length, so a browser that measures the path a little
  * longer never shows the next dash.
  */