README
¶
estreia
A TUI video player for headless machines. Browse and play local files, DVDs, Blu-rays, and YouTube videos via mpv with DRM/KMS output, controlled over SSH.
Features
- File browser with DVD and Blu-ray folder detection
- Plays local video files, DVD folders, Blu-ray folders, and YouTube URLs
- Direct DRM/KMS video output (no X11, no Wayland, no desktop environment)
- Full playback control: pause, seek, volume
- Hardware-accelerated decoding
- Designed for SSH control of headless Raspberry Pi or similar
Dependencies
- mpv (video playback)
- yt-dlp (YouTube stream resolution)
Installation
go install codeberg.org/curiosa/estreia@latest
Then install dependencies:
estreia install
This checks for mpv and yt-dlp and installs any that are missing.
Configuration
Config is stored at ~/.config/estreia/config.json:
{
"media_root": "/mnt/hd",
"audio_device": ""
}
Set media_root to the path where your videos are stored.
Set audio_device if you need to override the default (e.g. for
HDMI audio or the analog headphone jack).
Usage
SSH into your headless machine and run:
estreia
Browser Controls
| Key | Action |
|---|---|
| up / k | Move cursor up |
| down / j | Move cursor down |
| enter / right / l | Open directory / play |
| esc / left / h | Go up one directory |
| home / g | Jump to top |
| end / G | Jump to bottom |
| u | Enter a URL |
| y | YouTube subscriptions |
| s | Settings |
| r | Refresh listing |
| q / ctrl+c | Quit |
The browser detects DVD folders (containing VIDEO_TS/) and Blu-ray folders (containing BDMV/) and presents them as single playable items rather than showing their internal structure. Hidden directories (starting with ".") are skipped.
Playback Controls
| Key | Action |
|---|---|
| space | Pause / resume |
| left / right | Seek ±5 seconds |
| shift+left/right | Seek ±30 seconds |
| up / down | Volume ±5% |
| q / esc | Stop playback |
When playback ends, estreia returns to the browser automatically.
How It Works
estreia launches mpv in idle mode with --vo=drm for direct framebuffer
output and --input-ipc-server for JSON IPC control. The TUI
communicates with mpv over a Unix domain socket using mpv's JSON IPC
protocol.
mpv handles YouTube via its built-in yt-dlp integration. When you enter a YouTube URL, mpv calls yt-dlp to resolve the stream URL and plays it directly.
Media Detection
| Type | Detection | Playback |
|---|---|---|
| Video | File extension (.mp4, .mkv, etc.) | Direct file path |
| DVD | Directory contains VIDEO_TS/ | dvd:// protocol |
| Blu-ray | Directory contains BDMV/ | bd:// protocol |
YouTube
estreia can browse your YouTube subscription feed and play videos. This requires exporting cookies from your browser.
Setup
-
Install a browser extension to export cookies in Netscape format (e.g. "Get cookies.txt LOCALLY")
-
Export your cookies to a file
-
On your local machine, filter and upload to the Pi:
estreia upload-cookies ~/Downloads/cookies.txt odette
This extracts only YouTube/Google cookies and uploads them via scp to
~/.local/share/estreia/cookies.txt on the remote host. The full
cookie file never leaves your machine.
- On the Pi, press
yin estreia to browse your subscriptions
Cookies expire periodically. When videos stop loading or the feed shows an error, re-export and upload fresh cookies.
Audio
By default, mpv uses the system default audio device. To use HDMI audio
or the analog headphone jack, set audio_device in the config file or
configure mpv directly:
# ~/.config/mpv/mpv.conf
audio-device=alsa/hdmi:CARD=vc4hdmi0,DEV=0
Check available devices with mpv --audio-device=help.
License
MIT
Documentation
¶
There is no documentation for this package.
Source Files