PX7 Music
A fast terminal music player that streams YouTube audio through MPV or VLC.
Search, queue, favorite, and organize music without leaving your terminal.
No downloads. No browser tabs. No ads.
>> search radiohead
1. Creep — Radiohead
2. No Surprises — Radiohead
3. Karma Police — Radiohead
>> play 2
♪ Now Playing: No Surprises — Radiohead
Features
- Stream audio directly from YouTube — no downloads, no accounts
- Persistent favorites and playlists saved across sessions
- Queue management with shuffle support
- Hands-free jukebox mode with live playback UI and synchronized lyrics
- MPV and VLC backend support
Requirements
Python 3.10+ • MPV (recommended) or VLC
Installation
pip install px7-music
px7-music # Launch normally (auto-detects player)
px7-music --mpv # Force MPV
px7-music --vlc # Force VLC
px7-music -v # Show version and exit (or --version)
Player not found? See Player Not Found.
Quick Start
>> /s <song/artist to search> # Queries YT to return a list of songs
>> play 2 # Plays the #2 result
>> fav add # Adds the currently playing song to favs
>> /s radiohead -> My_Playlist # Creates/prepends the results to My_Playlist
>> /j # /j or jukebox enables jukebox mode
Usage
To keep the main page clean, detailed command documentation has been moved to docs/USAGE.md.
Player Not Found
PX7 requires MPV or VLC installed on your system, plus their Python bindings.
Install the Python bindings:
pip install python-mpv
pip install python-vlc
Install the player:
| OS | MPV | VLC |
|---|---|---|
| Windows | winget install mpv |
winget install VideoLAN.VLC |
| macOS | brew install mpv |
brew install --cask vlc |
| Ubuntu/Debian | sudo apt install mpv |
sudo apt install vlc |
| Arch | sudo pacman -S mpv |
sudo pacman -S vlc |
MPV is recommended. Ensure the player binary and
libmpvshared library (e.g.,mpv-1.dll/mpv-2.dllon Windows orlibmpv.soon Linux) are in your system PATH.
Known Limitations
- Streams directly from YouTube — subject to rate limiting or regional restrictions
How It Works
searchqueries YouTube viayt-dlpin metadata-only mode — fast, no download- Results are stored as the active result list;
play <index>loads them into the queue and starts streaming playfetches the direct audio stream URL and pipes it to MPV or VLC- Jukebox mode uses a thread-safe event loop to advance tracks without blocking input
- Favorites and playlists are saved to
~/.px7/and persist between sessions
Project Structure
px7_music/
├── config.py # yt-dlp options, defaults, file paths
├── main.py # entry point, command registration, main loop
├── core/
│ ├── handler.py # command handlers (search, play, volume, fav, pl)
│ ├── jukebox_mode.py # jukebox UI and input listener thread
│ ├── lrclib.py # LRCLIB synchronized lyrics client
│ ├── parser.py # command parser and flag parser
│ ├── pipe.py # pipe operator logic
│ ├── latency.py # network latency check
│ ├── cfg_manager.py # config persistence and tunable settings
│ ├── seek_handler.py # seek command parsing and dispatch
│ └── youtube.py # yt-dlp search and stream URL extraction
├── library/
│ ├── favorites.py # favorites persistence (load, save, add, remove)
│ └── playlists.py # playlists persistence (create, delete, rename, add, remove)
├── player/
│ ├── player_base.py # abstract Player interface
│ ├── player.py # MPV and VLC backend implementations
│ └── playback.py # queue state, playback control, jukebox events
└── utility/
├── docs.py # help text and installation guide
└── utils.py # ANSI codes, spinner, banner builder, screen utilities
Dependencies
| Package | Purpose |
|---|---|
yt-dlp |
YouTube search and stream extraction |
python-mpv |
MPV player bindings (optional) |
python-vlc |
VLC player bindings (optional) |
At least one of
python-mpvorpython-vlcmust be installed, with its corresponding player binary present on the system.
Changelog
See CHANGELOG.md for the full version history.
License
MIT — do whatever you want, just don't remove the header.
Metadata
Release files for px7-music 1.8.0
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 |
|---|---|---|---|---|
| px7_music-1.8.0.tar.gz | 37.1 kB | Without provenance | Details for px7_music-1.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| px7_music-1.8.0-py3-none-any.whl | Python 3 | none | any | Details for px7_music-1.8.0-py3-none-any.whl |
Total release size: 78.3 kB
Release files / px7_music-1.8.0.tar.gz
| Download URL | px7_music-1.8.0.tar.gz |
|---|---|
| Size | 37.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e36466e1ba318f189d40c933cd005ee6b98e2522954a42a42d1b07a6490945d
|
|
BLAKE2b-256 checksum How to use checksums |
f77989caa04f5c4b88bd7c96b5e2403f184776397f9ac5e1c154a1733651987a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / px7_music-1.8.0-py3-none-any.whl
| Download URL | px7_music-1.8.0-py3-none-any.whl |
|---|---|
| Size | 41.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d83600743d87e005575a0aa892e071a1c6ae938985f674a573dc1fac10b23dbb
|
|
BLAKE2b-256 checksum How to use checksums |
48d2e9bff26500eacda3cb02103cc922eeb0685b7b292766e2d9e0f78944a3c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for px7-music 1.8.0
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.