@smoove/core 0.1.0

package/dist/engine/composition.d.ts

@@ -0,0 +1,182 @@
+import Konva from "konva";
+import type { AudioAsset } from "../media/audio/asset.js";
+import { AudioMixer } from "../media/audio/mixer.js";
+import { type Environment, type EnvironmentMode } from "./environment.js";
+import { type SequenceProvider } from "./sequence.js";
+import { type ReadonlySignal } from "./signal.js";
+export type CompositionOptions<P extends Record<string, unknown> = Record<string, unknown>> = Konva.StageConfig & {
+    id: string;
+    fps: number;
+    durationInFrames: number;
+    loop?: boolean;
+    /** Initial props handed to the scene. Read live with `comp.props.get()` in
+        updaters; pushed to with `comp.setProps()` by a player or the studio. */
+    props?: P;
+    /** Force the runtime environment. Defaults to ambient detection (see `detectEnvironment`). */
+    mode?: EnvironmentMode;
+};
+export type CompositionEvent = {
+    frame: number;
+    durationInFrames: number;
+};
+/**
+ * Asset-buffering state. `"idle"` — nothing pending; `"buffering"` — one or more
+ * assets (fonts, …) are still loading; `"ready"` — everything registered so far
+ * has settled. Observe it to show a spinner; `play()` honors it (see below).
+ */
+export type BufferState = "idle" | "buffering" | "ready";
+export type CompositionEventMap = {
+    play: CompositionEvent;
+    stop: CompositionEvent;
+    time: CompositionEvent;
+};
+export type CompositionEventName = keyof CompositionEventMap;
+export declare function getComposition(stage: Konva.Stage): Composition | null;
+export declare class Composition<P extends Record<string, unknown> = Record<string, unknown>> extends Konva.Stage {
+    readonly fps: number;
+    readonly environment: Environment;
+    /** Composition-level audio bus — master volume/mute scaling every Video and Audio. */
+    readonly mixer: AudioMixer;
+    readonly frame: ReadonlySignal<number>;
+    readonly isPlaying: ReadonlySignal<boolean>;
+    readonly durationInFrames: ReadonlySignal<number>;
+    readonly isStopped: ReadonlySignal<boolean>;
+    readonly isPaused: ReadonlySignal<boolean>;
+    readonly loop: ReadonlySignal<boolean>;
+    /** Playback speed multiplier. 1 = realtime; negative plays in reverse. */
+    readonly playbackRate: ReadonlySignal<number>;
+    /** Live props the scene reads. Pushed to with {@link setProps} by a player or
+        the studio form; updaters read it via `comp.props.get()`. */
+    readonly props: ReadonlySignal<P>;
+    /** Asset-buffering state — `"idle"` | `"buffering"` | `"ready"`. See {@link registerAsset}. */
+    readonly buffer: ReadonlySignal<BufferState>;
+    /** Convenience: `buffer.get() === "buffering"`. */
+    readonly isBuffering: ReadonlySignal<boolean>;
+    private readonly _frame;
+    private readonly _props;
+    private readonly _isPlaying;
+    private readonly _durationInFrames;
+    private readonly _loop;
+    private readonly _playbackRate;
+    private readonly _buffer;
+    private readonly _emitter;
+    private _rafId;
+    private _startWallMs;
+    private _startFrame;
+    private _suspended;
+    private readonly _assets;
+    private _readyWaiters;
+    private _resumeOnReady;
+    private readonly _renderHandles;
+    private _nextHandle;
+    private _renderWaiters;
+    private _audioAssets;
+    private _captureCanvas;
+    constructor(opts: CompositionOptions<P>);
+    on(evtStr: any, handler: any): any;
+    off(evtStr?: any, handler?: any): any;
+    add(first: Konva.Layer | SequenceProvider, ...rest: (Konva.Layer | SequenceProvider)[]): this;
+    play(): void;
+    private _startClock;
+    destroy(): this;
+    pause(): void;
+    /** `true` between {@link suspend} and {@link resume}. */
+    get isSuspended(): boolean;
+    /**
+     * Release background work — halt the clock and tell every media node to drop
+     * its source, so a composition that isn't being shown (e.g. a `<smoove-player>`
+     * removed from the DOM) stops downloading/decoding video and audio. This does
+     * NOT tear the composition down: the scene graph stays intact and {@link resume}
+     * re-acquires the sources. No-op if already suspended.
+     */
+    suspend(): void;
+    /**
+     * Undo {@link suspend}: re-acquire the media sources released while suspended
+     * (they re-download and redraw once ready) and repaint the current frame.
+     * No-op if not suspended.
+     */
+    resume(): void;
+    /** Walk every media node (Video/Audio) across all sequences. */
+    private _forEachMedia;
+    stop(): void;
+    setLoop(value: boolean): void;
+    /**
+     * Set the playback speed multiplier. `1` is realtime; `2` is double speed;
+     * negative values play in reverse. Clamped to `[-10, 10]`; `0` throws (it
+     * would freeze the clock). Changing the rate mid-playback resyncs the clock
+     * so the new speed takes effect from the current frame onward.
+     */
+    setPlaybackRate(rate: number): void;
+    setFrame(target: number): void;
+    /**
+     * Re-apply the **current** frame to every sequence without advancing the
+     * playhead — the engine's "re-render" hook. Call this after mutating external
+     * state that updaters read (e.g. live-edited props) so the change shows
+     * immediately while paused. Updaters re-run, `Flex`/`Block` re-layout, and
+     * active sequences `batchDraw` — exactly like a normal tick at the same frame.
+     */
+    refresh(): void;
+    /**
+     * Replace the live props and re-render the current frame. Any holder — a bare
+     * `<smoove-player>` or the studio form — drives the scene by calling this; the
+     * `createSignal` `Object.is` guard skips a redundant refresh when nothing
+     * changed. Pass an updater to derive the next value from the previous one.
+     */
+    setProps(next: P | ((prev: P) => P)): void;
+    /**
+     * Register an outstanding asset load (e.g. a {@link Font}). While any asset is
+     * pending, {@link buffer} is `"buffering"`; once all settle it flips to
+     * `"ready"` and {@link whenReady} waiters resolve. A `play()` issued while
+     * buffering is deferred and starts automatically here. Errors are swallowed
+     * (the asset logs its own) so one bad asset can't wedge playback.
+     *
+     * This is the preview-side buffer; offline rendering uses the per-frame
+     * {@link delayRender}/{@link renderFrame} gate instead.
+     */
+    registerAsset(load: Promise<unknown>, _label?: string): void;
+    /** Resolves once no assets are pending — immediately if idle/ready. */
+    whenReady(): Promise<void>;
+    /**
+     * Register an outstanding async task that must finish before the current
+     * frame is considered fully rendered — Remotion's `delayRender`. Returns a
+     * handle to clear with {@link continueRender}.
+     */
+    delayRender(_label?: string): number;
+    /** Clear a {@link delayRender} handle; resolves `renderFrame()` once all clear. */
+    continueRender(handle: number): void;
+    /**
+     * Apply a frame and wait until all {@link delayRender} handles registered
+     * during that application clear. This is the offline / server render
+     * entrypoint — e.g. `for (f) { await comp.renderFrame(f); capture(); }`.
+     */
+    renderFrame(target: number): Promise<void>;
+    /**
+     * Composite every visible sequence layer into a single canvas and return it.
+     * Works headlessly (no DOM container needed); under the server skia backend
+     * the result is a skia `Canvas`, on which a renderer can call
+     * `.toBufferSync("raw")` for RGBA pixels.
+     *
+     * Unlike `Stage.toCanvas()`, this **reuses one scratch canvas** across calls.
+     * Allocating a fresh skia `Canvas` per frame leaks native memory (invisible to
+     * V8's GC), which balloons RSS and collapses throughput over a long render.
+     */
+    captureCanvas(): HTMLCanvasElement;
+    /** @internal — {@link RenderingAudioDriver} records one sample per audio per frame. */
+    _collectAudioAsset(asset: AudioAsset): void;
+    /**
+     * Audio samples collected during offline rendering — one per {@link Audio}
+     * per rendered frame. Feed these to an external mux pass (e.g. ffmpeg) to
+     * assemble the audio track. Empty during preview.
+     */
+    getAudioAssets(): AudioAsset[];
+    /** Reset the collected audio samples — call before re-rendering a range. */
+    clearAudioAssets(): void;
+    private _event;
+    private _applyFrame;
+    /** Hide every sequence (transparent stage) — used while buffering assets. */
+    private _hideAllSequences;
+    private _scheduleTick;
+    private _cancelTick;
+    private _tick;
+}
+//# sourceMappingURL=composition.d.ts.map

package/dist/engine/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/engine/composition.ts"],"names":[],"mappings":"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"}