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

package/node_modules/@allyhub-next/video-core/dist/piece.d.ts

@@ -0,0 +1,1146 @@
+import type { CaptureOptions } from "./render-types.js";
+import type { Look } from "./look.js";
+import type { MediaInfo, Word } from "./media.js";
+import type { FixedShape, MasterOptions, MixOptions, SoundMoment, SoundShape, VoiceSetting } from "./audio-types.js";
+import type { Format, FormatEntry, SizeInfo } from "./formats.js";
+import type { Combo, Matrix } from "./matrix.js";
+import type { Ease } from "./motion.js";
+import type { MusicStretch, MusicTime } from "./music.js";
+import type { PixelRect } from "./timeline.js";
+import type { TransitionInput } from "./transition.js";
+import type { PagedOutput, PagedPiece } from "./slides.js";
+/** Marks a piece made by video() or slides(). */
+export declare const PIECE_BRAND = "__allyhubPiece";
+/** Marks a part made by part(), so the runtime can tell parts from other values. */
+export declare const PART_BRAND = "__allyhubPart";
+/** Marks a layer made by footage(), a component or custom(). */
+export declare const LAYER_BRAND = "__allyhubLayer";
+/** Marks a speech source made by take() or say(). */
+export declare const SPEECH_BRAND = "__allyhubSpeech";
+/** Marks a media value (an import or ctx.asset), whose url the runtime resolves. */
+export declare const MEDIA_BRAND = "__allyhubMedia";
+/** The two output kinds: videos and paged outputs (decks, images, PDFs). */
+export declare const OUTPUT_KINDS: readonly ["video", "paged"];
+export type OutputKind = (typeof OUTPUT_KINDS)[number];
+/**
+ * A moment in a part: a word of its speech ("inbox"), the nth time it is
+ * said ("inbox@2"), shifted by seconds ("inbox+0.2", "inbox@2-0.3"), or
+ * seconds from the part's start (a number, or a string that is only one).
+ */
+export type WordRef = string | number;
+export interface MessageHint {
+    /** Length budget in characters; a hint for whoever writes the text. */
+    max?: number;
+    /** A note for whoever edits the text. */
+    note?: string;
+}
+/** ctx.s: the current language's text. */
+export interface MessageReader {
+    (key: string, hint?: MessageHint): string;
+    /**
+     * Numbered keys under a prefix, in order: `x.0`, `x.1`… Deeper keys make
+     * objects (`x.0.name`) and nested lists. What each item is, the SDK's
+     * reader types from the project's messages; here it is not known.
+     */
+    list(prefix: string, hint?: MessageHint): unknown[];
+    /** The text with its {name} variables filled in. */
+    with(key: string, inputs: Readonly<Record<string, string | number>>, hint?: MessageHint): string;
+}
+/** What every output's build function receives. */
+export interface PieceContext {
+    /**
+     * This combo: one value per dimension and, when the piece has slots, its
+     * structure (when it declares structures) and one candidate per slot of
+     * it, e.g. { lang: "en", hook: "price", demo: "inbox" }.
+     */
+    combo: Combo;
+    /**
+     * The file a pool slot picked in this combo (`slots: { demo: { pool:
+     * "./pool/demos" } }`), as a path footage() and ctx.asset() take.
+     */
+    pool(slot: string): string;
+    s: MessageReader;
+    /** Media at a path relative to the piece's file (dynamic paths; fixed ones are imports). */
+    asset(path: string): MediaInfo;
+    /**
+     * A data file (CSV rows, YAML, JSON) at a path relative to the piece's
+     * file: for dynamic paths; fixed ones are imports. Recorded in reads().
+     * Cast it to the shape you expect: `ctx.data(path) as Plan[]`.
+     */
+    data(path: string): unknown;
+    look: Look;
+}
+/**
+ * A sound effect a part plays (`part({ sounds })`). Nothing plays unless
+ * it is placed here.
+ */
+export interface SoundSpec {
+    /**
+     * When it hits: a word reference or seconds from the part's start. A
+     * built-in sound's transient lands there; a file starts there.
+     */
+    at: WordRef;
+    /**
+     * A name from the look's sounds (`look.sfx`, plus the built-in
+     * synthesized "whoosh", "tick" and "pop"), or an audio file: an import
+     * or a path relative to the piece.
+     */
+    sound: MediaRef;
+    /** Its gain in dB, over the mix's sound-effect level; default 0. */
+    gainDb?: number;
+    /**
+     * How it is shaped before it is levelled: an ffmpeg `filter` chain run
+     * on its file, equalizer bands (`eq`) and a `compress`or (SoundShape);
+     * none by default.
+     */
+    shape?: FixedShape;
+    /** A note for people: what it marks (the timeline prints it). */
+    what?: string;
+}
+/**
+ * A part's own anchors (`part({ anchors })`): each name a point, or a
+ * stretch [from, to], in seconds from the part's start.
+ */
+export type PartAnchors = Readonly<Record<string, number | readonly [from: number, to: number]>>;
+/** What is wrong with a part's own anchors, or nothing. */
+export declare function partAnchorsProblem(anchors: unknown): string | undefined;
+/** A part's own anchors as a list: a point's `at`, a stretch's `at` and `end`. */
+export declare function partAnchorList(anchors: PartAnchors | undefined): {
+    name: string;
+    at: number;
+    end?: number;
+}[];
+/**
+ * Where an outer video shows a video item: its film seconds from `from`
+ * to `to` play in the outer's part `part`, from the outer's film time
+ * `start`, the part starting at `partStart`.
+ */
+export interface ShownIn {
+    from: number;
+    to: number;
+    part: string;
+    start: number;
+    partStart: number;
+    /** Its seconds per outer second; default 1. */
+    speed?: number;
+}
+/** What mount and render receive besides the element and props. */
+/** A video drawn inside a layer (StageContext.video). */
+export interface EmbeddedVideo {
+    /** Its piece's id. */
+    id: string;
+    /** Seconds. */
+    duration: number;
+    /** The pixels it is drawn in. */
+    width: number;
+    height: number;
+    /** Draws its moment t (seconds from its start), settled when it returns; `layout`: for its layout alone. */
+    seek(t: number, layout?: boolean): Promise<void>;
+    /** Its moment by a reference of its own (an anchor, "@click", or a part's key), in its seconds (momentOf). */
+    at(ref: string): number;
+}
+export interface StageContext {
+    look: Look;
+    /** The format being drawn, e.g. "9x16"; a paged output's may be "a4", "letter" or "1200x630". */
+    format: Format;
+    /** Its pixels, orientation and platform safe zone. */
+    dims: SizeInfo;
+    /**
+     * The combo. A layer may read the dimensions and its own part's slot,
+     * never another slot's pick (AK-X005): a part is rendered once and
+     * reused in every combo that has it.
+     */
+    combo: Combo;
+    /** The part's length in seconds. */
+    dur: number;
+    asset(path: string): MediaInfo;
+    /**
+     * A project file that may not be there (a scenery's bake): its media when
+     * it is, undefined when not, with no problem either way. The read is
+     * recorded, so the part is drawn again once the file is made.
+     */
+    optionalAsset?(path: string): MediaInfo | undefined;
+    /**
+     * The part's words on its own clock (seconds from the part's start), for
+     * captions and karaoke-style layers; empty when the part has no speech.
+     */
+    words(): readonly Word[];
+    /** Seconds from the part's start of a word reference. */
+    at(ref: WordRef): number;
+    /** This layer's own window, in seconds from the part's start. */
+    layer: {
+        start: number;
+        end: number;
+    };
+    /**
+     * Work this layer must finish before anything is drawn, such as a 3D
+     * scenery building: the runtime awaits it before the output is ready and
+     * before a frame is drawn, whatever the moment. A rejection is reported
+     * with the layer, its part and the moment (an error carrying a rule
+     * `code`, such as AK-W001, under that rule; else AK-R001); work that
+     * does not settle within the piece's seekLimit is AK-P003.
+     */
+    wait(work: Promise<unknown>): void;
+    /**
+     * Reports what went wrong drawing this layer, at any moment (a 3D
+     * scenery's shader that does not compile, a screen it cannot draw): the
+     * output's problems carry it, with the layer's part, and every command
+     * prints it. `code` is a rule's (AK-W006); a code that is not one is
+     * AK-R001.
+     */
+    report?(p: {
+        code: string;
+        message: string;
+        level?: "error" | "warn";
+    }): void;
+    /**
+     * The caption cues shown in this part, on its own clock (seconds from
+     * the part's start), each with its words: built from the speech heard
+     * during the part's picture, spelled as the script when there is one.
+     * `maxChars` (default 32, 16 for Chinese, Japanese and Korean) and
+     * `maxWords` (default none) cap a cue; `keep` lists phrases a cue never
+     * breaks inside; a cue never spans two parts.
+     * Empty when nothing is said during the part.
+     */
+    captions(opts?: CaptionOptions): readonly CaptionTrackCue[];
+    /**
+     * Where a face is at part time t, in the frame's pixels: from the face
+     * track of the topmost footage showing then that has one (check and
+     * render make it). Face `id` of that track; by default that layer's speaker
+     * (its `speaker` option, else the track's default speaker). Undefined
+     * when no footage with a face track shows, or that face is not seen then.
+     */
+    face(t: number, id?: number): PixelRect | undefined;
+    /**
+     * Every face at part time t with its id and box, in the frame's pixels:
+     * from the face track of the topmost footage showing then that has one.
+     * Empty when there is none.
+     */
+    faces(t: number): readonly FaceOnFrame[];
+    /**
+     * The text of the part's layers listed before this one at part time t:
+     * each block of text (a line, a paragraph) as that layer draws it then,
+     * in the frame's pixels. Layers not showing at t give none. Measures by
+     * drawing those layers at t, so call it in mount (list a layer after
+     * the ones it should see).
+     */
+    texts(t: number): readonly TextBox[];
+    /**
+     * The areas the format's platform interface covers, in the frame's
+     * pixels: a strip per covered edge (none for a custom format).
+     */
+    covered: readonly PixelRect[];
+    /**
+     * The content box, [x, y, w, h] in the frame's pixels: clear of the
+     * covered areas with a gap, and at least a margin from every side. The
+     * same box layout(ctx) gives as left, top, right and bottom with its
+     * default options (see contentEdges for how it is computed).
+     */
+    content: PixelRect;
+    /**
+     * The output this layer is in, on its film clock: the part's start, and
+     * the film seconds of a reference anywhere in the output (an anchor of
+     * any part, "@turn", or a part's key). Reading it makes the part's
+     * place in the film part of its identity.
+     */
+    readonly film?: {
+        readonly start: number;
+        /** The part's key. */
+        readonly part: string;
+        at(ref: string): number;
+        /** Where an outer video shows this one (a part's video take, a footage of it); absent at the top. */
+        readonly outer?: ShownIn;
+    };
+    /**
+     * The camera an outer video asks a scenery layer of this name to be drawn
+     * from (footage({ camera }) of a video item); undefined: its own.
+     */
+    cameraFor?(name: string): unknown;
+    /** The drawing scale an outer video asks scenery layers for (footage({ quality })); undefined: their own. */
+    readonly sceneryScale?: number;
+    /** True in a video drawn inside another (a screen, a part's video take, a footage of a video item). */
+    readonly embedded?: boolean;
+    /**
+     * True while the runtime draws a moment only to measure its layout (the
+     * check's text and box measurements, ctx.texts): nothing reads this
+     * frame's pixels. A layer that paints a canvas no layout depends on (a
+     * 3D scenery) may skip painting then; whatever it places in the DOM it
+     * still places. False for every frame that is shown or captured.
+     */
+    readonly layoutOnly?: boolean;
+    /**
+     * Another video of the project, drawn in an element of this layer's (a
+     * scenery's screen): the piece this one imported (`import demo from
+     * "../demo/video"`), in its own format, in this video's language where
+     * it has it. Its parts, speech, anchors and components are its own; it
+     * draws its graphic layers over its background (no footage yet), and
+     * what it reads counts as this video's. Absent where the host cannot
+     * embed.
+     */
+    video?(piece: unknown, el: HTMLElement): Promise<EmbeddedVideo>;
+    /**
+     * Answers a question the host asks every layer of the output by name
+     * (`LoadedOutput.ask`): a scenery's cuts, the world times of references,
+     * its facts. A layer answers only the questions it registers; the host
+     * gets each answer with the layer and part it came from. Absent where
+     * the host asks nothing.
+     */
+    answer?<K extends keyof LayerQueries>(name: K, handler: (args: LayerQueries[K]["args"]) => LayerQueries[K]["answer"] | Promise<LayerQueries[K]["answer"]>): void;
+    /**
+     * The page's real clock and timers, which the runtime replaces with the
+     * moment's for piece code: for work that must wait on the wall clock (a
+     * scenery's model loaders, a decoder's worker), never for what a frame
+     * shows.
+     */
+    readonly realTimers?: RealTimers;
+}
+/** The page's own clock and timers (StageContext.realTimers). */
+export interface RealTimers {
+    now(): number;
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(id: unknown): void;
+}
+/**
+ * The questions a layer may answer (StageContext.answer), by name: each
+ * its arguments and its answer. Empty here: a package that draws a kind of
+ * layer adds its own by declaration merging, e.g.
+ *
+ *   declare module "@allyhub-next/video-core" {
+ *     interface LayerQueries { "scenery.cuts": { args: undefined; answer: readonly number[] } }
+ *   }
+ */
+export interface LayerQueries {
+}
+/** An answer to a question, with where it came from (LoadedOutput.ask). */
+export interface LayerAnswer<A> {
+    part: string;
+    /** The layer's component name, and its index in the part. */
+    layer: string;
+    index: number;
+    answer: A;
+}
+/** A face on the frame (StageContext.faces): its id in the face track, and its box in the frame's pixels. */
+export interface FaceOnFrame {
+    id: number;
+    box: PixelRect;
+}
+/** A block of another layer's text at a moment (StageContext.texts). */
+export interface TextBox {
+    /** The layer's component name. */
+    layer: string;
+    /** The text. */
+    text: string;
+    /** Where it is, in the frame's pixels. */
+    box: PixelRect;
+}
+/** How a captions layer wants its cues cut (StageContext.captions). */
+export interface CaptionOptions {
+    /** Most characters in a cue; default 32 (16 for Chinese, Japanese and Korean). */
+    maxChars?: number;
+    /** Most words in a cue; default no limit. */
+    maxWords?: number;
+    /**
+     * Phrases a cue never breaks inside (["work harder"]), matched as said
+     * (case, accents and punctuation ignored, whole words): the cue around
+     * one may run over maxChars or maxWords.
+     */
+    keep?: readonly string[];
+    /**
+     * Seconds: a gap between two cues of a part shorter than this closes,
+     * the first held until the next (no flicker); default 0.4.
+     */
+    close?: number;
+    /**
+     * The part's first cue from the part's start and its last to its end,
+     * so a caption shows across the part's whole picture and a cut leaves
+     * no frame without one; default false (from the first word to the last).
+     */
+    edges?: boolean;
+}
+/** A word of a caption cue, as the script spells it, on the part's clock. */
+export interface CaptionWord {
+    text: string;
+    start: number;
+    end: number;
+}
+/** A caption cue on the part's clock, with its words. */
+export interface CaptionTrackCue {
+    start: number;
+    end: number;
+    text: string;
+    words: CaptionWord[];
+}
+/** Media named by a path relative to the piece's file, or an imported media value. */
+export type MediaRef = string | MediaInfo;
+/** A stretch of a recording (audio or video) and its words. */
+export interface TakeSpeech {
+    [SPEECH_BRAND]: true;
+    kind: "take";
+    file: MediaRef;
+    /** The folder of the module that named `file` (a path), a project path ("" the root): it is relative to that. */
+    fileBase?: string;
+    /** The first words of the stretch (range). */
+    from?: string;
+    /** Its last words (range). */
+    to?: string;
+    /** The line the stretch says (saying). */
+    line?: string;
+    /**
+     * A cut list: a JSON file (`edits/<name>.json`, relative to the file
+     * that named it, editsBase) of removed word ranges, removed sounds and
+     * the longest pause kept.
+     */
+    editsFile?: string;
+    /** The folder of the module that named `editsFile`, a project path ("" the root): it is relative to that. */
+    editsBase?: string;
+    /** Noise reduction of its sound in dB (ffmpeg afftdn); absent: none. */
+    denoiseDb?: number;
+    /**
+     * How many times as fast it plays, pitch kept (take().speed()): 1.1 is
+     * 10 % faster, its words and the part with them (SPEECH_SPEED, 0.5 to
+     * 2); absent: as recorded.
+     */
+    tempo?: number;
+    /**
+     * The room tone that fills a part's lead and tail where the take has no
+     * silence of its own around the part's words: false for none (digital
+     * silence), or how to fill (take().roomTone()).
+     */
+    room?: false | RoomTone;
+}
+/** How a take's room tone fills a part's lead and tail. Every field has a default. */
+export interface RoomTone {
+    /**
+     * The stretch of the file to use, seconds (both, or neither); default
+     * the quietest steady stretch the build measured.
+     */
+    from?: number;
+    to?: number;
+    /**
+     * Whether each fill's level is matched to the floor of the take's kept
+     * sound beside the join it meets (default true). False plays it as
+     * recorded.
+     */
+    match?: boolean;
+    /** A gain for every fill, dB, instead of the matched one. */
+    gainDb?: number;
+    /** The most a matched gain raises or lowers a fill, dB (default ROOM_MATCH.limitDb, 6). */
+    limitDb?: number;
+    /** Seconds a fill and the take cross-fade over at the join (default ROOM_MATCH.fade, 0.04). */
+    fade?: number;
+}
+/** Text to speech, from the file `allyhub voice` makes for it. */
+export interface SaySpeech {
+    [SPEECH_BRAND]: true;
+    kind: "say";
+    text: string;
+    /** The voice tool's voice id. */
+    voice?: string;
+    /** The voice tool; default tts-elevenlabs-multilingual-v2. */
+    tool?: string;
+    /**
+     * More input for the voice tool (plain JSON), passed with the text and
+     * voice; the tool's schema says which it takes.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * How many times as fast the file plays, pitch kept (say's speed,
+     * SPEECH_SPEED, 0.5 to 2); absent: as the tool made it. AllyHub's, not
+     * the voice tool's: the same file.
+     */
+    tempo?: number;
+}
+/** The speeds a take or a say plays at: ffmpeg's atempo keeps a voice's pitch well in this range. */
+export declare const SPEECH_SPEED: {
+    readonly min: 0.5;
+    readonly max: 2;
+};
+/** Why a speech speed cannot be played; undefined when it can. */
+export declare function speechSpeedProblem(v: unknown): string | undefined;
+/**
+ * A stretch of another video item of the project, a source with a clock
+ * of its own (take(piece).range(from, to)): the part lasts the stretch,
+ * hears its sound and says its words; `footage()` without a file draws
+ * its picture, in sync.
+ */
+export interface VideoSpeech {
+    [SPEECH_BRAND]: true;
+    kind: "video";
+    /** The imported piece. It is drawn in the part's frame, whatever its own format. */
+    piece: PieceDefinition;
+    /** Where the stretch starts and ends: seconds of its clock, an anchor ("@turn", "@/turn", "@turn+0.2") or a part's key. Default its start and its end. */
+    from?: number | string;
+    to?: number | string;
+}
+/** Where a part's speech comes from. */
+export type SpeechSpec = TakeSpeech | SaySpeech | VideoSpeech;
+export declare function isSpeechSpec(v: unknown): v is SpeechSpec;
+/** When a layer starts and stops in its part. Default: the whole part. */
+export interface LayerTiming {
+    /** A word reference or seconds from the part's start; default 0. */
+    at?: WordRef;
+    /** A word reference or seconds from the part's start; default the part's end. */
+    until?: WordRef;
+    /** Seconds from `at`, when there is no `until`. */
+    dur?: number;
+}
+/** A rectangle as fractions of the frame (or of a source picture): x, y, width, height, each 0 to 1. */
+export type Rect = [x: number, y: number, w: number, h: number];
+/** A keyframe of a footage layer's box: when (a word reference or seconds), where, and the easing of the move into it. */
+/**
+ * A value per frame shape: the one named for the output's orientation
+ * ("landscape", "portrait" or "square"), else `default`; with neither,
+ * the option is left unset in that output.
+ */
+export interface PerOrient<T> {
+    landscape?: T;
+    portrait?: T;
+    square?: T;
+    default?: T;
+}
+/** The frame shapes a PerOrient names, and its fallback. */
+export declare const ORIENT_KEYS: readonly ["landscape", "portrait", "square", "default"];
+/** A PerOrient, as against the value itself (which is never a plain object). */
+export declare function isPerOrient<T>(v: T | PerOrient<T> | undefined): v is PerOrient<T>;
+/** The value for an orientation: a PerOrient's entry for it (else its default), or the value itself. */
+export declare function forOrient<T>(v: T | PerOrient<T> | undefined, orient: "landscape" | "portrait" | "square"): T | undefined;
+export interface BoxKey {
+    t: WordRef;
+    box: Rect | "full";
+    ease?: Ease;
+}
+/** A punch-in: zoom in on a word (or from `at` until `until`), by `scale` (default 1.12). */
+export interface PunchIn {
+    at: WordRef;
+    until?: WordRef;
+    scale?: number;
+    /** Seconds it takes to come in, centred on `at`; default 0.2. */
+    in?: number;
+    /** Seconds it takes to go out after the word (or `until`); default 0.25. */
+    out?: number;
+    /** The easing of its moves; default "in-out". */
+    ease?: Ease;
+    /**
+     * The point it zooms about, as fractions of the box; default the
+     * layer's speaker's face, else { x: 0.5, y: 0.42 }.
+     */
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/** A pullback's options (FootageOptions.pullback). */
+export interface Pullback {
+    /** How far in it starts; default 1.12. */
+    scale?: number;
+    /** Seconds back to the whole picture; default 0.6. */
+    dur?: number;
+    /** The easing of the move; default "out". */
+    ease?: Ease;
+    /**
+     * The point it zooms about, as fractions of the box; default the
+     * layer's speaker's face, else { x: 0.5, y: 0.42 }.
+     */
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Where a reframed picture is centred: on the face track ("face", or
+ * { face: true, faceY } to place the face's centre at faceY of the crop's
+ * height, default 0.4), the centre, or a point (fractions of the source).
+ */
+export type Reframe = "face" | {
+    face: true;
+    faceY?: number;
+} | "center" | {
+    x: number;
+    y: number;
+};
+/**
+ * What a footage layer does to its picture behind the person
+ * (FootageOptions.background). Lengths are px at 1080p: they scale with
+ * the format's shorter side.
+ */
+export interface FootageBackground {
+    /** Blurs the background: the Gaussian blur's standard deviation (CSS `blur()`'s length), px at 1080p. */
+    blur?: number;
+    /** Darkens the background: 0 (as it is) to 1 (black). */
+    dim?: number;
+    /** Takes the colour out of the background: 0 (as it is) to 1 (gray). */
+    desaturate?: number;
+    /**
+     * A flat colour instead of the background: any CSS colour.
+     * "transparent" leaves the person alone, over whatever is under the
+     * layer (in a transparent video, over nothing).
+     */
+    color?: string;
+    /**
+     * An image instead of the background (PNG, JPEG or WebP), filling the
+     * layer's box (cover); `blur`, `dim` and `desaturate` then treat the image.
+     */
+    image?: MediaRef;
+    /** The softness of the person's edge, px at 1080p; default 2 (MATTE_FEATHER). */
+    feather?: number;
+    /**
+     * How far the person's edge is pulled in, px at 1080p (negative lets it
+     * out); default 4 (MATTE_SHRINK). More hides a rim of the old
+     * background round the person; less keeps thin hair and fingers.
+     */
+    shrink?: number;
+}
+/** Where a footage layer shows: the full frame, a rectangle of it, or keyframes of rectangles. */
+export type FootageBox = Rect | "full" | BoxKey[];
+export interface FootageOptions extends LayerTiming {
+    /**
+     * Seconds into the file at the layer's start; a take's own footage
+     * follows its speech instead. For a video item, its own moment: seconds
+     * of its clock, an anchor or a part's key.
+     */
+    from?: number | string;
+    /**
+     * The camera a video item's scenery layers are drawn from, instead of
+     * their own: any camera a scenery layer takes (a state, a name, a move), on
+     * the item's clock. For the part's video take, or a video footage shows.
+     */
+    camera?: unknown;
+    /** Per scenery layer of the video item, by its name: when it has several. */
+    cameras?: Readonly<Record<string, unknown>>;
+    /**
+     * How finely a video item's scenery layers are drawn here, in place of
+     * their own `quality`: `scale` as scenery()'s (0.5 the fastest, 1 every
+     * pixel). Each film decides for itself, the item unchanged.
+     */
+    quality?: {
+        scale?: number;
+    };
+    /** Playback speed: 2 plays twice as fast, 0.5 half as fast; default 1. Its sound follows (pitch too). */
+    speed?: number;
+    /** Its sound's gain, in dB; default 0. */
+    gainDb?: number;
+    /** Mix its sound in; default false (a take's own footage sounds as its speech). */
+    audio?: boolean;
+    /**
+     * Where it shows: the full frame (default), a rectangle of it, or
+     * keyframes of rectangles (the picture moves and scales with its box).
+     * Per frame shape as { landscape, portrait, square, default }: each
+     * output takes the one for its orientation, so one piece places its
+     * footage differently in 16:9 and 9:16.
+     */
+    box?: FootageBox | PerOrient<FootageBox>;
+    /** How the picture fills its box; default "cover". */
+    fit?: "cover" | "contain";
+    /**
+     * A part of the source picture (fractions of it), which is then fitted
+     * to the box. Per frame shape as { landscape, portrait, square, default }.
+     */
+    crop?: Rect | PerOrient<Rect>;
+    /**
+     * Crops the source to the box's shape around the face ("face", from the
+     * face track, which check and render make; { face: true, faceY } places the
+     * face's centre at faceY of the crop's height, default 0.4), its centre,
+     * or a point; a smoothed path, so a 16:9 take fills a 9:16 frame around
+     * the speaker. Without a face then it centres on { x: 0.5, y: 0.4 } of
+     * the source.
+     */
+    reframe?: Reframe;
+    /**
+     * The face this layer follows: its id in the file's face track (allyhub
+     * index lists them). Default: the track's default speaker. Reframe
+     * "face", punch-ins, the pullback and ctx.face read it.
+     */
+    speaker?: number;
+    /**
+     * Zooms in on words: "word" (1.12×), "word@1.15" (a decimal after @ is
+     * the scale; "word@2" is still the second "word"), or
+     * { at, until, scale, in, out, ease, center }. Eased in over 0.2 s, held
+     * for the word, eased out over 0.25 s; about the speaker's face when
+     * there is a face track.
+     */
+    punchIn?: (WordRef | PunchIn)[];
+    /**
+     * Sharpens the picture after it is scaled, 0–1 (0.3 is gentle): for
+     * footage drawn larger than its pixels (allyhub inspect gives the
+     * scale). Renders and stills only; the live preview plays it unsharpened.
+     */
+    sharpen?: number;
+    /**
+     * Opens on a pullback: zoomed in at the layer's start, eased back to the
+     * whole picture: `true` (1.12× over 0.6 s, easing out) or
+     * { scale, dur, ease, center }; about the speaker's face when there is a
+     * face track. With one locked-off camera, each part then feels like a
+     * new shot.
+     */
+    pullback?: boolean | Pullback;
+    /**
+     * The box's shape: "rect" (default) or "circle", the ellipse inscribed
+     * in the box (a circle when the box is square in pixels), for an inset
+     * of the speaker while graphics take the frame.
+     */
+    shape?: "rect" | "circle";
+    /**
+     * Rounds the box's corners: the radius, px at 1080p (it scales with the
+     * format's shorter side, and with a keyframed box), at most half the
+     * box's shorter side. What is outside the corners is see-through: the
+     * frame's background shows there. Not with shape "circle".
+     */
+    radius?: number;
+    /**
+     * Treats the picture behind the person apart from the person: blurred,
+     * dimmed, desaturated, or replaced by a colour or an image, with the
+     * person drawn over it through the file's person matte (which check and
+     * render make). Until the file has a matte the layer shows as it is.
+     */
+    background?: FootageBackground;
+}
+export interface FootageLayer extends FootageOptions {
+    [LAYER_BRAND]: "footage";
+    /** The video; omitted: the part's take. */
+    file?: MediaRef;
+    /** The folder of the module that named `file` and a background image (paths), a project path ("" the root): they are relative to it. */
+    base?: string;
+    /** A video item of the project, imported: drawn by the stage at its own time. */
+    video?: PieceDefinition;
+}
+/**
+ * Where a component's props hold times (its time() props): `true` for a
+ * time or a list of times, an object for the fields of an object (or of
+ * each item of a list of objects).
+ */
+export interface TimeShape {
+    [prop: string]: true | TimeShape;
+}
+export interface GraphicLayer<P extends object = object> extends LayerTiming {
+    [LAYER_BRAND]: "graphic";
+    /** Component name: 'titleCard', 'custom' or a project component's name. */
+    component: string;
+    props: P;
+    /** The props that are times: their word references become seconds. */
+    times?: TimeShape;
+    /**
+     * "front" (default): at its place in the part's layers, over those
+     * listed before it. "behind-person": with the part's own footage (the
+     * footage layer without a file) wherever it is listed, drawn right over
+     * its picture and under its speaker, who is cut out with the person
+     * matte of the part's take (which check and render make). "overlay": over
+     * the finished picture, as an app lays its captions and stickers over a
+     * video after it is filmed: over every other layer, and not marked by
+     * the camera (`capture`), motion blur, `post` or the LUT.
+     */
+    z?: "front" | "behind-person" | "overlay";
+    mount(el: HTMLElement, props: P, ctx: StageContext): void;
+    render(el: HTMLElement, t: number, props: P, ctx: StageContext): void;
+}
+export type LayerSpec = FootageLayer | GraphicLayer;
+export declare function isLayerSpec(v: unknown): v is LayerSpec;
+export interface PartSpec {
+    [PART_BRAND]: true;
+    /** Unique in the output; stable across combos and formats. */
+    key: string;
+    /** Its name for people (the timeline, a note's part); default its largest text at its still. */
+    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;
+    speech?: SpeechSpec;
+    /** Without speech: seconds (default 4, or the part defaults). With speech: ignored. */
+    dur?: number;
+    /** Seconds before the first word and after the last; defaults 0.2 and 0.3 (or the part defaults). */
+    lead?: number;
+    tail?: number;
+    /**
+     * What the part shows, back to front: each layer is drawn over those
+     * listed before it, footage and graphics alike. A graphic layer listed
+     * before a footage layer is under it (a card behind a video); one
+     * between two footage layers is between them.
+     */
+    layers: LayerSpec[];
+    /** The still moment: a word reference, seconds, or a function of the part's length. */
+    still?: WordRef | ((dur: number) => number);
+    tags?: string[];
+    /**
+     * J and L cuts: `before` seconds of the speech play under the previous
+     * part's picture (a J cut), `after` seconds under the next part's (an L
+     * cut). The part's picture is that much shorter at that end.
+     */
+    overlap?: {
+        before?: number;
+        after?: number;
+    };
+    /** Sound effects, each placed by a word reference or seconds. */
+    sounds?: SoundSpec[];
+    /** The folder of the module that called part(), a project path ("" the root): its sounds' paths are relative to it. */
+    base?: string;
+    /**
+     * Named moments of the part, in seconds from its start: a point
+     * (`press: 7.1`) or a stretch (`map: [9.6, 13.4]`). "@press" is the
+     * point, "@map" and "@/map" the stretch's start and end, wherever a word
+     * reference goes. A part needs no speech to have them.
+     */
+    anchors?: PartAnchors;
+    /**
+     * How the part comes in from the part before it: a type's name
+     * ("fade", "dip", "slide", "push", "wipe", "zoom") or { type, dur, ease,
+     * split, … }. Absent: a cut. Pictures only: the sound is not changed.
+     */
+    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 (a clip's
+     * white balance and exposure), before the camera's marks and the video's
+     * post, under the same contract as the video's (the render's post).
+     */
+    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 finishing (its compressor)
+     * does not even it out, and its room tone moves with it. From -40 to
+     * 24; default 0.
+     */
+    speechGainDb?: number;
+}
+export declare function isPartSpec(v: unknown): v is PartSpec;
+/** A part's defaults: the length without speech, the lead and the tail. */
+export declare const PART_DEFAULTS: {
+    readonly dur: 4;
+    readonly lead: 0.2;
+    readonly tail: 0.3;
+};
+/**
+ * Part defaults a project (`defineConfig({ defaults: { part } })`) or an
+ * video (`video({ defaults: { part } })`) sets over PART_DEFAULTS.
+ */
+export interface PartDefaults {
+    /** Seconds of a part without speech. */
+    dur?: number;
+    /** Seconds before a part's first word. */
+    lead?: number;
+    /** Seconds after a part's last word. */
+    tail?: number;
+}
+/** The part defaults in force: the output's over the project's over PART_DEFAULTS. */
+export declare function partDefaults(...layers: (PartDefaults | undefined)[]): Required<PartDefaults>;
+export interface MusicOptions {
+    /**
+     * The music, or one per language (`{ en: a, "zh-cn": b }`): each
+     * language can have music cut to its own timing. A language with no
+     * entry has no music.
+     */
+    file?: MediaRef | Record<string, MediaRef>;
+    /** Seconds into the file where the music starts; default 0. */
+    from?: number;
+    /**
+     * `true` plays the whole file again (with a 0.25 s crossfade at each
+     * seam) while the video goes on; `{ from, to }` plays that stretch again
+     * and again after `play` (or after `from` to `to`), each seam crossed
+     * over `seam`. Default false: it plays once, and a video longer than the
+     * music ends without it (the `music-length` fact gives both lengths).
+     */
+    loop?: boolean | MusicStretch;
+    /**
+     * The stretches of the file to play, in order, back to back (`{ from,
+     * to }`, each a second of the file, `{ beat: n }` or `{ bar: n }`):
+     * bars 0 to 7 then 3 to 7 of a song that ends too soon. Each seam is
+     * crossed over `seam`; the film moves on by each stretch's exact length,
+     * so stretches cut on the beat keep the beat. Default: the file from
+     * `from` to its end.
+     */
+    play?: MusicStretch[];
+    /**
+     * Seconds each seam between stretches cross-fades over, equal-power;
+     * default 0.03 (the whole file looped, `loop: true`: 0.25).
+     */
+    seam?: number;
+    /** Beats a bar, for `{ bar }` places and `end: "bar"`; default 4. */
+    meter?: number;
+    /**
+     * The file's second of bar 0, the first downbeat (the beat finder does
+     * not know where a bar starts); default the first beat measured, or 0
+     * with a given `bpm`. Beats count from it too.
+     */
+    downbeat?: number;
+    /**
+     * Where the music stops: "film" at the video's end (default), "bar" on
+     * the last bar line before it, "beat" on the last beat; its fade out
+     * (`mix.musicFade.out`) ends there. Needs a tempo.
+     */
+    end?: "film" | "bar" | "beat";
+    /**
+     * Parts without speech end on the music's beat; default false. The beat
+     * is `bpm`, else the tempo measured from the file, laid out as the
+     * stretches play it; when neither is known, nothing is snapped and a
+     * `fallback` fact says so.
+     */
+    snap?: boolean;
+    /** Beats per minute, for `snap`, beats and bars; default: the tempo measured from the file. */
+    bpm?: number;
+    /**
+     * The music's level over the film, dB relative to its level (`mix`):
+     * points `{ at, db }`, linear between them in dB and held before the
+     * first and after the last, added to its dip under speech. `at` is film
+     * seconds, an anchor of any part ("@drop", "@drop-0.2"), a part's key
+     * (its start), or `{ part, at }`, a word reference in that part.
+     */
+    gain?: {
+        at: SoundMoment;
+        db: number;
+    }[];
+    /**
+     * An ffmpeg audio filter chain run on the file as it is decoded (its own
+     * clock): "acompressor=ratio=3,deesser". One chain; nothing that reads
+     * files, makes sound or changes the timing.
+     */
+    filter?: string;
+    /**
+     * Equalizer bands, in order, on the music as it plays: `{ type, hz, db?,
+     * q?, keys? }`, a type "highpass", "lowpass", "bandpass", "peak",
+     * "lowshelf" or "highshelf". `keys: [{ at, hz?, db?, q? }]` move a
+     * band's values over the film (a low-pass at 1100 Hz until "@drop",
+     * open 0.3 s later), `at` as `gain`'s.
+     */
+    eq?: SoundShape["eq"];
+    /**
+     * A compressor after the bands: `{ threshold, ratio?, knee?, attack?,
+     * release?, window? }`, its threshold dB over the music's loudness;
+     * defaults COMPRESS_DEFAULTS.
+     */
+    compress?: SoundShape["compress"];
+}
+export type { MusicStretch, MusicTime };
+export interface VideoOptions {
+    music?: MediaRef | MusicOptions;
+    /** The look's name; default "clean". */
+    look?: string;
+    /** Cover parts (optional): parts without speech, drawn at their still for the cover image. */
+    covers?(ctx: PieceContext): PartSpec[] | Promise<PartSpec[]>;
+    /**
+     * Frames per second: a whole number from 1 to 120, or an NTSC rate
+     * (23.976, 29.97, 47.952, 59.94, 119.88, or "24000/1001"…); default 30.
+     */
+    fps?: number | string;
+    /**
+     * The stage has no background: mov, webm and png keep the transparency;
+     * mp4 and gif show black where nothing is drawn. Default false.
+     */
+    transparent?: boolean;
+    /**
+     * The mix: each stem's loudness target (speech, music while speech
+     * plays and alone, sound effects, footage alone and under speech), the
+     * music's ducking under words and its fades. Defaults: MIX_DEFAULTS.
+     */
+    mix?: MixOptions;
+    /**
+     * How the speech was recorded: a setup's name ("studio", "phone",
+     * "lav"), or { setup, …changes } (the microphone, its distance and
+     * angle, the room, its tone, the device's automatic gain, the
+     * finishing), or false for the voice as it is. Default: "studio", the
+     * voice finished as a studio's is (a high-pass, a gentle de-esser and
+     * compressor) and nothing else. A part's own `mic` is over it.
+     */
+    mic?: VoiceSetting;
+    /**
+     * What the sound is mastered to: a loudness in LUFS (-70 to 0), or
+     * `{ lufs, truePeak }`; default the platform profile's loudness, else
+     * -14 LUFS, true peak -3 dBTP. The master is one measured gain, then a
+     * true-peak limiter: the mix keeps its own loudness range. false keeps
+     * the mix's own level and only limits its peaks.
+     */
+    master?: number | false | MasterOptions;
+    /** The longest a combo may last, in seconds: a longer one is a must-fix (AK-X006). */
+    maxDuration?: number;
+    /**
+     * false: a video only shown inside another (what a scenery's screen shows,
+     * a scene a film plays stretches of), not a film of its own. `allyhub
+     * render` renders it only when it is named, and the check leaves
+     * out the facts about watching it as a film: how long its text shows and
+     * how large on a phone, a platform's covered edges, flat and still
+     * stretches. Default true.
+     */
+    deliverable?: boolean;
+    /**
+     * How long loading it may take, seconds (mounting its layers, the work
+     * they wait for, a 3D scenery's build, each part's still); default
+     * LOAD_LIMIT, 10. Longer is AK-P002, which names what took the time.
+     */
+    loadLimit?: number;
+    /**
+     * How long one moment may take to draw, seconds: the work its layers
+     * wait for (ctx.wait) and the pictures it shows decoding; default
+     * SEEK_LIMIT, 30. Longer is AK-P003, which names what was still pending,
+     * and the command goes on. Loading waits for its layers' work at most
+     * LOAD_WAITS (4) times as long.
+     */
+    seekLimit?: number;
+    /** Motion blur: each frame blends moments across part of the frame's time. */
+    motionBlur?: MotionBlur;
+    /**
+     * What a camera filming the picture does to it, before post: bloom,
+     * chromatic aberration, vignetting, exposure breathing, grain and
+     * sharpening, each absent unless given (CaptureOptions; their defaults
+     * CAPTURE_DEFAULTS). Each frame's marks are a function of its number in
+     * the film, so a still is the render's frame.
+     */
+    capture?: CaptureOptions;
+    /** Processing after the frames are drawn, before they are encoded. */
+    post?: PostProcess;
+    /** This output's part defaults, over the project's (`defineConfig({ defaults: { part } })`). */
+    defaults?: {
+        part?: PartDefaults;
+    };
+}
+export interface MotionBlur {
+    /** Moments blended into each frame: 2 to 16. */
+    samples: number;
+    /** The part of a frame's time they span, over (0, 1]; default 0.5 (a 180° shutter). */
+    shutter?: number;
+}
+export interface PostProcess {
+    /**
+     * An ffmpeg filter chain over the frames, for example
+     * "eq=contrast=1.05:saturation=1.1,colortemperature=temperature=5600".
+     * One chain: no `;`, no `[labels]`, and no filters that read or write
+     * files. It is given the picture opaque, as 8-bit planar RGB (gbrp), its
+     * `t` the film's time, and what it gives back is made opaque gbrp again;
+     * use `t`, not `n`, which counts from each segment's first frame.
+     */
+    filter?: string;
+    /** A 3D LUT (.cube) applied after the filter: a path relative to the piece. */
+    lut?: string;
+}
+export type VideoBuild = (ctx: PieceContext) => PartSpec[] | Promise<PartSpec[]>;
+/**
+ * Where a piece was written, as video() and slides() record it from the
+ * module the SDK was bound to (the SDK's sdkFor): the paths a piece names
+ * as strings are relative to the module that wrote them, and an item's
+ * piece imported by another (a scenery's screen, a part's video take) is
+ * known by its file.
+ */
+export interface PieceWritten {
+    /** The module that called video() or slides(), a project path ("" where it was not known). */
+    file: string;
+    /**
+     * The folder each of its fields that names a file (music, post's LUT) is
+     * relative to: the value as written and the folder, a project path (""
+     * the project's root). A field spread from another piece
+     * (`video({ ...film, format })`) keeps the folder it was written in
+     * while its value is the same.
+     */
+    paths?: Readonly<Partial<Record<"music" | "post", readonly [value: unknown, base: string]>>>;
+}
+/** What every piece has, whatever it makes. */
+export interface PieceCommon {
+    /** Where it was written: video() and slides() set it. */
+    written?: PieceWritten;
+    /** A stable identity; default: the item's folder, from the project's root. */
+    id?: string;
+    /** A name for people: one string, or by language. */
+    title?: string | Record<string, string>;
+    /**
+     * What it is rendered as, one format: a preset ("16x9", "9x16", "1x1",
+     * "4x5"), a platform profile or WxH pixels ("a4" and "letter" for slides
+     * only), a name or a FormatSpec ({ format, safe, maxDuration, loudness }:
+     * the format with its numbers changed). Another format is a piece of
+     * its own, which imports what it shares. Default: allyhub.config.ts
+     * `defaults.format`, else "16x9".
+     */
+    format?: FormatEntry;
+    /**
+     * The matrix: dimensions (crossed in full), slots and their candidates,
+     * structures, and the rules and sampling that choose the combos
+     * (`ctx.combo`).
+     */
+    matrix?: Matrix;
+    /** Any key-values; the platform filters and groups by them. */
+    meta?: Record<string, unknown>;
+}
+/** A video: the default export of an item's video.ts, made by video(). */
+export interface VideoPiece extends PieceCommon, VideoOptions {
+    [PIECE_BRAND]: true;
+    kind: "video";
+    /**
+     * Its parts, in order. A method, so a piece whose parts take a narrower
+     * context (the SDK's, with message keys typed) is still a VideoPiece.
+     */
+    parts(ctx: PieceContext): PartSpec[] | Promise<PartSpec[]>;
+}
+/** One deliverable: a video or a deck. Another one is an item of its own. */
+export type PieceDefinition = VideoPiece | PagedPiece;
+export declare function isPieceDefinition(v: unknown): v is PieceDefinition;
+/**
+ * A piece's output as the build and the runtime handle it: its kind, the
+ * function that makes its parts or pages, and its options. A piece has
+ * one, named by its item's kind (`outputName`).
+ */
+export interface OutputDefinition<K extends OutputKind = OutputKind> {
+    kind: K;
+    build(ctx: PieceContext): unknown;
+    options: object;
+}
+export interface VideoOutput extends OutputDefinition<"video"> {
+    build: VideoBuild;
+    options: VideoOptions;
+}
+/**
+ * The name of a piece's one output: its item's kind, as its entry file is
+ * named (video, slides), and as a doc's file is doc.pdf.
+ */
+export declare const outputName: (kind: OutputKind) => string;
+/** A piece's one output: its kind, its build function and its options. */
+export declare function outputOf(def: PieceDefinition): VideoOutput | PagedOutput;
+/** The function that makes a piece's parts or pages. */
+export declare const buildOf: (def: PieceDefinition) => unknown;
+/**
+ * Whether a piece is the one a command names, or under it as a folder of
+ * items: `tr` takes `tr` and `tr/fade`, not `trailer`.
+ */
+export declare const pieceIn: (id: string, name: string) => boolean;
+/**
+ * What a command's item names, as a place: written as an id, or a path to an
+ * item's folder or entry file from the project (./launch/film,
+ * launch/film/video.ts), the entry file's name left out.
+ */
+export declare function pieceName(name: string): string;
+/**
+ * Whether a command's item names a piece, by its id or by its place (an id of its
+ * own does not hide its place), as a path to its folder or entry file, or
+ * as a folder of items above any of these.
+ */
+export declare const pieceNamed: (p: {
+    id: string;
+    path?: string;
+}, name: string) => boolean;
+/** Whether a command's item names exactly this piece, by its id, its place or a path to it. */
+export declare const pieceIs: (p: {
+    id: string;
+    path?: string;
+}, name: string) => boolean;
+/** The default message prefix of a piece id: `launch/film` → `launch.film`. */
+export declare function messagePrefix(pieceId: string): string;
+/**
+ * How the runtime shows and hides a layer's element, and a part's: an
+ * attribute a rule of the document's hides (`display: none !important`),
+ * never the element's own `display`, which is the layer's (a layer that
+ * centres its content with `display: grid` keeps it when shown).
+ */
+export declare const LAYER_OFF = "data-ak-off";
+/** Shows or hides a layer's (or a part's) element. */
+export declare function showLayer(el: HTMLElement, on: boolean): void;
+/** Whether a layer's (or a part's) element is shown. */
+export declare function layerShown(el: HTMLElement): boolean;
+/**
+ * Adds the rule that hides what is marked off, once per document, as an
+ * adopted style sheet: no element is added, so nothing watching the
+ * document's elements sees a change.
+ */
+export declare function addLayerRule(doc: Document): void;
+//# sourceMappingURL=piece.d.ts.map