Accept PCM8/32, float64, A-law, mu-law and WAVEFORMATEXTENSIBLE in the WAV reader (#319)

* feat(audio): accept PCM8/32, float64, A-law, mu-law and WAVEFORMATEXTENSIBLE

The reader handled PCM16, PCM24 and float32. Everything else -- including
ordinary PCM16 that happens to be tagged 0xFFFE -- came back as "unsupported WAV
encoding (need PCM16, PCM24, or float32)", which is confusing when PCM16 is
exactly what is inside. Encoders emit WAVEFORMATEXTENSIBLE routinely for more
than two channels or whenever a channel mask is set, and the real format tag
then lives in the SubFormat GUID rather than in wFormatTag.

Adds PCM8 (unsigned, biased by 128), PCM32, float64, G.711 A-law and mu-law, and
unwraps WAVEFORMATEXTENSIBLE to whatever its GUID names. Files that still cannot
be decoded now say what they are: a FLAC, Ogg, MP3, MP4, AIFF, RF64 or CAF given
to the reader is named as such instead of failing with "invalid WAV RIFF header".

Tests cover each added format. The G.711 cases are pinned to the published
decode values (mu-law 0x00 -> -32124, A-law 0x2A -> +32256, and A-law's absence
of an exact zero) rather than to a re-derivation of the same bit manipulation,
which would prove nothing. Two negative cases check that widening the accepted
set did not turn into accepting everything: ADPCM is still rejected, and a FLAC
is still identified as a FLAC.

Verified by execution: the new cases fail against the previous reader with the
old message and pass against this one; wav_reader_chunk_bounds_test still
passes.

This lands separately from #180 at @0xShug0's request. The decoders originate
from @dignome's contributed tree, where they existed so the CLI and server path
would accept the same files the web UI already did.

* fix(audio): correct the A-law sign and validate extensible headers

Four defects found by review before merge.

**A-law polarity was inverted on all 256 codes.** G.711 sets the sign bit for
*positive* samples in A-law and for *negative* ones in mu-law; this treated both
the same way. Decoded audio came out at the right amplitude, phase-inverted --
which is inaudible on its own and survives every spot check.

The tests did not catch it because they were circular: four "published" anchors
whose expected values had been worked out from the same shift-and-bias
arithmetic under test, so they confirmed the bug rather than finding it. They are
replaced with the full 256-entry decode tables for both codings, taken from
outside this codebase -- ffmpeg 9.0.1 decoding a 256-byte file, cross-checked
against the values implied by the ITU-T G.711 segment definitions. Reinstating
the old sign now fails on `A-law code 0`.

**The extensible SubFormat GUID was trusted on its first two bytes.** Only those
carry the format tag; the remaining fourteen are a fixed suffix shared by every
KSDATAFORMAT_SUBTYPE_*. Without checking them, an unrelated codec whose GUID
merely starts 0x0001 decoded as PCM16. Now compared, and cbSize is required to
be at least 22 as the structure demands. A sub-40-byte extensible fmt chunk gets
a clear error instead of falling through with a stale format tag.

**PCM32 and float64 silently dropped a trailing partial sample.** Integer
division trimmed it, so a truncated download decoded as valid audio. Both now
reject it, matching what PCM24 already did. PCM16 and float32 keep their existing
behaviour -- tightening those is not this PR's business.

Verified: full ctest green, an A-law file transcoded by ffmpeg works as a CLI
--voice-ref end to end, and each new negative case fails against the code as it
stood before this commit.

* fix(audio): stop the header sniff and the RIFF pad from breaking valid files

Two defects a second reviewer found in the parse loop, both introduced by the
first commit in this PR, and both invisible to tests that only ever read from a
file path.

**The 12-byte header sniff rewound absolutely.** After reading the RIFF header
for container identification it did `seekg(header_read, beg)`, which is
redundant for a stream that started at offset 0, wrong for one that did not, and
impossible for one that cannot seek. `read_wav_f32(std::istream &)` is public;
handed a pipe it set failbit and reported `incomplete WAV file` for a perfectly
good WAV. The bytes are already consumed, so the rewind is simply removed.

**The RIFF pad byte was required at EOF.** After an odd-sized chunk the reader
always seeks one byte. Seeking past the end is legal on an ifstream but not on
the in-memory buffer behind the string_view overload, so the same bytes parsed
from disk and threw from an upload. Plenty of writers omit the final pad, and
this PR is what makes it matter: PCM8, A-law and mu-law are one byte per sample,
so odd data chunks go from rare to routine. A pad byte carries no data, so a
missing one at EOF now ends the chunk loop instead of failing.

Also rejects a `fmt ` chunk shorter than 16 bytes, which previously read on into
whatever followed.

The PCM8, PCM32 and float64 expectations were still derived from the
implementation, the same construction that hid the A-law inversion. They are now
frozen from `ffmpeg -f f32le` output and extended to the endpoints that
distinguish a correct conversion from a plausible one: INT32_MAX, which float32
rounding maps to exactly 1.0, and a float64 value not representable in float32.

Verified: reinstating any of the three defects fails the suite with the matching
message; full ctest green; and our decode of a real ffmpeg-transcoded A-law file
matches ffmpeg on all 153280 samples with zero mismatches.

Author: 5uck1ess

src/framework/audio/wav_reader.cpp

@@ -1,6 +1,9 @@
 #include "engine/framework/audio/wav_reader.h"
 
+#include <algorithm>
+#include <array>
 #include <cstdint>
+#include <cstring>
 #include <fstream>
 #include <stdexcept>
 #include <string>
@@ -63,24 +66,127 @@ void skip_bytes(std::istream & input, std::streamoff count) {
     }
 }
 
+// WAVE format tags. EXTENSIBLE is the one that matters in practice: many
+// encoders emit it for ordinary PCM16 whenever there are more than two channels
+// or a channel mask is set, and the real codec then lives in a SubFormat GUID
+// rather than in the format tag itself.
+constexpr uint16_t kFormatPcm = 0x0001;
+constexpr uint16_t kFormatFloat = 0x0003;
+constexpr uint16_t kFormatALaw = 0x0006;
+constexpr uint16_t kFormatMuLaw = 0x0007;
+constexpr uint16_t kFormatExtensible = 0xFFFE;
+
+// Bytes 2..15 of every KSDATAFORMAT_SUBTYPE_* GUID:
+// XXXXXXXX-0000-0010-8000-00aa00389b71.
+constexpr std::array<char, 14> kKsDataFormatSubtypeTail = {
+    0x00, 0x00, 0x00, 0x00, 0x10, 0x00, static_cast<char>(0x80),
+    0x00, 0x00, static_cast<char>(0xAA), 0x00, 0x38, static_cast<char>(0x9B), 0x71,
+};
+
+// Names a container we can recognise but not decode, so the error can say what
+// the file actually is instead of "invalid WAV RIFF header".
+const char * identify_foreign_container(const std::array<char, 12> & header) {
+    const auto * bytes = reinterpret_cast<const uint8_t *>(header.data());
+    if (std::memcmp(header.data(), "fLaC", 4) == 0) {
+        return "FLAC";
+    }
+    if (std::memcmp(header.data(), "OggS", 4) == 0) {
+        return "Ogg (Vorbis/Opus)";
+    }
+    if (std::memcmp(header.data(), "ID3", 3) == 0) {
+        return "MP3";
+    }
+    // MPEG audio frame sync: 11 set bits.
+    if (bytes[0] == 0xFF && (bytes[1] & 0xE0) == 0xE0) {
+        return "MP3";
+    }
+    if (std::memcmp(header.data() + 4, "ftyp", 4) == 0) {
+        return "MP4/M4A (AAC or ALAC)";
+    }
+    if (std::memcmp(header.data(), "FORM", 4) == 0) {
+        return "AIFF";
+    }
+    if (std::memcmp(header.data(), "RF64", 4) == 0) {
+        return "RF64";
+    }
+    if (std::memcmp(header.data(), "caff", 4) == 0) {
+        return "CAF";
+    }
+    if (bytes[0] == 0x1A && bytes[1] == 0x45 && bytes[2] == 0xDF && bytes[3] == 0xA3) {
+        return "Matroska/WebM";
+    }
+    return nullptr;
+}
+
+// G.711 expansion. Both are 8-bit logarithmic codings still common in
+// telephony recordings and in WAVs produced by conferencing tools.
+float decode_mu_law(uint8_t value) {
+    value = static_cast<uint8_t>(~value);
+    const int sign = (value & 0x80) != 0 ? -1 : 1;
+    const int exponent = (value >> 4) & 0x07;
+    const int mantissa = value & 0x0F;
+    const int magnitude = ((mantissa << 3) + 0x84) << exponent;
+    return static_cast<float>(sign * (magnitude - 0x84)) / 32768.0F;
+}
+
+float decode_a_law(uint8_t value) {
+    value ^= 0x55;
+    // Note the inversion relative to mu-law above: in A-law the sign bit marks a
+    // POSITIVE sample. Getting this backwards is silent -- the audio decodes at
+    // the right amplitude, just phase-inverted -- so it is pinned by an
+    // exhaustive 256-code table in the tests rather than by spot checks.
+    const int sign = (value & 0x80) != 0 ? 1 : -1;
+    const int exponent = (value >> 4) & 0x07;
+    const int mantissa = value & 0x0F;
+    int magnitude = 0;
+    if (exponent == 0) {
+        magnitude = (mantissa << 4) + 8;
+    } else {
+        magnitude = ((mantissa << 4) + 0x108) << (exponent - 1);
+    }
+    return static_cast<float>(sign * magnitude) / 32768.0F;
+}
+
+std::string describe_encoding(uint16_t format, uint16_t bits) {
+    std::string name;
+    switch (format) {
+        case kFormatPcm: name = "PCM"; break;
+        case kFormatFloat: name = "IEEE float"; break;
+        case kFormatALaw: name = "A-law"; break;
+        case kFormatMuLaw: name = "mu-law"; break;
+        case kFormatExtensible: name = "extensible"; break;
+        default: name = "format tag " + std::to_string(format); break;
+    }
+    return name + ", " + std::to_string(bits) + "-bit";
+}
+
 }  // namespace
 
 WavData read_wav_f32(std::istream & input) {
     if (!input) {
         throw std::runtime_error("could not open WAV input");
     }
 
-    char riff[4];
-    input.read(riff, 4);
-    if (!input || std::string(riff, 4) != "RIFF") {
+    // Consume the 12-byte RIFF header once and keep it: it doubles as the magic
+    // for naming a non-WAV container below. Deliberately no rewind afterwards --
+    // these bytes are spent, and an absolute seek back to 12 would be wrong for
+    // an istream that did not begin at offset 0 and impossible for one that
+    // cannot seek at all, such as a pipe.
+    std::array<char, 12> header{};
+    input.read(header.data(), static_cast<std::streamsize>(header.size()));
+    const auto header_read = static_cast<size_t>(input.gcount());
+    input.clear();
+
+    if (header_read < 12 || std::memcmp(header.data(), "RIFF", 4) != 0 ||
+        std::memcmp(header.data() + 8, "WAVE", 4) != 0) {
+        if (const char * container = identify_foreign_container(header)) {
+            throw std::runtime_error(
+                std::string("input is ") + container +
+                ", not WAV; convert it first, e.g. "
+                "`ffmpeg -i input -ac 1 -ar 44100 -c:a pcm_s16le output.wav`");
+        }
         throw std::runtime_error("invalid WAV RIFF header");
     }
-    skip_bytes(input, 4);
-    char wave[4];
-    input.read(wave, 4);
-    if (!input || std::string(wave, 4) != "WAVE") {
-        throw std::runtime_error("invalid WAV WAVE header");
-    }
 
     uint16_t audio_format = 0;
     uint16_t channels = 0;
@@ -97,13 +203,54 @@ WavData read_wav_f32(std::istream & input) {
         const uint32_t chunk_size = read_scalar<uint32_t>(input);
         const std::string id(chunk_id, 4);
         if (id == "fmt ") {
+            if (chunk_size < 16) {
+                throw std::runtime_error(
+                    "malformed WAV fmt chunk (needs 16 bytes, got " +
+                    std::to_string(chunk_size) + ")");
+            }
             audio_format = read_scalar<uint16_t>(input);
             channels = read_scalar<uint16_t>(input);
             sample_rate = read_scalar<uint32_t>(input);
             skip_bytes(input, 6);
             bits_per_sample = read_scalar<uint16_t>(input);
-            if (chunk_size > 16) {
-                skip_bytes(input, static_cast<std::streamoff>(chunk_size - 16));
+            std::streamoff consumed = 16;
+            if (audio_format == kFormatExtensible) {
+                if (chunk_size < 40) {
+                    throw std::runtime_error(
+                        "malformed WAVEFORMATEXTENSIBLE fmt chunk (needs 40 bytes, got " +
+                        std::to_string(chunk_size) + ")");
+                }
+                const uint16_t cb_size = read_scalar<uint16_t>(input);
+                if (cb_size < 22) {
+                    throw std::runtime_error(
+                        "malformed WAVEFORMATEXTENSIBLE fmt chunk (cbSize " +
+                        std::to_string(cb_size) + ", needs at least 22)");
+                }
+                skip_bytes(input, 2);   // wValidBitsPerSample
+                skip_bytes(input, 4);   // dwChannelMask
+                // Only the first two bytes of the SubFormat GUID carry the real
+                // format tag. The remaining fourteen are a fixed suffix shared by
+                // every KSDATAFORMAT_SUBTYPE_*; checking them is what separates a
+                // genuine format tag from an unrelated codec whose GUID merely
+                // happens to start with the same two bytes.
+                const uint16_t sub_format = read_scalar<uint16_t>(input);
+                std::array<char, 14> guid_tail{};
+                input.read(guid_tail.data(), static_cast<std::streamsize>(guid_tail.size()));
+                if (!input) {
+                    throw std::runtime_error("truncated WAVEFORMATEXTENSIBLE SubFormat GUID");
+                }
+                if (std::memcmp(guid_tail.data(), kKsDataFormatSubtypeTail.data(),
+                                kKsDataFormatSubtypeTail.size()) != 0) {
+                    throw std::runtime_error(
+                        "unsupported WAV encoding (extensible SubFormat is not a "
+                        "KSDATAFORMAT_SUBTYPE_* GUID); convert with "
+                        "`ffmpeg -i input -ac 1 -ar 44100 -c:a pcm_s16le output.wav`");
+                }
+                audio_format = sub_format;
+                consumed = 40;
+            }
+            if (chunk_size > consumed) {
+                skip_bytes(input, static_cast<std::streamoff>(chunk_size) - consumed);
             }
         } else if (id == "data") {
             // chunk_size is a 32-bit field read straight from the file, so a
@@ -131,7 +278,16 @@ WavData read_wav_f32(std::istream & input) {
             skip_bytes(input, chunk_size);
         }
         if (chunk_size % 2 == 1) {
-            skip_bytes(input, 1);
+            // RIFF pads an odd-sized chunk to an even boundary, but plenty of
+            // writers omit that byte when the chunk is the last thing in the
+            // file. It carries no data, so a missing one at EOF is not an error.
+            // This matters more than it used to: PCM8, A-law and mu-law are one
+            // byte per sample, so odd data chunks are now common.
+            input.seekg(1, std::ios::cur);
+            if (!input) {
+                input.clear();
+                break;
+            }
         }
     }
 
@@ -143,6 +299,60 @@ WavData read_wav_f32(std::istream & input) {
     wav.sample_rate = static_cast<int>(sample_rate);
     wav.channels = static_cast<int>(channels);
 
+    if (audio_format == kFormatPcm && bits_per_sample == 8) {
+        // 8-bit PCM in WAV is unsigned, offset by 128.
+        wav.samples.resize(data.size());
+        const auto * pcm = reinterpret_cast<const uint8_t *>(data.data());
+        for (size_t i = 0; i < data.size(); ++i) {
+            wav.samples[i] = (static_cast<float>(pcm[i]) - 128.0F) / 128.0F;
+        }
+        return wav;
+    }
+
+    if (audio_format == kFormatMuLaw && bits_per_sample == 8) {
+        wav.samples.resize(data.size());
+        const auto * pcm = reinterpret_cast<const uint8_t *>(data.data());
+        for (size_t i = 0; i < data.size(); ++i) {
+            wav.samples[i] = decode_mu_law(pcm[i]);
+        }
+        return wav;
+    }
+
+    if (audio_format == kFormatALaw && bits_per_sample == 8) {
+        wav.samples.resize(data.size());
+        const auto * pcm = reinterpret_cast<const uint8_t *>(data.data());
+        for (size_t i = 0; i < data.size(); ++i) {
+            wav.samples[i] = decode_a_law(pcm[i]);
+        }
+        return wav;
+    }
+
+    if (audio_format == kFormatPcm && bits_per_sample == 32) {
+        if (data.size() % sizeof(int32_t) != 0) {
+            throw std::runtime_error("malformed PCM32 WAV data chunk");
+        }
+        const size_t sample_count = data.size() / sizeof(int32_t);
+        wav.samples.resize(sample_count);
+        const auto * pcm = reinterpret_cast<const int32_t *>(data.data());
+        for (size_t i = 0; i < sample_count; ++i) {
+            wav.samples[i] = static_cast<float>(pcm[i]) / 2147483648.0F;
+        }
+        return wav;
+    }
+
+    if (audio_format == kFormatFloat && bits_per_sample == 64) {
+        if (data.size() % sizeof(double) != 0) {
+            throw std::runtime_error("malformed float64 WAV data chunk");
+        }
+        const size_t sample_count = data.size() / sizeof(double);
+        wav.samples.resize(sample_count);
+        const auto * pcm = reinterpret_cast<const double *>(data.data());
+        for (size_t i = 0; i < sample_count; ++i) {
+            wav.samples[i] = static_cast<float>(pcm[i]);
+        }
+        return wav;
+    }
+
     if (audio_format == 1 && bits_per_sample == 16) {
         const size_t sample_count = data.size() / sizeof(int16_t);
         wav.samples.resize(sample_count);
@@ -184,7 +394,10 @@ WavData read_wav_f32(std::istream & input) {
         return wav;
     }
 
-    throw std::runtime_error("unsupported WAV encoding (need PCM16, PCM24, or float32)");
+    throw std::runtime_error(
+        "unsupported WAV encoding (" + describe_encoding(audio_format, bits_per_sample) +
+        "); supported: PCM 8/16/24/32-bit, float 32/64-bit, A-law and mu-law. "
+        "Convert with `ffmpeg -i input -ac 1 -ar 44100 -c:a pcm_s16le output.wav`");
 }
 
 WavData read_wav_f32(std::string_view input) {