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

package/src/video_decoder.cc

@@ -3,13 +3,15 @@
 
 #include "src/video_decoder.h"
 
+#include <chrono>
 #include <cmath>
 #include <cstring>
 #include <memory>
 #include <string>
+#include <thread>
+#include <utility>
 #include <vector>
 
-#include "src/async_decode_worker.h"
 #include "src/common.h"
 #include "src/encoded_video_chunk.h"
 #include "src/video_frame.h"
@@ -39,6 +41,8 @@ Napi::Object VideoDecoder::Init(Napi::Env env, Napi::Object exports) {
                            nullptr),
           InstanceAccessor("codecSaturated", &VideoDecoder::GetCodecSaturated,
                            nullptr),
+          InstanceAccessor("pendingFrames", &VideoDecoder::GetPendingFrames,
+                           nullptr),
           StaticMethod("isConfigSupported", &VideoDecoder::IsConfigSupported),
       });
 
@@ -52,6 +56,9 @@ VideoDecoder::VideoDecoder(const Napi::CallbackInfo& info)
       state_("unconfigured"),
       coded_width_(0),
       coded_height_(0) {
+  // Track active decoder instance (following sharp pattern)
+  webcodecs::counterProcess++;
+  webcodecs::counterVideoDecoders++;
   Napi::Env env = info.Env();
 
   if (info.Length() < 1 || !info[0].IsObject()) {
@@ -74,22 +81,64 @@ VideoDecoder::VideoDecoder(const Napi::CallbackInfo& info)
   error_callback_ = Napi::Persistent(init.Get("error").As<Napi::Function>());
 }
 
-VideoDecoder::~VideoDecoder() { Cleanup(); }
+VideoDecoder::~VideoDecoder() {
+  // CRITICAL: Call Cleanup() first to stop the async worker thread and wait
+  // for pending TSFN callbacks. The worker may still be processing frames,
+  // and we must ensure it exits cleanly before any further cleanup.
+  Cleanup();
+
+  // Now safe to disable FFmpeg logging. The worker thread has exited and all
+  // pending callbacks have been processed or aborted.
+  webcodecs::ShutdownFFmpegLogging();
+
+  // Track active decoder instance (following sharp pattern)
+  webcodecs::counterProcess--;
+  webcodecs::counterVideoDecoders--;
+}
 
 void VideoDecoder::Cleanup() {
-  // Stop async worker first.
+  // Stop async worker before cleaning up codec context
   if (async_worker_) {
+    // Stop() joins the worker thread - after this, no new TSFN calls will be made
     async_worker_->Stop();
-    async_worker_.reset();
+
+    // DARWIN-X64 FIX: Wait for pending TSFN callbacks to complete.
+    // After Stop() joins the thread, there may still be queued TSFN callbacks
+    // that haven't been processed yet. These callbacks reference memory that
+    // will be freed below.
+    auto deadline =
+        std::chrono::steady_clock::now() + std::chrono::milliseconds(100);
+    while (async_worker_->GetPendingFrames() > 0 &&
+           std::chrono::steady_clock::now() < deadline) {
+      std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    }
   }
 
-  // Release ThreadSafeFunctions if they were created.
+  // DARWIN-X64 FIX: Release ThreadSafeFunctions to ensure proper cleanup.
+  // Release() signals no more calls will be made and decrements the reference
+  // count. Without explicit Release(), TSFN cleanup during environment teardown
+  // may race with other shutdown operations on Intel Mac (slower timing).
+  // The shared_ptr<atomic<int>> pending_frames_ captured by callbacks ensures
+  // thread-safety even if callbacks are cancelled mid-flight.
   if (async_mode_) {
     output_tsfn_.Release();
     error_tsfn_.Release();
+    async_mode_ = false;
   }
 
-  async_mode_ = false;
+  // Safe to destroy async_worker_ - worker thread has exited and TSFN aborted
+  if (async_worker_) {
+    async_worker_.reset();
+  }
+
+  // DARWIN-X64 FIX: Flush codec internal buffers before destruction.
+  // Some 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).
+  if (codec_context_ && avcodec_is_open(codec_context_.get())) {
+    avcodec_flush_buffers(codec_context_.get());
+  }
 
   frame_.reset();
   packet_.reset();
@@ -258,21 +307,41 @@ Napi::Value VideoDecoder::Configure(const Napi::CallbackInfo& info) {
     throw Napi::Error::New(env, "Could not allocate packet");
   }
 
-  // Create ThreadSafeFunctions for async worker.
-  output_tsfn_ = Napi::ThreadSafeFunction::New(env, output_callback_.Value(),
-                                               "VideoDecoder::output", 0, 1,
-                                               [](Napi::Env) {});
+  state_ = "configured";
 
+  // Enable async decoding via worker thread.
+  // Flush semantics use pendingFrames counter - TypeScript polls with
+  // setTimeout to wait for all TSFN callbacks to complete without blocking
+  // the event loop.
+  async_mode_ = true;
+
+  // Create ThreadSafeFunctions for async callbacks
+  output_tsfn_ = Napi::ThreadSafeFunction::New(env, output_callback_.Value(),
+                                               "VideoDecoderOutput", 0, 1);
   error_tsfn_ = Napi::ThreadSafeFunction::New(env, error_callback_.Value(),
-                                              "VideoDecoder::error", 0, 1,
-                                              [](Napi::Env) {});
+                                              "VideoDecoderError", 0, 1);
 
-  // Initialize async worker.
+  // Create and start the async worker
   async_worker_ =
       std::make_unique<AsyncDecodeWorker>(this, output_tsfn_, error_tsfn_);
-  async_mode_ = true;
-
-  state_ = "configured";
+  // Pass nullptr for sws_context - AsyncDecodeWorker creates it lazily
+  async_worker_->SetCodecContext(codec_context_.get(), nullptr, coded_width_,
+                                 coded_height_);
+
+  // Set metadata config for async output frames (matching encoder pattern)
+  DecoderMetadataConfig metadata_config;
+  metadata_config.rotation = rotation_;
+  metadata_config.flip = flip_;
+  metadata_config.display_width = display_aspect_width_;
+  metadata_config.display_height = display_aspect_height_;
+  metadata_config.color_primaries = color_primaries_;
+  metadata_config.color_transfer = color_transfer_;
+  metadata_config.color_matrix = color_matrix_;
+  metadata_config.color_full_range = color_full_range_;
+  metadata_config.has_color_space = has_color_space_;
+  async_worker_->SetMetadataConfig(metadata_config);
+
+  async_worker_->Start();
 
   return env.Undefined();
 }
@@ -289,6 +358,13 @@ Napi::Value VideoDecoder::GetCodecSaturated(const Napi::CallbackInfo& info) {
   return Napi::Boolean::New(info.Env(), codec_saturated_.load());
 }
 
+Napi::Value VideoDecoder::GetPendingFrames(const Napi::CallbackInfo& info) {
+  if (async_worker_) {
+    return Napi::Number::New(info.Env(), async_worker_->GetPendingFrames());
+  }
+  return Napi::Number::New(info.Env(), 0);
+}
+
 Napi::Value VideoDecoder::Decode(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -296,6 +372,22 @@ Napi::Value VideoDecoder::Decode(const Napi::CallbackInfo& info) {
     throw Napi::Error::New(env, "InvalidStateError: Decoder not configured");
   }
 
+  // Reject if queue is too large (prevents OOM).
+  if (async_mode_ && async_worker_) {
+    size_t queue = async_worker_->QueueSize() + async_worker_->GetPendingFrames();
+    if (queue >= kMaxHardQueueSize) {
+      throw Napi::Error::New(
+          env,
+          "QuotaExceededError: Decode queue is full. You must handle "
+          "backpressure by waiting for decodeQueueSize to decrease.");
+    }
+  } else if (decode_queue_size_ >= static_cast<int>(kMaxHardQueueSize)) {
+    throw Napi::Error::New(
+        env,
+        "QuotaExceededError: Decode queue is full. You must handle "
+        "backpressure by waiting for decodeQueueSize to decrease.");
+  }
+
   if (info.Length() < 1 || !info[0].IsObject()) {
     throw Napi::Error::New(env, "decode requires EncodedVideoChunk");
   }
@@ -308,8 +400,31 @@ Napi::Value VideoDecoder::Decode(const Napi::CallbackInfo& info) {
   const uint8_t* data = chunk->GetData();
   size_t data_size = chunk->GetDataSize();
   int64_t timestamp = chunk->GetTimestampValue();
+  int64_t duration = chunk->GetDurationValue();
   bool is_key_frame = (chunk->GetTypeValue() == "key");
 
+  // Use async decoding path
+  if (async_mode_ && async_worker_) {
+    // Create decode task with copy of chunk data
+    DecodeTask task;
+    task.data.assign(data, data + data_size);
+    task.timestamp = timestamp;
+    task.duration = duration;
+    task.is_key = is_key_frame;
+
+    // Enqueue to async worker (non-blocking)
+    async_worker_->Enqueue(std::move(task));
+
+    // Update queue size tracking
+    decode_queue_size_++;
+    webcodecs::counterQueue++;  // Global queue tracking
+    bool saturated = decode_queue_size_ >= static_cast<int>(kMaxQueueSize);
+    codec_saturated_.store(saturated);
+
+    return env.Undefined();
+  }
+
+  // Fallback to synchronous decoding (shouldn't normally reach here)
   // Setup packet.
   av_packet_unref(packet_.get());
   packet_->data = const_cast<uint8_t*>(data);
@@ -353,6 +468,24 @@ Napi::Value VideoDecoder::Flush(const Napi::CallbackInfo& info) {
     return deferred.Promise();
   }
 
+  // Use async flush path
+  if (async_mode_ && async_worker_) {
+    // Wait for async worker's task queue to drain
+    async_worker_->Flush();
+
+    // Reset queue after flush
+    decode_queue_size_ = 0;
+    codec_saturated_.store(false);
+
+    // Return resolved promise.
+    // TypeScript layer will poll pendingFrames to wait for all TSFN
+    // callbacks to complete.
+    Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(env);
+    deferred.Resolve(env.Undefined());
+    return deferred.Promise();
+  }
+
+  // Fallback to synchronous flush (shouldn't normally reach here)
   // Send NULL packet to flush decoder.
   int ret = avcodec_send_packet(codec_context_.get(), nullptr);
   if (ret < 0 && ret != AVERROR_EOF) {
@@ -378,9 +511,22 @@ Napi::Value VideoDecoder::Flush(const Napi::CallbackInfo& info) {
 Napi::Value VideoDecoder::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") {
-    throw Napi::Error::New(env,
-                           "InvalidStateError: Cannot reset a closed decoder");
+    return env.Undefined();
+  }
+
+  // Stop async worker first before accessing codec
+  if (async_worker_) {
+    async_worker_->Stop();
+    async_worker_.reset();
+  }
+
+  // Release ThreadSafeFunctions
+  if (async_mode_) {
+    output_tsfn_.Release();
+    error_tsfn_.Release();
+    async_mode_ = false;
   }
 
   // Flush any pending frames (discard them).
@@ -392,7 +538,11 @@ Napi::Value VideoDecoder::Reset(const Napi::CallbackInfo& info) {
   }
 
   // Clean up FFmpeg resources.
-  Cleanup();
+  frame_.reset();
+  packet_.reset();
+  sws_context_.reset();
+  codec_context_.reset();
+  codec_ = nullptr;
 
   // Reset state.
   state_ = "unconfigured";

package/src/video_decoder.h

@@ -18,11 +18,9 @@ extern "C" {
 #include <memory>
 #include <string>
 
+#include "src/async_decode_worker.h"
 #include "src/ffmpeg_raii.h"
 
-// Forward declaration
-class AsyncDecodeWorker;
-
 class VideoDecoder : public Napi::ObjectWrap<VideoDecoder> {
  public:
   static Napi::Object Init(Napi::Env env, Napi::Object exports);
@@ -44,6 +42,7 @@ class VideoDecoder : public Napi::ObjectWrap<VideoDecoder> {
   Napi::Value GetState(const Napi::CallbackInfo& info);
   Napi::Value GetDecodeQueueSize(const Napi::CallbackInfo& info);
   Napi::Value GetCodecSaturated(const Napi::CallbackInfo& info);
+  Napi::Value GetPendingFrames(const Napi::CallbackInfo& info);
 
   // Internal helpers.
   void Cleanup();
@@ -61,12 +60,6 @@ class VideoDecoder : public Napi::ObjectWrap<VideoDecoder> {
   Napi::FunctionReference output_callback_;
   Napi::FunctionReference error_callback_;
 
-  // Async worker for non-blocking decode.
-  std::unique_ptr<AsyncDecodeWorker> async_worker_;
-  Napi::ThreadSafeFunction output_tsfn_;
-  Napi::ThreadSafeFunction error_tsfn_;
-  bool async_mode_ = false;
-
   // State.
   std::string state_;
   int coded_width_;
@@ -74,6 +67,7 @@ class VideoDecoder : public Napi::ObjectWrap<VideoDecoder> {
   int decode_queue_size_ = 0;
   std::atomic<bool> codec_saturated_{false};
   static constexpr size_t kMaxQueueSize = 16;
+  static constexpr size_t kMaxHardQueueSize = 64;
 
   // Rotation and flip config (per W3C spec).
   int rotation_ = 0;   // 0, 90, 180, 270
@@ -102,8 +96,12 @@ class VideoDecoder : public Napi::ObjectWrap<VideoDecoder> {
   int last_frame_width_ = 0;
   int last_frame_height_ = 0;
 
-  // Friend declaration
-  friend class AsyncDecodeWorker;
+  // Async decoding via worker thread (non-blocking).
+  bool async_mode_ = false;
+  Napi::ThreadSafeFunction output_tsfn_;
+  Napi::ThreadSafeFunction error_tsfn_;
+  std::unique_ptr<AsyncDecodeWorker> async_worker_;
+  std::atomic<int> pending_frames_{0};  // Track frames in flight for flush
 };
 
 #endif  // SRC_VIDEO_DECODER_H_