@pproenca/node-webcodecs 0.1.0 → 0.1.1-alpha.5

package/src/async_encode_worker.cc

@@ -5,50 +5,79 @@
 
 #include "src/async_encode_worker.h"
 
+#include <chrono>
+#include <cstdio>
+#include <memory>
 #include <string>
 #include <utility>
 #include <vector>
 
+#include "src/common.h"
 #include "src/encoded_video_chunk.h"
 #include "src/video_encoder.h"
 
-AsyncEncodeWorker::AsyncEncodeWorker(VideoEncoder* encoder,
+namespace {
+
+// Compute temporal layer ID based on frame position and layer count.
+// Uses standard WebRTC temporal layering pattern.
+// Note: Duplicated from video_encoder.cc to avoid exposing in header.
+int ComputeTemporalLayerId(int64_t frame_index, int temporal_layer_count) {
+  if (temporal_layer_count <= 1) return 0;
+
+  if (temporal_layer_count == 2) {
+    // L1T2: alternating pattern [0, 1, 0, 1, ...]
+    return (frame_index % 2 == 0) ? 0 : 1;
+  }
+
+  // L1T3: pyramid pattern [0, 2, 1, 2, 0, 2, 1, 2, ...]
+  int pos = frame_index % 4;
+  if (pos == 0) return 0;  // Base layer
+  if (pos == 2) return 1;  // Middle layer
+  return 2;                // Enhancement layer (pos 1, 3)
+}
+
+}  // namespace
+
+AsyncEncodeWorker::AsyncEncodeWorker(VideoEncoder* /* encoder */,
                                      Napi::ThreadSafeFunction output_tsfn,
                                      Napi::ThreadSafeFunction error_tsfn)
-    : encoder_(encoder),
-      output_tsfn_(output_tsfn),
+    : output_tsfn_(output_tsfn),
       error_tsfn_(error_tsfn),
       codec_context_(nullptr),
       sws_context_(nullptr) {}
 
 void AsyncEncodeWorker::SetCodecContext(AVCodecContext* ctx, SwsContext* sws,
                                         int width, int height) {
+  std::lock_guard<std::mutex> lock(codec_mutex_);
   codec_context_ = ctx;
   sws_context_ = sws;
   width_ = width;
   height_ = height;
-  frame_ = av_frame_alloc();
+  frame_ = ffmpeg::make_frame();
   if (frame_) {
     frame_->format = AV_PIX_FMT_YUV420P;
     frame_->width = width;
     frame_->height = height;
-    av_frame_get_buffer(frame_, 32);
+    int ret = av_frame_get_buffer(frame_.get(), 32);
+    if (ret < 0) {
+      frame_.reset();  // Clear on allocation failure
+    }
   }
-  packet_ = av_packet_alloc();
+  packet_ = ffmpeg::make_packet();
+
+  // DARWIN-X64 FIX: Mark codec as valid only after successful initialization.
+  // ProcessFrame checks this flag to avoid accessing codec during shutdown.
+  codec_valid_.store(true, std::memory_order_release);
 }
 
 void AsyncEncodeWorker::SetMetadataConfig(const EncoderMetadataConfig& config) {
+  std::lock_guard<std::mutex> lock(codec_mutex_);
   metadata_config_ = config;
 }
 
 AsyncEncodeWorker::~AsyncEncodeWorker() {
   Stop();
-  if (frame_) {
-    av_frame_free(&frame_);
-  }
-  if (packet_) {
-    av_packet_free(&packet_);
-  }
+  // frame_ and packet_ are RAII-managed, automatically cleaned up
 }
 
 void AsyncEncodeWorker::Start() {
@@ -59,9 +88,26 @@ void AsyncEncodeWorker::Start() {
 }
 
 void AsyncEncodeWorker::Stop() {
+  // DARWIN-X64 FIX: Use stop_mutex_ to prevent double-stop race.
+  // Cleanup() and destructor may both call Stop().
+  std::lock_guard<std::mutex> stop_lock(stop_mutex_);
+
   if (!running_.load()) return;
 
-  running_.store(false);
+  // DARWIN-X64 FIX: Invalidate codec FIRST, before signaling shutdown.
+  // This prevents ProcessFrame from accessing codec_context_ during the
+  // race window between setting running_=false and the worker thread exiting.
+  codec_valid_.store(false, std::memory_order_release);
+
+  {
+    // CRITICAL: Hold mutex while modifying condition predicate to prevent
+    // lost wakeup race on x86_64. Without mutex, there's a window where:
+    // 1. Worker checks predicate (running_==true), starts entering wait()
+    // 2. Main thread sets running_=false, calls notify_all()
+    // 3. Worker enters wait() after notification - blocked forever
+    std::lock_guard<std::mutex> lock(queue_mutex_);
+    running_.store(false, std::memory_order_release);
+  }
   queue_cv_.notify_all();
 
   if (worker_thread_.joinable()) {
@@ -89,11 +135,13 @@ void AsyncEncodeWorker::Flush() {
 
   flushing_.store(true);
 
-  // Wait for queue to drain (including flush task)
+  // Wait for queue to drain AND all in-flight processing to complete
   {
     std::unique_lock<std::mutex> lock(queue_mutex_);
-    queue_cv_.wait(lock,
-                   [this] { return task_queue_.empty() || !running_.load(); });
+    queue_cv_.wait(lock, [this] {
+      return (task_queue_.empty() && processing_.load() == 0) ||
+             !running_.load();
+    });
   }
 
   flushing_.store(false);
@@ -124,29 +172,49 @@ void AsyncEncodeWorker::WorkerThread() {
 
       task = std::move(task_queue_.front());
       task_queue_.pop();
+      processing_++;  // Track that we're processing this task
     }
 
     ProcessFrame(task);
 
-    if (task_queue_.empty()) {
-      queue_cv_.notify_all();
+    // Decrement counter and notify under lock (fixes race condition).
+    {
+      std::lock_guard<std::mutex> lock(queue_mutex_);
+      processing_--;
+      if (task_queue_.empty() && processing_.load() == 0) {
+        queue_cv_.notify_all();
+      }
     }
   }
 }
 
 void AsyncEncodeWorker::ProcessFrame(const EncodeTask& task) {
+  // DARWIN-X64 FIX: Check codec_valid_ BEFORE acquiring mutex.
+  // During shutdown, Stop() sets codec_valid_=false before running_=false.
+  // This creates a window where the worker thread could still be running
+  // but the codec is being destroyed. Early exit prevents the race.
+  if (!codec_valid_.load(std::memory_order_acquire)) {
+    return;
+  }
+
+  std::lock_guard<std::mutex> lock(codec_mutex_);
   if (!codec_context_ || !sws_context_ || !frame_ || !packet_) {
     return;
   }
 
-  // Handle flush task - send NULL frame to drain encoder
+  // Handle flush task - send NULL frame to drain encoder.
+  // Note: After this, the codec enters EOF mode and won't accept new frames.
+  // The VideoEncoder::Flush() method handles codec reinitialization after
+  // the worker drains to allow continued encoding per W3C WebCodecs spec.
   if (task.is_flush) {
     avcodec_send_frame(codec_context_, nullptr);
     // Drain all remaining packets
-    while (avcodec_receive_packet(codec_context_, packet_) == 0) {
-      EmitChunk(packet_);
-      av_packet_unref(packet_);
+    while (avcodec_receive_packet(codec_context_, packet_.get()) == 0) {
+      EmitChunk(packet_.get());
+      av_packet_unref(packet_.get());
     }
+    // Clear frame info map after flush
+    frame_info_.clear();
     return;
   }
 
@@ -157,7 +225,11 @@ void AsyncEncodeWorker::ProcessFrame(const EncodeTask& task) {
   sws_scale(sws_context_, src_data, src_linesize, 0, height_, frame_->data,
             frame_->linesize);
 
-  frame_->pts = task.timestamp;
+  // Use frame_index as pts for consistent SVC layer computation
+  // Store original timestamp/duration for lookup when emitting packets
+  frame_->pts = task.frame_index;
+  frame_info_[task.frame_index] =
+      std::make_pair(task.timestamp, task.duration);
 
   // Apply per-frame quantizer if specified (matches sync path)
   if (task.quantizer >= 0) {
@@ -166,21 +238,26 @@ void AsyncEncodeWorker::ProcessFrame(const EncodeTask& task) {
     frame_->quality = 0;  // Let encoder decide
   }
 
-  int ret = avcodec_send_frame(codec_context_, frame_);
+  int ret = avcodec_send_frame(codec_context_, frame_.get());
   if (ret < 0 && ret != AVERROR(EAGAIN)) {
     std::string error_msg = "Encode error: " + std::to_string(ret);
     error_tsfn_.NonBlockingCall(
         new std::string(error_msg),
         [](Napi::Env env, Napi::Function fn, std::string* msg) {
+          // If env is null, TSFN is closing during teardown. Just cleanup.
+          if (env == nullptr) {
+            delete msg;
+            return;
+          }
           fn.Call({Napi::Error::New(env, *msg).Value()});
           delete msg;
         });
     return;
   }
 
-  while (avcodec_receive_packet(codec_context_, packet_) == 0) {
-    EmitChunk(packet_);
-    av_packet_unref(packet_);
+  while (avcodec_receive_packet(codec_context_, packet_.get()) == 0) {
+    EmitChunk(packet_.get());
+    av_packet_unref(packet_.get());
   }
 }
 
@@ -190,21 +267,38 @@ struct ChunkCallbackData {
   int64_t pts;
   int64_t duration;
   bool is_key;
+  int64_t frame_index;  // For SVC layer computation
   EncoderMetadataConfig metadata;
   std::vector<uint8_t> extradata;  // Copy from codec_context at emit time
-  std::atomic<int>* pending;
+  // Use shared_ptr to pending counter so it remains valid even if worker is
+  // destroyed before callback executes on main thread.
+  std::shared_ptr<std::atomic<int>> pending;
 };
 
 void AsyncEncodeWorker::EmitChunk(AVPacket* pkt) {
   // Increment pending count before async operation
-  pending_chunks_.fetch_add(1);
+  pending_chunks_->fetch_add(1);
+
+  // pkt->pts is the frame_index (set in ProcessFrame)
+  int64_t frame_index = pkt->pts;
+
+  // Look up original timestamp/duration from the map
+  int64_t timestamp = 0;
+  int64_t duration = 0;
+  auto it = frame_info_.find(frame_index);
+  if (it != frame_info_.end()) {
+    timestamp = it->second.first;
+    duration = it->second.second;
+    frame_info_.erase(it);  // Clean up after use
+  }
 
   // Create callback data with all info needed on main thread
   auto* cb_data = new ChunkCallbackData();
   cb_data->data.assign(pkt->data, pkt->data + pkt->size);
-  cb_data->pts = pkt->pts;
-  cb_data->duration = pkt->duration;
+  cb_data->pts = timestamp;  // Use original timestamp, not frame_index
+  cb_data->duration = duration;
   cb_data->is_key = (pkt->flags & AV_PKT_FLAG_KEY) != 0;
+  cb_data->frame_index = frame_index;  // For SVC layer computation
   cb_data->metadata = metadata_config_;
   // Copy extradata from codec_context at emit time (may be set after configure)
   if (codec_context_ && codec_context_->extradata &&
@@ -213,25 +307,42 @@ void AsyncEncodeWorker::EmitChunk(AVPacket* pkt) {
         codec_context_->extradata,
         codec_context_->extradata + codec_context_->extradata_size);
   }
-  cb_data->pending = &pending_chunks_;
+  cb_data->pending = pending_chunks_;
 
   output_tsfn_.NonBlockingCall(cb_data, [](Napi::Env env, Napi::Function fn,
                                            ChunkCallbackData* info) {
-    // Create EncodedVideoChunk-like object (matches synchronous path)
-    Napi::Object chunk = Napi::Object::New(env);
-    chunk.Set("type", info->is_key ? "key" : "delta");
-    chunk.Set("timestamp", Napi::Number::New(env, info->pts));
-    chunk.Set("duration", Napi::Number::New(env, info->duration));
-    chunk.Set("data", Napi::Buffer<uint8_t>::Copy(env, info->data.data(),
-                                                  info->data.size()));
+    // CRITICAL: If env is null, the TSFN is being destroyed (environment teardown).
+    // Must still clean up data and counters, then return to avoid crashing.
+    // NOTE: Do NOT access static variables (like counterQueue) here - they may
+    // already be destroyed due to static destruction order during process exit.
+    if (env == nullptr) {
+      info->pending->fetch_sub(1);
+      // Skip counterQueue-- : static may be destroyed during process exit
+      delete info;
+      return;
+    }
+
+    // Decrement pending count before any operations
+    info->pending->fetch_sub(1);
+    webcodecs::counterQueue--;
+
+    // Create native EncodedVideoChunk directly to avoid double-copy.
+    // The data is copied once into the chunk's internal buffer.
+    // Previously we created a plain JS object here, which the TS layer
+    // would wrap in a new EncodedVideoChunk, causing a second copy.
+    Napi::Object chunk = EncodedVideoChunk::CreateInstance(
+        env, info->is_key ? "key" : "delta", info->pts, info->duration,
+        info->data.data(), info->data.size());
 
     // Create metadata object matching sync path
     Napi::Object metadata = Napi::Object::New(env);
 
-    // TODO(pproenca): Implement actual temporal/spatial layer tracking.
-    // See video_encoder.cc for related TODO. For now, always report layer 0.
+    // Add SVC metadata per W3C spec.
+    // Compute temporal layer ID based on frame_index and scalabilityMode.
     Napi::Object svc = Napi::Object::New(env);
-    svc.Set("temporalLayerId", Napi::Number::New(env, 0));
+    int temporal_layer = ComputeTemporalLayerId(
+        info->frame_index, info->metadata.temporal_layer_count);
+    svc.Set("temporalLayerId", Napi::Number::New(env, temporal_layer));
     metadata.Set("svc", svc);
 
     // Add decoderConfig for keyframes per W3C spec
@@ -277,8 +388,8 @@ void AsyncEncodeWorker::EmitChunk(AVPacket* pkt) {
 
     fn.Call({chunk, metadata});
 
-    // Decrement pending count after callback completes
-    info->pending->fetch_sub(1);
+    // ChunkCallbackData is no longer tied to the buffer lifetime.
+    // Delete it now that the data has been copied into the EncodedVideoChunk.
     delete info;
   });
 }

package/src/async_encode_worker.h

@@ -12,27 +12,33 @@ extern "C" {
 #include <libswscale/swscale.h>
 }
 
+#include "src/ffmpeg_raii.h"
+
 #include <napi.h>
 
 #include <atomic>
 #include <condition_variable>
+#include <map>
+#include <memory>
 #include <mutex>
 #include <queue>
 #include <string>
 #include <thread>
+#include <utility>
 #include <vector>
 
 class VideoEncoder;
 
 struct EncodeTask {
   std::vector<uint8_t> rgba_data;
-  uint32_t width;
-  uint32_t height;
-  int64_t timestamp;
-  int64_t duration;
-  bool key_frame;
-  bool is_flush = false;  // When true, flush the encoder instead of encoding
-  int quantizer = -1;     // -1 means not specified, otherwise 0-63 range
+  uint32_t width = 0;
+  uint32_t height = 0;
+  int64_t timestamp = 0;
+  int64_t duration = 0;
+  bool key_frame = false;
+  bool is_flush = false;    // When true, flush the encoder instead of encoding
+  int quantizer = -1;       // -1 means not specified, otherwise 0-63 range
+  int64_t frame_index = 0;  // Sequential frame index for SVC layer computation
 };
 
 struct EncodedChunk {
@@ -53,6 +59,7 @@ struct EncoderMetadataConfig {
   std::string color_transfer;
   std::string color_matrix;
   bool color_full_range = false;
+  int temporal_layer_count = 1;  // From scalabilityMode (L1T1=1, L1T2=2, L1T3=3)
   // Note: extradata is copied from codec_context at emit time (may be set after
   // configure)
 };
@@ -74,7 +81,11 @@ class AsyncEncodeWorker {
   void Flush();
   bool IsRunning() const { return running_.load(); }
   size_t QueueSize() const;
-  int GetPendingChunks() const { return pending_chunks_.load(); }
+  int GetPendingChunks() const { return pending_chunks_->load(); }
+  // Get shared pending counter for TSFN callbacks to capture
+  std::shared_ptr<std::atomic<int>> GetPendingChunksPtr() const {
+    return pending_chunks_;
+  }
   void SetCodecContext(AVCodecContext* ctx, SwsContext* sws, int width,
                        int height);
   void SetMetadataConfig(const EncoderMetadataConfig& config);
@@ -84,28 +95,43 @@ class AsyncEncodeWorker {
   void ProcessFrame(const EncodeTask& task);
   void EmitChunk(AVPacket* packet);
 
-  VideoEncoder* encoder_;
   Napi::ThreadSafeFunction output_tsfn_;
   Napi::ThreadSafeFunction error_tsfn_;
 
   std::thread worker_thread_;
   std::queue<EncodeTask> task_queue_;
   mutable std::mutex queue_mutex_;  // mutable for const QueueSize()
+  std::mutex codec_mutex_;  // Protects codec_context_, sws_context_, frame_, packet_, metadata_config_
   std::condition_variable queue_cv_;
   std::atomic<bool> running_{false};
   std::atomic<bool> flushing_{false};
-  std::atomic<int> pending_chunks_{0};
+  std::atomic<int> processing_{0};  // Track tasks currently being processed
+  // DARWIN-X64 FIX: Guard against codec access during shutdown race window.
+  // Set to true after SetCodecContext, false at START of Stop().
+  // ProcessFrame checks this before accessing codec_context_.
+  std::atomic<bool> codec_valid_{false};
+  // Mutex to synchronize Stop() calls from Cleanup() and destructor
+  std::mutex stop_mutex_;
+  // Use shared_ptr for pending counter so TSFN callbacks can safely access it
+  // even after the worker object is destroyed. The shared_ptr is captured by
+  // the callback lambda, ensuring the atomic counter remains valid.
+  std::shared_ptr<std::atomic<int>> pending_chunks_ =
+      std::make_shared<std::atomic<int>>(0);
 
   // FFmpeg contexts (owned by VideoEncoder, just references here)
   AVCodecContext* codec_context_;
   SwsContext* sws_context_;
-  AVFrame* frame_;
-  AVPacket* packet_;
+  ffmpeg::AVFramePtr frame_;       // RAII-managed, owned by this worker
+  ffmpeg::AVPacketPtr packet_;     // RAII-managed, owned by this worker
   int width_;
   int height_;
 
   // Encoder metadata for output chunks
   EncoderMetadataConfig metadata_config_;
+
+  // Map from frame_index (used as pts) to original timestamp/duration
+  // Needed because packets may come out in different order due to B-frames
+  std::map<int64_t, std::pair<int64_t, int64_t>> frame_info_;  // frame_index -> (timestamp, duration)
 };
 
 #endif  // SRC_ASYNC_ENCODE_WORKER_H_

package/src/audio_data.cc

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "src/common.h"
+#include "src/ffmpeg_raii.h"
 
 extern "C" {
 #include <libavutil/channel_layout.h>
@@ -98,6 +99,7 @@ AudioData::AudioData(const Napi::CallbackInfo& info)
       number_of_channels_(0),
       timestamp_(0),
       closed_(false) {
+  webcodecs::counterAudioData++;
   Napi::Env env = info.Env();
 
   if (info.Length() < 1 || !info[0].IsObject()) {
@@ -197,6 +199,26 @@ AudioData::AudioData(const Napi::CallbackInfo& info)
         .ThrowAsJavaScriptException();
     return;
   }
+
+  // Inform V8 of external memory allocation for GC pressure calculation.
+  Napi::MemoryManagement::AdjustExternalMemory(
+      env, static_cast<int64_t>(data_.size()));
+}
+
+AudioData::~AudioData() {
+  webcodecs::counterAudioData--;
+  // Note: We intentionally DO NOT call AdjustExternalMemory here.
+  //
+  // Calling NAPI functions (including AdjustExternalMemory) from destructors
+  // during V8 shutdown is unsafe and causes crashes on Node.js 24+ due to
+  // race conditions with V8's ArrayBufferSweeper during Heap::TearDown().
+  // See: https://github.com/nodejs/node-addon-api/issues/1153
+  //
+  // The WebCodecs spec mandates that close() must be called for proper
+  // resource management. External memory tracking is handled exclusively
+  // in Close() to avoid shutdown crashes.
+  data_.clear();
+  data_.shrink_to_fit();
 }
 
 size_t AudioData::GetBytesPerSample() const {
@@ -503,8 +525,8 @@ void AudioData::CopyTo(const Napi::CallbackInfo& info) {
     return;
   }
 
-  // Create resampler context.
-  SwrContext* swr = swr_alloc();
+  // Create resampler context (RAII managed).
+  ffmpeg::SwrContextPtr swr(swr_alloc());
   if (!swr) {
     Napi::Error::New(env, "Failed to allocate SwrContext")
         .ThrowAsJavaScriptException();
@@ -517,18 +539,17 @@ void AudioData::CopyTo(const Napi::CallbackInfo& info) {
   av_channel_layout_default(&ch_layout, number_of_channels_);
 
   // Set input parameters.
-  av_opt_set_chlayout(swr, "in_chlayout", &ch_layout, 0);
-  av_opt_set_int(swr, "in_sample_rate", sample_rate_, 0);
-  av_opt_set_sample_fmt(swr, "in_sample_fmt", src_fmt, 0);
+  av_opt_set_chlayout(swr.get(), "in_chlayout", &ch_layout, 0);
+  av_opt_set_int(swr.get(), "in_sample_rate", sample_rate_, 0);
+  av_opt_set_sample_fmt(swr.get(), "in_sample_fmt", src_fmt, 0);
 
   // Set output parameters.
-  av_opt_set_chlayout(swr, "out_chlayout", &ch_layout, 0);
-  av_opt_set_int(swr, "out_sample_rate", sample_rate_, 0);
-  av_opt_set_sample_fmt(swr, "out_sample_fmt", dst_fmt, 0);
+  av_opt_set_chlayout(swr.get(), "out_chlayout", &ch_layout, 0);
+  av_opt_set_int(swr.get(), "out_sample_rate", sample_rate_, 0);
+  av_opt_set_sample_fmt(swr.get(), "out_sample_fmt", dst_fmt, 0);
 
-  int ret = swr_init(swr);
+  int ret = swr_init(swr.get());
   if (ret < 0) {
-    swr_free(&swr);
     av_channel_layout_uninit(&ch_layout);
     Napi::Error::New(env, "Failed to initialize SwrContext")
         .ThrowAsJavaScriptException();
@@ -566,9 +587,8 @@ void AudioData::CopyTo(const Napi::CallbackInfo& info) {
           temp_buffer.data() + c * frame_count * target_bytes_per_sample;
     }
 
-    ret = swr_convert(swr, dst_data, frame_count, src_data, frame_count);
+    ret = swr_convert(swr.get(), dst_data, frame_count, src_data, frame_count);
     if (ret < 0) {
-      swr_free(&swr);
       av_channel_layout_uninit(&ch_layout);
       Napi::Error::New(env, "swr_convert failed").ThrowAsJavaScriptException();
       return;
@@ -581,16 +601,15 @@ void AudioData::CopyTo(const Napi::CallbackInfo& info) {
     // Interleaved output: write directly to destination.
     dst_data[0] = dest_data;
 
-    ret = swr_convert(swr, dst_data, frame_count, src_data, frame_count);
+    ret = swr_convert(swr.get(), dst_data, frame_count, src_data, frame_count);
     if (ret < 0) {
-      swr_free(&swr);
       av_channel_layout_uninit(&ch_layout);
       Napi::Error::New(env, "swr_convert failed").ThrowAsJavaScriptException();
       return;
     }
   }
 
-  swr_free(&swr);
+  // RAII handles swr cleanup
   av_channel_layout_uninit(&ch_layout);
 }
 
@@ -610,6 +629,10 @@ Napi::Value AudioData::Clone(const Napi::CallbackInfo& info) {
 
 void AudioData::Close(const Napi::CallbackInfo& info) {
   if (!closed_) {
+    if (!data_.empty()) {
+      Napi::MemoryManagement::AdjustExternalMemory(
+          info.Env(), -static_cast<int64_t>(data_.size()));
+    }
     data_.clear();
     data_.shrink_to_fit();
     closed_ = true;

package/src/audio_data.h

@@ -20,6 +20,7 @@ class AudioData : public Napi::ObjectWrap<AudioData> {
                                      int64_t timestamp, const uint8_t* data,
                                      size_t data_size);
   explicit AudioData(const Napi::CallbackInfo& info);
+  ~AudioData();
 
   // Prevent copy and assignment.
   AudioData(const AudioData&) = delete;

package/src/audio_decoder.cc

@@ -50,6 +50,8 @@ AudioDecoder::AudioDecoder(const Napi::CallbackInfo& info)
       state_("unconfigured"),
       sample_rate_(0),
       number_of_channels_(0) {
+  // Track active decoder instance
+  webcodecs::counterAudioDecoders++;
   Napi::Env env = info.Env();
 
   if (info.Length() < 1 || !info[0].IsObject()) {
@@ -75,9 +77,29 @@ AudioDecoder::AudioDecoder(const Napi::CallbackInfo& info)
   error_callback_ = Napi::Persistent(init.Get("error").As<Napi::Function>());
 }
 
-AudioDecoder::~AudioDecoder() { Cleanup(); }
+AudioDecoder::~AudioDecoder() {
+  // CRITICAL: Call Cleanup() first to ensure codec context is properly
+  // flushed before any further cleanup.
+  Cleanup();
+
+  // Now safe to disable FFmpeg logging.
+  webcodecs::ShutdownFFmpegLogging();
+
+  webcodecs::counterAudioDecoders--;
+}
 
 void AudioDecoder::Cleanup() {
+  // DARWIN-X64 FIX: Flush codec internal buffers BEFORE destroying resources.
+  // Audio decoders may have internal queued frames. Flushing ensures they're
+  // drained before context destruction, preventing use-after-free.
+  // CRITICAL: Only flush if codec was successfully opened. avcodec_flush_buffers
+  // crashes on an unopened codec context (the internal codec pointer is NULL).
+  // NOTE: Order matters - flush must happen before resetting frame_/packet_/swr_
+  // to match VideoDecoder pattern and ensure codec internal state is consistent.
+  if (codec_context_ && avcodec_is_open(codec_context_.get())) {
+    avcodec_flush_buffers(codec_context_.get());
+  }
+
   frame_.reset();
   packet_.reset();
   swr_context_.reset();
@@ -236,9 +258,8 @@ void AudioDecoder::Close(const Napi::CallbackInfo& info) {
 Napi::Value AudioDecoder::Reset(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
+  // W3C spec: reset() is a no-op when closed (don't throw)
   if (state_ == "closed") {
-    Napi::Error::New(env, "InvalidStateError: Cannot reset closed decoder")
-        .ThrowAsJavaScriptException();
     return env.Undefined();
   }