@clipwright/core 0.34.0 → 0.35.0

package/dist/reference-staging.d.ts

@@ -0,0 +1,571 @@
+import { z } from "zod";
+export declare const REFERENCE_STAGING_VERSION = "reference-staging-v1";
+export declare const STAGING_METHODS: readonly ["cv-cells/v1", "cv-template/v1", "cv-parallax/v1", "cv-before-after/v1", "yunet-native/v1", "vision-video", "vision-still"];
+export declare const STAGING_ANCHOR_KINDS: readonly ["cut", "flash", "freeze_start", "freeze_end", "beat"];
+export declare const STAGING_ENTRY_STYLES: readonly ["pop", "fade", "blur_in", "slide", "scale_up", "tilt_in", "typewriter", "wipe", "unknown"];
+export declare const STAGING_EXIT_STYLES: readonly ["pop", "fade", "blur_in", "slide", "scale_up", "tilt_in", "typewriter", "wipe", "unknown", "cut", "flash"];
+export declare const STAGING_SIDES: readonly ["left", "right", "top", "bottom", "lower_left", "lower_right", "upper_left", "upper_right", "none"];
+export declare const STAGING_LAYERS: readonly ["in_front_of_presenter", "behind_presenter", "no_overlap", "presenter_absent", "unknown"];
+export declare const STAGING_COVERS: readonly ["hair", "face", "shoulder", "hand", "body", "chair", "microphone", "desk", "other"];
+export type StagingCover = (typeof STAGING_COVERS)[number];
+export declare const STAGING_MOTIONS: readonly ["static", "float", "drift", "scale", "moves_with_frame", "pushed"];
+export declare const STAGING_GAZES: readonly ["camera", "up_left", "up_right", "left", "right", "down", "element", "closed"];
+/** The image side the top of the head leans to; a roll within ±5° is upright. */
+export declare const STAGING_HEAD_ROLLS: readonly ["left", "right", "upright"];
+export declare const STAGING_EXPRESSIONS: readonly ["neutral", "smile", "surprised", "thinking", "other"];
+export declare const STAGING_HANDS: readonly ["at_chest", "gesturing", "out_of_frame", "other"];
+export declare const STAGING_FREEZE_ENDS: readonly ["cut", "flash", "unfreeze", "end"];
+export declare const stagingRect: z.ZodObject<{
+    left: z.ZodNumber;
+    top: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strict>;
+export type StagingRect = z.infer<typeof stagingRect>;
+export declare const stagingFaceRect: z.ZodObject<{
+    left: z.ZodNumber;
+    top: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strict>;
+/** A moment named by its anchor: the nearest anchor on a side is never used, because it moves when the edit does. */
+export declare const stagingAnchorRef: z.ZodObject<{
+    id: z.ZodString;
+    offset_s: z.ZodNumber;
+}, z.core.$strict>;
+export declare const stagingElement: z.ZodObject<{
+    id: z.ZodString;
+    beat_index: z.ZodNumber;
+    graphic_index: z.ZodNullable<z.ZodNumber>;
+    kind: z.ZodEnum<{
+        before_after_split: "before_after_split";
+        callout: "callout";
+        checklist: "checklist";
+        compare: "compare";
+        end_card: "end_card";
+        insert_media: "insert_media";
+        layout_split: "layout_split";
+        lower_third: "lower_third";
+        notification: "notification";
+        other: "other";
+        overlay_media: "overlay_media";
+        particles: "particles";
+        phone_call: "phone_call";
+        product_ui: "product_ui";
+        progress: "progress";
+        quote: "quote";
+        rating: "rating";
+        screenshot: "screenshot";
+        split_screen: "split_screen";
+        stat: "stat";
+        tag: "tag";
+        title_card: "title_card";
+        toggle_checklist: "toggle_checklist";
+        unmapped: "unmapped";
+    }>;
+    rect_hold: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    rect_hold_face: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    rect_method: z.ZodOptional<z.ZodEnum<{
+        "cv-before-after/v1": "cv-before-after/v1";
+        "cv-cells/v1": "cv-cells/v1";
+        "cv-parallax/v1": "cv-parallax/v1";
+        "cv-template/v1": "cv-template/v1";
+        "vision-still": "vision-still";
+        "vision-video": "vision-video";
+        "yunet-native/v1": "yunet-native/v1";
+    }>>;
+    rects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        t_s: z.ZodNumber;
+        rect: z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>;
+        visible: z.ZodNumber;
+    }, z.core.$strict>>>;
+    entry: z.ZodOptional<z.ZodObject<{
+        first_visible_s: z.ZodOptional<z.ZodNumber>;
+        settled_s: z.ZodOptional<z.ZodNumber>;
+        anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            offset_s: z.ZodNumber;
+        }, z.core.$strict>>>;
+        style: z.ZodOptional<z.ZodEnum<{
+            blur_in: "blur_in";
+            fade: "fade";
+            pop: "pop";
+            scale_up: "scale_up";
+            slide: "slide";
+            tilt_in: "tilt_in";
+            typewriter: "typewriter";
+            unknown: "unknown";
+            wipe: "wipe";
+        }>>;
+        from: z.ZodOptional<z.ZodEnum<{
+            bottom: "bottom";
+            left: "left";
+            lower_left: "lower_left";
+            lower_right: "lower_right";
+            none: "none";
+            right: "right";
+            top: "top";
+            upper_left: "upper_left";
+            upper_right: "upper_right";
+        }>>;
+        duration_s: z.ZodOptional<z.ZodNumber>;
+        displacement: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        scale_from: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        method: z.ZodOptional<z.ZodEnum<{
+            "cv-before-after/v1": "cv-before-after/v1";
+            "cv-cells/v1": "cv-cells/v1";
+            "cv-parallax/v1": "cv-parallax/v1";
+            "cv-template/v1": "cv-template/v1";
+            "vision-still": "vision-still";
+            "vision-video": "vision-video";
+            "yunet-native/v1": "yunet-native/v1";
+        }>>;
+    }, z.core.$strict>>;
+    exit: z.ZodOptional<z.ZodObject<{
+        last_visible_s: z.ZodOptional<z.ZodNumber>;
+        anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            offset_s: z.ZodNumber;
+        }, z.core.$strict>>>;
+        style: z.ZodOptional<z.ZodEnum<{
+            blur_in: "blur_in";
+            cut: "cut";
+            fade: "fade";
+            flash: "flash";
+            pop: "pop";
+            scale_up: "scale_up";
+            slide: "slide";
+            tilt_in: "tilt_in";
+            typewriter: "typewriter";
+            unknown: "unknown";
+            wipe: "wipe";
+        }>>;
+        to: z.ZodOptional<z.ZodEnum<{
+            bottom: "bottom";
+            left: "left";
+            lower_left: "lower_left";
+            lower_right: "lower_right";
+            none: "none";
+            right: "right";
+            top: "top";
+            upper_left: "upper_left";
+            upper_right: "upper_right";
+        }>>;
+        duration_s: z.ZodOptional<z.ZodNumber>;
+        displacement: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        method: z.ZodOptional<z.ZodEnum<{
+            "cv-before-after/v1": "cv-before-after/v1";
+            "cv-cells/v1": "cv-cells/v1";
+            "cv-parallax/v1": "cv-parallax/v1";
+            "cv-template/v1": "cv-template/v1";
+            "vision-still": "vision-still";
+            "vision-video": "vision-video";
+            "yunet-native/v1": "yunet-native/v1";
+        }>>;
+    }, z.core.$strict>>;
+    layer: z.ZodOptional<z.ZodObject<{
+        value: z.ZodEnum<{
+            behind_presenter: "behind_presenter";
+            in_front_of_presenter: "in_front_of_presenter";
+            no_overlap: "no_overlap";
+            presenter_absent: "presenter_absent";
+            unknown: "unknown";
+        }>;
+        method: z.ZodEnum<{
+            "cv-before-after/v1": "cv-before-after/v1";
+            "cv-cells/v1": "cv-cells/v1";
+            "cv-parallax/v1": "cv-parallax/v1";
+            "cv-template/v1": "cv-template/v1";
+            "vision-still": "vision-still";
+            "vision-video": "vision-video";
+            "yunet-native/v1": "yunet-native/v1";
+        }>;
+        covered_by: z.ZodArray<z.ZodEnum<{
+            body: "body";
+            chair: "chair";
+            desk: "desk";
+            face: "face";
+            hair: "hair";
+            hand: "hand";
+            microphone: "microphone";
+            other: "other";
+            shoulder: "shoulder";
+        }>>;
+        face_clear: z.ZodOptional<z.ZodBoolean>;
+        face_core_cover_max: z.ZodOptional<z.ZodNumber>;
+        face_covered_share: z.ZodOptional<z.ZodNumber>;
+        blurs_presenter: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    motion: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodOptional<z.ZodEnum<{
+            drift: "drift";
+            float: "float";
+            moves_with_frame: "moves_with_frame";
+            pushed: "pushed";
+            scale: "scale";
+            static: "static";
+        }>>;
+        drift_per_s: z.ZodOptional<z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+        scale_per_s: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        wobble: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+            amplitude: z.ZodNumber;
+            period_s: z.ZodNumber;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type StagingElement = z.infer<typeof stagingElement>;
+export declare const stagingFreeze: z.ZodObject<{
+    start_s: z.ZodNumber;
+    end_s: z.ZodNumber;
+    anchors: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        offset_s: z.ZodNumber;
+    }, z.core.$strict>>;
+    face_box_start: z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>;
+    face_box_end: z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>;
+    roll_deg: z.ZodNumber;
+    yaw: z.ZodNumber;
+    pitch: z.ZodNumber;
+    gaze: z.ZodOptional<z.ZodEnum<{
+        camera: "camera";
+        closed: "closed";
+        down: "down";
+        element: "element";
+        left: "left";
+        right: "right";
+        up_left: "up_left";
+        up_right: "up_right";
+    }>>;
+    head_roll: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        upright: "upright";
+    }>;
+    expression: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        other: "other";
+        smile: "smile";
+        surprised: "surprised";
+        thinking: "thinking";
+    }>>;
+    hands: z.ZodOptional<z.ZodEnum<{
+        at_chest: "at_chest";
+        gesturing: "gesturing";
+        other: "other";
+        out_of_frame: "out_of_frame";
+    }>>;
+    frame_motion: z.ZodOptional<z.ZodObject<{
+        scale_end: z.ZodNumber;
+        centre_shift: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strict>>;
+    ends_with: z.ZodEnum<{
+        cut: "cut";
+        end: "end";
+        flash: "flash";
+        unfreeze: "unfreeze";
+    }>;
+}, z.core.$strict>;
+export type StagingFreeze = z.infer<typeof stagingFreeze>;
+export declare const referenceStaging: z.ZodObject<{
+    version: z.ZodLiteral<"reference-staging-v1">;
+    analysis_width: z.ZodNumber;
+    anchors: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        t_s: z.ZodNumber;
+    }, z.core.$strict>>;
+    elements: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        beat_index: z.ZodNumber;
+        graphic_index: z.ZodNullable<z.ZodNumber>;
+        kind: z.ZodEnum<{
+            before_after_split: "before_after_split";
+            callout: "callout";
+            checklist: "checklist";
+            compare: "compare";
+            end_card: "end_card";
+            insert_media: "insert_media";
+            layout_split: "layout_split";
+            lower_third: "lower_third";
+            notification: "notification";
+            other: "other";
+            overlay_media: "overlay_media";
+            particles: "particles";
+            phone_call: "phone_call";
+            product_ui: "product_ui";
+            progress: "progress";
+            quote: "quote";
+            rating: "rating";
+            screenshot: "screenshot";
+            split_screen: "split_screen";
+            stat: "stat";
+            tag: "tag";
+            title_card: "title_card";
+            toggle_checklist: "toggle_checklist";
+            unmapped: "unmapped";
+        }>;
+        rect_hold: z.ZodOptional<z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        rect_hold_face: z.ZodOptional<z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        rect_method: z.ZodOptional<z.ZodEnum<{
+            "cv-before-after/v1": "cv-before-after/v1";
+            "cv-cells/v1": "cv-cells/v1";
+            "cv-parallax/v1": "cv-parallax/v1";
+            "cv-template/v1": "cv-template/v1";
+            "vision-still": "vision-still";
+            "vision-video": "vision-video";
+            "yunet-native/v1": "yunet-native/v1";
+        }>>;
+        rects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            t_s: z.ZodNumber;
+            rect: z.ZodObject<{
+                left: z.ZodNumber;
+                top: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>;
+            visible: z.ZodNumber;
+        }, z.core.$strict>>>;
+        entry: z.ZodOptional<z.ZodObject<{
+            first_visible_s: z.ZodOptional<z.ZodNumber>;
+            settled_s: z.ZodOptional<z.ZodNumber>;
+            anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                offset_s: z.ZodNumber;
+            }, z.core.$strict>>>;
+            style: z.ZodOptional<z.ZodEnum<{
+                blur_in: "blur_in";
+                fade: "fade";
+                pop: "pop";
+                scale_up: "scale_up";
+                slide: "slide";
+                tilt_in: "tilt_in";
+                typewriter: "typewriter";
+                unknown: "unknown";
+                wipe: "wipe";
+            }>>;
+            from: z.ZodOptional<z.ZodEnum<{
+                bottom: "bottom";
+                left: "left";
+                lower_left: "lower_left";
+                lower_right: "lower_right";
+                none: "none";
+                right: "right";
+                top: "top";
+                upper_left: "upper_left";
+                upper_right: "upper_right";
+            }>>;
+            duration_s: z.ZodOptional<z.ZodNumber>;
+            displacement: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            scale_from: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+            method: z.ZodOptional<z.ZodEnum<{
+                "cv-before-after/v1": "cv-before-after/v1";
+                "cv-cells/v1": "cv-cells/v1";
+                "cv-parallax/v1": "cv-parallax/v1";
+                "cv-template/v1": "cv-template/v1";
+                "vision-still": "vision-still";
+                "vision-video": "vision-video";
+                "yunet-native/v1": "yunet-native/v1";
+            }>>;
+        }, z.core.$strict>>;
+        exit: z.ZodOptional<z.ZodObject<{
+            last_visible_s: z.ZodOptional<z.ZodNumber>;
+            anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                offset_s: z.ZodNumber;
+            }, z.core.$strict>>>;
+            style: z.ZodOptional<z.ZodEnum<{
+                blur_in: "blur_in";
+                cut: "cut";
+                fade: "fade";
+                flash: "flash";
+                pop: "pop";
+                scale_up: "scale_up";
+                slide: "slide";
+                tilt_in: "tilt_in";
+                typewriter: "typewriter";
+                unknown: "unknown";
+                wipe: "wipe";
+            }>>;
+            to: z.ZodOptional<z.ZodEnum<{
+                bottom: "bottom";
+                left: "left";
+                lower_left: "lower_left";
+                lower_right: "lower_right";
+                none: "none";
+                right: "right";
+                top: "top";
+                upper_left: "upper_left";
+                upper_right: "upper_right";
+            }>>;
+            duration_s: z.ZodOptional<z.ZodNumber>;
+            displacement: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            method: z.ZodOptional<z.ZodEnum<{
+                "cv-before-after/v1": "cv-before-after/v1";
+                "cv-cells/v1": "cv-cells/v1";
+                "cv-parallax/v1": "cv-parallax/v1";
+                "cv-template/v1": "cv-template/v1";
+                "vision-still": "vision-still";
+                "vision-video": "vision-video";
+                "yunet-native/v1": "yunet-native/v1";
+            }>>;
+        }, z.core.$strict>>;
+        layer: z.ZodOptional<z.ZodObject<{
+            value: z.ZodEnum<{
+                behind_presenter: "behind_presenter";
+                in_front_of_presenter: "in_front_of_presenter";
+                no_overlap: "no_overlap";
+                presenter_absent: "presenter_absent";
+                unknown: "unknown";
+            }>;
+            method: z.ZodEnum<{
+                "cv-before-after/v1": "cv-before-after/v1";
+                "cv-cells/v1": "cv-cells/v1";
+                "cv-parallax/v1": "cv-parallax/v1";
+                "cv-template/v1": "cv-template/v1";
+                "vision-still": "vision-still";
+                "vision-video": "vision-video";
+                "yunet-native/v1": "yunet-native/v1";
+            }>;
+            covered_by: z.ZodArray<z.ZodEnum<{
+                body: "body";
+                chair: "chair";
+                desk: "desk";
+                face: "face";
+                hair: "hair";
+                hand: "hand";
+                microphone: "microphone";
+                other: "other";
+                shoulder: "shoulder";
+            }>>;
+            face_clear: z.ZodOptional<z.ZodBoolean>;
+            face_core_cover_max: z.ZodOptional<z.ZodNumber>;
+            face_covered_share: z.ZodOptional<z.ZodNumber>;
+            blurs_presenter: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        motion: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodOptional<z.ZodEnum<{
+                drift: "drift";
+                float: "float";
+                moves_with_frame: "moves_with_frame";
+                pushed: "pushed";
+                scale: "scale";
+                static: "static";
+            }>>;
+            drift_per_s: z.ZodOptional<z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+            scale_per_s: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+            wobble: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+                amplitude: z.ZodNumber;
+                period_s: z.ZodNumber;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    freezes: z.ZodArray<z.ZodObject<{
+        start_s: z.ZodNumber;
+        end_s: z.ZodNumber;
+        anchors: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            offset_s: z.ZodNumber;
+        }, z.core.$strict>>;
+        face_box_start: z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>;
+        face_box_end: z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>;
+        roll_deg: z.ZodNumber;
+        yaw: z.ZodNumber;
+        pitch: z.ZodNumber;
+        gaze: z.ZodOptional<z.ZodEnum<{
+            camera: "camera";
+            closed: "closed";
+            down: "down";
+            element: "element";
+            left: "left";
+            right: "right";
+            up_left: "up_left";
+            up_right: "up_right";
+        }>>;
+        head_roll: z.ZodEnum<{
+            left: "left";
+            right: "right";
+            upright: "upright";
+        }>;
+        expression: z.ZodOptional<z.ZodEnum<{
+            neutral: "neutral";
+            other: "other";
+            smile: "smile";
+            surprised: "surprised";
+            thinking: "thinking";
+        }>>;
+        hands: z.ZodOptional<z.ZodEnum<{
+            at_chest: "at_chest";
+            gesturing: "gesturing";
+            other: "other";
+            out_of_frame: "out_of_frame";
+        }>>;
+        frame_motion: z.ZodOptional<z.ZodObject<{
+            scale_end: z.ZodNumber;
+            centre_shift: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strict>>;
+        ends_with: z.ZodEnum<{
+            cut: "cut";
+            end: "end";
+            flash: "flash";
+            unfreeze: "unfreeze";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ReferenceStaging = z.infer<typeof referenceStaging>;
+/** Cross-field checks a profile runs on its staging: the beats and graphics it names exist, its anchors exist, and its times are ordered. */
+export declare function stagingIssues(staging: ReferenceStaging, beats: readonly {
+    graphics: readonly unknown[];
+}[], duration: number): {
+    path: (string | number)[];
+    message: string;
+}[];
+/** A frame rect in face units: origin the face box's centre, unit its height in pixels (Q2: our actor does not sit where theirs does). */
+export declare function faceRelativeRect(rect: StagingRect, face: StagingRect, width: number, height: number): z.infer<typeof stagingFaceRect>;
+/** Samples thinned to change points: one is kept when an edge moved more than `tolerance` since the last kept, and the last always stays. */
+export declare function thinStagingRects<T extends {
+    rect: StagingRect;
+}>(samples: readonly T[], tolerance?: number, max?: number): T[];