S.P.A.N. — Stereo-Panel Amplification Nexus

Belmont Labs · Multi-Screen YouTube Player powered by mpv + yt-dlp

---

╔══════════════════════════════════════════════════════════════════╗
║   B E L M O N T   L A B S                                        ║
║   Stereo-Panel Amplification Nexus  ·  S.P.A.N.                  ║
║                                                                  ║
║   Spans YouTube video across multiple screens via mpv + yt-dlp   ║
║   Built-in remote control server — send URLs from your phone     ║
╚══════════════════════════════════════════════════════════════════╝

S.P.A.N. is a Python GUI frontend that lets you launch YouTube (and other yt-dlp-supported) streams through mpv with precise multi-monitor control — including spanning video across two screens (or cheap outdoor projectors, in my needs-case) as one seamless canvas. It also runs a local web server so you can send URLs wirelessly from your phone.

Currently there is a known issue with starting new streams while another stream is playing. It wants to start another stream rather than taking control from MPV and starting the new stream as intended. This is something that I am working on and if you have any ideas, feel free to let me know because my head hurts from hitting it on the desk.

---

Local UI

Mobile UI

## Features

• Multi-screen playback — span video across multiple monitors, fullscreen on either, or windowed
• Stretch mode — fill the full window/canvas with no black bars (no horizontal/vertical blank space)
• Quality selection — Best, 1080p, 720p, 480p
• Built-in remote control — phone-accessible web UI at http://<your-ip>:8765 with URL history
• QR code — scan from the app to open the remote on your phone instantly
• yt-dlp stream resolution — separate best-video + best-audio streams for maximum quality
• Hardware decoding — --hwdec=auto for smooth playback
• Aggressive buffering — 300 MiB read-ahead cache for stutter-free streams
• Desktop launcher — installs to KDE/GNOME app menu via --install

---

Requirements

Tool	Purpose
mpv	Video playback engine
yt-dlp	Stream URL resolution
python3-tkinter	GUI framework
python3-qrcode + python3-pillow	QR code generation (optional but recommended)

---

Installation

python3 span.py --install

This will:

1. Install mpv, yt-dlp, python3-tkinter, python3-qrcode, python3-pillow via dnf
2. Update yt-dlp to the latest version
3. Copy span.py to ~/.local/bin/span
4. Create a .desktop launcher for KDE/GNOME app menus

After installation, launch with:

span

Or search S.P.A.N. in your application launcher.

---

Usage

1. Paste a YouTube URL into the URL field (or send one from your phone via the remote)
2. Select a Display mode:
   • Span both screens — video fills both monitors as one canvas
   • Fullscreen – Screen 1 / 2 — fullscreen on a specific monitor
   • Windowed – Screen 1 / 2 — 1280×720 windowed on a specific monitor
3. Set the Combined resolution & offset for span mode (defaults to 3840×1080 +(-1920)+0 for two 1920×1080 screens with screen 2 on the left)
4. Choose Quality and whether to Stretch the video
5. Hit ▶ TRANSMIT

Remote Control (Phone)

Open http://<your-local-ip>:8765 on any device on the same Wi-Fi network, or scan the QR code shown in the app. Paste a URL and tap TRANSMIT — the video starts immediately on the main display.

Span Geometry Reference

Layout	W	H	X	Y
Screen 2 left of Screen 1 (2×1080p)	3840	1080	-1920	0
Screen 1 left of Screen 2 (2×1080p)	3840	1080	0	0
Two 4K screens side-by-side	7680	2160	0	0

---

Platform Notes

S.P.A.N. is developed on Fedora / KDE Plasma / Wayland. It auto-detects the session type and sets --vo=gpu --gpu-context=wayland or x11egl accordingly. It has not been tested on other distributions, though it should work on any Linux system with the dependencies installed.

---

License

MIT — do whatever you want with it.

---

Belmont Labs · belmontlabs.dev