wav

A native WAVE/AIFF/AIFF-C decoding library written from scratch in Zig.

This project provides a clean, dependency-free decoding engine designed for seamless integration into audio players, game engines, and mixing pipelines. It eliminates wrappers around legacy C binaries, offering an easy-to-use API built natively for modern Zig I/O paradigms.

Features

• 100% Native Zig: Zero dependencies on external C source code. Easy to cross-compile out of the box with no third-party dependencies.
• Zero Allocation During Decoding: While initialization requires an allocator to set up necessary internal decoding structures, the hot-path decoding loop is completely allocation-free.
• Flexible Sample Conversion: Seamlessly decodes and transforms the underlying stream directly into whatever target sample bit depth or format your application requires, including i16, i24, i32, f32 and f64.
• SIMD Accelerated: Utilizes hardware vector extensions where available for high-throughput channel interleaving and audio math.
• Robust I/O Abstraction: Built on top of the Zig 0.16 std.Io.Reader infrastructure. Natively supports unseekable media (like live network streams) while gracefully supporting hardware/OS-level seeking when a positioning function is supplied.
• No AI/LLM Code: 100% of the code is both inspired and written by a human.

Supported Containers

• RIFF: Microsoft WAV (little-endian)
• RIFX: Microsoft WAV (big-endian)
• IFF: Amiga IFF
• AIFF: Apple AIFF/AIFF-C (compressed)
• RF64: European Broadcasting Union RIFF with 64-bit support
• W64: Sony Wave64 with 64-bit support

Supported Encodings

• Raw PCM
  • All standard 8, 16, 24, and 32 bits-per-sample (signed/unsigned)
  • Non-standard bit-depths, anything from 1 to 64 bits-per-sample
• IEEE 32-bit floating point
• IEEE 64-bit floating point
• A-law
• μ-law (mulaw)
• Microsoft ADPCM
• IMA ADPCM (DVI ADPCM)

Installation & Integration

Add wav to your project's build.zig.zon:

.{.name="my_project",.version="0.1.0",.dependencies=.{.wav=.{.url="https://codeberg.org/audiophile/wav/archive/v1.0.0.tar.gz",// .hash = "...",},},}

Expose the module in your build.zig:

conststd=@import("std");pubfnbuild(b:*std.Build)void{consttarget=b.standardTargetOptions(.{});constoptimize=b.standardOptimizeOption(.{});constwav_dep=b.dependency("wav",.{.target=target,.optimize=optimize,});constexe=b.addExecutable(.{.name="my_audio_app",.root_source_file=b.path("src/main.zig"),.target=target,.optimize=optimize,.imports=&.{.{.name="wav",.module=wav_dep.module("wav")},},});b.installArtifact(exe);}

Quick Start

conststd=@import("std");pubfnmain(init:std.process.Init)!void{constio=init.io;constallocator=init.gpa;// Boilerplate for opening a filevarcwd=std.Io.Dir.cwd();constfile=trycwd.openFile(io,"myfile.wav",.{});deferfile.close(io);varfile_buffer:[8192]u8=undefined;varreader=file.reader(io,&file_buffer);// Initialize the decoder.vardec=trywav.Decoder.init(allocator,&reader.interface,.{// Skip metadata parsing.skip_metadata=true,// Hint to the decoder that source is a file reader, so it knows how to seek..seek_impl=.file,});deferdec.deinit(allocator);// Output to your preferred sample type.// Conversion from source format to your preferred sample type is automatic.constOutSample=i24;varsample_buffer:[4096]OutSample=undefined;// Begin readingwhile(true){// Decode samples into your bufferconstsamples=trydec.read(OutSample,&sample_buffer);// `samples` is a sub-slice of `sample_buffer` with the decoded samples.if(samples.len==0)break;// TODO: Do whatever you need with the interleaved PCM sample data}}

Testing & Conformance

This library is fully validated against ~350 test vectors with a wide assortment of encodings, bit rates, metadata, and edge-cases.

• AIFF/AIFF-C format tests are sourced from Toisto AIFF Test Suite repository.
• WAVE format tests are sourced from the test vectors used by the wavefile project.

To run the test suite locally, first clone the repository with the --recursive flag:

git clone --recursive https://codeberg.org/audiophile/wav.git
cd wav

Alternatively using SSH:

git clone --recursive ssh://git@codeberg.org/audiophile/wav.git
cd wav

If you have already cloned the repository without the submodule, initialize it using:

git submodule update --init --recursive

To run the test suite locally once the test files are present:

zig build test

License

This project is licensed under the MIT License.

• AIFF test vectors are licensed under the CC0 1.0 Universal License
• WAVE test vectors are licensed under the MIT License