allyhub 0.3.0 → 0.5.0

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

@@ -0,0 +1,649 @@
+import type { SlidesFile } from "@allyhub-next/formats";
+import { type TextAnchor } from "./anchors.js";
+import type { PlatformProfile } from "./formats.js";
+import type { Look } from "./look.js";
+import type { MediaInfo, MediaKind } from "./media.js";
+import type { FixedShape, MasterTargets, MixLevels, ResolvedShape, ResolvedVoice } from "./audio-types.js";
+import type { MessagesFile } from "./messages.js";
+import type { MessageHint, PartDefaults } from "./piece.js";
+import type { Combo, Dims, MatrixRule, MatrixSpace } from "./matrix.js";
+import type { Ease } from "./motion.js";
+import type { PlacedStretch } from "./music.js";
+import type { TimelineTransition } from "./transition.js";
+import type { RoomLevel } from "./voice.js";
+export interface LoadOptions {
+    /** The combo: one value per dimension, e.g. { lang: "zh-cn" }. */
+    combo: Combo;
+    purpose: "play" | "render" | "check";
+    /** A deck drawn for its editor: an empty placeholder is drawn, to type into. */
+    editing?: boolean;
+    /**
+     * The most different console messages kept from piece code (see
+     * console.ts); default CONSOLE_LIMIT.
+     */
+    consoleLimit?: number;
+}
+/** A data file ctx.data(path) can read: parsed, or why it could not be. */
+export interface DataFile {
+    sha256: string;
+    value?: unknown;
+    error?: string;
+}
+/** What the host hands load(): one piece, as the build made it. */
+export interface BuildSource {
+    /** What it is: a video (the default) or a deck, which the stage loads with the deck's runtime. */
+    kind?: "video" | "slides";
+    /** The piece's id: seeds and problems use it. */
+    piece: string;
+    /**
+     * The piece's file, relative to the project root: a path its own options
+     * name (music, a LUT) and ctx.asset() are relative to it, unless the
+     * piece says where it was written (`base`).
+     */
+    file: string;
+    /** URL of the bundled piece module. */
+    module: string;
+    /** URLs of stylesheets the bundle imports. */
+    styles?: string[];
+    /** The piece's dimensions, as the build resolved them (lang filled in). */
+    dims: Dims;
+    /** Its slots, structures and rules, when it has slots (pools resolved). */
+    matrix?: {
+        space: MatrixSpace;
+        rules: MatrixRule[];
+    };
+    /**
+     * The piece's one format, as the build resolved it (the project's
+     * default filled in), e.g. "9x16". A piece has one output, its kind's.
+     */
+    format: string;
+    /** Locales, the default first. */
+    locales: string[];
+    /** Every message by locale: the messages files' and the items' scripts'. */
+    messages: Record<string, MessagesFile>;
+    /**
+     * locale → key → the anchors a script wrote in that line (@{name}), by
+     * their place in the line as spoken.
+     */
+    anchors?: Record<string, Record<string, TextAnchor[]>>;
+    /** The folder of the shared words (allyhub.config.ts's text); default assets/text. */
+    text?: string;
+    /** Repo path → media, with a URL valid in this page. */
+    media: Record<string, MediaInfo>;
+    /** Repo path → data files (CSV, YAML, JSON) that ctx.data(path) reads. */
+    data?: Record<string, DataFile>;
+    /** Looks by name; the built-in clean is always there. */
+    looks?: Record<string, Look>;
+    /** The project's part defaults (allyhub.config.ts `defaults.part`). */
+    partDefaults?: PartDefaults;
+    /** A deck's pages: its slides.yaml as the build read it (none when it has none, or it does not match the format). */
+    slides?: SlidesFile;
+    /**
+     * Every piece of the build by id, for a piece that shows another inside
+     * it (a scenery's screen): its file, dimensions, format and matrix.
+     */
+    pieces?: Record<string, {
+        file: string;
+        dims: Dims;
+        format: string;
+        matrix?: {
+            space: MatrixSpace;
+            rules: MatrixRule[];
+        };
+    }>;
+}
+/**
+ * stage/source.json in a build folder: what a host
+ * needs, besides the build's files, to hand load() a BuildSource for any
+ * piece of the build. Paths are relative to the build folder; the host
+ * adds URLs (media are fetched by sha256).
+ */
+export interface StageSource {
+    schema: 1;
+    /** The runtime's browser bundle the build was made with. */
+    runtime: string;
+    /** Locales, the default first. */
+    locales: string[];
+    pieces: Record<string, {
+        file: string;
+        module: string;
+        styles: string[];
+        dims: Dims;
+        matrix?: {
+            space: MatrixSpace;
+            rules: MatrixRule[];
+        };
+        format: string;
+    }>;
+    media: Record<string, Omit<MediaInfo, "url">>;
+    data: Record<string, DataFile>;
+    /** The project's looks (allyhub.config.ts `look`), when it sets one. */
+    looks?: Record<string, Look>;
+}
+/** Where a part's speech plays: film seconds, and the take's file and offset. */
+export interface PartSpeech {
+    /** Film time the speech starts and ends. */
+    start: number;
+    end: number;
+    /** Repo path of the take (a recording, or a `say` file). */
+    file: string;
+    /** Seconds into the file at `start`. */
+    from: number;
+    /**
+     * Seconds of the file it plays per second of film, pitch kept (the
+     * take's or the say's speed); absent: 1.
+     */
+    speed?: number;
+    /**
+     * A cut take: the stretches of the file it plays, in film order, each
+     * from film time `at`; without them the file plays on from `from`.
+     */
+    cuts?: SpeechCut[];
+    /** The edits file of the take (repo path), when it has one. */
+    edits?: string;
+    /** The indices of the take's words the part says (first and last), before edits. */
+    words?: [first: number, last: number];
+    /** The words the part plays, as recognised (a cut take: only those its edits keep). */
+    heard?: string;
+    /**
+     * A `saying` line: the share of its letters found in the take's kept
+     * words (0 to 1; in runs of three letters or more), and the take's word
+     * the search started from (0 when it was not found after the part before
+     * and the whole take was searched).
+     */
+    match?: {
+        score: number;
+        from: number;
+    };
+}
+/** From film time `at`, a cut take plays its file from `from` (until the next cut). */
+export interface SpeechCut {
+    at: number;
+    from: number;
+}
+/** A graphic layer in its plane: the component, and when it shows. */
+export interface PlaneLayer {
+    component: string;
+    /** Film seconds (end exclusive). The plane is empty where none of its layers shows. */
+    start: number;
+    end: number;
+}
+/**
+ * One of a part's graphics planes: graphic layers drawn together, back to
+ * front, with no footage between them.
+ */
+export interface PartPlane {
+    layers: PlaneLayer[];
+    /**
+     * Its layers have z "behind-person": drawn right over the part's own
+     * footage and under its speaker, who is cut out with the person matte
+     * and drawn again over this plane.
+     */
+    behindPerson?: true;
+    /**
+     * Its layers have z "overlay": the part's last plane, laid over the
+     * finished picture (after the camera's marks, post and the LUT), with
+     * no motion blur, one image a frame.
+     */
+    overlay?: true;
+}
+/**
+ * Whether a graphic layer of a part's plane shows at film time t: the
+ * plane there is not empty. Generous by a microsecond either way: drawing
+ * an empty moment costs a capture, missing one would lose a frame.
+ */
+export declare function planeAt(part: Part | undefined, plane: number, t: number): boolean;
+/** What a part's stack holds at one place, back to front. */
+export type StackItem = {
+    kind: "footage";
+    footage: TimelineFootage;
+} | {
+    kind: "graphics";
+    plane: number;
+    layers: PlaneLayer[];
+}
+/** The speaker of a footage layer, cut out and drawn again over the plane behind them. */
+ | {
+    kind: "person";
+    footage: TimelineFootage;
+};
+/**
+ * A part's layers as they are stacked, back to front: each footage layer
+ * after the planes under it, each plane after the footage under it, and
+ * the speaker cut out over a plane behind them.
+ */
+export declare function stackOf(part: Part, footage: readonly TimelineFootage[]): StackItem[];
+export interface Part {
+    key: string;
+    /** The slot it fills, when the piece has slots. */
+    slot?: string;
+    /** What its layers are: component names, and "footage". */
+    layers: string[];
+    start: number;
+    end: number;
+    /**
+     * Its graphics planes, back to front. A part's layers are drawn in the
+     * order they are listed, footage and graphics alike: graphic layers
+     * with no footage between them are one plane, which the page draws in
+     * one picture, and each footage layer says how many planes are under
+     * it (`TimelineFootage.over`). Most parts have one plane, over all
+     * their footage.
+     */
+    planes: PartPlane[];
+    /** The part's still moment, absolute. */
+    still: number;
+    /** A deck's page: each of its steps' still moments, absolute, step 0 first (the last is `still`). */
+    steps?: number[];
+    /** A deck's page left out when the deck is presented or exported (slides.yaml's `hidden`). */
+    hidden?: boolean;
+    /** A name for people: part({ title }), else its largest text at its still that not every part shows. */
+    title?: string;
+    /** Voiced parts: where the speech plays. */
+    speech?: PartSpeech;
+    /** A part that plays a stretch of another video item (take(piece).range): the item, and the stretch on its clock. */
+    plays?: {
+        video: string;
+        from: number;
+        to: number;
+    };
+    /** Its own post chain (part({ post })): run on its picture before the camera's marks and the video's post. */
+    post?: {
+        filter: string;
+    };
+    /**
+     * Its anchors, where each landed in the film: its own (`part({ anchors
+     * })`), then those of the line it says (its script's @{name}). `at` is
+     * what "@name" gives, `end` what "@/name" does.
+     */
+    anchors?: PartAnchor[];
+    tags?: string[];
+    /** dB its speech is turned up or down after it is recorded (`part({ speechGainDb })`). */
+    speechGainDb?: number;
+}
+/** An anchor of a part's line, in film seconds. */
+export interface PartAnchor {
+    name: string;
+    at: number;
+    end?: number;
+}
+/** A sound effect a part placed (`part({ sounds })`), on the film's clock. */
+export interface Cue {
+    /** Film seconds where it hits. */
+    t: number;
+    /** Its name: a look's sound, a built-in one, or the file's path. */
+    sound: string;
+    part: string;
+    what?: string;
+    /** The audio file it plays (repo path); absent: a built-in synthesized sound. */
+    file?: string;
+    /** Its gain in dB over the mix's sound-effect level. */
+    gainDb?: number;
+    /** How it is shaped before it is levelled (its sound's `shape`). */
+    shape?: FixedShape;
+}
+/** A rectangle in pixels: x, y, width, height. */
+export type PixelRect = [x: number, y: number, w: number, h: number];
+/**
+ * A footage layer's background as its `background` option resolved: what
+ * is drawn behind the person, and the person's edge, in the frame's pixels.
+ */
+export interface Backdrop {
+    /** Blur of the background (or of the image): the Gaussian's standard deviation, in the frame's pixels. */
+    blur?: number;
+    /** 0–1 towards black. */
+    dim?: number;
+    /** 0–1 towards gray. */
+    desaturate?: number;
+    /**
+     * A flat colour instead: "#rrggbb" or "#rrggbbaa", or "transparent" (the
+     * person over what is under the layer).
+     */
+    color?: string;
+    /** An image instead (repo path), filling the layer's box (cover). */
+    image?: string;
+    /** The person's edge: its softness and how far it is pulled in, in the frame's pixels. */
+    feather: number;
+    shrink: number;
+}
+/**
+ * A footage layer on the film's clock, resolved for the footage plane: the
+ * host compiles these into ffmpeg filters (render, stills, check's final
+ * look), and the player places a muted <video> by the same numbers.
+ */
+export interface TimelineFootage {
+    /** The part that shows it. */
+    part: string;
+    /** Repo path of the video. */
+    file: string;
+    /** Film seconds it shows from and until (end exclusive), on the frame grid. */
+    start: number;
+    end: number;
+    /**
+     * Video seconds at `start`. Below 0 (a take's own footage whose speech
+     * starts within the lead), its first frame holds until the file starts.
+     * Past the file's end its last frame holds.
+     */
+    from: number;
+    /** Video seconds per film second: at film time t it shows from + (t − start) × speed. */
+    speed: number;
+    /** Its sound's gain, in dB. */
+    gainDb: number;
+    /** Its sound is mixed in. */
+    audio: boolean;
+    /** The part's own take: its sound is the part's speech, never mixed twice. */
+    take?: boolean;
+    fit: "cover" | "contain";
+    /** Where it shows, in the frame's pixels (the timeline's width × height): nothing outside it. */
+    box: PixelRect;
+    /**
+     * The part of the source picture it shows, in the source's pixels: the
+     * whole picture, or the layer's crop. Absent when the source's size is
+     * not known; the picture then fills the box.
+     */
+    crop?: PixelRect;
+    /**
+     * Where that part of the picture is drawn, in the frame's pixels: cover
+     * fills the box and overflows it (the box clips it), contain fits inside.
+     */
+    picture: PixelRect;
+    /**
+     * A cut take's own footage: from film time `at` it shows the file from
+     * `from` on (speed 1), until the next cut. The first cut is at `start`.
+     */
+    cuts?: SpeechCut[];
+    /**
+     * Reframe: the crop's top-left over time, in source pixels (film
+     * seconds, linear between keys); its size stays crop[2] × crop[3], and
+     * the picture is the box.
+     */
+    pan?: {
+        t: number;
+        x: number;
+        y: number;
+    }[];
+    /**
+     * Punch-ins: the zoom over time (1: none) about a point of the box
+     * (fractions), film seconds, eased into each key.
+     */
+    zoom?: {
+        t: number;
+        z: number;
+        cx: number;
+        cy: number;
+        ease?: Ease;
+    }[];
+    /**
+     * Box keyframes: the box over time, in the frame's pixels; what shows in
+     * the box at `box` (picture ∩ box) is drawn into the moving box.
+     */
+    boxes?: {
+        t: number;
+        box: PixelRect;
+        ease?: Ease;
+    }[];
+    /**
+     * How many of its part's graphics planes are under it (`Part.planes`,
+     * back to front): it is drawn over those and under the rest. Absent: 0,
+     * under every plane.
+     */
+    over?: number;
+    /**
+     * The speaker is drawn again, cut out with the person matte, over the
+     * part's behind-person graphics: the plane right over this layer
+     * (`Part.planes[over]`; the part's take, when it has such layers).
+     */
+    cutout?: boolean;
+    /** Sharpening after it is scaled, 0–1 (the layer's `sharpen`); renders only. */
+    sharpen?: number;
+    /**
+     * Its background treated apart from the person (the layer's
+     * `background`), when the file has a person matte: the footage plane
+     * draws the background, then the person through the matte.
+     */
+    background?: Backdrop;
+    /**
+     * The picture shows only in the ellipse inscribed in the box (moving
+     * with a keyframed box); the rest of the box is see-through.
+     */
+    shape?: "circle";
+    /**
+     * The box's corners are rounded by this many frame pixels (at most half
+     * its shorter side; scaling with a keyframed box): what is outside them
+     * is see-through.
+     */
+    radius?: number;
+    /**
+     * The id of the face in the file's face track the layer follows (the
+     * layer's `speaker`); absent: the track's default speaker.
+     */
+    speaker?: number;
+}
+/** A voiced part's speech in the mix. */
+export interface SpeechClip {
+    /** Repo path of the take; the bytes are fetched by sha256. */
+    file: string;
+    /** The part whose speech it is: its recording setup is that part's. */
+    part?: string;
+    /** Film time it starts. */
+    at: number;
+    /** Seconds into the file. */
+    from: number;
+    /** Film seconds it plays. */
+    dur: number;
+    /**
+     * Seconds of the file it plays per second of film, pitch kept (the
+     * take's or the say's speed: ffmpeg's atempo in the mix); absent: 1.
+     */
+    speed?: number;
+    gainDb?: number;
+    /** Noise reduction in dB (the take's denoise). */
+    denoise?: number;
+    /**
+     * Seconds its start fades in over and its end fades out over, with an
+     * equal-power curve: a cross-fade with the clip it overlaps there (room
+     * tone into the take, one loop of room tone into the next). Absent: the
+     * mix's own 10 ms fade at every clip edge.
+     */
+    fadeIn?: number;
+    fadeOut?: number;
+    /** A room tone fill: the part and side it fills, and how its level was set. */
+    tone?: RoomFill;
+}
+/** A room tone fill of a part's lead or tail, measured. */
+export interface RoomFill extends RoomLevel {
+    /** The part's key. */
+    part: string;
+    /** `lead`: before the part's speech; `tail`: after it. */
+    side: "lead" | "tail";
+    /** Film time of the join: where the fill meets the take. */
+    join: number;
+    /** Seconds of its own room the take keeps at the join (before its first word, or after its last). */
+    pad: number;
+    /** Seconds the fill and the take cross-fade over at the join. */
+    fade: number;
+}
+export interface AudioPlan {
+    /** One entry per voiced part, in film order. */
+    speech?: SpeechClip[];
+    /**
+     * A take's room tone filling a part's lead or tail where its own silence
+     * around the words runs out: mixed like speech, holding no words.
+     */
+    room?: SpeechClip[];
+    music?: MusicPlan;
+    /** The output's mix settings (video({ mix }) over the defaults); absent: the defaults. */
+    mix?: MixLevels;
+    /** What the sum is mastered to (video({ master }) over the platform's loudness and the defaults). */
+    master?: MasterTargets;
+    /**
+     * How the speech was recorded, resolved over its presets: the video's
+     * (`video({ mic })`, a studio's finishing when it says none) and the
+     * parts' own; false plays it as it is.
+     */
+    mic?: {
+        video: ResolvedVoice | false;
+        parts?: Record<string, ResolvedVoice | false>;
+    };
+}
+/** The output's music as the timeline plays it. */
+export interface MusicPlan {
+    /** Repo path; absent when this combo has none (or it is missing). */
+    file?: string;
+    /** Seconds into the file at film time 0. */
+    from: number;
+    /** The file plays again while the video goes on. */
+    loop: boolean;
+    /**
+     * The tempo: given (`bpm`) or measured from the file (`confidence`
+     * 0–1 says how steady its beat is); absent when neither is known.
+     */
+    tempo?: {
+        bpm: number;
+        source: "given" | "measured";
+        confidence?: number;
+        /** Measured: seconds into the file of its first beat (a given bpm counts from 0). */
+        beat?: number;
+    };
+    /** Parts without speech ended on the beat (snap asked, and a tempo known). */
+    snapped: boolean;
+    /**
+     * The stretches of the file played on the film, back to back from film
+     * second 0 (`music.play`, then `music.loop`'s stretch again and again),
+     * up to the film's end; absent: the file from `from` to its end, or the
+     * whole file looped (`loop`). Each seam crosses over `seam` seconds.
+     */
+    play?: PlacedStretch[];
+    /** Seconds each seam between stretches cross-fades over. */
+    seam?: number;
+    /** The grid's beats a bar and its downbeat (the file's second of bar 0), when a tempo is known. */
+    meter?: number;
+    downbeat?: number;
+    /**
+     * Film seconds the music stops at, its fade out ending there: the bar
+     * or beat it ends on (`music.end`); absent: the film's end.
+     */
+    until?: number;
+    /** Its level over the film, dB over its level, film seconds (`music.gain`). */
+    gain?: {
+        t: number;
+        db: number;
+    }[];
+    /** How it is shaped, its bands' keys at film seconds (`music.filter`, `eq`, `compress`). */
+    shape?: ResolvedShape;
+}
+export interface Timeline {
+    fps: number;
+    /** The pixels the frame is drawn in. */
+    width: number;
+    height: number;
+    /**
+     * A video in a platform profile's format: the profile, with the
+     * numbers the piece's formats entry changes (covered edges, length,
+     * loudness).
+     */
+    profile?: PlatformProfile;
+    /** A deck's paper (CSS `@page size`): its slide size, as PowerPoint prints it. */
+    paper?: string;
+    duration: number;
+    /**
+     * What the footage plane draws under everything: the look's background
+     * as "#rrggbb" (or "#rrggbbaa"), or "transparent" for a transparent video.
+     */
+    background: string;
+    parts: Part[];
+    cues: Cue[];
+    /** Footage layers, in film order. */
+    footage?: TimelineFootage[];
+    /**
+     * The transitions parts asked for (`part({ transition })`), in film
+     * order: the window of each, and what it does to the two parts'
+     * pictures. Absent: every join is a cut.
+     */
+    transitions?: TimelineTransition[];
+    audio: AudioPlan;
+    /**
+     * What the media index lacks for this output: videos whose face track
+     * (reframe "face", captions that avoid the face, the face check) or
+     * person matte (layers behind the person) the output reads and is not
+     * there yet. Hosts make them on this computer (check, render and dev do).
+     */
+    index?: IndexNeed[];
+}
+/** A video the media index should learn about: its face track, its person matte. */
+export interface IndexNeed {
+    file: string;
+    faces?: true;
+    matte?: true;
+}
+export interface PartText {
+    key: string;
+    onScreen: string[];
+    /** What the part says, as written: the say or saying text, else the take's words. */
+    spoken?: string;
+    /** What it says as read aloud, when that differs (a message's `speak`). */
+    speak?: string;
+    /** The message key the spoken text came from (say(s(key)), saying(s(key))). */
+    speechKey?: string;
+    /** A deck's speaker notes for this slide (the script's `notes`). */
+    notes?: string;
+}
+export interface MessageRead {
+    key: string;
+    part?: string;
+    kind: "text" | "list";
+    hint?: MessageHint;
+    fallback: boolean;
+}
+export interface Reads {
+    messages: MessageRead[];
+    media: {
+        path: string;
+        sha256: string;
+        part?: string;
+        kind: MediaKind;
+    }[];
+    /** Data files read with ctx.data (imported data is in the bundle). */
+    data: {
+        path: string;
+        sha256: string;
+    }[];
+}
+export interface CoverInfo {
+    key: string;
+    /** What its layers are: component names, and "footage". */
+    layers: string[];
+}
+/**
+ * A moment of a video by a reference of its own, in film seconds: an
+ * anchor of one of its parts ("@click" its start, "@/click" its end,
+ * "@click+0.2" shifted), the first part in film order that has it; or a
+ * part's key, its start. Throws, naming what there is, for anything else.
+ */
+export declare function momentOf(tl: {
+    readonly parts: readonly {
+        readonly key: string;
+        readonly start: number;
+        readonly anchors?: readonly PartAnchor[] | undefined;
+    }[];
+}, ref: string): number;
+/**
+ * What a moment shows that an editor lets a person point at
+ * (LoadedOutput.objects): what was placed on a deck's page (by its
+ * element's id) and every text block, with the message keys its words are
+ * (none: words written in code), each box in the frame's pixels.
+ */
+export interface PageObjects {
+    t: number;
+    elements: {
+        id: string;
+        box: [number, number, number, number];
+    }[];
+    texts: {
+        text: string;
+        box: [number, number, number, number];
+        /** Its font size as drawn, in the frame's pixels. */
+        size: number;
+        keys: string[];
+    }[];
+}
+//# sourceMappingURL=timeline.d.ts.map

package/dist/node_modules/@allyhub-next/video-core/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@allyhub-next/video-core",
+  "version": "0.5.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "private": true,
+  "license": "SEE LICENSE IN LICENSE.md"
+}