Introduction
This content is for v0.4. Switch to the latest version for up-to-date documentation.
This page explains what alpha2 does, how its pieces fit together and where to start. After reading it you know which package your app needs and what your code is responsible for.
What alpha2 is
Section titled “What alpha2 is”alpha2 is a portable, general-purpose media engine for WebAssembly and native. It renders a timeline project (sources, video, audio and caption tracks, clips, effects and transitions) on the GPU, for preview and for export.
The preview below is a real project rendered by the engine in your browser: three photos, a directional wipe and a fade.
The core idea: one project, the same frames
Section titled “The core idea: one project, the same frames”A project is a JSON document. It names its sources, puts clips on tracks, and says what effects and transitions apply and when. The format is versioned ("schema_version": 1) and described by a JSON Schema, so you can generate it from code, store it, diff it and check it before you render it.
Every target runs the same rendering code: the WebAssembly build in a browser, the native host on a server, and the Rust crate in your own program. So a project renders the same in a browser preview, in a server export and in a Rust program. Determinism explains what “the same” means exactly, and where it stops.
Times in a project are integers in ticks, 120,000 to the second. Time and ticks explains why.
Packages
Section titled “Packages”| You are building | Use |
|---|---|
| A browser app that previews and exports, decoding and encoding the media itself | alpha2 (npm) |
| A browser editor: documents, commands, undo, and a preview and export bridge | @alpha2-sh/editor (npm) |
A React canvas over the alpha2 browser player |
@alpha2-sh/react (npm) |
| MP4, MOV, MKV or WebM export from Node.js or Electron | @alpha2-sh/node (npm) and alpha2-host |
| MP4, MOV, MKV or WebM export from any other language | alpha2-host serve and its stdio protocol |
| Projects built, validated and exported from Python | alpha2 (PyPI) |
| A Rust program | alpha2 (crate) |
Choose your target compares them in detail.
Who does what
Section titled “Who does what”The engine renders. The engine itself does not read or write media files, so on each target something else decodes and encodes.
In the browser, your app decodes its media and uploads the pixels and samples: uploadRgbaImage for a still, uploadVideoFrame for a WebCodecs VideoFrame, uploadAudioBlock for audio. The engine asks for exactly the frames a time needs (frameNeeds), draws the frame on a canvas (renderAt), and for export hands back each frame as planar I420 and the mixed audio. Your app encodes them, for example with WebCodecs through MediabunnySink in alpha2/mediabunny.
Natively, alpha2-host does all three. It decodes and encodes with FFmpeg 8 and renders on the GPU (Vulkan, Metal or Direct3D 12), or on the CPU where there is no GPU. @alpha2-sh/node, the Python package and the CLI all run it.
In Rust, your program lends the engine its decoded frames through a FrameProvider and takes back rendered frames and YUV planes. alpha2-native decodes and encodes with FFmpeg if you want it.