PX7 Terminal 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

Preview

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
• MPV and VLC backend support

Comparison

Requirements

• Python 3.10+
• MPV (recommended) or VLC

Installation

pip install px7-music

Then start PX7:

px7-music

You should see:

>>

If you see an error about a missing player, see Player Not Found below.

Quick Start

>> search joji
>> play 1
>> fav add

>> /s radiohead -> Favorites

>> jukebox

Search, play, save, pipe results straight into a playlist, and listen hands-free.

How Results Work

PX7 always has an active result list.

Commands that produce a list — search, favs, queue, pl show, pl load — replace the active results. play <index> always acts on the current active results.

>> search the weeknd       # active results = search results
>> play 3                  # plays result #3

>> favs                    # active results = your favorites
>> play 1                  # plays favorite #1

>> pl load Chill Mix       # active results = playlist tracks
>> shuffle
>> play 1

This is why load works after any of these — it reloads whatever the active results are into the queue.

Usage

command [arguments] [--flags]

Search & Play

play with no argument defaults to play 1.

Flags:

>> search c418
>> /s the weeknd --limit=10
>> /s radiohead --no-postfix
>> /s https://youtube.com/playlist?list=... --p
>> play 2

Playback Controls

Seek formats: 1:30  ·  90  ·  +30  ·  -10  ·  2:04:15

Queue & Info

Queue flags:

>> queue
>> queue --no-compact
>> queue add 3
>> queue add all --next

Favorites

Persist to ~/.px7/.px7_favorites.json. New favorites appear at the top.

Favs flags:

>> fav add
>> fav add 3
>> fav add all
>> fav remove 2
>> favs
>> favs /rock
>> favs /lofi --order=duration --reverse
>> favs --limit=10 --order=date-added

Playlists

Persist to ~/.px7/.px7_playlists.json. New tracks in a playlist appear at the top.

pl show / pl load flags:

Shorthand — name first, subcommand second (defaults to show):

>> pl Chill Mix              # → pl show Chill Mix
>> pl Chill Mix load         # → pl load Chill Mix
>> pl Chill Mix add 3        # → pl add  Chill Mix 3

>> pl create Chill Mix
>> pl add Chill Mix
>> pl add Chill Mix 3
>> pl add Chill Mix all
>> pl Chill Mix
>> pl list /chill
>> pl show Chill Mix /rock --order=duration
>> pl load Chill Mix /lofi --reverse
>> pl rename Chill Mix -> Late Night
>> pl remove Late Night 2
>> pl delete Late Night

Pipe ->

Pipe a result list directly into a playlist. The playlist is auto-created if it doesn't exist.

<source> [--flags] -> <playlist name>

>> /s c418 -> Minecraft Vibes
>> /s joji --limit=20 -> Late Night
>> /s https://youtube.com/playlist?list=... --p -> Imports
>> favs --order=duration --limit=10 -> Top 10
>> queue -> Current Session

Jukebox Mode

Hands-free mode that plays through the queue automatically with a live playback UI.

>> jukebox

Alias: /j

Keybinds — no Enter needed, keys are instant:

Config

Tune persistent settings that survive across sessions.

Tunable keys:

>> config DEFAULT_SEARCH_LIMIT 10
>> config DEFAULT_SEARCH_LIMIT *    # reset to default
>> config reset                     # reset everything

Volume

>> volume        # show current volume
>> volume 70     # set volume to 70

Utility

Player Not Found

PX7 requires MPV or VLC installed on your system, plus its Python bindings.

Install the Python bindings:

pip install python-mpv
pip install python-vlc

Install the player:

MPV is recommended. Ensure the player binary is available in your system PATH.

Known Limitations

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

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
│   ├── 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

Changelog

See CHANGELOG.md for the full version history.

License

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