wavefile

wavefile is a JavaScript library for working with WAV audio files at the byte level. It exposes a single WaveFile class that can build a wave file from scratch out of raw samples, parse an existing file from a buffer, base64 string, or data URI, and serialize it back out — with full control over container format (RIFF, RIFX, RF64), bit depth (4-bit through 64-bit, including odd depths like 12-bit or 20-bit), and sample rate.

Beyond basic read/write, it implements its own codecs for IMA-ADPCM, A-Law, and mu-Law encode/decode, plus four resampling algorithms (point, linear, cubic, windowed sinc) each with optional IIR/FIR low-pass filtering. It also reads and writes the metadata chunks real audio tools care about — RIFF INFO tags, cue points and regions, sample loops, Broadcast Wave Format (“bext”) metadata, and iXML/_PMX chunks — without needing a native binding or a separate metadata library.

Because it has zero runtime dependencies and ships both an ES module and a UMD browser bundle, it runs identically in Node.js and in the browser (IE10+), and installing it globally also gives you a wavefile CLI for resampling, bit-depth conversion, compression, and tag inspection from the command line.

What You Get

• A single WaveFile class covering creation, parsing, tag/cue editing, and format conversion through one consistent API
• Support for RIFF, RIFX (big-endian), and (partial) RF64 containers, with conversion between RIFF and RIFX
• Bit depth conversion across 4-bit IMA-ADPCM, 8/16/24/32-bit integer, 32-bit float, 64-bit float, and arbitrary intermediate depths (8-53 bit) via WAVE_FORMAT_EXTENSIBLE
• Four resampling methods — point, linear, cubic, and windowed sinc — each with optional IIR or FIR low-pass filtering
• Native encode/decode for IMA-ADPCM, A-Law, and mu-Law compression, with no external codec dependency
• Read/write support for RIFF INFO tags, cue points, regions, sample loops, BWF “bext” metadata, and iXML/_PMX XML chunks
• A global CLI (wavefile) for resampling, bit-depth conversion, compression, and tag/cue inspection from the shell
• Works identically in Node.js and the browser (IE10+) via a UMD bundle, plus bundled TypeScript type declarations

Common Use Cases

• Programmatically generating WAV files from synthesized or computed sample data (e.g. audio synthesis, test fixtures, DSP experiments)
• Converting uploaded or recorded audio between bit depths and sample rates in a Node.js backend without shelling out to FFmpeg
• Reading and writing broadcast metadata (BWF “bext”, cue points, iXML) for audio post-production and archival pipelines
• Compressing/decompressing telephony- or embedded-oriented audio using IMA-ADPCM, A-Law, or mu-Law from JavaScript
• Batch-processing WAV files from the command line via the bundled wavefile CLI (resample, change bit depth, inspect tags)

Under The Hood

Architecture The library is built as a seven-level linear inheritance chain culminating in the public WaveFile class (index.js): RIFFFile (low-level chunk signature parsing in lib/riff-file.js) is extended by WaveFileReader, then WaveFileParser, WaveFileCreator, WaveFileTagEditor, WaveFileCueEditor, and finally WaveFileConverter, each adding one cohesive responsibility — byte-level RIFF reading, header parsing, from-scratch file creation, INFO-tag editing, cue-point/region editing, and format/bit-depth/sample-rate conversion — before WaveFile itself adds only the base64/DataURI convenience methods. Each layer only depends on the one below it, so the chain reads like a changelog of capabilities added over the project’s life; changing the RIFF chunk model at the base would ripple through every layer above it.

Tech Stack Plain ES2015+ JavaScript with zero runtime dependencies ("dependencies": {} in package.json). The published main is a Rollup-bundled UMD build (dist/wavefile.js) built via @rollup/plugin-commonjs and @rollup/plugin-node-resolve, with Closure Compiler (@ampproject/rollup-plugin-closure-compiler) minifying the output using JSDoc type annotations throughout the source instead of TypeScript syntax; a hand-maintained index.d.ts supplies TypeScript types separately. JSHint enforces style, and API docs are generated with JSDoc/docdash.

Code Quality Tests are organized by concern under test/ — test/src (unit tests against source), test/dist and test/AMD (tests against the built bundle in different module formats), test/resampler and test/resampler-full (resampler correctness), test/wavefile-parser, and test/TypeScript (compiles and runs a TypeScript consumer against index.d.ts) — run with Mocha and coverage collected via nyc/Codecov. CI runs the full npm run build (lint + test + bundle + doc) across Node 8-12 on both Travis (Linux/macOS) and AppVeyor (Windows), giving genuine cross-platform and cross-Node-version coverage for a byte-manipulation library where endianness and typed-array behavior matter.

What Makes It Unique Most JS WAV libraries either shell out to FFmpeg or only handle basic PCM read/write; wavefile instead reimplements IMA-ADPCM, A-Law, mu-Law, and four resampling algorithms (including windowed sinc with selectable IIR/FIR low-pass filtering) natively in JavaScript, with zero runtime dependencies, so it runs unmodified in the browser as well as Node.js. Support for less common containers (RIFX, partial RF64) and broadcast-specific chunks (bext, iXML, _PMX, cue/region metadata) also goes well beyond what typical “read a wav file” packages cover.