fix(video): enable NVDEC in Linux release builds

.github/workflows/release.yml

@@ -78,7 +78,7 @@ jobs:
         run: |
           mkdir -p "${{ github.workspace }}/.vcpkg-cache"
           /opt/vcpkg/vcpkg install \
-            'ffmpeg[core,avcodec,avformat,swscale,swresample]:x64-linux-static' \
+            'ffmpeg[core,avcodec,avformat,swscale,swresample,nvcodec]:x64-linux-static' \
             --overlay-triplets="$GITHUB_WORKSPACE/.github/vcpkg-triplets"
 
       - name: Install stable Rust
@@ -110,6 +110,17 @@ jobs:
           PKG_CONFIG_ALL_STATIC: "1"
         run: cargo build --release --bin wallr --features static-ffmpeg
 
+      - name: Verify static FFmpeg hardware support
+        env:
+          MEDIA_PREFIX: /opt/vcpkg/installed/x64-linux-static
+          PKG_CONFIG_PATH: /opt/vcpkg/installed/x64-linux-static/lib/pkgconfig
+          PKG_CONFIG_ALL_STATIC: "1"
+        run: |
+          set -euo pipefail
+          capabilities=$(cargo run -q -p wallr-core --example video_probe --release --features static-ffmpeg -- --capabilities)
+          printf '%s\n' "$capabilities"
+          grep -qx 'cuda: enabled' <<<"$capabilities"
+
       - name: Verify binary is self-contained
         run: |
           set -euo pipefail

CHANGELOG.md

@@ -25,6 +25,10 @@ and versions follow [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- Linux release binaries now include FFmpeg NVCodec support, so configured
+  NVDEC playback no longer silently falls back to CPU decoding.
+- Explicit hardware decode failures are reported as software fallback rather
+  than ordinary software decoding.
 - Fixed false hardware-decoding reports when a decoder opened but produced no
   hardware frames.
 - Fixed decoder shutdown caused by transient queue pressure.

docs/video-wallpaper.md

@@ -20,6 +20,9 @@ MP4, WebM, MKV, MOV, and AVI. Anything FFmpeg can demux is a candidate; the FFmp
 - Frames are decoded into a small bounded latest-frame queue and presented on PTS timing. Temporary queue pressure drops stale frames instead of terminating the decoder or allowing memory growth.
 - `wallpaper.loop_video` (default `true`) restarts the stream when it ends, producing a continuous loop.
 - `wallr ipc info` distinguishes hardware negotiation, active hardware frames, software decoding, software fallback, and decoder failure. A backend is not reported as active until a hardware frame has actually been received.
+- Official Linux release binaries include FFmpeg NVCodec support; NVDEC still
+  loads the installed NVIDIA driver at runtime and falls back cleanly when it
+  is unavailable.
 
 ## Playback control
 

scripts/benchmark-video.sh

@@ -10,37 +10,70 @@ report=${BENCHMARK_REPORT:-"$root_dir/benchmarks/video-$(date -u +%Y%m%d-%H%M%S)
 
 [[ -s "$input" ]] || { echo "error: missing video: $input" >&2; exit 2; }
 mkdir -p "$(dirname "$report")"
+probe="$root_dir/target/release/examples/video_probe"
+cargo build -q -p wallr-core --example video_probe --release
 
 run_probe() {
     local backend=$1
-    cargo run -q -p wallr-core --example video_probe --release -- "$input" "$backend" 2>&1
+    TIMEFORMAT='wall_seconds=%R user_seconds=%U system_seconds=%S'
+    { time "$probe" "$input" "$backend"; } 2>&1
 }
 
-software=$(run_probe software)
+software=$(run_probe software) || { printf '%s\n' "$software" >&2; exit 1; }
+if ! grep -qx 'result: PASS' <<<"$software"; then
+    printf 'error: software probe failed; no benchmark report generated\n%s\n' "$software" >&2
+    exit 1
+fi
 vaapi=$(run_probe vaapi || true)
+nvdec=$(run_probe nvdec || true)
 
 frames=$(awk '/^decoded / {print $2; exit}' <<<"$software")
+vaapi_frames=$(awk '/^decoded / {print $2; exit}' <<<"$vaapi")
+nvdec_frames=$(awk '/^decoded / {print $2; exit}' <<<"$nvdec")
 software_rate=$(sed -n 's/^decoded .* (\([0-9.]*\) fps,.*/\1/p' <<<"$software" | head -n1)
-software_state=$(sed -n 's/^active backend: \([^ ]*\) (state:.*/\1/p' <<<"$software" | head -n1)
+software_state=$(sed -n 's/^active backend: .* (state: \([^,]*\),.*/\1/p' <<<"$software" | head -n1)
 vaapi_rate=$(sed -n 's/^decoded .* (\([0-9.]*\) fps,.*/\1/p' <<<"$vaapi" | head -n1)
-vaapi_state=$(sed -n 's/^active backend: \([^ ]*\) (state:.*/\1/p' <<<"$vaapi" | head -n1)
+vaapi_backend=$(sed -n 's/^active backend: \([^ ]*\) (state:.*/\1/p' <<<"$vaapi" | head -n1)
+vaapi_state=$(sed -n 's/^active backend: .* (state: \([^,]*\),.*/\1/p' <<<"$vaapi" | head -n1)
+nvdec_rate=$(sed -n 's/^decoded .* (\([0-9.]*\) fps,.*/\1/p' <<<"$nvdec" | head -n1)
+nvdec_backend=$(sed -n 's/^active backend: \([^ ]*\) (state:.*/\1/p' <<<"$nvdec" | head -n1)
+nvdec_state=$(sed -n 's/^active backend: .* (state: \([^,]*\),.*/\1/p' <<<"$nvdec" | head -n1)
 software_drops=$(awk -F'dropped frames: ' '/^active backend:/ {gsub(/\).*/, "", $2); print $2; exit}' <<<"$software")
 vaapi_drops=$(awk -F'dropped frames: ' '/^active backend:/ {gsub(/\).*/, "", $2); print $2; exit}' <<<"$vaapi")
+nvdec_drops=$(awk -F'dropped frames: ' '/^active backend:/ {gsub(/\).*/, "", $2); print $2; exit}' <<<"$nvdec")
+software_cpu=$(awk -F'[ =]' '/^wall_seconds=/ {printf "%.3f", $4 + $6; exit}' <<<"$software")
+vaapi_cpu=$(awk -F'[ =]' '/^wall_seconds=/ {printf "%.3f", $4 + $6; exit}' <<<"$vaapi")
+nvdec_cpu=$(awk -F'[ =]' '/^wall_seconds=/ {printf "%.3f", $4 + $6; exit}' <<<"$nvdec")
+
+vaapi_reason=""
+if [[ $vaapi_backend != VAAPI || $vaapi_state != 'hardware active' ]] || ! grep -qx 'result: PASS' <<<"$vaapi" || ! grep -qx 'fallback occurred: false' <<<"$vaapi"; then
+    vaapi_reason="probe failed, fell back, or did not remain hardware active (backend: ${vaapi_backend:-unavailable}, state: ${vaapi_state:-unavailable})"
+    vaapi_frames= vaapi_rate= vaapi_cpu= vaapi_drops=
+fi
+
+nvdec_reason=""
+if [[ $nvdec_backend != NVDEC || $nvdec_state != 'hardware active' ]] || ! grep -qx 'result: PASS' <<<"$nvdec" || ! grep -qx 'fallback occurred: false' <<<"$nvdec"; then
+    nvdec_reason="probe failed, fell back, or did not remain hardware active (backend: ${nvdec_backend:-unavailable}, state: ${nvdec_state:-unavailable})"
+    nvdec_frames= nvdec_rate= nvdec_cpu= nvdec_drops=
+fi
 
 {
     echo "# Wallr video decoder benchmark"
     echo
     echo "Machine-specific decoder measurements. This report does not measure compositor presentation or GPU render time."
     echo
     printf -- '- Date (UTC): %s\n' "$(date -u '+%Y-%m-%d %H:%M:%S')"
-    printf -- '- Host: %s\n' "$(hostname)"
+    printf -- '- Host: %s\n' "$(uname -n)"
     printf -- '- Input: `%s`\n' "$input"
     printf -- '- Wallr version: %s\n' "$(cargo run -q -p wallr -- --version 2>/dev/null)"
     echo
-    echo "| Backend | Frames | Throughput (fps) | Decoder state | Dropped frames |"
-    echo "|:--|--:|--:|:--|--:|"
-    printf '| Software | %s | %s | %s | %s |\n' "${frames:-unavailable}" "${software_rate:-unavailable}" "${software_state:-unavailable}" "${software_drops:-unavailable}"
-    printf '| VAAPI | %s | %s | %s | %s |\n' "${frames:-unavailable}" "${vaapi_rate:-unavailable}" "${vaapi_state:-unavailable}" "${vaapi_drops:-unavailable}"
+    echo "| Backend | Frames | Throughput (fps) | CPU time (s) | Decoder state | Dropped frames |"
+    echo "|:--|--:|--:|--:|:--|--:|"
+    printf '| Software | %s | %s | %s | %s | %s |\n' "${frames:-unavailable}" "${software_rate:-unavailable}" "${software_cpu:-unavailable}" "${software_state:-unavailable}" "${software_drops:-unavailable}"
+    printf '| VAAPI | %s | %s | %s | %s | %s |\n' "${vaapi_frames:-unavailable}" "${vaapi_rate:-unavailable}" "${vaapi_cpu:-unavailable}" "${vaapi_state:-unavailable}" "${vaapi_drops:-unavailable}"
+    printf '| NVDEC | %s | %s | %s | %s | %s |\n' "${nvdec_frames:-unavailable}" "${nvdec_rate:-unavailable}" "${nvdec_cpu:-unavailable}" "${nvdec_state:-unavailable}" "${nvdec_drops:-unavailable}"
+    [[ -z $vaapi_reason ]] || printf '\n- VAAPI unavailable: %s.\n' "$vaapi_reason"
+    [[ -z $nvdec_reason ]] || printf '\n- NVDEC unavailable: %s.\n' "$nvdec_reason"
 } >"$report"
 
 echo "Report saved to: $report"

wallr-core/examples/video_probe.rs

@@ -11,6 +11,10 @@ use wallr_core::video::{HwAccel, VideoDecoder};
 fn main() {
     let mut args = std::env::args().skip(1);
     let path = args.next().expect("usage: video_probe <video> [backend]");
+    if path == "--capabilities" {
+        print_capabilities();
+        return;
+    }
     let backend = match args.next().as_deref() {
         Some("vaapi") => HwAccel::Vaapi,
         Some("nvdec") => HwAccel::Nvdec,
@@ -71,5 +75,46 @@ fn main() {
         decoder.decoder_state().name(),
         decoder.dropped_frames()
     );
+    println!("fallback occurred: {}", decoder.fallback_occurred());
     println!("result: {}", if count > 30 { "PASS" } else { "FAIL" });
 }
+
+fn print_capabilities() {
+    println!(
+        "cuda: {}",
+        if h264_supports_pixel_format(ffmpeg_next::ffi::AVPixelFormat::AV_PIX_FMT_CUDA) {
+            "enabled"
+        } else {
+            "disabled"
+        }
+    );
+    for (name, backend) in [("vaapi", "vaapi"), ("videotoolbox", "videotoolbox")] {
+        let backend = std::ffi::CString::new(backend).expect("static backend name");
+        let available = unsafe {
+            ffmpeg_next::ffi::av_hwdevice_find_type_by_name(backend.as_ptr())
+                != ffmpeg_next::ffi::AVHWDeviceType::AV_HWDEVICE_TYPE_NONE
+        };
+        println!("{name}: {}", if available { "enabled" } else { "disabled" });
+    }
+}
+
+fn h264_supports_pixel_format(pixel_format: ffmpeg_next::ffi::AVPixelFormat) -> bool {
+    unsafe {
+        let codec =
+            ffmpeg_next::ffi::avcodec_find_decoder(ffmpeg_next::ffi::AVCodecID::AV_CODEC_ID_H264);
+        if codec.is_null() {
+            return false;
+        }
+        let mut index = 0;
+        loop {
+            let config = ffmpeg_next::ffi::avcodec_get_hw_config(codec, index);
+            if config.is_null() {
+                return false;
+            }
+            if (*config).pix_fmt == pixel_format {
+                return true;
+            }
+            index += 1;
+        }
+    }
+}

wallr-core/src/video/decoder.rs

@@ -210,6 +210,7 @@ pub struct VideoDecoder {
     seek_epoch: Arc<AtomicU64>,
     hw_in_use: Arc<AtomicU8>,
     decoder_state: Arc<AtomicU8>,
+    fallback_occurred: Arc<AtomicBool>,
     decode_thread: Option<thread::JoinHandle<()>>,
 }
 
@@ -256,6 +257,8 @@ impl VideoDecoder {
         let hw_in_use_clone = hw_in_use.clone();
         let decoder_state = Arc::new(AtomicU8::new(DecoderState::Initializing.code()));
         let decoder_state_clone = decoder_state.clone();
+        let fallback_occurred = Arc::new(AtomicBool::new(false));
+        let fallback_clone = fallback_occurred.clone();
         let frame_queue_clone = frame_queue.clone();
         let dropped_frames_clone = dropped_frames.clone();
 
@@ -273,6 +276,7 @@ impl VideoDecoder {
                     seek_epoch_clone,
                     hw_in_use_clone.clone(),
                     decoder_state_clone.clone(),
+                    fallback_clone,
                     loop_video,
                 );
                 let used = match used {
@@ -298,6 +302,7 @@ impl VideoDecoder {
             seek_epoch,
             hw_in_use,
             decoder_state,
+            fallback_occurred,
             decode_thread: Some(decode_thread),
         })
     }
@@ -477,7 +482,8 @@ impl VideoDecoder {
     fn build_decoder(
         stream: &ffmpeg::format::stream::Stream,
         hw_accel: HwAccel,
-    ) -> (ffmpeg::codec::decoder::Video, HwAccel) {
+    ) -> (ffmpeg::codec::decoder::Video, HwAccel, DecoderState) {
+        let mut hardware_attempted = false;
         match hw_accel {
             HwAccel::Auto => {
                 // Probe only what this machine can actually use, in
@@ -488,8 +494,9 @@ impl VideoDecoder {
                 let mut tried = 0;
                 for backend in HwAccel::auto_hardware_order() {
                     tried += 1;
+                    hardware_attempted = true;
                     if let Some(result) = Self::try_hw_decoder(stream, backend) {
-                        return result;
+                        return (result.0, result.1, DecoderState::HardwareNegotiating);
                     }
                 }
                 if tried == 0 {
@@ -504,8 +511,9 @@ impl VideoDecoder {
             }
             specific => {
                 // Try the requested hardware backend first
+                hardware_attempted = true;
                 if let Some(result) = Self::try_hw_decoder(stream, specific) {
-                    return result;
+                    return (result.0, result.1, DecoderState::HardwareNegotiating);
                 }
                 // Fall back to software
                 tracing::info!(
@@ -519,7 +527,8 @@ impl VideoDecoder {
         let decoder = ffmpeg::codec::context::Context::from_parameters(stream.parameters())
             .and_then(|ctx| ctx.decoder().video())
             .expect("software decoder must be available");
-        (decoder, HwAccel::Software)
+        let state = software_decoder_state(hardware_attempted);
+        (decoder, HwAccel::Software, state)
     }
 
     #[allow(clippy::too_many_arguments)]
@@ -534,6 +543,7 @@ impl VideoDecoder {
         seek_epoch: Arc<AtomicU64>,
         hw_in_use: Arc<AtomicU8>,
         decoder_state: Arc<AtomicU8>,
+        fallback_occurred: Arc<AtomicBool>,
         loop_video: bool,
     ) -> VideoResult<HwAccel> {
         let mut ictx = ffmpeg::format::input(&path).map_err(|e| VideoError::FileOpen {
@@ -549,14 +559,11 @@ impl VideoDecoder {
         let video_stream_index = stream.index();
         let time_base = stream.time_base();
 
-        let (mut decoder, used_hw) = Self::build_decoder(&stream, hw_accel);
+        let (mut decoder, used_hw, initial_state) = Self::build_decoder(&stream, hw_accel);
         tracing::info!("Decoder in use: {}", used_hw.name());
-        decoder_state.store(
-            if used_hw == HwAccel::Software {
-                DecoderState::SoftwareActive.code()
-            } else {
-                DecoderState::HardwareNegotiating.code()
-            },
+        decoder_state.store(initial_state.code(), Ordering::Release);
+        fallback_occurred.store(
+            initial_state == DecoderState::SoftwareFallback,
             Ordering::Release,
         );
 
@@ -688,9 +695,17 @@ impl VideoDecoder {
                         }
                         hardware_frame_seen = true;
                         hw_in_use.store(used_hw.code(), Ordering::Release);
-                        decoder_state.store(DecoderState::HardwareActive.code(), Ordering::Release);
+                        decoder_state
+                            .store(frame_decoder_state(used_hw, true).code(), Ordering::Release);
                         &sw_frame
                     } else {
+                        hw_in_use.store(HwAccel::Software.code(), Ordering::Release);
+                        // Preserve initialization fallback and remember any software
+                        // frames even if hardware decoding resumes later.
+                        decoder_state.store(
+                            observe_software_frame(used_hw, &fallback_occurred).code(),
+                            Ordering::Release,
+                        );
                         &decoded_frame
                     };
 
@@ -858,6 +873,11 @@ impl VideoDecoder {
         DecoderState::from_code(self.decoder_state.load(Ordering::Acquire))
     }
 
+    /// Whether this decoder has ever fallen back, including before recovery.
+    pub fn fallback_occurred(&self) -> bool {
+        self.fallback_occurred.load(Ordering::Acquire)
+    }
+
     pub fn is_video_file<P: AsRef<Path>>(path: P) -> bool {
         path.as_ref()
             .extension()
@@ -942,6 +962,31 @@ fn ensure_ffmpeg_init() -> VideoResult<()> {
         .map(|_| ())
 }
 
+const fn software_decoder_state(hardware_attempted: bool) -> DecoderState {
+    if hardware_attempted {
+        DecoderState::SoftwareFallback
+    } else {
+        DecoderState::SoftwareActive
+    }
+}
+
+const fn frame_decoder_state(selected_backend: HwAccel, hardware_frame: bool) -> DecoderState {
+    if hardware_frame {
+        DecoderState::HardwareActive
+    } else if matches!(selected_backend, HwAccel::Software) {
+        DecoderState::SoftwareActive
+    } else {
+        DecoderState::SoftwareFallback
+    }
+}
+
+fn observe_software_frame(selected_backend: HwAccel, fallback: &AtomicBool) -> DecoderState {
+    if selected_backend != HwAccel::Software {
+        fallback.store(true, Ordering::Release);
+    }
+    software_decoder_state(fallback.load(Ordering::Acquire))
+}
+
 /// True when any `/sys/class/drm/card*` sibling reports NVIDIA vendor 0x10de.
 fn nvidia_gpu_present() -> bool {
     any_nvidia_card(std::path::Path::new("/sys/class/drm"))
@@ -1188,6 +1233,47 @@ mod tests {
             DecoderState::from_code(DecoderState::Failed.code()),
             DecoderState::Failed
         );
+        assert_eq!(software_decoder_state(true), DecoderState::SoftwareFallback);
+        assert_eq!(software_decoder_state(false), DecoderState::SoftwareActive);
+    }
+
+    #[test]
+    fn software_frame_from_hardware_decoder_reports_fallback() {
+        assert_eq!(
+            frame_decoder_state(HwAccel::Nvdec, false),
+            DecoderState::SoftwareFallback
+        );
+        assert_eq!(
+            frame_decoder_state(HwAccel::Nvdec, true),
+            DecoderState::HardwareActive
+        );
+        assert_eq!(
+            frame_decoder_state(HwAccel::Software, false),
+            DecoderState::SoftwareActive
+        );
+    }
+
+    #[test]
+    fn fallback_history_survives_recovery_and_software_frames() {
+        let fallback = AtomicBool::new(false);
+        assert_eq!(
+            observe_software_frame(HwAccel::Software, &fallback),
+            DecoderState::SoftwareActive
+        );
+        assert!(!fallback.load(Ordering::Acquire));
+        assert_eq!(
+            observe_software_frame(HwAccel::Nvdec, &fallback),
+            DecoderState::SoftwareFallback
+        );
+        assert_eq!(
+            frame_decoder_state(HwAccel::Nvdec, true),
+            DecoderState::HardwareActive
+        );
+        assert!(fallback.load(Ordering::Acquire));
+        assert_eq!(
+            observe_software_frame(HwAccel::Software, &fallback),
+            DecoderState::SoftwareFallback
+        );
     }
 
     #[test]