@cutcraft/player 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,298 @@
+import { $ as postEffects, A as ImageFrameSource, At as FRAME_EPS, B as buildGainEnvelope, Bt as QUEUE_MAX, C as ClipDecoder, Ct as devWarn, D as ErrorFrame, Dt as DUCK_ATTACK_S, E as AssetSources, Et as AUDIO_PRIME_S, F as ManualClock, Ft as MAX_RATE, G as MaskSpec, Gt as SEEK_MODE_SPEED, H as BackgroundGradient, Ht as REVERSE_WINDOW_FRAMES, I as PerformanceClock, It as MIN_RATE, J as buildFramePlan, K as ResolveNested, Kt as SETTLE_MS, L as AudioOccurrence, Lt as MOUNT_AHEAD_S, M as defaultCreateCanvas, Mt as INPUT_IDLE_CLOSE_S, N as fromMap, Nt as LOOKAHEAD_S, O as ErrorFrameSource, Ot as DUCK_RELEASE_S, P as toResolver, Pt as MAX_OPEN_INPUTS, Q as filterString, R as GainPoint, Rt as PICK_EPS, S as DecoderPool, St as captureWarnings, T as AssetSourceDeps, Tt as AUDIO_CHUNK_S, U as DrawOp, Ut as REVERSE_WINDOW_S, V as duckIntervals, Vt as QUEUE_TARGET, W as FramePlan, Wt as SCHEDULER_MS, X as FilterResult, Y as compositionBackground, Z as PostEffect, _ as FrameSourceHooks, _t as MediaHandle, a as TickOptions, at as AudioOutput, b as mediabunnyFrameSourceFactory, bt as PlayerEvents, c as backgroundCss, ct as AudioSourceInfo, d as paintBackground, dt as Ctx2D, et as EASING_FN, f as setMatrix, ft as EnvelopePoint, g as mediabunnyAudioSourceFactory, gt as FrameSourceInfo, h as MediabunnyAudioSource, ht as FrameSourceFactory, i as FrameIntercept, it as AnyCanvas, j as copyFrame, jt as FRAME_WAIT_MS, k as ImageFrame, kt as ENVELOPE_STEP_S, l as backgroundFill, lt as Clock, m as traceMask, mt as FrameSource, n as Compositor, nt as hasKeyframes, o as CanvasPainter, ot as AudioSource, p as roundedRect, pt as Frame, q as blendOf, qt as UNMOUNT_BEHIND_S, r as CompositorDeps, rt as keyframedValue, s as PaintInputs, st as AudioSourceFactory, t as makeNestedResolver, tt as ease, u as coversCanvas, ut as CreateCanvas, v as MediabunnyFrameSource, vt as MediaResolver, w as DecodeMode, wt as AUDIO_CACHE_S, x as MediabunnyInputs, xt as ScheduledSource, y as SampleFrame, yt as PlayerErrorEvent, z as buildAudioPlan, zt as PLAY_PRIME_TIMEOUT_MS } from "./nested-Bd4Y7qrF.mjs";
+import { A as visiblePlacements, C as scaleM, D as VisibleItem, E as TransitionRole, F as nestedSourceTime, I as placementSourceTime, L as timecode, M as frameTime, N as layerClock, O as isVisibleAt, P as localT, S as rotate, T as translate, _ as cssTransform, a as Motion, b as matrixToCss, c as effect, d as DrawRect, f as IDENTITY, g as boundsOf, h as animatedTransform, i as GraphicAnimation, j as frameIndex, k as trackItems, l as motionAt, m as Matrix2D, n as backdropTracks, o as STILL, p as Layout, r as ClipRect, s as combine, t as OVERLAY_KINDS, u as Box, v as fitRect, w as transformMatrix, x as multiply, y as layoutRect } from "./backdrop-BqrzCzTB.mjs";
+import { t as indexLayerInteriors } from "./layer-interiors-r4SeMbp2.mjs";
+import { LayerClock, ResolvedState } from "@cutcraft/kit";
+import { CSSProperties, ReactNode } from "react";
+/**
+ * `AudioContext.currentTime` while the context runs, the performance clock
+ * otherwise, with an offset captured at every state change so `now()` never
+ * jumps. Audio scheduling converts back with `toContextTime`.
+ */
+export declare class AudioContextClock implements Clock {
+  private readonly ctx;
+  private offset;
+  private wasRunning;
+  private lastNow;
+  constructor(ctx: BaseAudioContext);
+  get running(): boolean;
+  now(): number;
+  /** Audio context seconds for a clock time; exact while the context runs. */
+  toContextTime(clockTime: number): number;
+}
+/**
+ * Composition time as an anchor on the clock: `anchorTime + (now − anchorClock) × rate`.
+ * Every play, pause, seek and rate change re-anchors, so time is always derived from
+ * the clock and never accumulates drift.
+ */
+export declare class Transport {
+  private readonly clock;
+  duration: number;
+  private anchorTime;
+  private anchorClock;
+  private _rate;
+  private _playing;
+  loop: boolean;
+  constructor(clock: Clock, duration: number);
+  get playing(): boolean;
+  get rate(): number;
+  time(): number;
+  timeAt(clockTime: number): number;
+  /** Clock time at which composition time `t` plays; the inverse of `timeAt` while playing. */
+  clockTimeFor(t: number): number;
+  play(): void;
+  pause(): void;
+  seek(t: number): void;
+  setRate(rate: number): void;
+  /** Advance bookkeeping at the end: loops wrap, otherwise playback stops on the last time. */
+  check(): "ended" | "looped" | null;
+  private clamp;
+}
+export interface AudioEngineDeps {
+  readonly output: AudioOutput;
+  readonly transport: Transport;
+  /** Clock seconds (the transport's clock) → audio context seconds. */
+  readonly toContextTime: (clockTime: number) => number;
+  readonly audioSource: (assetId: string) => Promise<AudioSource>;
+  readonly state: () => ResolvedState;
+  readonly resolveNested?: ResolveNested | undefined;
+  readonly setInterval: (fn: () => void, ms: number) => unknown;
+  readonly clearInterval: (id: unknown) => void;
+  readonly onError?: ((e: PlayerErrorEvent) => void) | undefined;
+}
+/**
+ * Schedules audio chunks on the output ahead of the transport. Every play
+ * starts a session; a scheduler tick plans the window since the last tick
+ * up to the lookahead and schedules each new chunk once, with offset,
+ * duration and playback rate derived from the transport. Pause cancels
+ * everything; seek and rate changes restart the session.
+ */
+export declare class AudioEngine {
+  private readonly deps;
+  private session;
+  private timer;
+  private scheduled;
+  private scheduledUpTo;
+  private running;
+  private cache;
+  private cacheSeconds;
+  private _muted;
+  private _volume;
+  constructor(deps: AudioEngineDeps);
+  get muted(): boolean;
+  get volume(): number;
+  get active(): boolean;
+  setMaster(volume: number, muted: boolean): void;
+  /** Decode what plays in the first moments after `t`, bounded by a timeout, so play starts on time. */
+  prime(t: number): Promise<void>;
+  start(): void;
+  stop(): void;
+  /** After a seek, a rate change or a loop: reschedule from the new position. */
+  reseek(): void;
+  tick(): void;
+  dispose(): void;
+  private schedule;
+  private buffer;
+}
+/** Web Audio graph: per scheduled chunk `source → gain(envelope) → [pan] → master → destination`. */
+export declare class WebAudioOutput implements AudioOutput {
+  private readonly ctx;
+  private readonly master;
+  private readonly live;
+  constructor(ctx: AudioContext);
+  get contextTime(): number;
+  get running(): boolean;
+  schedule(src: ScheduledSource): void;
+  cancel(keyPrefix: string): void;
+  cancelAll(): void;
+  setMaster(gain: number): void;
+  resume(): Promise<void>;
+  private drop;
+  private stop;
+  private disconnect;
+}
+export interface CaptureSheetOptions {
+  /** Cells per row; default 4, never more than the number of times. */
+  readonly columns?: number;
+  /** Cell width in pixels; default the composition width capped at 320. Height follows the aspect ratio. */
+  readonly cellWidth?: number;
+  /** Draw a `mm:ss:ff` label in each cell; default true. */
+  readonly labels?: boolean;
+}
+export interface PlayerOptions {
+  readonly state: ResolvedState;
+  readonly media: MediaResolver | Readonly<Record<string, Blob | string>>;
+  readonly audioContext?: AudioContext | undefined;
+  readonly loop?: boolean | undefined;
+  readonly initiallyMuted?: boolean | undefined;
+  readonly playbackRate?: number | undefined;
+  readonly resolveNested?: ResolveNested | undefined;
+  /** Test seams; the browser defaults are the audio-context clock, Web Audio and mediabunny. */
+  readonly clock?: Clock | undefined;
+  readonly audioOutput?: AudioOutput | undefined;
+  readonly toContextTime?: ((clockTime: number) => number) | undefined;
+  readonly frameSourceFactory?: FrameSourceFactory | undefined;
+  readonly audioSourceFactory?: AudioSourceFactory | undefined;
+  readonly createCanvas?: CreateCanvas | undefined;
+  readonly raf?: ((cb: () => void) => number) | undefined;
+  readonly cancelRaf?: ((id: number) => void) | undefined;
+  readonly setInterval?: ((fn: () => void, ms: number) => unknown) | undefined;
+  readonly clearInterval?: ((id: unknown) => void) | undefined;
+  readonly setTimeout?: ((fn: () => void, ms: number) => unknown) | undefined;
+  readonly clearTimeout?: ((id: unknown) => void) | undefined;
+}
+export interface TimeSnapshot {
+  readonly time: number;
+  readonly frame: number;
+}
+type Listener<K extends keyof PlayerEvents> = (e: PlayerEvents[K]) => void;
+/**
+ * The framework-free player: owns the transport, the compositor (canvas),
+ * the audio engine and the media sources. React's `<Player>` is a thin
+ * wrapper over it; a headless exporter can drive `renderFrame` directly.
+ */
+export declare class PlayerCore {
+  private _state;
+  private readonly media;
+  private readonly clock;
+  private readonly transport;
+  readonly compositor: Compositor;
+  private readonly engine;
+  private readonly sources;
+  private readonly inputs;
+  private readonly audioContext;
+  private readonly audioSources;
+  private readonly listeners;
+  private readonly timeListeners;
+  private readonly createCanvas;
+  private readonly raf;
+  private readonly cancelRaf;
+  private rafId;
+  private readonly setTimeoutFn;
+  private readonly clearTimeoutFn;
+  private settleTimer;
+  private seekGeneration;
+  private snapshot;
+  private _muted;
+  private _volume;
+  private disposed;
+  constructor(options: PlayerOptions);
+  get state(): ResolvedState;
+  get duration(): number;
+  get playbackRate(): number;
+  set playbackRate(rate: number);
+  get loop(): boolean;
+  set loop(v: boolean);
+  get muted(): boolean;
+  set muted(v: boolean);
+  get volume(): number;
+  set volume(v: number);
+  /** The media handle for an asset id, for DOM elements that show images. */
+  resolveMedia(assetId: string): Promise<MediaHandle>;
+  getCurrentTime(): number;
+  getCurrentFrame(): number;
+  isPlaying(): boolean;
+  getTime(): TimeSnapshot;
+  play(): Promise<void>;
+  pause(): void;
+  toggle(): Promise<void>;
+  /** Jump to `time` and draw its exact frame before resolving, playing or not. */
+  seekTo(time: number): Promise<void>;
+  seekToFrame(frame: number): Promise<void>;
+  /** Draw `time` without moving the transport; decoders return to the play head afterwards. */
+  renderFrame(time: number): Promise<void>;
+  /**
+   * A contact sheet of the canvas plane at `times`: each cell is `renderFrame`
+   * of that time with a timecode label, laid out `columns` wide. The way an
+   * agent or a test looks at the result without exporting. DOM overlays
+   * (titles, shapes, Layer interiors) are not on the canvas and do not appear.
+   */
+  captureSheet(times: readonly number[], options?: CaptureSheetOptions): Promise<AnyCanvas>;
+  /**
+   * The editor pushes a new resolve on every drag step. Decoders of the same
+   * asset keep their frames and take the new trim; a paused preview paints at
+   * once with what is decoded and fetches the exact frame after the gesture
+   * has been quiet for `SETTLE_MS`.
+   */
+  setState(state: ResolvedState): void;
+  attachCanvas(canvas: HTMLCanvasElement | OffscreenCanvas | null): void;
+  addEventListener<K extends keyof PlayerEvents>(type: K, fn: Listener<K>): () => void;
+  removeEventListener<K extends keyof PlayerEvents>(type: K, fn: Listener<K>): void;
+  /** For `useSyncExternalStore`: notified once per painted frame and on every seek. */
+  subscribeTime(fn: () => void): () => void;
+  dispose(): void;
+  private startLoop;
+  private stopLoop;
+  private publish;
+  private emit;
+  private audioSource;
+}
+export declare const PlayerContext: import("react").Context<PlayerCore | null>;
+/** The layer's clock inside a `<Layer>`; null outside one. */
+export declare const LayerContext: import("react").Context<LayerClock | null>;
+export declare function usePlayer(): PlayerCore;
+export declare function useCompositionTime(): number;
+export declare function useCompositionFrame(): number;
+/** What the kit's `useLayer()` and `useT()` delegate to while a Player is mounted. */
+export declare function useLayerClock(): LayerClock;
+/** 0..1 progress through the enclosing Layer. */
+export declare function useLayerT(): number;
+/** Installs the kit's layer hooks for the first mounted Player and removes them after the last unmounts. */
+export declare function retainUseT(): () => void;
+export interface DomLayerProps {
+  readonly state: ResolvedState;
+  readonly interiors: ReadonlyMap<string, ReactNode>;
+  /** Which overlays: those beneath the footage (`backdropTracks`), or the rest and the captions (default). */
+  readonly layer?: "backdrop" | "front";
+}
+/** Overlay elements as DOM, one absolutely positioned group per track in compositing order, above the canvas (or, for the backdrop, below it). */
+export declare function DomLayer({ state, interiors, layer }: DomLayerProps): import("react").JSX.Element;
+export interface ElementCellProps {
+  item: VisibleItem;
+  state: ResolvedState;
+  time: number;
+  interior: ReactNode;
+}
+/**
+ * Whether two renders of an overlay would produce the same DOM. Placements
+ * are new objects on every resolve, so compare what matters: timing, the
+ * parsed props (referentially stable while untouched), children, the
+ * element-relative frame, the transition progress, the text and the
+ * composition box.
+ */
+export declare function sameElement(a: ElementCellProps, b: ElementCellProps): boolean;
+/** Play/pause, scrubber, time readout, mute and rate. */
+export declare function Controls(): import("react").JSX.Element;
+export interface PlayerProps {
+  readonly state: ResolvedState;
+  readonly media: MediaResolver | Readonly<Record<string, Blob | string>>;
+  /** The evaluated file element (`mod.default(props)`); needed only to render `<Layer>` interiors. */
+  readonly element?: ReactNode;
+  readonly controls?: boolean;
+  readonly loop?: boolean;
+  readonly autoPlay?: boolean;
+  readonly initiallyMuted?: boolean;
+  readonly playbackRate?: number;
+  /** `contain` scales the composition into the box; `none` renders at composition pixels. */
+  readonly fit?: "contain" | "none";
+  readonly style?: CSSProperties;
+  readonly className?: string;
+  readonly audioContext?: AudioContext;
+  readonly onError?: (e: PlayerEvents["error"]) => void;
+  readonly onFrame?: (e: PlayerEvents["frameupdate"]) => void;
+  /** Test seams forwarded to PlayerCore. */
+  readonly coreOptions?: Partial<PlayerOptions>;
+}
+export type PlayerRef = Pick<PlayerCore, "play" | "pause" | "toggle" | "seekTo" | "seekToFrame" | "getCurrentTime" | "getCurrentFrame" | "isPlaying" | "addEventListener" | "removeEventListener" | "renderFrame" | "captureSheet" | "duration" | "state"> & {
+  playbackRate: number;
+  loop: boolean;
+  muted: boolean;
+  volume: number;
+  readonly core: PlayerCore;
+  readonly canvas: HTMLCanvasElement | null;
+};
+/**
+ * Canvas for media, DOM for overlays, controls below. The root carries
+ * `data-time` and `data-frame`; every element carries `data-el`/`data-kind`.
+ */
+export declare const Player: import("react").ForwardRefExoticComponent<PlayerProps & import("react").RefAttributes<PlayerRef>>;
+export { AUDIO_CACHE_S, AUDIO_CHUNK_S, AUDIO_PRIME_S, AnyCanvas, AssetSourceDeps, AssetSources, AudioOccurrence, AudioOutput, AudioSource, AudioSourceFactory, AudioSourceInfo, BackgroundGradient, Box, CanvasPainter, ClipDecoder, ClipRect, Clock, Compositor, CompositorDeps, CreateCanvas, Ctx2D, DUCK_ATTACK_S, DUCK_RELEASE_S, DecodeMode, DecoderPool, DrawOp, DrawRect, EASING_FN, ENVELOPE_STEP_S, EnvelopePoint, ErrorFrame, ErrorFrameSource, FRAME_EPS, FRAME_WAIT_MS, FilterResult, Frame, FrameIntercept, FramePlan, FrameSource, FrameSourceFactory, FrameSourceHooks, FrameSourceInfo, GainPoint, GraphicAnimation, IDENTITY, INPUT_IDLE_CLOSE_S, ImageFrame, ImageFrameSource, LOOKAHEAD_S, Layout, MAX_OPEN_INPUTS, MAX_RATE, MIN_RATE, MOUNT_AHEAD_S, ManualClock, MaskSpec, Matrix2D, MediaHandle, MediaResolver, MediabunnyAudioSource, MediabunnyFrameSource, MediabunnyInputs, Motion, OVERLAY_KINDS, PICK_EPS, PLAY_PRIME_TIMEOUT_MS, PaintInputs, PerformanceClock, PlayerErrorEvent, PlayerEvents, PostEffect, QUEUE_MAX, QUEUE_TARGET, REVERSE_WINDOW_FRAMES, REVERSE_WINDOW_S, ResolveNested, SCHEDULER_MS, SEEK_MODE_SPEED, SETTLE_MS, STILL, SampleFrame, ScheduledSource, TickOptions, TransitionRole, UNMOUNT_BEHIND_S, VisibleItem, animatedTransform, backdropTracks, backgroundCss, backgroundFill, blendOf, boundsOf, buildAudioPlan, buildFramePlan, buildGainEnvelope, captureWarnings, combine, compositionBackground, copyFrame, coversCanvas, cssTransform, defaultCreateCanvas, devWarn, duckIntervals, ease, effect, filterString, fitRect, frameIndex, frameTime, fromMap, hasKeyframes, indexLayerInteriors, isVisibleAt, keyframedValue, layerClock, layoutRect, localT, makeNestedResolver, matrixToCss, mediabunnyAudioSourceFactory, mediabunnyFrameSourceFactory, motionAt, multiply, nestedSourceTime, paintBackground, placementSourceTime, postEffects, rotate, roundedRect, scaleM, setMatrix, timecode, toResolver, traceMask, trackItems, transformMatrix, translate, visiblePlacements };