@dojo-video-engine/player 0.0.0-stage → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { type Scene } from "@dojo-video-engine/schema";
+import { type ResolvedAssets, type ResolveAssetsOptions, type ScratchSurfacePool, type Canvas2DStaticDisplayCache, type Canvas2DOpaqueExtensionRegistry } from "@dojo-video-engine/renderer-canvas2d";
+import { type Canvas2DSceneRuntime } from "@dojo-video-engine/renderer-canvas2d/runtime";
+import { type AudioPreview } from "./audio.js";
+export { ChunkedWebAudioPreview, previewAudioChunkRange, WebAudioPreview, type AudioPreview, } from "./audio.js";
+/**
+ * Maps wall-clock time to scene frames. This is the only place in the
+ * playback path where wall-clock time exists: rendering stays a pure function
+ * of (scene, frame). The clock is pure given injected timestamps, so playback
+ * timing is unit-testable without timers.
+ *
+ * Frames are integers in [0, durationInFrames). While playing, the frame at
+ * time `now` is anchored to the play() position: floor((now − anchorTime) /
+ * 1000 × fps) + anchorFrame. Pausing re-anchors; seeking re-anchors while
+ * preserving play state.
+ */
+export declare class FrameClock {
+    readonly fps: number;
+    readonly durationInFrames: number;
+    loop: boolean;
+    private anchorFrame;
+    private anchorTime;
+    private isPlaying;
+    constructor(options: {
+        fps: number;
+        durationInFrames: number;
+        loop?: boolean;
+    });
+    get playing(): boolean;
+    /** Starts (or restarts) playback at the current frame position. */
+    play(now: number): void;
+    /** Freezes the clock at the frame visible at `now`. */
+    pause(now: number): void;
+    /** Jumps to a frame (clamped to the scene range), preserving play state. */
+    seek(frame: number, now: number): void;
+    /**
+     * The frame visible at wall time `now`, and whether non-looping playback
+     * has run past the final frame. Calling this never mutates the clock;
+     * the caller decides what to do at the end (pause, loop is internal).
+     */
+    frameAt(now: number): {
+        frame: number;
+        ended: boolean;
+    };
+}
+export type PlayerEvent = "frame" | "play" | "pause" | "ended";
+export type PlayerOptions = {
+    /** A 2D context sized to the scene; the player draws into it. */
+    context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+    scene: unknown;
+    /** Host-owned frame renderer (for example a worker). Requires audio:false;
+     * the host owns media resolution and renderer disposal. */
+    renderFrame?: (frame: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * Pre-resolved assets. When omitted, createPlayer() resolves them and
+     * dispose() releases them; when provided, the caller owns their lifetime.
+     */
+    assets?: ResolvedAssets;
+    /** Trusted extension definitions used when resolving extension nodes. */
+    extensions?: ResolveAssetsOptions["extensions"];
+    /** Require every extension definition to support worker execution. */
+    worker?: boolean;
+    /** Exact opaque handlers used for extension display preflight/execution. */
+    opaqueExtensionRegistry?: Canvas2DOpaqueExtensionRegistry;
+    /** Preview uses declared proxy sources by default. */
+    preferProxy?: boolean;
+    /** Decoder/cache/image memory limits forwarded to asset resolution. */
+    budget?: ResolveAssetsOptions["budget"];
+    assetPolicy?: ResolveAssetsOptions["assetPolicy"];
+    analysisCache?: ResolveAssetsOptions["analysisCache"];
+    fontCache?: ResolveAssetsOptions["fontCache"];
+    /** Cancels asset resolution and in-flight frame preparation. */
+    signal?: AbortSignal;
+    analyzeWaveforms?: boolean;
+    /** Reused for every frame; the caller retains ownership and must dispose it. */
+    scratchSurfacePool?: ScratchSurfacePool;
+    /** Caller-owned bounded static raster cache; Player never disposes it. */
+    staticDisplayCache?: Canvas2DStaticDisplayCache;
+    loop?: boolean;
+    /**
+     * Audio preview. Defaults to a WebAudioPreview when the environment has
+     * AudioContext; pass `false` to disable sound, or your own AudioPreview.
+     * Preview audio is best-effort — the export is the audio source of truth.
+     */
+    audio?: AudioPreview | false;
+    /** Injectable time source for tests; defaults to performance.now. */
+    now?: () => number;
+    /** Injectable frame scheduler for tests; defaults to requestAnimationFrame. */
+    requestFrame?: (callback: () => void) => number;
+    cancelFrame?: (handle: number) => void;
+};
+type PlayerRuntimeOwnedOption = "scene" | "assets" | "extensions" | "worker" | "opaqueExtensionRegistry" | "preferProxy" | "budget" | "assetPolicy" | "analysisCache" | "fontCache" | "analyzeWaveforms" | "scratchSurfacePool" | "staticDisplayCache";
+/**
+ * Player options for an already-prepared Canvas2D runtime. Media resolution
+ * belongs to the runtime; the player only borrows its current Scene/assets.
+ */
+export type RuntimePlayerOptions = Omit<PlayerOptions, PlayerRuntimeOwnedOption>;
+type PlayerLifecycle = {
+    onDisposeRequested?: () => void;
+};
+/**
+ * A playing/seekable view of a scene on a canvas. Create with createPlayer().
+ *
+ * The render loop awaits prepareFrame() per displayed frame (video decode),
+ * so a slow decode never tears: the player skips to the latest target frame
+ * rather than rendering stale intermediates.
+ */
+export declare class Player {
+    readonly scene: Scene;
+    private readonly clock;
+    private readonly context;
+    private readonly externalRenderFrame;
+    private readonly assets;
+    private readonly ownsAssets;
+    private readonly now;
+    private readonly requestFrame;
+    private readonly cancelFrame;
+    private readonly signal;
+    private readonly scratchSurfacePool;
+    private readonly staticDisplayCache;
+    private readonly renderController;
+    private unlinkOptionSignal;
+    private listeners;
+    private renderedFrame;
+    private rafHandle;
+    private rendering;
+    private renderQueue;
+    private assetsReleased;
+    private disposed;
+    private disposalPromise;
+    private lastRenderError;
+    private errorListeners;
+    private audio;
+    private pendingAudio;
+    private readonly disposedAudio;
+    private audioReadyPromise;
+    private readonly textMeasureCache;
+    private onDisposeRequested;
+    /** @internal — use createPlayer(). */
+    constructor(scene: Scene, options: PlayerOptions, assets: ResolvedAssets | undefined, ownsAssets: boolean, lifecycle?: PlayerLifecycle);
+    get playing(): boolean;
+    /** The most recently rendered frame (−1 before the first render). */
+    get currentFrame(): number;
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Last asynchronous render-loop error, if playback stopped because of one. */
+    get error(): Error | null;
+    onError(listener: (error: Error) => void): () => void;
+    /**
+     * Resolves once the audio preview is attached, or once the player knows
+     * there will be none (silent scene, unsupported environment, mix failure).
+     * The mix is prepared off the critical path, so the first frame paints
+     * before sound exists; playback started earlier joins the audio clock the
+     * moment it attaches. Await this when audio must be live before play().
+     */
+    get audioReady(): Promise<void>;
+    on(event: PlayerEvent, listener: (frame: number) => void): () => void;
+    play(): void;
+    pause(): void;
+    /** Jumps to a frame and renders it; resolves when the frame is on screen. */
+    seek(frame: number): Promise<void>;
+    /** Stops playback and releases player-owned assets. */
+    dispose(): void;
+    /** Stops playback and waits for audio/render work and owned media teardown. */
+    disposeAsync(): Promise<void>;
+    /** @internal — wired by createPlayer() after load() decides audibility. */
+    attachAudio(audio: AudioPreview): void;
+    /** @internal — binds preview preparation to the player lifecycle signal. */
+    loadAudio(audio: AudioPreview): Promise<boolean>;
+    /** @internal — clears a preview that resolved silent or failed to load. */
+    discardAudio(audio: AudioPreview): void;
+    private disposeAudioOnce;
+    /** @internal — wired by createPlayer(). */
+    setAudioReady(ready: Promise<void>): void;
+    /** @internal — first paint from createPlayer(). */
+    renderInitialFrame(): Promise<void>;
+    private scheduleTick;
+    private stopTicking;
+    private tick;
+    private renderFrame;
+    private performRenderFrame;
+    private beginDisposal;
+    private releaseOwnedAssets;
+    private handleRenderError;
+    private emit;
+    private assertAlive;
+}
+/**
+ * Validates the scene, resolves assets (unless provided), renders frame 0,
+ * and returns a ready Player.
+ */
+export declare function createPlayer(options: PlayerOptions): Promise<Player>;
+/**
+ * Creates a player that borrows the current prepared Canvas2D runtime state.
+ *
+ * The compatibility scope stays open until the player is fully disposed, so
+ * the runtime cannot replace or release media while a frame/audio task still
+ * uses it. A runtime update/disposal or caller abort disposes the player and
+ * releases the scope before the newer runtime operation can continue.
+ */
+export declare function createPlayerFromRuntime(runtime: Canvas2DSceneRuntime, options: RuntimePlayerOptions): Promise<Player>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,+BAA+B,EAErC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,IAAI,EAAE,OAAO,CAAC;IAEd,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,gBAAgB,EAAE,MAAM,CAAC;QACzB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB;IAoBD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,mEAAmE;IACnE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAevB,uDAAuD;IACvD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IASxB,4EAA4E;IAC5E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAQtC;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE;CAkBxD;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAyB/D,MAAM,MAAM,aAAa,GAAG;IAC1B,iEAAiE;IACjE,OAAO,EAAE,wBAAwB,GAAG,iCAAiC,CAAC;IACtE,KAAK,EAAE,OAAO,CAAC;IACf;+DAC2D;IAC3D,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,yEAAyE;IACzE,UAAU,CAAC,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAChD,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,uBAAuB,CAAC,EAAE,+BAA+B,CAAC;IAC1D,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,MAAM,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACxC,WAAW,CAAC,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAC;IAClD,aAAa,CAAC,EAAE,oBAAoB,CAAC,eAAe,CAAC,CAAC;IACtD,SAAS,CAAC,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC9C,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IAChD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC;IAC7B,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC;IAChD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC,CAAC;AAEF,KAAK,wBAAwB,GACzB,OAAO,GACP,QAAQ,GACR,YAAY,GACZ,QAAQ,GACR,yBAAyB,GACzB,aAAa,GACb,QAAQ,GACR,aAAa,GACb,eAAe,GACf,WAAW,GACX,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,aAAa,EACb,wBAAwB,CACzB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;CACjC,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,MAAM;IACjB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA+B;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IACpE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyC;IAC5E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,kBAAkB,CAA6B;IAEvD,OAAO,CAAC,SAAS,CAAwD;IACzE,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;IAC7D,OAAO,CAAC,iBAAiB,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CACD;IAChC,OAAO,CAAC,kBAAkB,CAAsB;IAEhD,sCAAsC;gBAEpC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,UAAU,EAAE,OAAO,EACnB,SAAS,GAAE,eAAoB;IAkCjC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,qEAAqE;IACrE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,OAAO,EAEtB;IAED,+EAA+E;IAC/E,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAExB;IAED,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD;;;;;;OAMG;IACH,IAAI,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9B;IAED,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IASrE,IAAI,IAAI,IAAI;IAcZ,KAAK,IAAI,IAAI;IAab,6EAA6E;IACvE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxC,uDAAuD;IACvD,OAAO,IAAI,IAAI;IA4Bf,+EAA+E;IACzE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnC,2EAA2E;IAC3E,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAgBtC,4EAA4E;IAC5E,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhD,2EAA2E;IAC3E,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAKvC,OAAO,CAAC,gBAAgB;IAMxB,2CAA2C;IAC3C,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAIzC,mDAAmD;IAC7C,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzC,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,WAAW;YAOL,IAAI;YA4CJ,WAAW;YAQX,kBAAkB;IAmDhC,OAAO,CAAC,aAAa;YAUP,kBAAkB;IAShC,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,WAAW;CAOpB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E;AA4ED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAsEjB"}