WASM Audio Decoders

WASM Audio Decoders is a collection of Web Assembly audio decoder libraries that are highly optimized for browser use. Each module supports synchronous decoding on the main thread as well as asynchronous (threaded) decoding through a built in Web Worker implementation.

Web Assembly is a binary instruction format for a stack-based virtual machine that allows for near native code execution speed inside of a web browser. In practice, these decoders are just as fast, and in some cases faster, than the browser implementation.

Checkout the demo here

Decoders

Each decoder is built with inline WASM to reduce bundling complexity with transpilers like Webpack. The inlined WASM is encoded using yEnc for efficient binary encoding and is gzip compressed for reduced file size.

Pre-built minified JS files are available from NPM and in each decoder's dist folder.

`mpg123-decoder`

Decodes MPEG Layer I/II/III into PCM

84.6 KiB minified bundle size
Browser and NodeJS support
Built in Web Worker support
Based on mpg123
Install using NPM

`@wasm-audio-decoders/flac`

Decodes FLAC and Ogg FLAC data into PCM

65.3 KiB minified bundle size
Browser and NodeJS support
Built in Web Worker support
Multichannel decoding (up to 8 channels)
Supports full FLAC bit depth and sample rate.
Based on libFLAC and codec-parser
Install using NPM

`ogg-opus-decoder`

Decodes Ogg Opus data into PCM

108.9 KiB minified bundle size
Browser and NodeJS support
Built in Web Worker support
Multichannel decoding (up to 255 channels)
Based on libopus and codec-parser
Install using NPM

`opus-decoder`

Decodes raw Opus audio frames into PCM

85.0 KiB minified bundle size
Browser and NodeJS support
Built in Web Worker support
Multichannel decoding (up to 255 channels)
Intended for users that already have Opus frames extracted from a container, i.e. (Ogg, Matroska (WEBM), or ISOBMFF (mp4))
Based on libopus
Install using NPM

`@wasm-audio-decoders/ogg-vorbis`

Decodes Ogg Vorbis data into PCM

97.9 KiB minified bundle size
Browser and NodeJS support
Built in Web Worker support
Multichannel decoding (up to 255 channels)
Supports full Vorbis sample rate.
Based on libvorbis and codec-parser
Install using NPM

Developing

Prerequisites

Linux, or a Linux-like environment to build (i.e. WSL).
NodeJS 18.x or higher.
Emscripten 3.1.51
- Install by following these instructions.

Initial Setup

Clone this repo.
Change directory to this repo and run git submodule update --init to clone the git sub-modules.

git clone https://github.com/eshaz/wasm-audio-decoders.git
cd wasm-audio-decoders
git submodule update --init

Installing Dependencies

Run npm install to install the build dependencies.
Run npm run install-decoders to install the dependencies for each decoder.

npm install
npm run install-decoders

Building

source the Emscripten path in the terminal you want build in.
- i.e. $ source path_to_your_emscripten_installation/emsdk_env.sh
Run npm run configure to configure the libraries. (only required for first time build, or after updating the Makefile)
Run npm run build to build the libraries.
- The builds will be located in each library's dist folder.

# only required for first time build, OR after updating the `Makefile`
npm run configure
# builds the project
npm run build

Testing

Run npm run test to run the test suite.

npm run test

Rebuilding after changes

Make your changes
If you updated any dependencies, make sure to install them.
If you updated any configuration in the Makefile, make sure to configure the project.
Rebuild the project.
Ensure the tests still pass by running npm run test.

Contributing

All contributions are welcome!

General recommendations

Questions / comments should be entered into an issue.
Changes should be entered into a PR.
Please read through the existing issues to check if your question / comment has already been addressed, but don't hesitate to reach out if you still have unanswered questions.
Please make sure to clearly describe your question / comment, or the feature / fix you wish to contribute.
- Sharing sample data as a demonstration is usually the best way to do this.
Adding test cases for new features or fixes is highly appreciated.

All contributes / interactions with this repository must follow the code of conduct.

Supporting

Show your support by 'starring' this repo, contributing, or donating through Github sponsors.

Attributions

OggOpusDecoder was originally based on AnthumChris/opus-stream-decoder.
- This version has been optimized for size and for simple bundling in web applications:
  - Everything is bundled in a single minified Javascript file for ease of use.
  - Multichannel decoding (all 255 Opus channels) is supported.
  - WASM binary is encoded inline using yEnc binary encoding and compressed using DEFLATE to significantly reduce bundle size.
  - WASM compiler, minifier, and bundler options are tuned for best possible size and performance.
puff is included as a WASM build from madler/zlib and is used to decompress the WASM binary.

Licensing

The source code that originates in this project is licensed under the MIT license. Please note that any external source code included by repository, such as the decoding libraries included as git submodules and compiled into the dist files, may have different licensing terms.