@miraiclip/renderer

npm install @miraiclip/renderer

FunctionsCopy Anchor Link

accumulatePeaksCopy Anchor Link

Fold one decoded chunk into peaks (pure; exported for tests and custom decoders).

function accumulatePeaks(peaks: Float32Array, bucketUs: Us, chunk: AudioChunk): void

analyzeHtmlAnimationsCopy Anchor Link

The animation timeline of (already parameter-substituted) markup laid out at widthPx×heightPx, or undefined when it can't be analysed (no DOM, time read through --t, SMIL…) — callers then treat every frame as new. Cached per markup; analysis costs a few ms once per template.

function analyzeHtmlAnimations(markup: string, widthPx: number, heightPx: number): HtmlAnimationTimeline | undefined

assertDecodableCopy Anchor Link

Per-asset capability check — reject one asset, not the whole renderer.

function assertDecodable(assetId: string, config: VideoDecoderConfig): Promise<void>

assignVideoLanesCopy Anchor Link

Decoder lanes per asset — interval colouring over each clip's render span (its bounds plus any transition extension), padded by gapUs. Clips that never come within gapUs of each other share lane 0 (the asset's shared pipeline, where sequential cuts keep decoder continuity); overlapping or adjacent ones get the lowest free lane. The number of decoders an asset ever needs is therefore its peak overlap — a montage of 12 back-to-back transitioned cuts needs 2–3 lanes, not 12 (which is what one dedicated pipeline per transition clip cost, and what exhausted mobile memory).

function assignVideoLanes(doc: ProjectDocument, gapUs: Us): Map<string, number>

buildAnimationTimelineCopy Anchor Link

Build the timeline from animation descriptors (pure — see analyzeHtmlAnimations for the DOM side).

function buildAnimationTimeline(descriptors: readonly AnimationDescriptor[]): HtmlAnimationTimeline | undefined

clipFadesCopy Anchor Link

The clip's fade envelope (0..1) at a timeline position: a linear ramp up over fadeInUs from the clip start and down over fadeOutUs to its end. Fades longer than the clip are scaled down proportionally so they meet.

function clipFades(clip: VideoClip | AudioClip): {
    inUs: Us;
    outUs: Us;
}

collectHtmlRastersCopy Anchor Link

Rasterize every html clip of doc on THIS thread (requires a DOM) into transferable bitmaps for a worker export. Keys match what the worker-side compositor computes, so rasterizeHtml there resolves without a DOM. Deduplicated: clips sharing (template, params, size) share one raster. Animated clips are skipped — they change every frame, so the worker asks for each frame's raster on demand instead (setHtmlRasterSource).

function collectHtmlRasters(doc: Pick<ProjectDocument, "clips" | "assets" | "settings">, options?: {
    outputSize?: {
        width?: number;
        height?: number;
    };
}): Promise<{
    rasters: Record<string, ImageBitmap>;
    transfer: Transferable[];
}>

Guides: HTML clips

compositionEndCopy Anchor Link

End of the last clip — the default export range's end.

function compositionEnd(doc: ProjectDocument): Us

Guides: Timeline

computePlacementCopy Anchor Link

Convert a clip's normalized transform to pixel-space placement.

function computePlacement(clip: Clip, settings: ProjectSettings): Placement

computeWaveformPeaksCopy Anchor Link

Compute peaks for a whole asset. Resolves with all-zero peaks for silent media.

function computeWaveformPeaks(source: AudioTrackSource, options: WaveformPeaksOptions): Promise<WaveformPeaks>

Guides: Timeline, Waveform

createMediabunnyDemuxerFactoryCopy Anchor Link

A demuxer factory with options (see MediabunnyDemuxerOptions).

function createMediabunnyDemuxerFactory(options?: MediabunnyDemuxerOptions): (assetId: string, src: unknown) => Promise<VideoTrackDemuxer>

createMediabunnySinkCopy Anchor Link

Probe-then-build: rejects up front with a clear error when this browser cannot encode the chosen format (e.g. H.264 encode missing), instead of failing frames deep into an export.

function createMediabunnySink(options: CreateMediabunnySinkOptions): Promise<ExportSink>

createMonitoredWebAudioOutputCopy Anchor Link

A WebAudio output whose channels all pass through one master GainNode, so the monitoring volume is a single gain change. The audio engine connects each channel to context.destination; shadowing that property on this context instance routes them into the master instead.

function createMonitoredWebAudioOutput(gain: number): MonitoredAudioOutput

createPixiBackendCopy Anchor Link

Create the PixiJS scene backend bound to a canvas.

function createPixiBackend(options: PixiBackendOptions): Promise<SceneBackend>

Guides: Preview & playback

createPlayerCopy Anchor Link

The playback controller: wires media pipeline, compositor, audio engine and the master clock into one transport. The clock is derived from the audio output's own time, so scheduled audio and the frames chasing the clock cannot drift apart. The playhead is pushed into the core each frame via setPlayhead (ephemeral — never in undo history).

function createPlayer(project: Project, options: CreatePlayerOptions): Player

Guides: Preview & playback, Custom clip kinds, Custom effects, Production readiness

createPreviewControllerCopy Anchor Link

The preview half of an editor, without any UI framework: owns the canvas's renderer and player, a fallback clock, and the monitoring volume. Framework adapters subscribe to it (getState / subscribe) and forward DOM events.

Safe under React StrictMode: an attach → detach → attach on the same canvas builds one renderer, never two on one WebGL context.

function createPreviewController(project: Project, options?: PreviewControllerOptions): PreviewController

Guides: Preview & playback, Quickstart, Roadmap

createVideoSupportCopy Anchor Link

Bridges the MediaManager into the Compositor: creates video scene nodes that pull cached frames on every tick and keep decode-ahead primed. Pipelines stay owned by the MediaManager (shared per asset).

function createVideoSupport(project: Project, manager: MediaManager, options?: VideoSupportOptions): VideoSupport

createWebAudioOutputCopy Anchor Link

Create the WebAudio output (and its master clock source).

function createWebAudioOutput(context?: AudioContext): AudioOutput

createWebCodecsDecoderFactoryCopy Anchor Link

A decoder factory with options — e.g. { maxOutputDimensionPx: 1920 } for proxy preview of 4K sources.

function createWebCodecsDecoderFactory(options?: WebCodecsDecoderOptions): FrameDecoderFactory

exportCompositionCopy Anchor Link

function exportComposition(options: ExportCompositionOptions): Promise<Uint8Array>

exportFrameWindowCopy Anchor Link

Output frame n of an export of [rangeStartUs, rangeEndUs): its timeline span and the position it is rendered at. Frames follow the core frame rule (frameToUs from

function exportFrameWindow(n: number, rangeStartUs: Us, rangeEndUs: Us, fps: number | FrameRate): {
    startUs: Us;
    endUs: Us;
    sampleUs: Us;
}

Guides: Roadmap

exportProjectCopy Anchor Link

Offline export: renders the composition frame-by-frame into an OffscreenCanvas via the same compositor preview uses, and encodes as fast as decode+encode allow. Decode is capped at 2× the output's longest side (visually lossless for compositing; pass createDecoder: createWebCodecsDecoder for uncapped). Time moves strictly forward, so the streaming decoders never re-seek.

function exportProject(project: Project, options: ExportProjectOptions): Promise<Uint8Array>

Guides: HTML clips, Text & typography, Browser, Server (Node)

exportProjectInWorkerCopy Anchor Link

Run exportProject in a dedicated worker so the main thread stays free. Same total CPU — the work is identical — but the page keeps rendering and responding while the export runs, and the export stops competing with the UI for its thread.

function exportProjectInWorker(project: Project, options: ExportProjectInWorkerOptions): Promise<Uint8Array>

Guides: Export UI, HTML clips, Browser, Web worker

exportViaWorkerCopy Anchor Link

Drive an export inside worker (a Worker running the export worker entry).

function exportViaWorker(worker: Worker, project: Project, options: ExportViaWorkerOptions): Promise<Uint8Array>

Guides: Export UI, HTML clips, Browser, Web worker

fadeGainAtCopy Anchor Link

function fadeGainAt(clip: VideoClip | AudioClip, timelineUs: Us): number

getEffectRendererCopy Anchor Link

function getEffectRenderer(kind: string): EffectRendererFactory | undefined

Guides: Custom effects

getTransitionRendererCopy Anchor Link

function getTransitionRenderer(kind: string): TransitionRenderer | undefined

Guides: Custom transitions

hasHardwareVideoEncoderCopy Anchor Link

Whether this browser has a HARDWARE encoder for the format's video codec at the given output size. Used to pick the capture route: with a hardware encoder, zero-copy canvas capture drains fast and stays flat; with a SOFTWARE encoder (VP9/WebM on macOS, for example) the GPU-backed captured frames outlive the slow encode and Chrome's shared-image retention balloons — the same failure class as the SwiftShader capture leak, reported from the field as a machine-exhausting WebM High export on a real GPU. Probe errs toward false (CPU capture), the safe side.

function hasHardwareVideoEncoder(format: ExportFormat, width: number, height: number): Promise<boolean>

Guides: Browser

htmlAnimationTimingCopy Anchor Link

Animated clips: the animation time (seconds) at timeline position timeUs, and its length.

function htmlAnimationTiming(clip: HtmlClip, timeUs: number): {
    timeS: number;
    durationS: number;
}

htmlRasterKeyCopy Anchor Link

The raster inputs that require a re-raster when they change. Animated clips pass the frame's timeS (and the animation length): one key per frame, matching rasterizeHtml's lookup of provided rasters.

function htmlRasterKey(clip: HtmlClip, widthPx: number, heightPx: number, density?: number, timing?: {
    timeS: number;
    durationS: number;
}): string

isPcmAudioChunkCopy Anchor Link

function isPcmAudioChunk(value: unknown): value is PcmAudioChunk

isRecoverableDecoderErrorCopy Anchor Link

Errors that mean "this decoder instance is gone", not "this media can't be decoded": reclamation (QuotaExceededError, WebCodecs spec) and calls on a closed/unconfigured codec (InvalidStateError — Safari words it "VideoDecoder is not configured", Chromium "Cannot call 'decode' on a closed codec").

function isRecoverableDecoderError(error: Error): boolean

isSoftwareWebGLCopy Anchor Link

True when the canvas's WebGL context reports a software rasterizer.

function isSoftwareWebGL(canvas: HTMLCanvasElement | OffscreenCanvas): boolean

isWebCodecsSupportedCopy Anchor Link

True when this environment can run the WebCodecs decode pipeline.

function isWebCodecsSupported(): boolean

Guides: Browser, Compatibility

loadFontAssetsCopy Anchor Link

Load every font asset in the document that hasn't been loaded yet. Resolves when all newly seen fonts have finished loading (or failed — a bad font URL logs loudly and falls back, it never wedges playback or an export). Returns true when at least one NEW font finished loading — the caller should re-render text (glyph metrics changed).

function loadFontAssets(doc: ProjectDocument, env?: FontEnv): Promise<boolean>

Guides: Text & typography

mixCompositionAudioCopy Anchor Link

Render the composition's audio mix for a range into a single AudioBuffer, faster than realtime. Returns null when nothing contributes audio (the export then has no audio track). Browser-only (OfflineAudioContext); covered by the export e2e — the planning and mapping halves are unit-tested.

function mixCompositionAudio(options: MixCompositionAudioOptions): Promise<AudioBuffer | null>

openMediabunnyAudioCopy Anchor Link

Open an asset's primary audio track; resolves null when it has none.

function openMediabunnyAudio(assetId: string, src: unknown): Promise<AudioTrackSource | null>

Guides: Timeline, Waveform

openMediabunnyDemuxerCopy Anchor Link

Open the primary video track of a URL or Blob/File source (16 MiB read cache).

function openMediabunnyDemuxer(assetId: string, src: unknown): Promise<VideoTrackDemuxer>

Guides: Asset import

peaksForRangeCopy Anchor Link

Downsample peaks to width columns (max per column) for drawing a clip's visible range.

function peaksForRange(waveform: WaveformPeaks, fromMediaUs: Us, toMediaUs: Us, width: number): Float32Array

Guides: Timeline

planAudioJobsCopy Anchor Link

The pure planning half: which clips contribute audio to the range, at what gain, and where in their source to start reading. Headless-testable.

function planAudioJobs(doc: ProjectDocument, range: ExportRange): AudioMixJob[]

probeCompositionAudioCopy Anchor Link

Whether the composition contributes ANY audio over range — decided by probing each distinct contributing asset until one actually opens an audio track (planning alone counts every video clip as audible even when its asset carries no audio stream). Shared by exportProject and the worker export driver, which must decide this on the MAIN thread.

function probeCompositionAudio(doc: ProjectDocument, range: ExportRange, openAudio: AudioSourceFactory): Promise<boolean>

provideHtmlRastersCopy Anchor Link

Install pre-rendered rasters (replaces — and closes — any previous set).

function provideHtmlRasters(rasters: Record<string, ImageBitmap>): void

rasterizeHtmlCopy Anchor Link

Rasterize markup to a WebGL-safe texture source. With a DOM, that is a laundered canvas (see header). Without one (workers), a pre-rendered bitmap installed via provideHtmlRasters is served instead — exportViaWorker pre-rasterizes on the main thread and transfers the bitmaps — and a miss throws a clear error.

function rasterizeHtml(options: RasterizeHtmlOptions): Promise<HTMLCanvasElement | ImageBitmap>

Guides: HTML clips

registerEffectRendererCopy Anchor Link

Register how a custom effect kind draws: a factory building a Pixi filter from validated params, updated in place on effect/update. Pair it with core's registerEffectKind(kind, paramsSchema) so commands validate. A kind without a renderer applies no visual (the stack skips it).

Custom renderers are functions, so they cannot cross a process or thread boundary: server export and worker export support built-in kinds only — the same rule as custom clip-kind factories.

function registerEffectRenderer(kind: string, factory: EffectRendererFactory): void

Guides: Custom effects, Roadmap

registerTransitionRendererCopy Anchor Link

Register how a custom transition kind draws. Pair it with core's registerTransitionKind(kind, paramsSchema) so commands validate. A kind without a renderer draws as a hard cut at the boundary.

function registerTransitionRenderer(kind: string, renderer: TransitionRenderer): void

Guides: Custom transitions, Roadmap

renderEffectThumbnailsCopy Anchor Link

Render effect thumbnails as data URLs, keyed by kind. Kinds that fail to render are skipped.

function renderEffectThumbnails(options?: EffectThumbnailOptions): Promise<Map<string, string>>

Guides: Effects, Custom effects

renderProjectStillCopy Anchor Link

Render ONE composition frame to an image, through the exact pipeline exports use (same compositor, same decode path, same fonts) — so a still is what that frame will look like in the exported file, by construction. Thumbnails, poster frames, and agent previews all want this.

function renderProjectStill(project: Project, options: RenderProjectStillOptions): Promise<Blob>

Guides: HTML clips, Text & typography, Stills, Custom clip kinds

setHtmlRasterSourceCopy Anchor Link

Install (or clear, with undefined) the on-demand raster source for DOM-less threads.

function setHtmlRasterSource(source: HtmlRasterSource | undefined): void

Guides: HTML clips

substituteParamsCopy Anchor Link

{{name}} → params.name, HTML-escaped (params are data, never markup).

function substituteParams(template: string, params: Record<string, HtmlParamValue>): string

Guides: HTML clips

toMediaUsCopy Anchor Link

Timeline position → position on the clip's source media.

function toMediaUs(clip: VideoClip, timelineUs: Us): Us

zIndexForCopy Anchor Link

function zIndexFor(trackIndex: number, clipIndexInTrack: number): number

ClassesCopy Anchor Link

AudioEngineCopy Anchor Link

Schedules decoded audio against the output clock. The mapping is anchored once per start/seek: timeline time t plays at output time anchorOutputUs + (t - anchorTimelineUs) / rate. Because the master clock IS the output clock, video (which chases the clock) and audio (scheduled on it) cannot drift apart.

new AudioEngine(project: Project, output: AudioOutput, openAudio: AudioSourceFactory, options?: AudioEngineOptions)

CompositorCopy Anchor Link

Mirrors the project document into a scene backend and renders it as a pure function of time. Subscribes to the core's patch events, so any dispatched command — including undo/redo and remote patches — updates the scene granularly: only clips named in the patches are re-synced.

new Compositor(project: Project, backend: SceneBackend, options?: CompositorOptions)

ExportAbortedErrorCopy Anchor Link

Extends Error.

new ExportAbortedError()

Guides: Export UI, Browser, Web worker

FrameCacheCopy Anchor Link

Holds decoded frames around the playhead. Owns every frame it stores: frames are closed when evicted, replaced, or cleared.

new FrameCache(options?: FrameCacheOptions)

MediaManagerCopy Anchor Link

Central owner of decode resources. One pipeline per ASSET LANE (clips that never overlap share a lane; overlapping clips of one asset get separate lanes), a cap on simultaneously active pipelines, idle release once no clip holds a pipeline, and one frame-memory budget shared by every pipeline.

new MediaManager(options: MediaManagerOptions)

Guides: Production readiness

RealtimeClockCopy Anchor Link

Wall-clock playback clock with rate control. The time source is injectable (defaults to performance.now / Date.now) so it is fully testable; the audio graph will later supply an AudioContext-derived source for drift-free sync.

Extends Clock.

new RealtimeClock(nowMs?: () => number)

StepClockCopy Anchor Link

Deterministic clock for export and tests: time moves only when told to.

Extends Clock.

UnsupportedMediaErrorCopy Anchor Link

Raised when an asset's codec cannot be decoded in this environment.

Extends Error.

new UnsupportedMediaError(assetId: string, message: string, codec?: string)

Guides: Browser, Compatibility

VideoPipelineCopy Anchor Link

Per-asset decode pipeline with continuous streaming: one decoder is kept alive and fed forward as the playhead advances (with an ahead budget as backpressure). A fresh keyframe seek happens only on a backward jump or a large forward jump — linear playback never tears the decoder down, which is what keeps preview smooth. A prime() whose target invalidates the current decode position aborts the in-flight feed via a generation counter.

new VideoPipeline(demuxer: VideoTrackDemuxer, createDecoder: FrameDecoderFactory, options?: VideoPipelineOptions)

ConstantsCopy Anchor Link

createWebCodecsDecoderCopy Anchor Link

Full-resolution decoder factory. For preview playback of large sources, prefer createWebCodecsDecoderFactory.

const createWebCodecsDecoder: FrameDecoderFactory

Z_PER_TRACKCopy Anchor Link

Clips per track are stacked by start time (later starts on top).

const Z_PER_TRACK: 10000

InterfacesCopy Anchor Link

ActiveEffectCopy Anchor Link

Guides: Custom effects

AnimationDescriptorCopy Anchor Link

One CSS animation, reduced to what decides when its output changes.

AudioChannelCopy Anchor Link

One mixable output lane (per clip): gain + scheduled buffers.

AudioChunkCopy Anchor Link

A decoded chunk of audio on the media's own timeline.

AudioEngineOptionsCopy Anchor Link

AudioMixJobCopy Anchor Link

Offline audio mix for export: the same clip math the realtime AudioEngine uses (shared via audio/mapping.ts), rendered in one non-realtime pass with an OfflineAudioContext instead of being scheduled against a live clock.

AudioOutputCopy Anchor Link

Audio output abstraction (a WebAudio AudioContext in the browser; a fake in tests). Its clock is the master playback clock.

AudioTrackSourceCopy Anchor Link

Streaming source of decoded audio for one asset. Audio is pulled in chunks around the playhead — a long file is never decoded whole (an hour of PCM is gigabytes). The real implementation wraps mediabunny's AudioBufferSink.

Guides: Timeline

ClipBoundsCopy Anchor Link

Where a clip is drawn, in composition pixels, at one timeline position: the content rectangle after the clip's scale and rotation (keyframes evaluated). What an interaction layer needs to draw a selection box and map pointer drags back onto the clip's transform.

ClockCopy Anchor Link

The compositor renders as a pure function of (document, clock.timeUs). Playback uses a realtime clock (audio-driven once the audio graph lands); export drives the same compositor with a StepClock.

CompositorOptionsCopy Anchor Link

CompositorResidencyOptionsCopy Anchor Link

ConstantSpanCopy Anchor Link

The answer for one time.

CreateMediabunnySinkOptionsCopy Anchor Link

CreatePlayerOptionsCopy Anchor Link

EffectContextCopy Anchor Link

The Pixi half of the effect registry: kind → filter factory. Built-ins (colorAdjust, blur, chromaKey) register through the same public contract custom kinds use — registerEffectRenderer. Filters mutate in place on param updates (no shader recompiles while dragging a slider).

Guides: Custom effects

EffectThumbnailOptionsCopy Anchor Link

EncodedChunkLikeCopy Anchor Link

An encoded chunk flowing from demuxer to decoder. Opaque beyond metadata.

ExportCompositionOptionsCopy Anchor Link

ExportProgressCopy Anchor Link

Guides: Browser, Web worker

ExportProjectInWorkerOptionsCopy Anchor Link

Extends ExportViaWorkerOptions.

ExportProjectOptionsCopy Anchor Link

ExportRangeCopy Anchor Link

ExportSinkCopy Anchor Link

Where exported media goes: one video frame at a time (the sink captures the canvas it was constructed around), plus the mixed audio. The production implementation wraps mediabunny's Output; tests use a fake.

ExportViaWorkerOptionsCopy Anchor Link

Main-thread side of the worker export: serializes the document across, relays progress and abort, mixes audio chunks on THIS thread (the OfflineAudioContext mixer is window-only) and transfers them as PCM planes, and resolves with the result exactly like exportProject.

Two layers:

• exportViaWorker(worker, project, options) — bring your own Worker (bundler worker imports, custom URLs). The worker is NOT terminated.
• exportProjectInWorker(project, options) — convenience: spawns the bundled entry (new URL("./export.worker.js", import.meta.url), the pattern Vite/webpack/Rollup rewrite; pass worker or workerUrl where that pattern can't resolve) and terminates it when done.

Boundary rules: custom clip-kind factories cannot cross (functions) — built-in kinds only, same as server export. Media src values must be reachable from a worker: http(s)/blob URLs and Blob/File objects all work. Html clips DO cross: they rasterize on this thread (workers have no DOM) and the bitmaps transfer with the start message.

Extends WorkerExportWireOptions.

FrameCacheOptionsCopy Anchor Link

FrameDecoderCopy Anchor Link

Decoder abstraction (a WebCodecs VideoDecoder in the browser).

HtmlAnimationTimelineCopy Anchor Link

HtmlRasterOptionsCopy Anchor Link

Live-preview quality limits for html clips (exports leave these unset: exact, full density).

LocalBoundsCopy Anchor Link

A node's drawn content as a rectangle in its LOCAL space: relative to the node's placement point (the clip's transform x/y), before the clip's own scale and rotation, in composition pixels. Node-intrinsic sizing is already applied (a video's fit-to-composition, a text's measured glyphs, an html clip's raster box). xPx/yPx is the rectangle's top-left corner, so a node drawn centered on its placement point has xPx = -widthPx / 2.

MediabunnyDemuxerOptionsCopy Anchor Link

MediaManagerOptionsCopy Anchor Link

MediaManagerStatsCopy Anchor Link

MixCompositionAudioOptionsCopy Anchor Link

Extends MixAudioContext.

MonitoredAudioOutputCopy Anchor Link

A preview audio output whose level can be changed after creation.

NodeFactoryContextCopy Anchor Link

Guides: Custom clip kinds

PcmAudioChunkCopy Anchor Link

Raw planar PCM audio chunk — the worker-export audio interchange. AudioBuffer and OfflineAudioContext are window-only, so a worker export mixes audio on the main thread and transfers chunks as channel planes (zero-copy); the sink turns them into encoder samples. Accepted anywhere an AudioBuffer chunk is (the exporter treats chunks as opaque).

PixiBackendOptionsCopy Anchor Link

PlacementCopy Anchor Link

Pixel-space placement computed from a clip's normalized transform.

PlayerCopy Anchor Link

PlayerEventsCopy Anchor Link

Transport events. Subscribe with player.on(type, listener); adapters use these instead of polling playing.

Extends Record<string, unknown>.

PlayerMemoryOptionsCopy Anchor Link

PlayerStatsCopy Anchor Link

Live resource counts — for dev overlays, tests and memory dashboards.

PointCopy Anchor Link

PreviewControllerCopy Anchor Link

PreviewControllerOptionsCopy Anchor Link

PreviewStateCopy Anchor Link

Everything a transport UI renders. A new object whenever any field changes.

RasterizeHtmlOptionsCopy Anchor Link

RenderProjectStillOptionsCopy Anchor Link

SceneBackendCopy Anchor Link

Rendering backend abstraction. The production implementation is PixiJS; tests use a fake. Backends draw — the Compositor decides what and when.

SceneNodeCopy Anchor Link

Guides: Custom clip kinds

SolidSceneNodeCopy Anchor Link

A full-composition solid overlay — how dip-to-black/white transitions cover the hard cut. Owned by the Compositor, created lazily on first use.

TransitionFrameEffectsCopy Anchor Link

The transition renderer registry: kind → how the compositor draws it.

A transition renderer is PURE math over progress — it returns per-frame adjustments the compositor applies to the participating clips through the existing primitives (opacity, directional reveal, pixel offset, and a full-composition overlay). The built-ins are expressed through this exact contract, so a registered custom kind is a first-class citizen: it renders identically in preview, browser export, and stills.

Custom renderers are functions, so they cannot cross a process or thread boundary: server export and worker export support built-in kinds only — the same rule as custom clip-kind factories. Register the matching param schema in core with registerTransitionKind so transition/add validates.

Guides: Custom transitions

TransitionRenderContextCopy Anchor Link

TransitionRendererCopy Anchor Link

Guides: Custom transitions

VideoFrameHandleCopy Anchor Link

A decoded video frame owned by the cache. close() releases the underlying resource (a WebCodecs VideoFrame in the browser) — every handle MUST be closed exactly once, by whoever holds it last.

VideoPipelineOptionsCopy Anchor Link

VideoSceneNodeCopy Anchor Link

A scene node that displays decoded video frames.

Extends SceneNode.

VideoSupportCopy Anchor Link

VideoSupportOptionsCopy Anchor Link

VideoTrackDemuxerCopy Anchor Link

Demuxer abstraction over one media source's primary video track. The real implementation wraps mediabunny; tests inject fakes.

VideoTrackInfoCopy Anchor Link

WaveformPeaksCopy Anchor Link

Waveform peaks for timeline drawing: one max-abs amplitude (0..1) per bucket of media time, across all channels. Streams the asset through an AudioTrackSource chunk by chunk — never holds the decoded file — and is computed once per asset (cache the result; peaks don't depend on clips).

Chunks are read as Web Audio AudioBuffer-like objects (numberOfChannels, sampleRate, getChannelData).

WaveformPeaksOptionsCopy Anchor Link

WebCodecsDecoderOptionsCopy Anchor Link

WorkerExportWireOptionsCopy Anchor Link

The subset of ExportProjectOptions that crosses the boundary as data.

TypesCopy Anchor Link

AudioSourceFactoryCopy Anchor Link

Resolves to null when the asset has no audio track.

type AudioSourceFactory = (assetId: string, src: unknown) => Promise<AudioTrackSource | null>;

DemuxerFactoryCopy Anchor Link

type DemuxerFactory = (assetId: string, src: unknown) => Promise<VideoTrackDemuxer>;

EffectRendererFactoryCopy Anchor Link

Builds the live filter for one effect instance. params arrive validated against the kind's core schema (register it with registerEffectKind); length-denoting params should be composition-relative fractions, converted to pixels via context.compositionSize() — absolute pixels diverge between scaled preview and full-res export.

type EffectRendererFactory = (params: Record<string, unknown>, context: EffectContext) => ActiveEffect;

ExportFormatCopy Anchor Link

The production ExportSink: mediabunny Output + WebCodecs encoding. MP4 (H.264 + AAC) and WebM (VP9 + Opus). Browser-only; everything above it (the export orchestrator) is environment-agnostic and unit-tested in Node.

type ExportFormat = "mp4" | "webm";

ExportQualityPresetCopy Anchor Link

type ExportQualityPreset = "draft" | "standard" | "high";

FrameDecoderFactoryCopy Anchor Link

type FrameDecoderFactory = () => FrameDecoder;

HtmlRasterRequestCopy Anchor Link

A raster request as data (no assets — the main thread has the document).

type HtmlRasterRequest = Omit<RasterizeHtmlOptions, "assets">;

HtmlRasterSourceCopy Anchor Link

Where a DOM-less thread gets rasters it wasn't given up front — animated html clips need one raster PER FRAME, far too many to pre-render and transfer, so the export worker installs a source that asks the main thread for each frame's raster on demand (see export.worker.ts).

type HtmlRasterSource = (request: HtmlRasterRequest) => Promise<ImageBitmap>;

MainToWorkerMessageCopy Anchor Link

type MainToWorkerMessage = {
    type: "start";
    doc: ProjectDocument;
    options: WorkerExportWireOptions;
    hasAudio: boolean;
    streamOutput?: boolean;
    htmlRasters?: Record<string, ImageBitmap>;
} | {
    type: "abort";
} | {
    type: "audio-chunk";
    id: number;
    chunk: PcmAudioChunk | null;
    error?: string;
} | {
    type: "html-raster";
    id: number;
    bitmap: ImageBitmap | null;
    error?: string;
} | {
    type: "output-chunk-ack";
    id: number;
    error?: string;
};

MediaSrcCopy Anchor Link

type MediaSrc = string | Blob;

NodeFactoryCopy Anchor Link

Creates the scene node for one clip kind — the extension seam for custom clip kinds (and how video plugs in). Return null to render nothing.

type NodeFactory = (clip: Clip, context: NodeFactoryContext) => SceneNode | null;

PreviewModeCopy Anchor Link

• live: real decode + WebGL compositing on the attached canvas.
• fallback: no live renderer (no canvas yet, or it failed to build); a requestAnimationFrame clock still moves the playhead so timelines work.
• unsupported: this browser has no WebCodecs; same clock as fallback.

type PreviewMode = "live" | "fallback" | "unsupported";

RevealDirectionCopy Anchor Link

Which way a wipe's edge sweeps / a slide's clip moves.

type RevealDirection = "left" | "right" | "up" | "down";

UsCopy Anchor Link

Microseconds, matching

type Us = number;

WorkerToMainMessageCopy Anchor Link

type WorkerToMainMessage = {
    type: "need-audio-chunk";
    id: number;
    startUs: number;
    endUs: number;
} | {
    type: "need-html-raster";
    id: number;
    request: HtmlRasterRequest;
} | {
    type: "output-chunk";
    id: number;
    chunk: StreamTargetChunk;
} | {
    type: "progress";
    progress: ExportProgress;
} | {
    type: "done";
    bytes: Uint8Array;
} | {
    type: "error";
    name: string;
    message: string;
};