Fix all remaining audio codec tests (84/84 passing)

Audio encoder improvements:
- FLAC: Generate proper fLaC header with STREAMINFO metadata block
- MP3: Auto-downmix to stereo when >2 channels (MP3 only supports mono/stereo)
- Vorbis: Explicit FLTP sample format handling
- Timestamps: Clamp negative timestamps to 0
- Better error messages: Include codec params in failure messages

Author: caseymanos

.beads/issues.jsonl

@@ -4,7 +4,7 @@
 {"id":"webcodecs-node-4ub","title":"Create troubleshooting/overview.mdx","description":"Troubleshooting hub with common errors, installation issues, memory leaks, performance tips","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-03T23:41:02.251818-06:00","updated_at":"2025-12-03T23:41:02.251818-06:00"}
 {"id":"webcodecs-node-4xx","title":"Create cookbook/thumbnails.mdx","description":"Recipe: Extract video thumbnails at specific timestamps","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-03T23:40:47.448285-06:00","updated_at":"2025-12-03T23:40:47.448285-06:00"}
 {"id":"webcodecs-node-57b","title":"Create examples/alpha-video.mdx","description":"Alpha channel video encoding example with VP8/VP9","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-03T23:40:54.924694-06:00","updated_at":"2025-12-03T23:40:54.924694-06:00"}
-{"id":"webcodecs-node-6qw","title":"Set up Mintlify documentation structure","description":"Initialize Mintlify docs in the webcodecs-node repo:\n- Create docs/ directory with mint.json\n- Set up navigation structure  \n- Configure theme colors (#00ffc8)\n- Create initial page structure","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T21:49:58.259928-06:00","updated_at":"2025-12-03T21:59:29.979253-06:00","closed_at":"2025-12-03T21:59:29.979509-06:00","dependencies":[{"issue_id":"webcodecs-node-6qw","depends_on_id":"webcodecs-node-nhw","type":"blocks","created_at":"2025-12-03T21:49:58.260839-06:00","created_by":"daemon"}]}
+{"id":"webcodecs-node-6qw","title":"Set up Mintlify documentation structure","description":"Initialize Mintlify docs in the webcodecs-node repo:\n- Create docs/ directory with mint.json\n- Set up navigation structure  \n- Configure theme colors (#00ffc8)\n- Create initial page structure","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T21:49:58.259928-06:00","updated_at":"2025-12-03T21:59:29.979253-06:00","closed_at":"2025-12-03T21:59:29.979509-06:00","dependencies":[{"issue_id":"webcodecs-node-6qw","depends_on_id":"webcodecs-node-nhw","type":"blocks","created_at":"2025-12-03T21:49:58.260839-06:00","created_by":"daemon","metadata":"{}"}]}
 {"id":"webcodecs-node-b6h","title":"Create cookbook/webrtc-recording.mdx","description":"Recipe: Record and composite WebRTC streams with re-encoding","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-03T23:40:47.484861-06:00","updated_at":"2025-12-03T23:40:47.484861-06:00"}
 {"id":"webcodecs-node-br4","title":"Create examples/basic-encoding.mdx","description":"Basic video encoding example with expected output (console, file size, visual)","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-03T23:40:54.843712-06:00","updated_at":"2025-12-03T23:40:54.843712-06:00"}
 {"id":"webcodecs-node-e3l","title":"Create cookbook/watermark.mdx","description":"Recipe: Add watermark overlay to videos using node-canvas","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-03T23:40:47.40937-06:00","updated_at":"2025-12-03T23:40:47.40937-06:00"}

native/audio.cpp

@@ -1,5 +1,6 @@
 #include "audio.h"
 #include <cstring>
+#include <vector>
 
 // ==================== AudioDataNative ====================
 
@@ -523,6 +524,12 @@ void AudioEncoderNative::Configure(const Napi::CallbackInfo& info) {
         codecCtx_->sample_fmt = AV_SAMPLE_FMT_S16;  // FLAC uses s16
     } else if (codecName == "libmp3lame") {
         codecCtx_->sample_fmt = AV_SAMPLE_FMT_FLTP; // MP3 uses float planar
+        // MP3 only supports mono or stereo - limit channels if needed
+        if (channels_ > 2) {
+            channels_ = 2;  // Downmix to stereo
+        }
+    } else if (codecName == "libvorbis") {
+        codecCtx_->sample_fmt = AV_SAMPLE_FMT_FLTP; // Vorbis uses float planar
     } else {
         // AAC and most others use float planar
         codecCtx_->sample_fmt = AV_SAMPLE_FMT_FLTP;
@@ -543,8 +550,11 @@ void AudioEncoderNative::Configure(const Napi::CallbackInfo& info) {
     if (ret < 0) {
         char errBuf[256];
         av_strerror(ret, errBuf, sizeof(errBuf));
+        std::string errMsg = std::string("Failed to open codec: ") + errBuf +
+            " (codec=" + codecName + ", sampleRate=" + std::to_string(sampleRate_) +
+            ", channels=" + std::to_string(channels_) + ", bitrate=" + std::to_string(codecCtx_->bit_rate) + ")";
         avcodec_free_context(&codecCtx_);
-        Napi::Error::New(env, std::string("Failed to open codec: ") + errBuf).ThrowAsJavaScriptException();
+        Napi::Error::New(env, errMsg).ThrowAsJavaScriptException();
         return;
     }
 
@@ -651,7 +661,35 @@ void AudioEncoderNative::EmitChunk(Napi::Env env, AVPacket* packet) {
 
     Napi::Value extradataValue = env.Undefined();
     if (codecCtx_->extradata && codecCtx_->extradata_size > 0) {
-        extradataValue = Napi::Buffer<uint8_t>::Copy(env, codecCtx_->extradata, codecCtx_->extradata_size);
+        // For FLAC, we need to wrap the STREAMINFO with "fLaC" header
+        // FLAC stream format: "fLaC" + metadata block header + STREAMINFO
+        if (codec_->id == AV_CODEC_ID_FLAC) {
+            // Build proper FLAC header: "fLaC" (4) + block header (4) + STREAMINFO (34)
+            size_t fullSize = 4 + 4 + codecCtx_->extradata_size;
+            std::vector<uint8_t> flacHeader(fullSize);
+
+            // "fLaC" stream marker
+            flacHeader[0] = 'f';
+            flacHeader[1] = 'L';
+            flacHeader[2] = 'a';
+            flacHeader[3] = 'C';
+
+            // Metadata block header: last-flag (1 bit) + type (7 bits) + size (24 bits)
+            // 0x80 = last block flag, 0x00 = STREAMINFO type
+            // Combined: 0x80 for "last STREAMINFO block"
+            flacHeader[4] = 0x80;  // Last block flag + STREAMINFO type (0)
+            // Size in big-endian (3 bytes): typically 34 for STREAMINFO
+            flacHeader[5] = (codecCtx_->extradata_size >> 16) & 0xFF;
+            flacHeader[6] = (codecCtx_->extradata_size >> 8) & 0xFF;
+            flacHeader[7] = codecCtx_->extradata_size & 0xFF;
+
+            // Copy STREAMINFO data
+            memcpy(flacHeader.data() + 8, codecCtx_->extradata, codecCtx_->extradata_size);
+
+            extradataValue = Napi::Buffer<uint8_t>::Copy(env, flacHeader.data(), fullSize);
+        } else {
+            extradataValue = Napi::Buffer<uint8_t>::Copy(env, codecCtx_->extradata, codecCtx_->extradata_size);
+        }
     }
 
     // WebCodecs spec: output timestamps should match input timestamps (in microseconds).
@@ -664,6 +702,10 @@ void AudioEncoderNative::EmitChunk(Napi::Env env, AVPacket* packet) {
         int64_t paddingUs = (int64_t)codecCtx_->initial_padding * 1000000 / codecCtx_->sample_rate;
         timestampUs += paddingUs;
     }
+    // Ensure timestamps are never negative (can happen with some codecs)
+    if (timestampUs < 0) {
+        timestampUs = 0;
+    }
 
     outputCallback_.Value().Call({
         buffer,