https://github.com/px7nn/px7-music
Terminal music player — stream YouTube audio from your CLI
https://github.com/px7nn/px7-music
audio-streaming cli lightweight mpv music-player python vlc youtube-cli yt-dlp
Last synced: 18 days ago
JSON representation
Terminal music player — stream YouTube audio from your CLI
- Host: GitHub
- URL: https://github.com/px7nn/px7-music
- Owner: px7nn
- License: mit
- Created: 2026-05-01T05:29:08.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-26T17:15:59.000Z (22 days ago)
- Last Synced: 2026-05-26T19:10:48.566Z (22 days ago)
- Topics: audio-streaming, cli, lightweight, mpv, music-player, python, vlc, youtube-cli, yt-dlp
- Language: Python
- Homepage:
- Size: 104 KB
- Stars: 14
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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 and playlists 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` | `` | 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=` | `6` | Number of results to fetch |
| `--no-postfix` | off | Disable the auto-appended `"song"` keyword |
| `--p` | off | Fetch tracks from a YouTube playlist URL instead of searching |
Examples
```
>> /s https://youtube.com/playlist?list=... --p
>> search hotel california --limit=1
>> /s 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 |
| `seek` | Show current playback position |
| `seek ` | Jump to a position in the current track |
Seek formats
```
>> seek # show current position
>> seek 1:30 # jump to 1 min 30 sec (mm:ss)
>> seek 90 # jump to 90 seconds
>> seek +30 # skip forward 30 seconds
>> seek -10 # rewind 10 seconds
```
---
### 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) |
Examples
```
>> /s the weeknd
>> load
>> shuffle
>> play 1
```
> **Note:** Viewing `queue`, `favs`, or a playlist loads them as the active results, so `play ` works directly after them.
---
### Favorites
Save tracks across sessions. Favorites persist to `~/.px7/.px7_favorites.json`.
New favorites appear at the top (newest first).
| Command | Args | Description |
|---------|------|-------------|
| `fav add` | | Add the currently playing track |
| `fav add` | `` | Add a track from the queue by index |
| `fav add` | `all` | Add all queued tracks |
| `fav remove` | `` | 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=` | newest first | Sort by: `name`, `date-added`, `duration` |
| `--limit=` | all | Show only the top N favorites |
| `--reverse` | off | Reverse the sort direction |
> **Tip:** `favs` loads your favorites as results, so you can `load` → `play` them directly.
Examples
```
>> 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
```
---
### Playlists
Organize tracks into named playlists. Playlists persist to `~/.px7/.px7_playlists.json`.
New tracks in a playlist appear at the top (newest first).
| Command | Args | Description |
|---------|------|-------------|
| `pl` / `pl list` | | List all playlists |
| `pl create` | `` | Create a new playlist |
| `pl delete` | `` | Delete a playlist *(asks for confirmation)* |
| `pl rename` | ` -> ` | Rename a playlist |
| `pl add` | `` | Add the currently playing track to a playlist |
| `pl add` | ` ` | Add a queue track by index to a playlist |
| `pl add` | ` all` | Add all queued tracks to a playlist |
| `pl remove` | ` ` | Remove a track from a playlist by index |
| `pl show` | `` | Display tracks in a playlist |
| `pl ` | | Shorthand for `pl show ` |
| `pl load` | `` | Load a playlist into the queue |
**pl show / pl load flags:**
| Flag | Default | Description |
|------|---------|-------------|
| `--order=` | newest first | Sort by: `name`, `date-added`, `duration` |
| `--limit=` | all | Limit number of tracks shown or loaded |
| `--reverse` | off | Reverse the sort direction |
> **Tip:** `pl load` sets the loaded playlist as active results, so `load` → `play` and `shuffle` work directly after it.
Examples
```
>> pl create Chill Mix
>> pl add Chill Mix
>> pl add Chill Mix 3
>> pl add Chill Mix all
>> pl Chill Mix
>> pl load Chill Mix
>> pl load Chill Mix --order=name --reverse
>> pl remove Chill Mix 2
>> pl rename Chill Mix -> Evening Vibes
>> pl delete Evening Vibes
```
---
### Volume
```bash
>> volume # print current volume
>> volume 70 # set volume to 70
```
---
### Auto-Play Mode
Hands-free mode that plays through the queue automatically.
```
>> autoplay
```
> Alias: `/a`
Auto-Play Keybinds
| Key | Action |
|-----|--------|
| `N` / `>` / `.` | Next track |
| `P` / `<` / `,` | Previous track |
| `SPACE` | Pause / Resume |
| `+` / `=` | Volume up (+10) |
| `-` / `_` | Volume down (−10) |
| `R` | Force refresh display |
| `Q` / `X` | Quit autoplay mode |
---
### 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 ` loads them into the queue and starts streaming
3. `play ` 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 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)
│ ├── parser.py # command parser and flag parser
│ ├── latency.py # network latency check
│ ├── 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, 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.