eshaz / wasm-audio-decoders

Browser and NodeJS Web Assembly audio decoder libraries that are highly optimized for size and performance.

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

• 64.8 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.5 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.5 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

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

Initial Setup

1. Clone this repo.
2. 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

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

npm install
npm run install-decoders

Building

1. source the Emscripten path in the terminal you want build in.
   • i.e. $ source path_to_your_emscripten_installation/emsdk_env.sh
2. Run npm run configure to configure the libraries. (only required for first time build, or after updating the Makefile)
3. 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

1. Run npm run test to run the test suite.

npm run test

Rebuilding after changes

1. Make your changes
2. If you updated any dependencies, make sure to install them.
3. If you updated any configuration in the Makefile, make sure to configure the project.
4. Rebuild the project.
5. 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.