perf: TV Guide streaming — ffmpeg backend, decode pipeline optimizations (#85)

* perf: TV Guide streaming — ffmpeg backend, decode pipeline optimizations

Switch default desktop video backend from openh264 (Baseline-only) to
system ffmpeg (Main/High profile, SIMD-optimized).  Profiling showed
openh264 caused repeated reinit cycles (~5s gaps) on archive.org
Main-profile content, yielding only 2 fps.  With ffmpeg: 27-32 fps
decode, 15-30 fps display, zero audio drops.

Streaming buffer optimizations:
- Lock-free reads for cached header/moov data (skip mutex on immutable regions)
- Buffer eviction uses copy_within+truncate instead of drain
- RETAIN_BEHIND increased to 8MB for tolerant-decode seek-back coverage

Video decode pipeline:
- Two-phase H.264 decode strategy for openh264 path: reinit only for
  initial sync, then tolerate errors during steady-state playback
- Move frame scaling from decode thread to main thread (unblock decode)
- Audio channel capacity 64→256 (eliminates 41-56% drop rate)
- AAC SampleBuffer reused across decode calls (avoid per-frame alloc)

YUV-to-RGBA conversion:
- Process pixel pairs sharing chroma samples (halves UV lookups)
- Unchecked indexing with row-level bounds verification
- Odd-width frame support

Measured improvement (CH5 / CH13):
- Decode: 2.3→27.7 fps / 2.1→32.5 fps
- Display: 2.0→15-19 fps / 1.6→30.1 fps
- Audio drops: 41%→0% / 56%→0%
- H.264 reinits: 4 per 16s → 0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address AI review feedback (iteration 1)

Automated fix by Claude in response to Gemini/Codex review.

Iteration: 1/5

Co-Authored-By: AI Review Agent <noreply@anthropic.com>

* fix: revert default feature to video-decode (openh264) for CI compat

CI Docker containers don't have ffmpeg dev libraries installed.
Keep openh264 as the default (works in CI), document ffmpeg as the
recommended desktop build path in Cargo.toml feature comments.

To build with ffmpeg locally:
  cargo build -p oasis-app --no-default-features \
    --features video-decode-ffmpeg,javascript

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: YUV bounds checks use assert! not debug_assert! (Gemini review)

The bounds checks guarding unsafe get_unchecked calls in yuv420_to_rgba
must use assert! (not debug_assert!) to maintain soundness in release
builds. debug_assert! is stripped in release, which would allow invalid
strides from callers to cause UB in this public safe function.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: AI Agent Bot <ai-agent@localhost>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: AI Review Agent <ai-review-agent@localhost>

Author: 4 people

crates/oasis-app/Cargo.toml

@@ -30,10 +30,12 @@ default = ["javascript", "video-decode"]
 javascript = ["oasis-core/javascript"]
 # Internal: oasis-video is available. Activated by video-decode or video-decode-ffmpeg.
 _video = ["dep:oasis-video"]
-# Software decode via openh264 (Baseline profile). Default for CI/dev.
+# Software decode via openh264 (Baseline profile). Default for CI where
+# ffmpeg dev libraries are not installed.
 video-decode = ["_video", "oasis-video/h264"]
-# Full decode via statically-linked ffmpeg (Main/High profile, SIMD).
-# For shipping desktop apps and UE5 games. Mutually exclusive with video-decode.
+# Full decode via system ffmpeg (Main/High profile, SIMD-optimized).
+# Recommended for desktop use — requires libavcodec-dev etc. on the system.
+# Build: cargo build -p oasis-app --no-default-features --features video-decode-ffmpeg,javascript
 video-decode-ffmpeg = ["_video", "oasis-video/ffmpeg"]
 
 [dependencies]

crates/oasis-app/src/tv_controller/streaming_buffer.rs

@@ -2,9 +2,11 @@
 //! fed by a background download thread.
 
 /// How much data to retain behind the decoder's read cursor.
-/// Allows minor backward seeks without re-downloading.
+/// Allows minor backward seeks without re-downloading.  Sized to cover
+/// symphonia's internal seek-back distance when the H.264 decoder skips
+/// many packets in tolerant-decode mode (openh264 Baseline-only gaps).
 #[cfg(feature = "_video")]
-pub(crate) const RETAIN_BEHIND: usize = 4 * 1024 * 1024; // 4 MB
+pub(crate) const RETAIN_BEHIND: usize = 8 * 1024 * 1024; // 8 MB
 
 /// Maximum bytes the download thread may be ahead of the decoder's read
 /// cursor before it pauses.  Keeps memory bounded to ~16 MB lookahead.
@@ -511,6 +513,12 @@ pub(crate) struct StreamingBuffer {
     pub(crate) eviction_enabled: std::sync::Arc<std::sync::atomic::AtomicBool>,
     /// Whether we've logged a "waiting for data" message (avoids log spam).
     logged_wait: bool,
+    /// Cached header (ftyp) data — once set it never changes, so reads from
+    /// the header region can be served without acquiring the state mutex.
+    cached_header: Option<Vec<u8>>,
+    /// Cached moov atom — once set it never changes. Reads from the moov
+    /// region can be served without acquiring the state mutex.
+    cached_moov: Option<(u64, std::sync::Arc<Vec<u8>>)>,
 }
 
 #[cfg(feature = "_video")]
@@ -521,6 +529,8 @@ impl StreamingBuffer {
             pos: 0,
             eviction_enabled: std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
             logged_wait: false,
+            cached_header: None,
+            cached_moov: None,
         }
     }
 
@@ -543,7 +553,11 @@ impl StreamingBuffer {
             let evict = cursor_in_buf - RETAIN_BEHIND;
             let evict = evict.min(s.buf.len());
             if evict > 0 {
-                s.buf.drain(..evict);
+                // In-place shift: copy_within avoids the Drain iterator
+                // overhead and keeps the Vec's allocation stable.
+                let new_len = s.buf.len() - evict;
+                s.buf.copy_within(evict.., 0);
+                s.buf.truncate(new_len);
                 s.base_offset += evict as u64;
                 log::debug!(
                     "TV: evicted {:.1}MB, window now {:.1}MB ({}-{})",
@@ -573,10 +587,46 @@ impl std::io::Read for StreamingBuffer {
                 return Err(std::io::Error::other(e.clone()));
             }
 
+            // Try serving from cached header/moov without acquiring the lock.
+            // These are set once and never modified, so lock-free access is safe.
+            if let Some(ref hdr) = self.cached_header
+                && (self.pos as usize) < hdr.len()
+            {
+                let local = self.pos as usize;
+                let n = buf.len().min(hdr.len() - local);
+                buf[..n].copy_from_slice(&hdr[local..local + n]);
+                self.pos += n as u64;
+                break n;
+            }
+            if let Some((moov_off, ref moov_data)) = self.cached_moov {
+                let moov_end = moov_off + moov_data.len() as u64;
+                if self.pos >= moov_off && self.pos < moov_end {
+                    let local = (self.pos - moov_off) as usize;
+                    let n = buf.len().min(moov_data.len() - local);
+                    buf[..n].copy_from_slice(&moov_data[local..local + n]);
+                    self.pos += n as u64;
+                    break n;
+                }
+            }
+
             let s = self.inner.state.lock().unwrap_or_else(|e| e.into_inner());
 
-            // Try serving from the retained file header (ftyp).
-            if let Some(ref hdr) = s.header
+            // Populate caches from state if not yet set (one-time copy).
+            if self.cached_header.is_none()
+                && let Some(ref hdr) = s.header
+            {
+                self.cached_header = Some(hdr.clone());
+            }
+            if self.cached_moov.is_none()
+                && let Some((off, ref arc)) = s.moov
+            {
+                self.cached_moov = Some((off, std::sync::Arc::clone(arc)));
+            }
+
+            // Retry header/moov from newly-populated caches before hitting
+            // the sliding buffer.  This handles the first read after moov
+            // becomes available.
+            if let Some(ref hdr) = self.cached_header
                 && (self.pos as usize) < hdr.len()
             {
                 let local = self.pos as usize;
@@ -585,9 +635,7 @@ impl std::io::Read for StreamingBuffer {
                 self.pos += n as u64;
                 break n;
             }
-
-            // Try serving from the retained moov atom.
-            if let Some((moov_off, ref moov_data)) = s.moov {
+            if let Some((moov_off, ref moov_data)) = self.cached_moov {
                 let moov_end = moov_off + moov_data.len() as u64;
                 if self.pos >= moov_off && self.pos < moov_end {
                     let local = (self.pos - moov_off) as usize;

crates/oasis-app/src/video_player.rs

@@ -377,7 +377,7 @@ impl VideoPlayer {
         self.frame_height = height;
 
         let (video_tx, video_rx) = mpsc::sync_channel::<VideoFrame>(4);
-        let (audio_tx, audio_rx) = mpsc::sync_channel::<SoftwareAudio>(64);
+        let (audio_tx, audio_rx) = mpsc::sync_channel::<SoftwareAudio>(256);
         let (stop_tx, stop_rx) = mpsc::channel::<()>();
 
         let target_w = width;
@@ -398,12 +398,20 @@ impl VideoPlayer {
                 },
             );
             let t0 = std::time::Instant::now();
+            // With the symphonia backend, extract avcC from moov to skip
+            // the full-file scan. With ffmpeg, it handles avcC internally.
+            #[cfg(not(feature = "video-decode-ffmpeg"))]
             let open_result = if let Some(ref moov) = moov_data {
                 let avcc = oasis_video::find_avcc_in_mp4(moov);
                 oasis_video::SoftwareVideoDecoder::open_stream_with_avcc(source, avcc)
             } else {
                 oasis_video::SoftwareVideoDecoder::open_stream(source)
             };
+            #[cfg(feature = "video-decode-ffmpeg")]
+            let open_result = {
+                let _ = &moov_data; // suppress unused warning
+                oasis_video::SoftwareVideoDecoder::open_stream(source)
+            };
             let mut decoder = match open_result {
                 Ok(d) => {
                     log::info!(
@@ -466,7 +474,7 @@ impl VideoPlayer {
         height: u32,
     ) {
         let (video_tx, video_rx) = mpsc::sync_channel::<VideoFrame>(4);
-        let (audio_tx, audio_rx) = mpsc::sync_channel::<SoftwareAudio>(64);
+        let (audio_tx, audio_rx) = mpsc::sync_channel::<SoftwareAudio>(256);
         let (stop_tx, stop_rx) = mpsc::channel::<()>();
 
         std::thread::spawn(move || {
@@ -522,8 +530,8 @@ impl VideoPlayer {
         video_tx: mpsc::SyncSender<VideoFrame>,
         audio_tx: mpsc::SyncSender<SoftwareAudio>,
         stop_rx: mpsc::Receiver<()>,
-        target_w: u32,
-        target_h: u32,
+        _target_w: u32,
+        _target_h: u32,
     ) {
         log::info!("VideoPlayer: software decode thread started");
 
@@ -567,26 +575,13 @@ impl VideoPlayer {
                             );
                         }
                         let ts = frame.timestamp_secs;
-                        let (data, w, h) = if frame.width == target_w && frame.height == target_h {
-                            (frame.rgba, frame.width, frame.height)
-                        } else {
-                            (
-                                simple_scale(
-                                    &frame.rgba,
-                                    frame.width,
-                                    frame.height,
-                                    target_w,
-                                    target_h,
-                                ),
-                                target_w,
-                                target_h,
-                            )
-                        };
+                        // Send native-resolution frames — scaling is done on
+                        // the main thread to keep the decode thread unblocked.
                         if video_tx
                             .send(VideoFrame {
-                                data,
-                                width: w,
-                                height: h,
+                                data: frame.rgba,
+                                width: frame.width,
+                                height: frame.height,
                                 timestamp_secs: ts,
                             })
                             .is_err()
@@ -805,7 +800,18 @@ impl VideoPlayer {
             #[cfg(feature = "_video")]
             let frame_ts = frame.timestamp_secs;
 
-            match backend.load_texture(fw, fh, &frame.data) {
+            // Scale on the main thread (moved from decode thread to avoid
+            // blocking decode with CPU-intensive scaling).
+            let needs_scale = fw != self.frame_width || fh != self.frame_height;
+            let scaled;
+            let (tex_data, upload_w, upload_h) = if needs_scale {
+                scaled = simple_scale(&frame.data, fw, fh, self.frame_width, self.frame_height);
+                (scaled.as_slice(), self.frame_width, self.frame_height)
+            } else {
+                (frame.data.as_slice(), fw, fh)
+            };
+
+            match backend.load_texture(upload_w, upload_h, tex_data) {
                 Ok(tex) => {
                     self.current_texture = Some(tex);
                     self.last_frame_time = Some(Instant::now());
@@ -950,14 +956,26 @@ impl VideoPlayer {
 /// Nearest-neighbor RGBA scale.
 #[cfg(feature = "_video")]
 fn simple_scale(src: &[u8], src_w: u32, src_h: u32, dst_w: u32, dst_h: u32) -> Vec<u8> {
-    let mut dst = vec![0u8; (dst_w * dst_h * 4) as usize];
-    for y in 0..dst_h {
-        let sy = (y * src_h / dst_h).min(src_h - 1);
-        for x in 0..dst_w {
-            let sx = (x * src_w / dst_w).min(src_w - 1);
-            let si = (sy * src_w + sx) as usize * 4;
-            let di = (y * dst_w + x) as usize * 4;
-            dst[di..di + 4].copy_from_slice(&src[si..si + 4]);
+    let sw = src_w as usize;
+    let sh = src_h as usize;
+    let dw = dst_w as usize;
+    let dh = dst_h as usize;
+    let mut dst = vec![0u8; dw * dh * 4];
+
+    for y in 0..dh {
+        let sy = (y * sh / dh).min(sh - 1);
+        let src_row = sy * sw * 4;
+        let dst_row = y * dw * 4;
+
+        for x in 0..dw {
+            let sx = (x * sw / dw).min(sw - 1);
+            let si = src_row + sx * 4;
+            let di = dst_row + x * 4;
+            // SAFETY: si + 4 <= src.len() because sy < src_h and sx < src_w,
+            // di + 4 <= dst.len() because y < dst_h and x < dst_w.
+            unsafe {
+                std::ptr::copy_nonoverlapping(src.as_ptr().add(si), dst.as_mut_ptr().add(di), 4);
+            }
         }
     }
     dst

crates/oasis-video/Cargo.toml

@@ -32,11 +32,10 @@ symphonia = { version = "0.5", default-features = false, features = [
 # H.264 decoding (Cisco OpenH264 C source compiled via cc)
 openh264 = { version = "0.9", optional = true }
 
-# FFmpeg via Rust bindings — static build from source, no runtime deps.
+# FFmpeg via Rust bindings — links against system ffmpeg (pkg-config).
+# For static builds (CI/shipping), add "build" + "static" features.
 # Only H.264 + AAC codecs and MP4 demuxer are needed.
 ffmpeg-next = { version = "7", optional = true, default-features = false, features = [
-    "build",
-    "static",
     "codec",
     "format",
     "software-resampling",

crates/oasis-video/src/aac.rs

@@ -1,6 +1,6 @@
 //! AAC audio decoder wrapping symphonia's AAC codec.
 
-use symphonia::core::audio::SampleBuffer;
+use symphonia::core::audio::{SampleBuffer, SignalSpec};
 use symphonia::core::codecs::{CODEC_TYPE_AAC, CodecParameters, Decoder, DecoderOptions};
 use symphonia::core::formats::Packet;
 
@@ -18,6 +18,12 @@ pub struct AacDecoder {
     decoder: Box<dyn Decoder>,
     sample_rate: u32,
     channels: u16,
+    /// Reusable sample buffer — avoids allocating a new `SampleBuffer` on
+    /// every `decode()` call.  Recreated only when the audio spec changes
+    /// (rare for AAC-LC; can happen with HE-AAC SBR).
+    sample_buf: Option<SampleBuffer<f32>>,
+    /// Tracks the last audio spec to detect mid-stream spec changes (e.g. HE-AAC SBR).
+    last_spec: Option<SignalSpec>,
 }
 
 impl AacDecoder {
@@ -42,6 +48,8 @@ impl AacDecoder {
             decoder,
             sample_rate,
             channels,
+            sample_buf: None,
+            last_spec: None,
         })
     }
 
@@ -62,7 +70,17 @@ impl AacDecoder {
             return Ok(None);
         }
 
-        let mut sample_buf = SampleBuffer::<f32>::new(duration as u64, spec);
+        // Reuse the sample buffer if its capacity and spec still match.
+        // Recreate when the audio spec changes (rare for AAC-LC) or capacity is insufficient.
+        let need_new = self
+            .sample_buf
+            .as_ref()
+            .is_none_or(|sb| sb.capacity() < duration || self.last_spec.as_ref() != Some(&spec));
+        if need_new {
+            self.sample_buf = Some(SampleBuffer::<f32>::new(duration as u64, spec));
+            self.last_spec = Some(spec);
+        }
+        let sample_buf = self.sample_buf.as_mut().expect("just created above");
         sample_buf.copy_interleaved_ref(decoded);
 
         Ok(Some(DecodedAudio {

crates/oasis-video/src/demux.rs

@@ -153,6 +153,21 @@ pub fn find_avcc_in_mp4(mp4_data: &[u8]) -> Option<AvccConfig> {
 /// with start codes.
 fn avcc_to_annex_b(data: &[u8], nal_length_size: usize) -> Result<Vec<u8>, VideoError> {
     let mut out = Vec::with_capacity(data.len() + 32);
+    avcc_to_annex_b_into(data, nal_length_size, &mut out)?;
+    Ok(out)
+}
+
+/// Convert AVCC to Annex B, reusing the provided output buffer.
+///
+/// Clears `out` before writing.  The caller retains the buffer across calls
+/// so its capacity grows to the largest packet and stays stable, eliminating
+/// per-packet allocation.
+fn avcc_to_annex_b_into(
+    data: &[u8],
+    nal_length_size: usize,
+    out: &mut Vec<u8>,
+) -> Result<(), VideoError> {
+    out.clear();
     let mut offset = 0;
 
     while offset + nal_length_size <= data.len() {
@@ -186,7 +201,7 @@ fn avcc_to_annex_b(data: &[u8], nal_length_size: usize) -> Result<Vec<u8>, Video
         offset += nal_len;
     }
 
-    Ok(out)
+    Ok(())
 }
 
 /// MP4 demuxer backed by symphonia.