mpv Broadcast Suite brings the legendary mpv playback core — born from the MPlayer lineage - into a professional broadcast context.
Designed for engineers who grew up with waveform monitors, colour bars and baseband matrices - yet demand today's precision, scripting power and open workflows.
Might suit broadcast engineers, QC ops and post-production. Features broadcast-style timecode display, quite advanced multi-channel audio routing, and loudness compliance tooling.
Built for those who never stopped caring about frame accuracy.
- Broadcast-Style Timecode Display - Large, centered SMPTE timecode with frame-accurate display
- Drop-Frame Support - Proper DF/NDF handling for all NTSC framerates (23.976, 29.97, 59.94, 119.88)
- Progress Visualisation - Clean progress bar showing file position
- Real-Time Metadata - Elapsed time, countdown timer, FPS indicator, duration display
- Multiple Display Modes - Full overlay, TC-only, minimal, and off modes
- Multi-Channel Routing - Flexible channel selection for 8/16-channel embedded audio
- Stereo Pair Selection - Direct access to CH1+2, CH3+4, up to CH15+16
- Solo Monitoring - Monitor individual channels in isolation (mono→stereo)
- Intelligent Downmix - RMS-normalised all-channel summation prevents clipping
- Loudness Compliance - Built-in EBU R128, ATSC A/85, and podcast normalisation
- Visual Feedback - On-screen confirmation of routing changes
- Frame-Accurate Seeking - Precise frame-by-frame navigation
- High-Quality Screenshots - Lossless PNG capture with customisable naming
- Video Inspection - Zoom, pan, and deinterlacing controls
- Metadata Display - Quick access to codec, resolution, and audio parameters
- Playback Control - Variable speed, looping, and A-B repeat functionality
- mpv 0.35.0+ (compiled with Lua and libavfilter support)
- Operating System: Linux, macOS, or Windows
- Optional: GPU with hardware decode support for improved performance
Linux/macOS:
# Clone repository
git clone https://github.com/FiLORUX/mpv-broadcast-suite.git
cd mpv-broadcast-suite
# Run installer
chmod +x install.sh
./install.shWindows (PowerShell):
# Clone repository
git clone https://github.com/FiLORUX/mpv-broadcast-suite.git
cd mpv-broadcast-suite
# Run installer
.\install.ps1Manual Installation:
# Copy files to mpv config directory
cp mpv.conf ~/.config/mpv/
cp input.conf ~/.config/mpv/
cp scripts/*.lua ~/.config/mpv/scripts/Launch mpv with any video file:
mpv your_video.mp4You should see:
- Large timecode display centred at bottom of screen
- Information overlay in top-left corner
- Green progress bar beneath timecode
All core functions are accessible from the keyboard — designed for operators who prefer precision over menus.
→ Full reference: docs/KEYBINDINGS.md
Every display and routing element can be adjusted through plain-text Lua configuration.
No GUI layers, no hidden logic — just direct control.
→ Configuration guide: docs/CUSTOMISATION.md
Framerates, loudness, and multi-channel routing follow established broadcast standards.
No reinvention, only careful implementation.
→ Technical reference: docs/TECHDETAILS.md
mpv-broadcast-suite/
├── README.md # Primary documentation and overview
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
├── .gitignore # Git ignore rules
├── install.sh # Installation script (Linux/macOS)
├── install.ps1 # Installation script (Windows)
├── mpv.conf # Main mpv configuration
├── input.conf # Keyboard bindings
├── scripts/
│ ├── timecode.lua # Broadcast-style timecode display
│ └── audiomap.lua # Multi-channel audio routing and loudness control
├── docs/
│ ├── KEYBINDINGS.md # Keyboard reference and operator shortcuts
│ ├── CUSTOMISATION.md # Lua configuration and display options
│ ├── TECHDETAILS.md # Framerates, audio formats and loudness standards
│ ├── ADVANCED.md # Advanced configuration and automation
│ └── TROUBLESHOOTING.md # Common issues and practical fixes
└── examples/
├── ffmpeg_commands.md # Useful FFmpeg commands for broadcast pipelines
└── sample_profiles.conf # Example mpv profile presets
Common first-line fixes for typical playback or routing issues. For in-depth analysis, platform-specific cases, and extended logs, see docs/TROUBLESHOOTING.md.
Symptom: No timecode appears when playing file
Solution: Press t to cycle display modes (may be set to 'off')
Verify: Check that timecode.lua exists in scripts/ directory
Symptom: Pressing Ctrl+1-8 has no effect
Solution: Press Ctrl+i to verify channel count. If file reports "2 channels", it's already stereo—routing not needed
Note: For files with multiple audio tracks (not channels), use # to select the track first, then use Ctrl+1-8 for channel routing within that track
Symptom: Timecode appears wrong or doesn't match external reference
Solution: Press i to verify actual framerate. Drop-frame only applies to NTSC-derived rates (~23.976, ~29.97, ~59.94)
Debug: Edit timecode.lua and adjust tolerance values in get_fps_info() if framerate detection is incorrect
Symptom: Playback stutters when loudness normalisation enabled
Solution: Loudness filtering is CPU-intensive. Press Ctrl+l to cycle to "none" on older hardware
Alternative: Use offline loudness normalisation with dedicated tools for critical listening
Symptom: Cannot access expected channels
Solution: Distinguish between tracks (separate audio streams) and channels (within a track):
- Use
#to cycle between tracks - Use
Ctrl+1-8to route channels within the active track - Press
Ctrl+ito see track count and channel layout
Contributions are welcome! This project aims to serve the broadcast engineering community with reliable, professional tooling.
- Code Style: Follow existing Lua conventions with British English spelling in comments
- Testing: Test changes across Linux, macOS, and Windows before submitting
- Documentation: Update README.md and inline comments for any user-facing changes
- Commit Messages: Use clear, descriptive commit messages in present tense
When reporting bugs, please include:
- mpv version (
mpv --version) - Operating system and version
- File format and codec information
- Steps to reproduce
- Expected vs. actual behaviour
See CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License - see LICENSE file for details.
Third-Party Components:
- mpv player: GPL-2.0+ (mpv.io)
- FFmpeg libavfilter: LGPL-2.1+ / GPL-2.0+ (ffmpeg.org)
Windows
- Latest community build:
- GitHub: https://github.com/shinchiro/mpv-winbuild-cmake/releases/latest
- SourceForge (direct “latest”): https://sourceforge.net/projects/mpv-player-windows/files/
Unpack and run mpv.exe. User configuration lives in
%APPDATA%\mpv\ (create if missing).
macOS
-
Homebrew (recommended):
brew install mpv
Alternative builds and notes: https://mpv.io/installation/
Linux
Install via your distribution:
# Debian / Ubuntu
sudo apt install mpv
# Fedora
sudo dnf install mpv
# Arch
sudo pacman -S mpv
Further guidance: https://mpv.io/installation/
Linux / macOS:
git clone https://github.com/FiLORUX/mpv-broadcast-suite.git
cd mpv-broadcast-suite && chmod +x install.sh && ./install.sh
Windows (PowerShell 5+):
git clone https://github.com/FiLORUX/mpv-broadcast-suite.git
cd mpv-broadcast-suite; .\install.ps1
The installer copies mpv.conf, input.conf, and scripts/ to your user mpv configuration directory. No binaries are included.
If you prefer fully automated set-up, the provided installers can (optionally) resolve the latest mpv builds per platform without bundling any upstream code. See comments inside install.sh and install.ps1.
This suite stands on the shoulders of open-source giants.
It does not distribute their binaries, only configuration and logic designed for professional broadcast environments.
- mpv Development Team — the resilient playback engine at its core
- FFmpeg Project — the invisible open(-source) heart pulsing beneath almost every broadcast chain on earth
- EBU (European Broadcasting Union) — R128 loudness & tech standards
- SMPTE (Society of Motion Picture and Television Engineers) — frame-accurate timecode foundations
- Broadcast Engineers Worldwide — for decades of obsessive precision
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- mpv Manual: mpv.io/manual
- Initial public release
- broadcast-style timecode display with drop-frame support
- Multi-channel audio routing (up to 16 channels)
- EBU R128, ATSC A/85, and podcast loudness normalisation
- Comprehensive keyboard shortcuts for broadcast workflows
- Support for all common broadcast framerates
- Cross-platform compatibility (Linux, macOS, Windows)
Made with ⚡ for broadcast engineers, by broadcast engineers.
If this project helps your workflow, consider starring the repository on GitHub!