px7-music 0.3.2

Terminal music player — stream YouTube audio from your CLI

 

PX7 Terminal Music

Stream music from YouTube directly in your terminal. No browser, no GUI, no nonsense.

PX7 is a lightweight CLI music player that searches YouTube via yt-dlp and streams audio through mpv or vlc — no downloads, no accounts, no ads. Just type a song name and play.

>> search radiohead
>> play 2

Features

• Search and stream directly, no ads
• Persistent favorites saved across sessions
• Queue shuffling and hands-free autoplay mode
• MPV and VLC support

Preview

Requirements

• Python 3.10+
• MPV (recommended) or VLC

Installation

Install via pip (Recommended)

pip install px7-music

Start the application:

px7-music

You will see a prompt:

>> 

Usage

command [arguments] [--flags]

Search & Play

Command	Args	Description
search / /s	<query>	Search YouTube and fill the results
play	[index]	Play a track from the current results and load them into queue

play with no arguments defaults to play 1.

Search flags:

Flag	Default	Description
--limit=<n>	6	Number of results to fetch
--no-postfix	off	Disable the auto-appended "song" keyword

>> search hotel california --limit=1
>> search my dear melancholy
>> play 2

Playback Controls

Command	Description
pause	Pause the current track
resume	Resume a paused track
next	Skip to the next track in queue
prev	Go back to the previous track

Queue & Info

Command	Description
queue	List all tracks in the current queue
current / now	Show info about the currently playing track
load	Load last results into queue and reset playback
shuffle	Shuffle the queue (current track stays at top)

>> search tame impala
>> load
>> shuffle
>> play 1

Note: Viewing queue or favs makes them the active results list, so commands like play <index> work directly after them.

Favorites

Save tracks across sessions. Favorites persist to ~/.px7_favorites.json.
New favorites appear at the top (newest first).

Command	Args	Description
fav add		Add the currently playing track
fav add	<index>	Add a track from the queue by index
fav add	all	Add all queued tracks
fav remove	<index>	Remove a favorite by index
fav remove	all	Clear all favorites (asks for confirmation)
favs		List all saved favorites

Favs flags:

Flag	Default	Description
--order=<by>	newest first	Sort by: name, date-added, duration
--limit=<n>	all	Show only the top N favorites
--reverse	off	Reverse the sort direction

>> fav add
>> fav add 3
>> fav add all
>> fav remove 2
>> favs
>> favs --order=name
>> favs --order=duration --limit=5
>> favs --order=date-added --reverse

Tip: favs loads your favorites as results, so you can load → play them directly.

Volume

>> volume         # print current volume
>> volume 70      # set volume to 70

Auto-Play Mode

Hands-free mode that plays through the queue automatically.

>> autoplay

Key	Action
N	Next track
P	Previous track
ENTER	Pause/Resume track
Q	Quit autoplay

Utility

Command	Description
latency	Check network latency
clear / cls	Clear the screen and redraw the banner
help	Show the help screen
exit	Quit PX7 Music

How It Works

1. search queries YouTube via yt-dlp in metadata-only mode (fast, no download)
2. Results are stored as "last results"; play <index> loads them into the queue and starts streaming
3. play <index> fetches the direct audio stream URL and pipes it to mpv or vlc
4. Auto-play uses a thread-safe event queue to advance tracks without blocking the input loop
5. Favorites are saved to ~/.px7_favorites.json 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)
│   ├── parser.py           # command parser and flag parser
│   ├── latency.py          # network latency check
│   └── youtube.py          # yt-dlp search and stream URL extraction
├── library/
│   └── favorites.py        # favorites persistence (load, save, add, remove)
├── player/
│   ├── player_base.py      # abstract Player interface
│   ├── player.py           # MPV and VLC backend implementations
│   ├── playback.py         # queue state, playback control, autoplay events
│   └── auto_play_mode.py   # autoplay UI and input listener thread
└── utility/
    ├── docs.py             # help text and installation guide
    └── utils.py            # ANSI codes, spinner, screen utilities

Dependencies

Package	Purpose
yt-dlp	YouTube search and stream URL 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 and its corresponding player binary must be present on your system.

Known Limitations

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

License

MIT — do whatever you want, just don't remove the header.