Skip to content
Three Steam Audio Docs

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

Section titled “Overview”

Building the project involves three main stages:

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

Requirements

Section titled “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

Section titled “Clone the repository”

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

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

If you already cloned without submodules, initialize them afterwards:

Terminal window
git submodule update --init --recursive

Enter the development shell

Section titled “Enter the development shell”

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

Terminal window
nix develop

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

Install JavaScript dependencies

Section titled “Install JavaScript dependencies”
Terminal window
pnpm install

Build the Steam Audio WASM artifact

Section titled “Build the Steam Audio WASM artifact”

Download the Steam Audio dependencies when they are not cached, then build the core library and WASM bindings through Nix:

Terminal window
just build-bindings

just build-steam-audio is also available when only the Nix artifact is needed. The two repository patches are applied inside the Nix build:

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

The core artifact is stored under .build/steam-audio-wasm/core/, while build-bindings copies the generated files into packages/three-steam-audio/src/bindings/.

Build the WASM bindings

Section titled “Build the WASM bindings”

Copy the bindings generated by the Nix build into the package source tree:

Terminal window
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

Section titled “Build the packages”

Compile the TypeScript source:

Terminal window
pnpm build

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

Run checks

Section titled “Run checks”
Terminal window
pnpm typecheck
pnpm lint
pnpm test

Build the documentation

Section titled “Build the documentation”
Terminal window
pnpm dev:docs          # development server
pnpm -F docs build     # static build

Run the React example

Section titled “Run the React example”
Terminal window
pnpm dev:example-react

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

CI summary

Section titled “CI summary”

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

Terminal window
nix develop --command just build-bindings
pnpm build
pnpm typecheck
pnpm lint
pnpm test
npm pack --dry-run

The dependency directories remain cached by GitHub Actions. The Nix package reads the checked-out steam-audio submodule directly; its derivation changes when the submodule revision changes, so the Nix build cache follows the submodule without duplicating Steam Audio’s dependency manifest in this repository.