@alpha2-sh/node

A Node.js client for alpha2-host, the native alpha2 renderer: it exports alpha2 projects to MP4, MOV, Matroska or WebM files from Node.js or an Electron main process, with FFmpeg for decoding and encoding and the GPU for rendering.

Install

npm install @alpha2-sh/node

The package does not include alpha2-host. Download it for this package's version and platform:

npx @alpha2-sh/node install

This fetches the platform's bundled native archive from the GitHub release of the same version, checks it against the SHA-256 this package pins for it (the published package carries the SHA-256 of every archive of its version, so a mirror cannot substitute one; a source checkout checks against the release's checksums.sha256 instead; the result's verifiedBy says which), and unpacks it into the cache: ALPHA2_HOST_CACHE_DIR when it is set, else alpha2 in $XDG_CACHE_HOME or ~/.cache on Linux, ~/Library/Caches on macOS and %LOCALAPPDATA% on Windows. --force downloads again, and installHost(options) does the same from code. Downloads go through HTTPS_PROXY (HTTP_PROXY for an http: mirror, with NO_PROXY exceptions) and trust the system's certificate store as well as Node's own roots, so a proxy that inspects TLS works once its root certificate is in the system store (or in NODE_EXTRA_CA_CERTS). ALPHA2_HOST_DOWNLOAD_URL (or the downloadUrl option) names a mirror laid out like https://github.com/alpha2-sh/alpha2/releases/download. Archives are published for linux-x64, linux-arm64 (glibc 2.35 or later; musl systems such as Alpine are refused), macos-arm64 (also used by an x64 Node under Rosetta) and win-x64 (not Windows on ARM). To use a system FFmpeg 8, build the host from source (cargo install alpha2-host) and set ALPHA2_HOST_PATH.

The client looks for alpha2-host (alpha2-host.exe on Windows) in this order:

1. the hostPath option;
2. the ALPHA2_HOST_PATH environment variable (a relative path is relative to the cwd option, else the working directory);
3. in Electron, process.resourcesPath/bin/, then process.resourcesPath/;
4. this package's own bin/ directory;
5. the archive of this package's version in the cache (the cacheDirectory option, else the directory above);
6. the directories on PATH.

When none has it, the client throws an Alpha2HostError with code HOST_NOT_FOUND. installHost rejects with an Alpha2HostInstallError instead, whose code is UNSUPPORTED_PLATFORM, DOWNLOAD_FAILED, CHECKSUM_MISMATCH, EXTRACT_FAILED or ABORTED.

Node.js 22.21 or later (24.5 or later on Node 24).

Export a project

import { Alpha2NodeClient } from "@alpha2-sh/node";

const client = new Alpha2NodeClient(); // finds the host `npx @alpha2-sh/node install` put in the cache
const output = await client.exportProject({
  project, // an alpha2 project document
  assets: { "image-1": "/media/image.png" }, // the file of each source
  startTicks: 0,
  endTicks: 120_000, // ticks: 120,000 a second
  frameRate: { num: 30, den: 1 },
  videoQuality: "high",
  output: "/exports/tutorial.mp4",
  onProgress: ({ phase, completed, total }) => console.log(phase, completed, total),
});

Each export runs in its own alpha2-host process. The project is checked with validateProject from alpha2/project before a process starts; an invalid one is refused with an Alpha2ProjectValidationError listing the problems. An existing output is refused unless the request sets overwrite: true, and an output that is one of the request's inputs is always refused: the host writes <stem>.a2partial.<ext> beside it and moves it into place when it is complete. A finished file that cannot be moved there is kept beside it, and the error (OUTPUT_PUBLISH_FAILED) names it in keptPath. exportProject resolves with the output path once the file is complete; onResult receives what the host reports about the export (frames, encoder, rate control, timing, which media each source read).

The request's fields are typed and described in ExportProjectRequest; the host protocol lists them with their defaults. Among them: container (mp4, mov, mkv or webm; by default the one the output's extension names), videoCodec and audioCodec (by default the container's: h264 and aac, or vp9 and opus for WebM; hevc, av1, mpeg4-part2 and prores (MOV) are the other video codecs, and each container offers only some, as encode.containers lists), alpha and bitDepth (transparency with VP9 in WebM or ProRes 4444, and 10-bit pictures), videoQuality and audioQuality (a level, very-low to very-high, high by default, which the host turns into a rate for the codec, size and frame rate, or an explicit bitrate), includeAudio, loudness, fonts, effectAssets, proxies with media: "proxies", renderCache and memory.

Capabilities

client.getCapabilities() reports what the host can decode and encode, and encode.containers which codecs each container offers. An MP4, MOV or Matroska export without videoCodec gets H.264, and a host that cannot encode it refuses the export instead of writing another codec. A host encodes H.264 either with an encoder listed in encode.video or through its GPU-resident path, encode.gpuOutputPath, whose encoder takes frames on the GPU only (on Linux, h264_vulkan) and so is not in encode.video. encode.h264 sums this up: available (every export can), gpu-only (only exports the GPU-resident path takes) or unavailable, with a reason and a remedy:

const { encode } = (await client.getCapabilities()).capabilities;
if (encode.h264.status !== "available") console.warn(encode.h264.reason, encode.h264.remedy);

The first getCapabilities call for a decode mode and renderer starts a host; calls made while it runs share it, and its answer serves later calls for those modes.

videoDecode (software, auto, hardware-required) chooses how the host decodes video, as a client option or per export; by default the host decides, auto on Linux and macOS and software on Windows. Under auto, an export whose hardware decoder stalls runs once more decoding in software.

renderer (auto, gpu, cpu) chooses what draws the frames, as a client option or per export; unset, the host reads ALPHA2_RENDERER, else uses auto. auto renders on a hardware GPU when there is one and on the CPU otherwise, never on a software GPU adapter (lavapipe, llvmpipe, WARP, SwiftShader); gpu takes whatever adapter the host finds and fails with GPU_INIT_FAILED without one; cpu opens no graphics driver. Results and capabilities report renderer (gpu or cpu), rendererReason (why the host renders on the CPU) and, on the CPU, rendererThreads; capabilities.features has renderer.gpu, renderer.cpu and effects.runtime. A runtime WGSL effect cannot run on the CPU renderer: such an export fails with EFFECT_ERROR.

Software H.264 (OpenH264)

Where no hardware H.264 encoder is available, alpha2-host can encode H.264 in software with Cisco's OpenH264 library, which it loads at run time. Neither this package nor the native archives include that library, and nothing downloads it unless you ask: Cisco's patent licence covers its binary only when the user fetches it from Cisco.

npx @alpha2-sh/node install --openh264

This downloads Cisco's OpenH264 2.7.0 binary for the platform from https://ciscobinary.openh264.org, checks the download and the library in it against their SHA-256s, and puts the library in the cache beside the host archives, in openh264-2.7.0-<target>/, where alpha2-host finds it. It installs only the library, not alpha2-host. --force downloads again, installOpenH264(options) does the same from code, and ALPHA2_OPENH264_DOWNLOAD_URL (or the downloadUrl option) names a mirror. Every run prints Cisco's notice:

OpenH264 Video Codec provided by Cisco Systems, Inc.

The library is Cisco's binary, under Cisco's terms. Set ALPHA2_OPENH264=0 to keep alpha2-host from using it. encode.openh264 in the capabilities says whether the host loaded it, and an export that used it names it as videoEncoder: "openh264" with videoEncoderLibrary.

Errors

Every rejection is an Alpha2HostError with a code, the protocol's error codes and the client's own (HOST_NOT_FOUND, HOST_EXITED, HOST_OOM_KILLED (a host the kernel's out-of-memory killer ended, on Linux), HOST_LOAD_FAILED, HOST_START_TIMEOUT, HOST_QUARANTINED, HOST_BLOCKED, ABORTED, and others). Its failure classifies it for a retry policy (alpha2/export-failure, alpha2/export-retry): the step and frame it failed at, and whether it is evidence of a lost device, running out of memory or bad input. stderr holds the end of the host's standard error. Subclasses:

• Alpha2ProjectValidationError: the project is invalid (problems).
• Alpha2ConformError: the media is not ready, so nothing was rendered (report says, per source, what is missing, offline or not the media the project recorded). client.conform({ project, assets }) asks the same question without exporting.
• Alpha2GpuInitializationError: the host could not create its GPU device (only with renderer: "gpu").
• Alpha2AbortError: the request's signal aborted it.

A host that writes nothing within hostStartTimeoutMs (a client option, 30 000 by default, Infinity to wait forever) is killed and the request fails with HOST_START_TIMEOUT: something held it before it ran, a Gatekeeper check on macOS, or an antivirus scan or an App Control policy on Windows. On macOS a host whose files carry the quarantine attribute of a browser download, and which Gatekeeper does not accept, is refused before it starts with HOST_QUARANTINED, whose message names the xattr -dr com.apple.quarantine command that clears it. A host Windows refuses by policy (Smart App Control, App Control, AppLocker) is HOST_BLOCKED, and a Linux host whose program interpreter is missing (a glibc build on musl, such as Alpine) or whose glibc is too old is HOST_LOAD_FAILED; no retry mends any of the three.

Cancelling

signal (an AbortSignal) cancels an export. The client writes a cancel line to the host, which stops the export, removes its partial file and answers; then the process ends, and exportProject rejects with Alpha2AbortError once it is gone. A host that does not answer within 5 seconds is ended. The host also watches the process that started it: when that process dies, the host cancels its export and exits.

Concurrency

client.still({ project, assets, time, output }) renders one frame to a PNG, the frame an export draws at that time (the frame of the project's grid that holds it, stills[0].frameTime in the result), without encoding a video; client.stills({ ..., stills: [{ time, output }, ...] }) renders up to 256 with one host. time is in ticks.

concurrency (default 1) is how many host processes a client runs at once, and so how many exports share the GPU; more requests wait for a slot. The module-level exportProject(request, options), still, stills and getCapabilities(options) share one client per host binary and concurrency.

Electron

Ship the archive's bin/ and lib/ outside the ASAR archive, for example as bin/ and lib/ in the application's resources directory (process.resourcesPath), where the client finds the host in an Electron main process. A host path inside app.asar is read from app.asar.unpacked instead.

License

MIT, copyright Alpha2 contributors. The native archive's FFmpeg is under the LGPL; see native archives.