From 6e4d30bfa9ba31e38c7ec5391ff334ea7055e0b5 Mon Sep 17 00:00:00 2001
From: Mollusk <silvernode@gmail.com>
Date: Thu, 21 May 2026 05:28:19 -0400
Subject: [PATCH] vlc-plugin-dvb: document and warn at launch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VLC's MPEG-TS demuxer (libts_plugin.so) ships in a separate package on
Arch / CachyOS (vlc-plugin-dvb). Without it, VLC silently falls back
to the PS demuxer and misidentifies our H.264 stream — the symptom is
a green screen. mpv doesn't share this dependency.

- README: list vlc-plugin-dvb under requirements, replace the
  "green screen, not yet diagnosed" gotcha with the diagnosis.
- interactive.rs: when the user picks VLC, check for
  /usr/lib/vlc/plugins/demux/libts_plugin.so and print a warning to
  stderr if it's missing. Soft warning, not a hard error — VLC still
  spawns so the user can confirm the symptom for themselves.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md          | 14 ++++++++++----
 src/interactive.rs | 29 +++++++++++++++++++++++++----
 2 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 3337ea5..c471c97 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,6 @@ Not yet working:
 - X11 capture (stubbed, returns an error)
 - Per-app audio routing (`--app <name>` is a flag stub)
 - Multi-viewer (single viewer per host by design right now)
-- VLC client renders the H.264 stream as a green screen — mpv works
 - `--repair` (PipeWire orphan cleanup) is a stub
 
 ## Quick start
@@ -68,6 +67,10 @@ pixelpass <ticket>
   - `gstreamer`, `gst-plugins-base`, `gst-plugins-good`, `gst-plugins-bad`,
     `gst-plugins-ugly`, `gst-libav`, `gst-plugin-va`, `gst-plugin-pipewire`
 - A player: `mpv` (recommended) or `vlc`
+- If you use VLC: `vlc-plugin-dvb` must also be installed. Arch / CachyOS
+  ship VLC's MPEG-TS demuxer (`libts_plugin.so`) in that separate
+  package, and without it VLC misidentifies the H.264 stream and shows
+  a green screen. mpv is unaffected.
 - PipeWire (for screencast portal + audio capture)
 
 On Arch / CachyOS:
@@ -77,6 +80,8 @@ sudo pacman -S gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad \
                gst-plugins-ugly gst-libav gst-plugin-va gst-plugin-pipewire \
                libva-utils mpv
 # plus your GPU's VAAPI driver
+# plus, if you want to use VLC instead of mpv:
+sudo pacman -S vlc vlc-plugin-dvb
 ```
 
 If the viewer is running on battery, set the CPU governor to performance
@@ -146,9 +151,10 @@ relay path otherwise. Both have been verified end-to-end.
 
 ## Known limitations and gotchas
 
-- **VLC shows a green screen** against a stream mpv handles correctly.
-  Likely a VLC-specific PCR / PMT / alignment expectation; not yet
-  diagnosed. Use mpv until this is fixed.
+- **VLC needs `vlc-plugin-dvb`** to demux MPEG-TS on Arch / CachyOS. The
+  symptom of missing it is a green screen — VLC falls back to the PS
+  demuxer and misidentifies the H.264 stream. pixelpass warns at
+  player-launch time if the plugin isn't on disk. mpv doesn't need it.
 - **Audio echo** if the host plays the stream through speakers and
   captures system audio — expected, the mic / monitor picks up the
   playback. Headphones bypass it.
diff --git a/src/interactive.rs b/src/interactive.rs
index 473d6db..1ecf53a 100644
--- a/src/interactive.rs
+++ b/src/interactive.rs
@@ -68,14 +68,35 @@ impl Player {
                     url,
                 ],
             ),
-            Player::Vlc => crate::common::process::spawn_detached(
-                "vlc",
-                &["--network-caching=200", "--live-caching=200", url],
-            ),
+            Player::Vlc => {
+                warn_if_vlc_ts_demuxer_missing();
+                crate::common::process::spawn_detached(
+                    "vlc",
+                    &["--network-caching=200", "--live-caching=200", url],
+                )
+            }
         }
     }
 }
 
+// VLC's MPEG-TS demuxer ships in a separate package on Arch / CachyOS
+// (`vlc-plugin-dvb`). Without it VLC falls through to the PS demuxer
+// and shows a green screen.
+fn warn_if_vlc_ts_demuxer_missing() {
+    const TS_DEMUX_PLUGIN: &str = "/usr/lib/vlc/plugins/demux/libts_plugin.so";
+    if !std::path::Path::new(TS_DEMUX_PLUGIN).exists() {
+        eprintln!();
+        eprintln!(
+            "Warning: VLC's MPEG-TS demuxer plugin ({TS_DEMUX_PLUGIN}) is missing."
+        );
+        eprintln!(
+            "         On Arch / CachyOS, install `vlc-plugin-dvb`. Without it,"
+        );
+        eprintln!("         VLC will show a green screen. mpv is unaffected.");
+        eprintln!();
+    }
+}
+
 pub fn prompt_player() -> Result<Player> {
     let theme = ColorfulTheme::default();
     let choice = Select::with_theme(&theme)