@matjash/pixi-native-win32-x64 0.2.1 → 0.2.3

package/native/audio/src/audio_impl.rs

@@ -228,15 +228,51 @@ impl Voice {
             self.timeline_updated_at = now;
             return;
         }
-        self.timeline_seconds +=
-            now.duration_since(self.timeline_updated_at).as_secs_f64() * self.playback_rate;
-        if self.looped {
-            if let Some(duration_seconds) = self.duration_seconds {
-                self.timeline_seconds %= duration_seconds;
-            }
-        }
+        self.timeline_seconds = advance_timeline(
+            self.timeline_seconds,
+            now.duration_since(self.timeline_updated_at).as_secs_f64(),
+            self.playback_rate,
+            self.duration_seconds,
+            self.looped,
+        );
         self.timeline_updated_at = now;
     }
+
+    fn store_snapshot_time(&self, elapsed_seconds: f64) {
+        if let Some(time) = finite_absolute_time(self.offset_seconds, elapsed_seconds) {
+            self.snapshot
+                .time_bits
+                .store(time.to_bits(), Ordering::Release);
+        }
+    }
+}
+
+fn advance_timeline(
+    current_seconds: f64,
+    elapsed_seconds: f64,
+    playback_rate: f64,
+    duration_seconds: Option<f64>,
+    looped: bool,
+) -> f64 {
+    let current_seconds = if current_seconds.is_finite() {
+        current_seconds.max(0.0)
+    } else {
+        0.0
+    };
+    let advanced_seconds = current_seconds + elapsed_seconds * playback_rate;
+    if !advanced_seconds.is_finite() {
+        return current_seconds;
+    }
+    match duration_seconds {
+        Some(duration) if looped => advanced_seconds % duration,
+        Some(duration) => advanced_seconds.min(duration),
+        None => advanced_seconds,
+    }
+}
+
+fn finite_absolute_time(offset_seconds: f64, elapsed_seconds: f64) -> Option<f64> {
+    let time = offset_seconds + elapsed_seconds;
+    time.is_finite().then_some(time)
 }
 
 enum EngineCommand {
@@ -507,7 +543,8 @@ impl NativeAudioEngine {
     #[napi]
     pub fn current_time(&self, id: u32) -> Option<f64> {
         let snapshot = self.state.snapshots.lock().ok()?.get(&id).cloned()?;
-        Some(f64::from_bits(snapshot.time_bits.load(Ordering::Acquire)))
+        let time = f64::from_bits(snapshot.time_bits.load(Ordering::Acquire));
+        time.is_finite().then_some(time)
     }
 
     #[napi]
@@ -917,11 +954,7 @@ impl EngineRuntime {
             } else {
                 voice.timeline_seconds
             };
-            let time = voice.offset_seconds + elapsed_seconds;
-            voice
-                .snapshot
-                .time_bits
-                .store(time.to_bits(), Ordering::Release);
+            voice.store_snapshot_time(elapsed_seconds);
             let current_volume = if voice.fade.is_some() {
                 sound.current_fade_volume()
             } else {
@@ -1345,4 +1378,27 @@ mod tests {
             "https://***:***@example.test/audio.mp3"
         );
     }
+
+    #[test]
+    fn static_timeline_stays_finite_and_within_sprite_duration() {
+        assert_eq!(advance_timeline(0.2, 0.05, 1.0, Some(0.8), false), 0.25);
+        assert_eq!(advance_timeline(0.7, 0.2, 1.0, Some(0.8), false), 0.8);
+        let looped = advance_timeline(0.7, 0.2, 1.0, Some(0.8), true);
+        assert!((looped - 0.1).abs() < f64::EPSILON);
+        assert_eq!(
+            advance_timeline(f64::INFINITY, 0.05, 1.0, Some(0.8), false),
+            0.05
+        );
+        assert_eq!(
+            advance_timeline(0.2, f64::INFINITY, 1.0, Some(0.8), false),
+            0.2
+        );
+    }
+
+    #[test]
+    fn snapshot_time_rejects_non_finite_values() {
+        assert_eq!(finite_absolute_time(1.0, 0.2), Some(1.2));
+        assert_eq!(finite_absolute_time(0.0, f64::INFINITY), None);
+        assert_eq!(finite_absolute_time(f64::INFINITY, 0.0), None);
+    }
 }

package/native/video/src/index.d.ts

@@ -19,11 +19,27 @@ export interface VideoFrame {
   data: Uint8Array;
 }
 
+export interface VideoFrameInfo {
+  width: number;
+  height: number;
+  timestampUs: number;
+}
+
+export interface VideoShutdownDiagnostics {
+  activeDecoderWorkers: number;
+  pendingDecoderShutdowns: number;
+  completedDecoderShutdowns: number;
+  maxDecoderShutdownMs: number;
+}
+
 export class NativeVideoDecoder {
   public constructor(options: DecoderOptions);
   public open(source: string): void;
   public pollLatest(): VideoFrame | null;
   public pollNext(): VideoFrame | null;
+  public supportsFrameBufferReuse(): boolean;
+  public pollLatestInto(target: Buffer): VideoFrameInfo | null;
+  public pollNextInto(target: Buffer): VideoFrameInfo | null;
   public queuedFrames(): number;
   public catchUpTo(timestampUs: number): void;
   public pollError(): string | null;
@@ -31,6 +47,11 @@ export class NativeVideoDecoder {
   public decodedFrames(): number;
   public droppedFrames(): number;
   public skippedFrames(): number;
+  public frameBufferAllocations(): number;
+  public frameBufferReuses(): number;
+  public recycledFrameBuffers(): number;
   public isFinished(): boolean;
   public close(): void;
 }
+
+export function videoShutdownDiagnostics(): VideoShutdownDiagnostics;

package/native/video/src/index.js

@@ -21,6 +21,18 @@ class NativeVideoDecoder {
     return this.decoder.pollNext();
   }
 
+  supportsFrameBufferReuse() {
+    return typeof this.decoder.pollNextInto === "function";
+  }
+
+  pollLatestInto(target) {
+    return this.pollIntoFallback("pollLatest", "pollLatestInto", target);
+  }
+
+  pollNextInto(target) {
+    return this.pollIntoFallback("pollNext", "pollNextInto", target);
+  }
+
   queuedFrames() {
     return this.decoder.queuedFrames();
   }
@@ -49,6 +61,18 @@ class NativeVideoDecoder {
     return this.decoder.skippedFrames();
   }
 
+  frameBufferAllocations() {
+    return this.decoder.frameBufferAllocations?.() ?? 0;
+  }
+
+  frameBufferReuses() {
+    return this.decoder.frameBufferReuses?.() ?? 0;
+  }
+
+  recycledFrameBuffers() {
+    return this.decoder.recycledFrameBuffers?.() ?? 0;
+  }
+
   isFinished() {
     return this.decoder.isFinished();
   }
@@ -56,6 +80,34 @@ class NativeVideoDecoder {
   close() {
     this.decoder.close();
   }
+
+  pollIntoFallback(pollName, pollIntoName, target) {
+    if (typeof this.decoder[pollIntoName] === "function") {
+      return this.decoder[pollIntoName](target);
+    }
+    const frame = this.decoder[pollName]();
+    if (!frame) return null;
+    if (target.byteLength !== frame.data.byteLength) {
+      throw new RangeError(
+        `NV12 target has ${target.byteLength} bytes; expected ${frame.data.byteLength}`,
+      );
+    }
+    target.set(frame.data);
+    return {
+      width: frame.width,
+      height: frame.height,
+      timestampUs: frame.timestampUs,
+    };
+  }
+}
+
+function videoShutdownDiagnostics() {
+  return native.videoShutdownDiagnostics?.() ?? {
+    activeDecoderWorkers: 0,
+    pendingDecoderShutdowns: 0,
+    completedDecoderShutdowns: 0,
+    maxDecoderShutdownMs: 0,
+  };
 }
 
-module.exports = { NativeVideoDecoder };
+module.exports = { NativeVideoDecoder, videoShutdownDiagnostics };

package/native/video/src/lib.rs

@@ -6,7 +6,7 @@ use std::process::{Child, ChildStdout, Command, Stdio};
 use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};
 use std::sync::{Arc, Condvar, Mutex};
 use std::thread;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 use napi::bindgen_prelude::*;
 use napi_derive::napi;
@@ -15,6 +15,11 @@ const FRAME_QUEUE_CAPACITY: usize = 4;
 const HARDWARE_DECODE_ATTEMPTS: usize = 5;
 const HARDWARE_RETRY_DELAY: Duration = Duration::from_millis(500);
 
+static ACTIVE_DECODER_WORKERS: AtomicU64 = AtomicU64::new(0);
+static PENDING_DECODER_SHUTDOWNS: AtomicU64 = AtomicU64::new(0);
+static COMPLETED_DECODER_SHUTDOWNS: AtomicU64 = AtomicU64::new(0);
+static MAX_DECODER_SHUTDOWN_MS: AtomicU64 = AtomicU64::new(0);
+
 #[napi(object)]
 pub struct DecoderOptions {
     pub width: i64,
@@ -38,6 +43,31 @@ pub struct VideoFrame {
     pub data: Buffer,
 }
 
+#[napi(object)]
+pub struct VideoFrameInfo {
+    pub width: i64,
+    pub height: i64,
+    pub timestamp_us: i64,
+}
+
+#[napi(object)]
+pub struct VideoShutdownDiagnostics {
+    pub active_decoder_workers: i64,
+    pub pending_decoder_shutdowns: i64,
+    pub completed_decoder_shutdowns: i64,
+    pub max_decoder_shutdown_ms: i64,
+}
+
+#[napi]
+pub fn video_shutdown_diagnostics() -> VideoShutdownDiagnostics {
+    VideoShutdownDiagnostics {
+        active_decoder_workers: atomic_i64(&ACTIVE_DECODER_WORKERS),
+        pending_decoder_shutdowns: atomic_i64(&PENDING_DECODER_SHUTDOWNS),
+        completed_decoder_shutdowns: atomic_i64(&COMPLETED_DECODER_SHUTDOWNS),
+        max_decoder_shutdown_ms: atomic_i64(&MAX_DECODER_SHUTDOWN_MS),
+    }
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 enum DecoderBackend {
     D3d11va,
@@ -84,7 +114,10 @@ struct DecoderState {
     decoded_frames: Arc<AtomicU64>,
     dropped_frames: Arc<AtomicU64>,
     skipped_frames: Arc<AtomicU64>,
+    frame_buffer_allocations: Arc<AtomicU64>,
+    frame_buffer_reuses: Arc<AtomicU64>,
     backend: Arc<Mutex<String>>,
+    stderr_workers: Arc<Mutex<Vec<thread::JoinHandle<()>>>>,
 }
 
 struct PendingFrame {
@@ -95,6 +128,7 @@ struct PendingFrame {
 #[derive(Default)]
 struct FrameQueue {
     frames: VecDeque<PendingFrame>,
+    recycled: Vec<Vec<u8>>,
 }
 
 impl FrameQueue {
@@ -108,6 +142,19 @@ impl FrameQueue {
         recycled
     }
 
+    fn take_recycled(&mut self, frame_bytes: usize) -> Option<Vec<u8>> {
+        while let Some(buffer) = self.recycled.pop() {
+            if buffer.len() == frame_bytes {
+                return Some(buffer);
+            }
+        }
+        None
+    }
+
+    fn recycle(&mut self, buffer: Vec<u8>) {
+        self.recycled.push(buffer);
+    }
+
     fn push_back(&mut self, frame: PendingFrame) {
         self.frames.push_back(frame);
     }
@@ -119,7 +166,9 @@ impl FrameQueue {
     fn pop_latest(&mut self) -> (Option<PendingFrame>, usize) {
         let latest = self.frames.pop_back();
         let skipped = self.frames.len();
-        self.frames.clear();
+        while let Some(frame) = self.frames.pop_front() {
+            self.recycle(frame.data);
+        }
         (latest, skipped)
     }
 
@@ -127,14 +176,22 @@ impl FrameQueue {
         self.frames.len()
     }
 
+    fn recycle_queued(&mut self) {
+        while let Some(frame) = self.frames.pop_front() {
+            self.recycle(frame.data);
+        }
+    }
+
     fn clear(&mut self) {
         self.frames.clear();
+        self.recycled.clear();
     }
 }
 
 struct SpawnedFfmpeg {
     child: Child,
     stdout: ChildStdout,
+    stderr_worker: Option<thread::JoinHandle<()>>,
 }
 
 #[derive(Clone)]
@@ -155,6 +212,8 @@ struct FfmpegRequest {
 pub struct NativeVideoDecoder {
     options: DecoderOptions,
     state: DecoderState,
+    worker: Option<thread::JoinHandle<()>>,
+    retired: bool,
 }
 
 #[napi]
@@ -171,6 +230,8 @@ impl NativeVideoDecoder {
 
         Ok(Self {
             options,
+            worker: None,
+            retired: false,
             state: DecoderState {
                 closed: Arc::new(AtomicBool::new(true)),
                 finished: Arc::new(AtomicBool::new(false)),
@@ -182,13 +243,24 @@ impl NativeVideoDecoder {
                 decoded_frames: Arc::new(AtomicU64::new(0)),
                 dropped_frames: Arc::new(AtomicU64::new(0)),
                 skipped_frames: Arc::new(AtomicU64::new(0)),
+                frame_buffer_allocations: Arc::new(AtomicU64::new(0)),
+                frame_buffer_reuses: Arc::new(AtomicU64::new(0)),
                 backend: Arc::new(Mutex::new(backend)),
+                stderr_workers: Arc::new(Mutex::new(Vec::new())),
             },
         })
     }
 
     #[napi]
     pub fn open(&mut self, source: String) -> Result<()> {
+        if self.retired {
+            return Err(Error::from_reason(
+                "Video decoder cannot reopen after shutdown",
+            ));
+        }
+        if self.state.closed.load(Ordering::SeqCst) {
+            self.join_worker();
+        }
         if !self.state.closed.swap(false, Ordering::SeqCst) {
             return Err(Error::from_reason("Video decoder is already open"));
         }
@@ -197,6 +269,10 @@ impl NativeVideoDecoder {
         self.state.decoded_frames.store(0, Ordering::SeqCst);
         self.state.dropped_frames.store(0, Ordering::SeqCst);
         self.state.skipped_frames.store(0, Ordering::SeqCst);
+        self.state
+            .frame_buffer_allocations
+            .store(0, Ordering::SeqCst);
+        self.state.frame_buffer_reuses.store(0, Ordering::SeqCst);
 
         if let Ok(mut error) = self.state.error.lock() {
             *error = None;
@@ -268,7 +344,9 @@ impl NativeVideoDecoder {
         let initial_stdout = install_child(&state, spawned)
             .map_err(|error| Error::from_reason(error.to_string()))?;
 
-        thread::spawn(move || {
+        ACTIVE_DECODER_WORKERS.fetch_add(1, Ordering::SeqCst);
+        self.worker = Some(thread::spawn(move || {
+            let _active_worker = ActiveDecoderWorker;
             let mut result =
                 consume_decoder_attempt(initial_stdout, width, height, fps, start_time, &state);
 
@@ -334,7 +412,7 @@ impl NativeVideoDecoder {
                 state.finished.store(true, Ordering::SeqCst);
             }
             state.closed.store(true, Ordering::SeqCst);
-        });
+        }));
 
         Ok(())
     }
@@ -360,6 +438,41 @@ impl NativeVideoDecoder {
         self.to_video_frame(pending)
     }
 
+    #[napi]
+    pub fn poll_latest_into(&self, mut target: BufferSlice) -> Result<Option<VideoFrameInfo>> {
+        let (frames, available) = &*self.state.frames;
+        let (pending, skipped) = frames
+            .lock()
+            .map_err(|_| Error::from_reason("Video frame queue lock poisoned"))?
+            .pop_latest();
+        if skipped > 0 {
+            self.state
+                .skipped_frames
+                .fetch_add(skipped as u64, Ordering::SeqCst);
+        }
+        let result = pending
+            .map(|pending| self.copy_video_frame_into(pending, &mut target))
+            .transpose();
+        available.notify_all();
+        result
+    }
+
+    #[napi]
+    pub fn poll_next_into(&self, mut target: BufferSlice) -> Result<Option<VideoFrameInfo>> {
+        let (frames, available) = &*self.state.frames;
+        let pending = frames
+            .lock()
+            .map_err(|_| Error::from_reason("Video frame queue lock poisoned"))?
+            .pop_next();
+        let result = pending
+            .map(|pending| self.copy_video_frame_into(pending, &mut target))
+            .transpose();
+        if result.as_ref().is_ok_and(Option::is_some) {
+            available.notify_one();
+        }
+        result
+    }
+
     #[napi]
     pub fn queued_frames(&self) -> i64 {
         let (frames, _) = &*self.state.frames;
@@ -383,7 +496,7 @@ impl NativeVideoDecoder {
         let (frames, available) = &*self.state.frames;
         if let Ok(mut frames) = frames.lock() {
             let skipped = frames.len();
-            frames.clear();
+            frames.recycle_queued();
             self.state
                 .skipped_frames
                 .fetch_add(skipped as u64, Ordering::SeqCst);
@@ -430,6 +543,26 @@ impl NativeVideoDecoder {
         i64::try_from(self.state.skipped_frames.load(Ordering::SeqCst)).unwrap_or(i64::MAX)
     }
 
+    #[napi]
+    pub fn frame_buffer_allocations(&self) -> i64 {
+        i64::try_from(self.state.frame_buffer_allocations.load(Ordering::SeqCst))
+            .unwrap_or(i64::MAX)
+    }
+
+    #[napi]
+    pub fn frame_buffer_reuses(&self) -> i64 {
+        i64::try_from(self.state.frame_buffer_reuses.load(Ordering::SeqCst)).unwrap_or(i64::MAX)
+    }
+
+    #[napi]
+    pub fn recycled_frame_buffers(&self) -> i64 {
+        let (frames, _) = &*self.state.frames;
+        frames
+            .lock()
+            .map(|frames| i64::try_from(frames.recycled.len()).unwrap_or(i64::MAX))
+            .unwrap_or(0)
+    }
+
     #[napi]
     pub fn is_finished(&self) -> bool {
         self.state.finished.load(Ordering::SeqCst)
@@ -437,13 +570,54 @@ impl NativeVideoDecoder {
 
     #[napi]
     pub fn close(&mut self) {
-        close_state(&self.state);
+        self.begin_shutdown();
+    }
+
+    fn begin_shutdown(&mut self) {
+        if self.retired {
+            return;
+        }
+        self.retired = true;
+        let child = request_close_state(&self.state);
+        retire_decoder_cleanup(self.worker.take(), child);
+    }
+
+    fn join_worker(&mut self) {
+        if let Some(worker) = self.worker.take() {
+            let _ = worker.join();
+        }
+    }
+
+    fn copy_video_frame_into(
+        &self,
+        pending: PendingFrame,
+        target: &mut [u8],
+    ) -> Result<VideoFrameInfo> {
+        if target.len() != pending.data.len() {
+            let actual = target.len();
+            let expected = pending.data.len();
+            if let Ok(mut frames) = self.state.frames.0.lock() {
+                frames.recycle(pending.data);
+            }
+            return Err(Error::from_reason(format!(
+                "NV12 target has {actual} bytes; expected {expected}"
+            )));
+        }
+        target.copy_from_slice(&pending.data);
+        if let Ok(mut frames) = self.state.frames.0.lock() {
+            frames.recycle(pending.data);
+        }
+        Ok(VideoFrameInfo {
+            width: self.options.width,
+            height: self.options.height,
+            timestamp_us: pending.timestamp_us,
+        })
     }
 }
 
 impl Drop for NativeVideoDecoder {
     fn drop(&mut self) {
-        close_state(&self.state);
+        self.begin_shutdown();
     }
 }
 
@@ -582,14 +756,18 @@ fn spawn_ffmpeg(request: &FfmpegRequest, backend: DecoderBackend) -> io::Result<
         .stdout
         .take()
         .ok_or_else(|| io::Error::other("FFmpeg stdout unavailable"))?;
-    if let Some(stderr) = child.stderr.take() {
+    let stderr_worker = child.stderr.take().map(|stderr| {
         thread::spawn(move || {
             for line in BufReader::new(stderr).lines().map_while(|line| line.ok()) {
                 eprintln!("{}", redact_url_credentials(&line));
             }
-        });
-    }
-    Ok(SpawnedFfmpeg { child, stdout })
+        })
+    });
+    Ok(SpawnedFfmpeg {
+        child,
+        stdout,
+        stderr_worker,
+    })
 }
 
 fn redact_url_credentials(value: &str) -> String {
@@ -612,11 +790,32 @@ fn redact_url_credentials(value: &str) -> String {
     result
 }
 
-fn install_child(state: &DecoderState, spawned: SpawnedFfmpeg) -> io::Result<ChildStdout> {
-    *state
+fn install_child(state: &DecoderState, mut spawned: SpawnedFfmpeg) -> io::Result<ChildStdout> {
+    let mut child = state
         .child
         .lock()
-        .map_err(|_| io::Error::other("FFmpeg process lock poisoned"))? = Some(spawned.child);
+        .map_err(|_| io::Error::other("FFmpeg process lock poisoned"))?;
+    if state.closed.load(Ordering::SeqCst) {
+        drop(child);
+        let _ = spawned.child.kill();
+        let _ = spawned.child.wait();
+        if let Some(worker) = spawned.stderr_worker {
+            let _ = worker.join();
+        }
+        return Err(io::Error::new(
+            io::ErrorKind::Interrupted,
+            "Video decoder closed before FFmpeg startup completed",
+        ));
+    }
+    *child = Some(spawned.child);
+    drop(child);
+    if let Some(worker) = spawned.stderr_worker {
+        state
+            .stderr_workers
+            .lock()
+            .map_err(|_| io::Error::other("FFmpeg stderr worker lock poisoned"))?
+            .push(worker);
+    }
     Ok(spawned.stdout)
 }
 
@@ -631,7 +830,7 @@ fn consume_ffmpeg_output(
     let frame_bytes = nv12_frame_bytes(width, height)?;
     let start_timestamp_us = (start_time * 1_000_000.0).round() as i64;
     let mut frame_index = 0_i64;
-    let mut data = vec![0_u8; frame_bytes];
+    let mut data = acquire_frame_buffer(frame_bytes, state)?;
     let read_result = loop {
         if state.closed.load(Ordering::SeqCst) {
             break Ok(());
@@ -644,20 +843,16 @@ fn consume_ffmpeg_output(
                 frame_index += 1;
                 state.decoded_frames.fetch_add(1, Ordering::SeqCst);
 
-                data = enqueue_frame(PendingFrame { timestamp_us, data }, frame_bytes, state)?;
+                enqueue_frame(PendingFrame { timestamp_us, data }, state)?;
+                data = acquire_frame_buffer(frame_bytes, state)?;
             }
             Err(error) if error.kind() == io::ErrorKind::UnexpectedEof => break Ok(()),
             Err(error) => break Err(error),
         }
     };
 
-    let status = state
-        .child
-        .lock()
-        .map_err(|_| io::Error::other("FFmpeg process lock poisoned"))?
-        .take()
-        .map(|mut process| process.wait())
-        .transpose()?;
+    let status = wait_for_child_exit(state)?;
+    join_stderr_workers(state);
 
     read_result?;
     if !state.closed.load(Ordering::SeqCst) && status.is_some_and(|status| !status.success()) {
@@ -709,15 +904,16 @@ fn wait_for_hardware_retry(state: &DecoderState) -> io::Result<bool> {
     Ok(!state.closed.load(Ordering::SeqCst))
 }
 
-fn enqueue_frame(
-    frame: PendingFrame,
-    frame_bytes: usize,
-    state: &DecoderState,
-) -> io::Result<Vec<u8>> {
+fn enqueue_frame(frame: PendingFrame, state: &DecoderState) -> io::Result<()> {
     let catch_up_timestamp_us = state.catch_up_timestamp_us.load(Ordering::SeqCst);
     if catch_up_timestamp_us >= 0 && frame.timestamp_us < catch_up_timestamp_us {
         state.skipped_frames.fetch_add(1, Ordering::SeqCst);
-        return Ok(frame.data);
+        let (frames, _) = &*state.frames;
+        frames
+            .lock()
+            .map_err(|_| io::Error::other("Video frame queue lock poisoned"))?
+            .recycle(frame.data);
+        return Ok(());
     }
     if catch_up_timestamp_us >= 0 {
         state.catch_up_timestamp_us.store(-1, Ordering::SeqCst);
@@ -731,7 +927,7 @@ fn enqueue_frame(
     if state.source_paced {
         if let Some(recycled) = frames.push_latest(frame) {
             state.dropped_frames.fetch_add(1, Ordering::SeqCst);
-            return Ok(recycled);
+            frames.recycle(recycled);
         }
     } else {
         while frames.len() >= FRAME_QUEUE_CAPACITY
@@ -743,12 +939,14 @@ fn enqueue_frame(
                 .map_err(|_| io::Error::other("Video frame queue lock poisoned"))?;
         }
         if state.closed.load(Ordering::SeqCst) {
-            return Ok(frame.data);
+            frames.recycle(frame.data);
+            return Ok(());
         }
         let target = state.catch_up_timestamp_us.load(Ordering::SeqCst);
         if target >= 0 && frame.timestamp_us < target {
             state.skipped_frames.fetch_add(1, Ordering::SeqCst);
-            return Ok(frame.data);
+            frames.recycle(frame.data);
+            return Ok(());
         }
         if target >= 0 {
             state.catch_up_timestamp_us.store(-1, Ordering::SeqCst);
@@ -756,9 +954,36 @@ fn enqueue_frame(
         frames.push_back(frame);
     }
 
+    Ok(())
+}
+
+fn acquire_frame_buffer(frame_bytes: usize, state: &DecoderState) -> io::Result<Vec<u8>> {
+    let (frames, _) = &*state.frames;
+    if let Some(buffer) = frames
+        .lock()
+        .map_err(|_| io::Error::other("Video frame queue lock poisoned"))?
+        .take_recycled(frame_bytes)
+    {
+        state.frame_buffer_reuses.fetch_add(1, Ordering::SeqCst);
+        return Ok(buffer);
+    }
+    state
+        .frame_buffer_allocations
+        .fetch_add(1, Ordering::SeqCst);
     Ok(vec![0_u8; frame_bytes])
 }
 
+fn join_stderr_workers(state: &DecoderState) {
+    let workers = state
+        .stderr_workers
+        .lock()
+        .map(|mut workers| workers.drain(..).collect::<Vec<_>>())
+        .unwrap_or_default();
+    for worker in workers {
+        let _ = worker.join();
+    }
+}
+
 fn set_backend_name(state: &DecoderState, name: &str) {
     if let Ok(mut backend) = state.backend.lock() {
         *backend = name.to_string();
@@ -772,18 +997,78 @@ fn store_error(state: &DecoderState, message: String) {
     }
 }
 
-fn close_state(state: &DecoderState) {
+/** Polls without holding the child mutex while the FFmpeg process exits. */
+fn wait_for_child_exit(state: &DecoderState) -> io::Result<Option<std::process::ExitStatus>> {
+    loop {
+        let status = {
+            let mut child = state
+                .child
+                .lock()
+                .map_err(|_| io::Error::other("FFmpeg process lock poisoned"))?;
+            match child.as_mut() {
+                Some(process) => process.try_wait()?,
+                None => return Ok(None),
+            }
+        };
+        if let Some(status) = status {
+            if let Ok(mut child) = state.child.lock() {
+                child.take();
+            }
+            return Ok(Some(status));
+        }
+        if state.closed.load(Ordering::SeqCst) {
+            return Ok(None);
+        }
+        thread::sleep(Duration::from_millis(10));
+    }
+}
+
+/** Signals decoder shutdown without waiting on FFmpeg or worker threads. */
+fn request_close_state(state: &DecoderState) -> Option<Child> {
     state.closed.store(true, Ordering::SeqCst);
     let (frames, available) = &*state.frames;
     available.notify_all();
-    if let Ok(mut child) = state.child.lock() {
-        if let Some(mut process) = child.take() {
-            let _ = process.kill();
-        }
+    let mut child = state.child.lock().ok().and_then(|mut child| child.take());
+    if let Some(process) = child.as_mut() {
+        let _ = process.kill();
     }
     if let Ok(mut frames) = frames.lock() {
         frames.clear();
     }
+    child
+}
+
+/** Reaps the killed process and joins workers away from the N-API thread. */
+fn retire_decoder_cleanup(worker: Option<thread::JoinHandle<()>>, child: Option<Child>) {
+    if worker.is_none() && child.is_none() {
+        return;
+    }
+    PENDING_DECODER_SHUTDOWNS.fetch_add(1, Ordering::SeqCst);
+    thread::spawn(move || {
+        let started = Instant::now();
+        if let Some(mut process) = child {
+            let _ = process.wait();
+        }
+        if let Some(worker) = worker {
+            let _ = worker.join();
+        }
+        let elapsed_ms = u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX);
+        MAX_DECODER_SHUTDOWN_MS.fetch_max(elapsed_ms, Ordering::SeqCst);
+        COMPLETED_DECODER_SHUTDOWNS.fetch_add(1, Ordering::SeqCst);
+        PENDING_DECODER_SHUTDOWNS.fetch_sub(1, Ordering::SeqCst);
+    });
+}
+
+fn atomic_i64(value: &AtomicU64) -> i64 {
+    i64::try_from(value.load(Ordering::SeqCst)).unwrap_or(i64::MAX)
+}
+
+struct ActiveDecoderWorker;
+
+impl Drop for ActiveDecoderWorker {
+    fn drop(&mut self) {
+        ACTIVE_DECODER_WORKERS.fetch_sub(1, Ordering::SeqCst);
+    }
 }
 
 #[cfg(test)]
@@ -906,13 +1191,13 @@ mod tests {
     fn file_queue_applies_backpressure_until_a_frame_is_consumed() {
         let state = decoder_state(false);
         for timestamp_us in 0..FRAME_QUEUE_CAPACITY as i64 {
-            enqueue_frame(pending(timestamp_us), 1, &state).unwrap();
+            enqueue_frame(pending(timestamp_us), &state).unwrap();
         }
 
         let producer_state = state.clone();
         let (sent, received) = mpsc::channel();
         thread::spawn(move || {
-            let result = enqueue_frame(pending(99), 1, &producer_state);
+            let result = enqueue_frame(pending(99), &producer_state);
             sent.send(result.is_ok()).unwrap();
         });
 
@@ -928,14 +1213,110 @@ mod tests {
         let state = decoder_state(false);
         state.catch_up_timestamp_us.store(30, Ordering::SeqCst);
 
-        assert_eq!(enqueue_frame(pending(10), 1, &state).unwrap(), vec![10]);
-        assert_eq!(enqueue_frame(pending(20), 1, &state).unwrap(), vec![20]);
-        enqueue_frame(pending(30), 1, &state).unwrap();
+        enqueue_frame(pending(10), &state).unwrap();
+        enqueue_frame(pending(20), &state).unwrap();
+        enqueue_frame(pending(30), &state).unwrap();
 
         assert_eq!(state.skipped_frames.load(Ordering::SeqCst), 2);
         let (frames, _) = &*state.frames;
         let mut frames = frames.lock().unwrap();
         assert_eq!(frames.pop_next().unwrap().timestamp_us, 30);
+        assert_eq!(frames.recycled.len(), 2);
+    }
+
+    #[test]
+    fn copies_frame_into_caller_buffer_and_recycles_native_storage() {
+        let decoder = NativeVideoDecoder::new(DecoderOptions {
+            width: 2,
+            height: 2,
+            fps: Some(30.0),
+            start_time: None,
+            ffmpeg_path: None,
+            vaapi_device: None,
+            playback_rate: None,
+            end_time: None,
+            source_paced: None,
+            input_args: None,
+            output_args: None,
+        })
+        .unwrap();
+        let mut target = vec![0; 6];
+        let info = decoder
+            .copy_video_frame_into(
+                PendingFrame {
+                    timestamp_us: 42,
+                    data: vec![1, 2, 3, 4, 5, 6],
+                },
+                &mut target,
+            )
+            .unwrap();
+
+        assert_eq!(target, vec![1, 2, 3, 4, 5, 6]);
+        assert_eq!(info.timestamp_us, 42);
+        assert_eq!(decoder.state.frames.0.lock().unwrap().recycled.len(), 1);
+    }
+
+    #[test]
+    fn rejects_wrong_caller_buffer_size_without_losing_native_storage() {
+        let decoder = NativeVideoDecoder::new(DecoderOptions {
+            width: 2,
+            height: 2,
+            fps: Some(30.0),
+            start_time: None,
+            ffmpeg_path: None,
+            vaapi_device: None,
+            playback_rate: None,
+            end_time: None,
+            source_paced: None,
+            input_args: None,
+            output_args: None,
+        })
+        .unwrap();
+        let mut target = vec![0; 5];
+        let result = decoder.copy_video_frame_into(
+            PendingFrame {
+                timestamp_us: 42,
+                data: vec![1, 2, 3, 4, 5, 6],
+            },
+            &mut target,
+        );
+
+        assert!(result.is_err());
+        assert_eq!(decoder.state.frames.0.lock().unwrap().recycled.len(), 1);
+    }
+
+    #[test]
+    fn close_retires_a_blocked_worker_without_waiting_for_it() {
+        let mut decoder = test_decoder();
+        let (started_tx, started_rx) = mpsc::channel();
+        let (release_tx, release_rx) = mpsc::channel();
+        decoder.worker = Some(thread::spawn(move || {
+            started_tx.send(()).unwrap();
+            release_rx.recv().unwrap();
+        }));
+        started_rx.recv_timeout(Duration::from_secs(1)).unwrap();
+        let completed_before = COMPLETED_DECODER_SHUTDOWNS.load(Ordering::SeqCst);
+
+        let started = Instant::now();
+        decoder.close();
+        assert!(started.elapsed() < Duration::from_millis(100));
+        assert!(PENDING_DECODER_SHUTDOWNS.load(Ordering::SeqCst) >= 1);
+
+        release_tx.send(()).unwrap();
+        let deadline = Instant::now() + Duration::from_secs(1);
+        while COMPLETED_DECODER_SHUTDOWNS.load(Ordering::SeqCst) == completed_before {
+            assert!(Instant::now() < deadline);
+            thread::sleep(Duration::from_millis(5));
+        }
+    }
+
+    #[test]
+    fn explicit_close_makes_the_decoder_terminal_without_blocking_reopen() {
+        let mut decoder = test_decoder();
+        decoder.close();
+
+        let error = decoder.open("unused.mp4".to_string()).unwrap_err();
+        assert!(error.to_string().contains("cannot reopen after shutdown"));
     }
 
     #[test]
@@ -961,6 +1342,23 @@ mod tests {
         }
     }
 
+    fn test_decoder() -> NativeVideoDecoder {
+        NativeVideoDecoder::new(DecoderOptions {
+            width: 2,
+            height: 2,
+            fps: Some(30.0),
+            start_time: None,
+            ffmpeg_path: None,
+            vaapi_device: None,
+            playback_rate: None,
+            end_time: None,
+            source_paced: None,
+            input_args: None,
+            output_args: None,
+        })
+        .unwrap()
+    }
+
     fn decoder_state(source_paced: bool) -> DecoderState {
         DecoderState {
             closed: Arc::new(AtomicBool::new(false)),
@@ -973,7 +1371,10 @@ mod tests {
             decoded_frames: Arc::new(AtomicU64::new(0)),
             dropped_frames: Arc::new(AtomicU64::new(0)),
             skipped_frames: Arc::new(AtomicU64::new(0)),
+            frame_buffer_allocations: Arc::new(AtomicU64::new(0)),
+            frame_buffer_reuses: Arc::new(AtomicU64::new(0)),
             backend: Arc::new(Mutex::new("test".to_string())),
+            stderr_workers: Arc::new(Mutex::new(Vec::new())),
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matjash/pixi-native-win32-x64",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "commonjs",
   "description": "Windows x64 native binaries for @matjash/pixi-native",
   "license": "MIT",