Something went wrong. Try again.
A sans-IO RIFF/WAVE reader and writer for Zig: 8, 16, 24 and 32 bit PCM and 32 and 64 bit float, in and out.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! What a WAVE file says about the samples in it, and the 44 bytes that say//! it.
const std = @import("std");const Writer = std.Io.Writer;
const format_mod = @import("format.zig");const Format = format_mod.Format;
/// What a WAVE file says its samples are: the same description whether it was/// read out of a file or is about to be written into one.pub const Header = struct { sample_rate: u32, channels: u16, format: Format, /// Frames — interchannel samples — in the `data` chunk, if that is known. /// /// `null` means it is not: the stream is endless, or is going somewhere /// that cannot be seeked back to afterwards, or was read from a file /// whose length fields were never filled in. The two length fields are /// then written as `0xFFFFFFFF`, which is the convention for a WAVE /// stream of indefinite length: a player reads until the pipe closes /// rather than stopping at a length that was a guess. frames: ?u64 = null,
/// Bytes per frame: one sample in each channel. pub fn blockAlign(h: Header) u32 { return @as(u32, h.channels) * h.format.bytesPerSample(); }
/// Bytes per second of audio, which is what the header calls the average /// byte rate and what a player sizes its buffers from. pub fn byteRate(h: Header) u32 { return h.sample_rate *% h.blockAlign(); }
/// The size of the `data` chunk, when `frames` says what it is. pub fn dataBytes(h: Header) ?u64 { return (h.frames orelse return null) * h.blockAlign(); }};
/// The value both length fields carry when the length is not known.pub const unknown_length: u32 = 0xFFFF_FFFF;
/// The size of the header `render` and `writeHeader` produce: the `RIFF`/// chunk, a 16 byte `fmt ` chunk, and the `data` chunk's own header.pub const header_size = 44;
/// Where the `RIFF` chunk's length field sits, for a caller who could not/// know the length in advance and can seek back to put it right.pub const riff_size_offset = 4;/// Where the `data` chunk's length field sits, likewise.pub const data_size_offset = 40;
/// The two length fields, for a caller writing them back over a header that/// was written before the length was known.pub const Sizes = struct { /// Goes at `riff_size_offset`. riff: u32, /// Goes at `data_size_offset`. data: u32,};
/// What the length fields of `h` should say, or `null` where they cannot say/// anything true — the length is unknown, or is past what a `u32` of bytes/// can count.////// A `data` chunk of odd length is followed by a pad byte. That byte is not/// counted in the chunk's own length and *is* counted in the file's, which is/// the one place in a WAVE file where the two lengths are not a fixed/// distance apart — and getting it wrong makes a file that a strict reader/// refuses, since the chunk then claims one byte more than the file holding/// it has left. `Writer.finish` is what writes that byte.pub fn sizes(h: Header) ?Sizes { const data = std.math.cast(u32, h.dataBytes() orelse return null) orelse return null; const pad: u32 = data & 1; if (data > std.math.maxInt(u32) - (header_size - 8) - pad) return null; return .{ .riff = data + pad + header_size - 8, .data = data };}
/// Render the 44 byte header into `buf`.////// The header is the canonical one — `WAVE_FORMAT_PCM` or/// `WAVE_FORMAT_IEEE_FLOAT` in sixteen bytes of `fmt `, and nothing between/// it and the samples — rather than the extensible header the specification/// asks for above two channels or sixteen bits. It is what every player/// reads, and it is a fixed 44 bytes, which is what lets a stream going to a/// pipe be written without knowing anything about what follows.pub fn render(h: Header, buf: *[header_size]u8) void { const block_align = h.blockAlign(); const data_bytes: u32 = if (sizes(h)) |s| s.data else unknown_length; const riff_size: u32 = if (sizes(h)) |s| s.riff else unknown_length;
@memcpy(buf[0..4], "RIFF"); std.mem.writeInt(u32, buf[4..8], riff_size, .little); @memcpy(buf[8..12], "WAVE"); @memcpy(buf[12..16], "fmt "); std.mem.writeInt(u32, buf[16..20], 16, .little); std.mem.writeInt(u16, buf[20..22], h.format.tag(), .little); std.mem.writeInt(u16, buf[22..24], h.channels, .little); std.mem.writeInt(u32, buf[24..28], h.sample_rate, .little); std.mem.writeInt(u32, buf[28..32], h.byteRate(), .little); std.mem.writeInt(u16, buf[32..34], @truncate(block_align), .little); std.mem.writeInt(u16, buf[34..36], h.format.bitsPerSample(), .little); @memcpy(buf[36..40], "data"); std.mem.writeInt(u32, buf[40..44], data_bytes, .little);}
/// Write the 44 byte header.pub fn writeHeader(w: *Writer, h: Header) Writer.Error!void { var buf: [header_size]u8 = undefined; render(h, &buf); try w.writeAll(&buf);}
const testing = std.testing;
test "the header describes what follows it" { var buf: [header_size]u8 = undefined; render(.{ .sample_rate = 44100, .channels = 2, .format = .s16, .frames = 100 }, &buf);
try testing.expectEqualStrings("RIFF", buf[0..4]); try testing.expectEqualStrings("WAVE", buf[8..12]); try testing.expectEqualStrings("fmt ", buf[12..16]); try testing.expectEqualStrings("data", buf[36..40]); try testing.expectEqual(@as(u32, 16), std.mem.readInt(u32, buf[16..20], .little)); try testing.expectEqual(@as(u16, 1), std.mem.readInt(u16, buf[20..22], .little)); try testing.expectEqual(@as(u16, 2), std.mem.readInt(u16, buf[22..24], .little)); try testing.expectEqual(@as(u32, 44100), std.mem.readInt(u32, buf[24..28], .little)); try testing.expectEqual(@as(u32, 44100 * 4), std.mem.readInt(u32, buf[28..32], .little)); try testing.expectEqual(@as(u16, 4), std.mem.readInt(u16, buf[32..34], .little)); try testing.expectEqual(@as(u16, 16), std.mem.readInt(u16, buf[34..36], .little)); try testing.expectEqual(@as(u32, 400), std.mem.readInt(u32, buf[40..44], .little)); try testing.expectEqual(@as(u32, 400 + 36), std.mem.readInt(u32, buf[4..8], .little));}
test "an endless stream declares itself as one" { var buf: [header_size]u8 = undefined; render(.{ .sample_rate = 48000, .channels = 1, .format = .f32 }, &buf); try testing.expectEqual(unknown_length, std.mem.readInt(u32, buf[4..8], .little)); try testing.expectEqual(unknown_length, std.mem.readInt(u32, buf[40..44], .little)); try testing.expectEqual(@as(u16, 3), std.mem.readInt(u16, buf[20..22], .little)); try testing.expectEqual(@as(u16, 32), std.mem.readInt(u16, buf[34..36], .little));}
test "a length too big for the field falls back to declaring it unknown" { // Nine hours of 24 bit stereo at 96 kHz is past 4 GiB, which the field // cannot hold. Saying "unknown" is honest; truncating the count is not. const h: Header = .{ .sample_rate = 96000, .channels = 2, .format = .s24, .frames = 96000 * 3600 * 9, }; try testing.expectEqual(@as(?Sizes, null), sizes(h));
var buf: [header_size]u8 = undefined; render(h, &buf); try testing.expectEqual(unknown_length, std.mem.readInt(u32, buf[40..44], .little)); try testing.expectEqual(unknown_length, std.mem.readInt(u32, buf[4..8], .little));}
test "an odd data chunk is one byte longer than it says, in the file's length" { // The pad byte: not in the chunk's own length, in the file's. Five bytes // of eight bit mono is the smallest thing that shows it. const h: Header = .{ .sample_rate = 8000, .channels = 1, .format = .u8, .frames = 5 }; const s = sizes(h).?; try testing.expectEqual(@as(u32, 5), s.data); try testing.expectEqual(@as(u32, 5 + 1 + header_size - 8), s.riff);
// And an even one is exactly the header apart, as everything else is. const even: Header = .{ .sample_rate = 8000, .channels = 1, .format = .u8, .frames = 6 }; const t = sizes(even).?; try testing.expectEqual(@as(u32, 6), t.data); try testing.expectEqual(@as(u32, 6 + header_size - 8), t.riff);}
test "the offsets are where the length fields are" { var buf: [header_size]u8 = undefined; const h: Header = .{ .sample_rate = 8000, .channels = 1, .format = .u8, .frames = 3 }; render(h, &buf); const s = sizes(h).?; try testing.expectEqual(s.riff, std.mem.readInt(u32, buf[riff_size_offset..][0..4], .little)); try testing.expectEqual(s.data, std.mem.readInt(u32, buf[data_size_offset..][0..4], .little)); try testing.expectEqual(@as(u32, 3), s.data);}
test "a header knows its own arithmetic" { const h: Header = .{ .sample_rate = 48000, .channels = 6, .format = .s24, .frames = 10 }; try testing.expectEqual(@as(u32, 18), h.blockAlign()); try testing.expectEqual(@as(u32, 48000 * 18), h.byteRate()); try testing.expectEqual(@as(?u64, 180), h.dataBytes()); try testing.expectEqual(@as(?u64, null), (Header{ .sample_rate = 48000, .channels = 1, .format = .s16, }).dataBytes());}