Hawkynt.FileFormats.Audio 1.0.0.696

Hawkynt.FileFormats.Audio

Pure-managed audio codecs and container readers / writers extracted from CompressionWorkbench. Sister package to Hawkynt.FileFormats.Images / Hawkynt.FileFormats.Archives / Hawkynt.FileFormats.FileSystems, all built on top of Hawkynt.Compression.Core.

The package bundles every audio-domain assembly (codecs + containers + tracker / chiptune / game audio bundles) into lib/, so consumers add a single dependency and get the full audio surface. Hawkynt.Compression.Core ships separately and is referenced as a NuGet <dependency> rather than bundled, so installing both packages doesn't create duplicate DLLs.

When to use this package

• You need a pure-managed audio codec without dragging in libsamplerate / libflac / FFmpeg
• You're building a tool that needs to read or write WAV / AIFF / AU / FLAC / ALAC / OGG / MP3 / MIDI files from C# without Windows Media Foundation or platform-specific APIs
• You want to inspect tracker (MOD / S3M / XM / IT) or chiptune (PSF) files programmatically
• You're processing game audio bundles (Wwise BNK, FMOD, AKB, AWB) and need their layout

Skip it when:

• You only need raw PCM I/O — Hawkynt.Compression.Core already exposes Codec.Pcm.PcmCodec.SplitInterleavedPcm / ToWavBlob indirectly, and PCM is in the smaller Hawkynt.Compression.Core graph through its dependency chain
• You need codec-quality features (resampling, normalisation, EBU R128 loudness) — those live in dedicated audio-DSP libraries; this package targets format I/O, not signal processing

Quick start

using Codec.Pcm;
using FileFormat.Wav;

// Read a stereo 16-bit WAV and split it into mono left/right WAVs.
var blob   = File.ReadAllBytes("input.wav");
var parsed = new WavReader().Read(blob);
foreach (var (name, monoWav) in PcmCodec.SplitInterleavedPcm(
             parsed.InterleavedPcm,
             parsed.NumChannels,
             parsed.SampleRate,
             parsed.BitsPerSample))
  File.WriteAllBytes($"{name}.wav", monoWav);

The container / carried-data model

Every audio file is surfaced as a pseudo-archive: the container is the archive, and everything it carries is listed as pseudo-files. The entry Kind makes the distinction explicit:

Channel naming follows FFmpeg's libavutil/channel_layout: when the container carries an explicit speaker bitmap (WAVE_FORMAT_EXTENSIBLE.dwChannelMask, CAF channel bitmap) each mono WAV is named for its real speaker; otherwise the FFmpeg default layout for the channel count applies — mono, stereo, 2.1, 4.0, 5.0, 5.1, 6.1, 7.1, 5.1.4, 7.1.4, 9.1.4, 9.1.6 and NHK 22.2 (24 channels: FRONT_LEFT … TOP_SIDE_LEFT … BOTTOM_FRONT_RIGHT). Channel counts beyond the table degrade to CH_n, so any multi-channel stream stays decodable to per-speaker mono WAVs and reassembles losslessly from them (Codec.Pcm.ChannelLayout + PcmCodec.SplitInterleavedPcm / Interleave).

Contents

State legend:

• R — read / decode only.
• WORM — Write-Once-Read-Many: can list / extract / decode AND can synthesise / encode a fresh output from scratch, but cannot modify an existing file in place.
• R/W — full read + true encoder; codec or container can produce the format from PCM / source data.

Codecs (Codec.*)

Honest scope note. Most lossy / lossless codecs in this package decode but don't encode. Writing a high-quality MP3 / AAC / Vorbis / Opus / FLAC encoder is a significant undertaking beyond the workbench's "no native deps" line in the sand and is out of scope for now. A-law / mu-law / PCM are simple enough that we ship full encoders. If you need to write lossy audio, reach for a dedicated encoder library; if you only need to read the format, this package covers it.

File-format containers (FileFormat.*)

Codec implementation reference

Each codec has a Decompress(Stream input, Stream output) entry point producing interleaved little-endian PCM and a ReadStreamInfo for metadata-only access. Encoders for the lossy / lossless modern codecs are out of scope (see the scope note above) — only the legacy / simple codecs ship with encoders.

Implementation philosophy. The four modern lossy codecs (MP3 / Vorbis / Opus / AAC-LC) ship under the project's "no toy implementations" rule — partial state is documented openly (in class summaries, in Assert.Ignore messages, and in the table above) rather than silently producing wrong PCM. Future work: bit-pack debugging for MP3, real CELT/SILK for Opus, spectral table population for AAC, reference test-vector validation across all four.

Versioning

This package version-locks 1:1 with Hawkynt.Compression.Core. Pin the same version across the two packages — independent versioning would risk binary-incompatibility windows where a member DLL bundled here was built against a different Compression.Core than the one a consumer installs.

License

LGPL-3.0-or-later. See the source repository for the full license text and per-algorithm references.