Build Instructions

This page explains how to build three-steam-audio from source. Most users can install the package from npm and skip this section.

Overview

Building the project involves three main stages:

Steam Audio core — download dependencies and build the Steam Audio SDK as a WebAssembly static library.
WASM bindings — generate TypeScript declarations and compile the C bridge into phonon_bindings.wasm / phonon_bindings.js.
npm packages — build the TypeScript source and the documentation site.

Requirements

The recommended development environment is managed with Nix. The project’s flake.nix provides cmake, emscripten, just, ninja, and other native tools.

Nix package manager with flakes enabled
pnpm
Node.js 24 or later
Git with submodules support

Clone the repository

three-steam-audio includes the Steam Audio SDK as a Git submodule. Clone recursively so the steam-audio/ directory is populated.

git clone --recursive https://github.com/kwaa/three-steam-audio.git
cd three-steam-audio

If you already cloned without submodules, initialize them afterwards:

git submodule update --init --recursive

Enter the development shell

From the repository root, enter the Nix shell to get the required build tools:

nix develop

This sets STEAMAUDIO_ROOT to $PWD/steam-audio and puts emcc, cmake, just, and ninja on your path.

Install JavaScript dependencies

pnpm install

Build the Steam Audio core

Download the Steam Audio dependencies for WebAssembly and build the core library:

just get_dependencies
just build-steam-audio

just build-steam-audio applies two small patches automatically:

patches/steam-audio/flatbuffers-1.12-table-key-comparator.patch
patches/steam-audio/emscripten-synchronous-thread-pool.patch

The build produces static libraries under steam-audio/core/bin/lib/wasm/ and headers under steam-audio/core/bin/include/.

Build the WASM bindings

Generate TypeScript types and compile the C bindings into the package source tree:

just build-bindings

This writes the following files to packages/three-steam-audio/src/bindings/:

phonon_bindings.js
phonon_bindings.wasm
phonon_bindings.d.ts

Build the packages

Compile the TypeScript source:

pnpm build

This builds the three-steam-audio package and any workspace dependents.

Run checks

pnpm typecheck
pnpm lint
pnpm test

Build the documentation

pnpm dev:docs          # development server
pnpm -F docs build     # static build

Run the React example

pnpm dev:example-react

This starts the interactive demo in examples/react/, which shows HRTF spatialization, occlusion, transmission, and parametric reflections.

CI summary

The .github/workflows/check.yml pipeline performs the following steps on every pull request:

nix develop --command just get_dependencies build-steam-audio build-bindings
pnpm build
pnpm typecheck
pnpm lint
pnpm test
npm pack --dry-run