Skip to main content

    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 libmpv shared library (e.g., mpv-1.dll/mpv-2.dll on Windows or libmpv.so on Linux) are in your system PATH.

Known Limitations

  • Streams directly from YouTube — subject to rate limiting or regional restrictions

How It Works
  1. search queries YouTube via yt-dlp in metadata-only mode — fast, no download
  2. Results are stored as the active result list; play <index> loads them into the queue and starts streaming
  3. play fetches the direct audio stream URL and pipes it to MPV or VLC
  4. Jukebox mode uses a thread-safe event loop to advance tracks without blocking input
  5. 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-mpv or python-vlc must 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)

Source distribution for px7-music 1.8.0
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)

Table of built distributions (wheels) for px7-music 1.8.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page