VoxPlayer
A modern desktop media player for Windows, macOS, and Linux. Four-pane shell (library rail, home/stage, now playing, transport), PyQt6 UI, optional native libmpv decode, and qBittorrent streaming.
Maintained by VoxHash Technologies · contact@voxhash.dev
pip install voxplayer
voxplayer
Features
- Modern shell: Left library rail, home/library grid, now-playing panel, bottom transport
- Universal format support: MP4, AVI, MKV, MOV, WMV, FLV, WebM, M4V, MP3, FLAC, WAV, OGG, M4A, AAC, WMA
- Hybrid playback: Qt Multimedia by default; optional libmpv via
pip install "voxplayer[native]" - True volume amplification: Up to 200% (mpv native / Pulse-boosted Qt path); Media Info matches the slider
- Thumbnails & live preview: ffmpeg-cached posters on library cards; live frame grabs in Now Playing / transport
- Metadata enrichment: offline-first local tags; optional online MusicBrainz / AcoustID / TMDB once per file with disk cache and manual refresh (see docs/configuration.md)
- Queue / playlists: Search, filtering, import/export
- Torrent streaming: qBittorrent Web UI integration with media-library gating
- File associations: Double-click media to open with VoxPlayer
- Cross-platform: Windows, macOS, and Linux
Table of Contents
Quick Start
pip install voxplayer
voxplayer "path/to/video.mp4"
Optional torrent streaming extras:
pip install "voxplayer[torrent]"
Optional native decode (requires system libmpv):
pip install "voxplayer[native]"
Installation
Method 1: PyPI (recommended)
pip install voxplayer
voxplayer
With torrent support:
pip install "voxplayer[torrent]"
Package page: https://pypi.org/project/voxplayer/
Method 2: Download Executable
Windows:
- Download
VoxPlayer.exefrom Releases - Run
VoxPlayer.exeto start - Run
register_file_associations.batas Administrator for file associations
macOS / Linux: download the matching asset from Releases when published for your platform.
Method 3: Python (source)
git clone https://github.com/VoxHash/VoxPlayer.git
cd VoxPlayer
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python test.py
python app.py "path/to/video.mp4"
Torrent extras from a clone:
pip install -e ".[torrent]"
Method 4: Built wheel (from source)
pip install build
python -m build
pip install dist/voxplayer-*.whl
voxplayer
System dependencies
| Dependency | Required? | Notes |
|---|---|---|
| Python 3.8+ (3.10–3.12 recommended) | Yes | Runtime |
| PyQt6 | Yes | Installed via requirements.txt |
| FFmpeg (Qt backend / system) | Recommended | Playback codecs; ffmpeg CLI useful for debugging |
| qBittorrent Web UI | Optional | Torrent streaming only |
| Alternate media client | Optional | Useful to compare problem files |
Usage
Opening media
- Double-click after file associations are registered
- Command line:
python app.py "path/to/video.mp4" - Drag & drop files or folders onto the window
Playlist
- Add via File menu or drag & drop
- Search/filter in the playlist dock
- Import/export M3U, PLS, XSPF
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Space |
Play/Pause |
Left/Right |
Seek |
Up/Down |
Volume |
M |
Mute/Unmute |
F11 |
Fullscreen |
Ctrl+O |
Open file(s) |
Ctrl+L |
Toggle playlist |
Ctrl+Q |
Quit |
Configuration
| Setting | Description | Default |
|---|---|---|
| Audio Output | Default or manual device | Default |
| Volume | Master volume | 50% |
| Theme | UI theme | Dark |
| Auto-Update | GitHub update checks | Enabled |
| Update Channel | Stable or Beta | Stable |
Environment variables (torrent streaming)
| Variable | Default | Purpose |
|---|---|---|
QB_HOST |
localhost:8080 |
qBittorrent Web UI host:port |
QB_USERNAME |
empty | Web UI username |
QB_PASSWORD |
empty | Web UI password (never commit) |
QT_QPA_PLATFORM |
unset | Use offscreen for headless tests |
See docs/configuration.md for details.
Documentation
- docs/index.md — documentation home
- docs/quick-start.md
- docs/installation.md
- docs/usage.md
- docs/troubleshooting.md
- CHANGELOG.md
- ROADMAP.md
- CONTRIBUTING.md
- SECURITY.md
- SUPPORT.md
Roadmap
Planned milestones live in ROADMAP.md.
Contributing
Read CONTRIBUTING.md and use the PR template. Run:
QT_QPA_PLATFORM=offscreen python test.py
Security
Report vulnerabilities via SECURITY.md or email contact@voxhash.dev.
License
MIT — see LICENSE.
Made by VoxHash Technologies
Metadata
Release files for voxplayer 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| voxplayer-1.1.1.tar.gz | 506.4 kB | Without provenance | Details for voxplayer-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| voxplayer-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for voxplayer-1.1.1-py3-none-any.whl |
Total release size: 764.2 kB
Release files / voxplayer-1.1.1.tar.gz
| Download URL | voxplayer-1.1.1.tar.gz |
|---|---|
| Size | 506.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
581d91ba07ac6e8e1be0212a8640c3df00d854327f0673a9c4f89481a4ec35ff
|
|
BLAKE2b-256 checksum How to use checksums |
32554dff52c33cabd6c227cd75fe2e3ff247fb25ae039c3d0126422e0a6960d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / voxplayer-1.1.1-py3-none-any.whl
| Download URL | voxplayer-1.1.1-py3-none-any.whl |
|---|---|
| Size | 257.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98ee5ba131931c1b8ec75207fd49edbc9d54ffc70e26191d839a001e40cf7ce5
|
|
BLAKE2b-256 checksum How to use checksums |
b341f9087eb494e4bcb431426313609309a41fd1eecc327306f885cb575f9efb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for voxplayer 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.