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

package/src/async_decode_worker.h

@@ -12,22 +12,40 @@ extern "C" {
 #include <libswscale/swscale.h>
 }
 
+#include "src/ffmpeg_raii.h"
+
 #include <napi.h>
 
 #include <atomic>
 #include <condition_variable>
+#include <memory>
 #include <mutex>
 #include <queue>
+#include <string>
 #include <thread>
 #include <vector>
 
 class VideoDecoder;
 
+// Metadata config for decoded video frames (mirrors EncoderMetadataConfig pattern)
+struct DecoderMetadataConfig {
+  int rotation = 0;
+  bool flip = false;
+  int display_width = 0;
+  int display_height = 0;
+  std::string color_primaries;
+  std::string color_transfer;
+  std::string color_matrix;
+  bool color_full_range = false;
+  bool has_color_space = false;
+};
+
 struct DecodeTask {
   std::vector<uint8_t> data;
   int64_t timestamp;
   int64_t duration;
   bool is_key;
+  bool is_flush = false;  // When true, flush the decoder instead of decoding
 };
 
 struct DecodedFrame {
@@ -55,8 +73,14 @@ class AsyncDecodeWorker {
   void Flush();
   void SetCodecContext(AVCodecContext* ctx, SwsContext* sws, int width,
                        int height);
+  void SetMetadataConfig(const DecoderMetadataConfig& config);
   bool IsRunning() const { return running_.load(); }
   size_t QueueSize() const;
+  int GetPendingFrames() const { return pending_frames_->load(); }
+  // Get shared pending counter for TSFN callbacks to capture
+  std::shared_ptr<std::atomic<int>> GetPendingFramesPtr() const {
+    return pending_frames_;
+  }
 
  private:
   void WorkerThread();
@@ -70,16 +94,44 @@ class AsyncDecodeWorker {
   std::queue<DecodeTask> task_queue_;
   mutable std::mutex queue_mutex_;  // mutable for const QueueSize()
   std::condition_variable queue_cv_;
+  std::mutex codec_mutex_;  // Protects codec_context_, sws_context_, frame_, packet_, metadata_config_
   std::atomic<bool> running_{false};
   std::atomic<bool> flushing_{false};
+  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().
+  // ProcessPacket 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_frames_ =
+      std::make_shared<std::atomic<int>>(0);
 
   // FFmpeg contexts (owned by VideoDecoder, just references here)
   AVCodecContext* codec_context_;
-  SwsContext* sws_context_;
-  AVFrame* frame_;
-  AVPacket* packet_;
+  ffmpeg::SwsContextPtr sws_context_;  // RAII-managed, created lazily on first frame
+  ffmpeg::AVFramePtr frame_;           // RAII-managed, owned by this worker
+  ffmpeg::AVPacketPtr packet_;         // RAII-managed, owned by this worker
   int output_width_;
   int output_height_;
+
+  // Track last frame format/dimensions for sws_context recreation
+  AVPixelFormat last_frame_format_ = AV_PIX_FMT_NONE;
+  int last_frame_width_ = 0;
+  int last_frame_height_ = 0;
+
+  // Buffer pool for decoded frame data to reduce allocations
+  std::vector<std::vector<uint8_t>*> buffer_pool_;
+  std::mutex pool_mutex_;
+
+  // Decoder metadata for output frames
+  DecoderMetadataConfig metadata_config_;
+
+  std::vector<uint8_t>* AcquireBuffer(size_t size);
+  void ReleaseBuffer(std::vector<uint8_t>* buffer);
 };
 
 #endif  // SRC_ASYNC_DECODE_WORKER_H_

package/src/async_encode_worker.cc

@@ -5,10 +5,14 @@
 
 #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"
 
@@ -44,32 +48,36 @@ AsyncEncodeWorker::AsyncEncodeWorker(VideoEncoder* /* encoder */,
 
 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() {
@@ -80,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()) {
@@ -110,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);
@@ -145,28 +172,46 @@ 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();
@@ -193,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());
   }
 }
 
@@ -220,12 +270,14 @@ struct ChunkCallbackData {
   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;
@@ -237,6 +289,7 @@ void AsyncEncodeWorker::EmitChunk(AVPacket* pkt) {
   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
@@ -254,17 +307,32 @@ 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);
@@ -320,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,11 +12,14 @@ 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>
@@ -78,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);
@@ -94,16 +101,28 @@ class AsyncEncodeWorker {
   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_;
 

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();
   }