{"id":50380519,"url":"https://github.com/px7nn/px7-music","last_synced_at":"2026-05-30T12:00:27.428Z","repository":{"id":354982678,"uuid":"1226214207","full_name":"px7nn/px7-music","owner":"px7nn","description":"Terminal music player — stream YouTube audio from your CLI","archived":false,"fork":false,"pushed_at":"2026-05-26T17:15:59.000Z","size":107,"stargazers_count":14,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T19:10:48.566Z","etag":null,"topics":["audio-streaming","cli","lightweight","mpv","music-player","python","vlc","youtube-cli","yt-dlp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/px7nn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T05:29:08.000Z","updated_at":"2026-05-26T17:15:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/px7nn/px7-music","commit_stats":null,"previous_names":["px7nn/px7-music"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/px7nn/px7-music","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/px7nn%2Fpx7-music","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/px7nn%2Fpx7-music/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/px7nn%2Fpx7-music/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/px7nn%2Fpx7-music/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/px7nn","download_url":"https://codeload.github.com/px7nn/px7-music/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/px7nn%2Fpx7-music/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33691312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-streaming","cli","lightweight","mpv","music-player","python","vlc","youtube-cli","yt-dlp"],"created_at":"2026-05-30T12:00:20.570Z","updated_at":"2026-05-30T12:00:27.422Z","avatar_url":"https://github.com/px7nn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"600\" alt=\"PX7 Terminal Music\" src=\"https://github.com/user-attachments/assets/f1607e3a-e1fe-42df-a455-155aca1a77c3\" /\u003e\n\n\u003cbr\u003e\n\n![](https://img.shields.io/badge/interface-CLI-black?style=for-the-badge\u0026color=03A907\u0026labelColor=000000)\n\u0026nbsp;\n![](https://img.shields.io/pypi/v/px7-music?style=for-the-badge\u0026color=03A907\u0026labelColor=000000) \n\n\n\u003cbr\u003e\n\n\u003c/div\u003e\n\n\n# PX7 Terminal Music\n\nStream music from YouTube directly in your terminal. No browser, no GUI, no nonsense.  \n  \nPX7 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.\n\n\n```\n\u003e\u003e search radiohead\n\u003e\u003e play 2\n```\n\n## Features\n\n- Search and stream directly, no ads\n- Persistent favorites and playlists saved across sessions\n- Queue shuffling and hands-free autoplay mode\n- MPV and VLC support\n\n## Preview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"415\" src=\"https://github.com/user-attachments/assets/6475eaf6-691f-4a3f-b4c9-1c0e846506c4\" /\u003e\n\u003c/p\u003e\n\n## Requirements\n\n- **Python 3.10+**\n- MPV *(recommended)* or VLC\n\n\n## Installation\n\n### Install via pip (Recommended)\n\n```\npip install px7-music\n```\n\nStart the application:\n```\npx7-music\n```\nYou will see a prompt:\n```\n\u003e\u003e \n```\n\n## Usage\n\n```\ncommand [arguments] [--flags]\n```\n\n### Search \u0026 Play\n\n| Command | Args | Description |\n|---------|------|-------------|\n| `search` / `/s` | `\u003cquery\u003e` | Search YouTube and fill the results |\n| `play` | `[index]` | Play a track from the current results and load them into queue |\n\n\u003e `play` with no arguments defaults to `play 1`.\n\n\n**Search flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--limit=\u003cn\u003e` | `6` | Number of results to fetch |\n| `--no-postfix` | off | Disable the auto-appended `\"song\"` keyword |\n| `--p` | off | Fetch tracks from a YouTube playlist URL instead of searching |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n```\n\u003e\u003e /s https://youtube.com/playlist?list=... --p\n\u003e\u003e search hotel california --limit=1\n\u003e\u003e /s my dear melancholy\n\u003e\u003e play 2\n```\n\n\u003c/details\u003e\n\n---\n\n### Playback Controls\n\n| Command | Description |\n|---------|-------------|\n| `pause` | Pause the current track |\n| `resume` | Resume a paused track |\n| `next` | Skip to the next track in queue |\n| `prev` | Go back to the previous track |\n| `seek` | Show current playback position |\n| `seek \u003cposition\u003e` | Jump to a position in the current track |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSeek formats\u003c/b\u003e\u003c/summary\u003e\n\n```\n\u003e\u003e seek           # show current position\n\u003e\u003e seek 1:30      # jump to 1 min 30 sec (mm:ss)\n\u003e\u003e seek 90        # jump to 90 seconds\n\u003e\u003e seek +30       # skip forward 30 seconds\n\u003e\u003e seek -10       # rewind 10 seconds\n```\n\n\u003c/details\u003e\n\n---\n\n### Queue \u0026 Info\n\n| Command | Description |\n|---------|-------------|\n| `queue` | List all tracks in the current queue |\n| `current` / `now` | Show info about the currently playing track |\n| `load` | Load last results into queue and reset playback |\n| `shuffle` | Shuffle the queue (current track stays at top) |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n```\n\u003e\u003e /s the weeknd\n\u003e\u003e load\n\u003e\u003e shuffle\n\u003e\u003e play 1\n```\n\u003e **Note:** Viewing `queue`, `favs`, or a playlist loads them as the active results, so `play \u003cindex\u003e` works directly after them.\n\n\u003c/details\u003e\n\n---\n\n### Favorites\n\nSave tracks across sessions. Favorites persist to `~/.px7/.px7_favorites.json`.  \nNew favorites appear at the top (newest first).\n\n| Command | Args | Description |\n|---------|------|-------------|\n| `fav add` | | Add the currently playing track |\n| `fav add` | `\u003cindex\u003e` | Add a track from the queue by index |\n| `fav add` | `all` | Add all queued tracks |\n| `fav remove` | `\u003cindex\u003e` | Remove a favorite by index |\n| `fav remove` | `all` | Clear all favorites *(asks for confirmation)* |\n| `favs` | | List all saved favorites |\n\n**Favs flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--order=\u003cby\u003e` | newest first | Sort by: `name`, `date-added`, `duration` |\n| `--limit=\u003cn\u003e` | all | Show only the top N favorites |\n| `--reverse` | off | Reverse the sort direction |\n\n\u003e **Tip:** `favs` loads your favorites as results, so you can `load` → `play` them directly.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n```\n\u003e\u003e fav add\n\u003e\u003e fav add 3\n\u003e\u003e fav add all\n\u003e\u003e fav remove 2\n\u003e\u003e favs\n\u003e\u003e favs --order=name\n\u003e\u003e favs --order=duration --limit=5\n\u003e\u003e favs --order=date-added --reverse\n```\n\n\u003c/details\u003e\n\n---\n\n### Playlists\n\nOrganize tracks into named playlists. Playlists persist to `~/.px7/.px7_playlists.json`.  \nNew tracks in a playlist appear at the top (newest first).\n\n| Command | Args | Description |\n|---------|------|-------------|\n| `pl` / `pl list` | | List all playlists |\n| `pl create` | `\u003cname\u003e` | Create a new playlist |\n| `pl delete` | `\u003cname\u003e` | Delete a playlist *(asks for confirmation)* |\n| `pl rename` | `\u003cold\u003e -\u003e \u003cnew\u003e` | Rename a playlist |\n| `pl add` | `\u003cname\u003e` | Add the currently playing track to a playlist |\n| `pl add` | `\u003cname\u003e \u003cindex\u003e` | Add a queue track by index to a playlist |\n| `pl add` | `\u003cname\u003e all` | Add all queued tracks to a playlist |\n| `pl remove` | `\u003cname\u003e \u003cindex\u003e` | Remove a track from a playlist by index |\n| `pl show` | `\u003cname\u003e` | Display tracks in a playlist |\n| `pl \u003cname\u003e` | | Shorthand for `pl show \u003cname\u003e` |\n| `pl load` | `\u003cname\u003e` | Load a playlist into the queue |\n\n**pl show / pl load flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--order=\u003cby\u003e` | newest first | Sort by: `name`, `date-added`, `duration` |\n| `--limit=\u003cn\u003e` | all | Limit number of tracks shown or loaded |\n| `--reverse` | off | Reverse the sort direction |\n\n\u003e **Tip:** `pl load` sets the loaded playlist as active results, so `load` → `play` and `shuffle` work directly after it.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n```\n\u003e\u003e pl create Chill Mix\n\u003e\u003e pl add Chill Mix\n\u003e\u003e pl add Chill Mix 3\n\u003e\u003e pl add Chill Mix all\n\u003e\u003e pl Chill Mix\n\u003e\u003e pl load Chill Mix\n\u003e\u003e pl load Chill Mix --order=name --reverse\n\u003e\u003e pl remove Chill Mix 2\n\u003e\u003e pl rename Chill Mix -\u003e Evening Vibes\n\u003e\u003e pl delete Evening Vibes\n```\n\n\u003c/details\u003e\n\n---\n\n\n### Volume\n\n```bash\n\u003e\u003e volume         # print current volume\n\u003e\u003e volume 70      # set volume to 70\n```\n\n---\n\n### Auto-Play Mode\n\nHands-free mode that plays through the queue automatically.\n\n```\n\u003e\u003e autoplay\n```\n\u003e Alias: `/a`\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAuto-Play Keybinds\u003c/b\u003e\u003c/summary\u003e\n\n| Key | Action |\n|-----|--------|\n| `N` / `\u003e` / `.` | Next track |\n| `P` / `\u003c` / `,` | Previous track |\n| `SPACE` | Pause / Resume |\n| `+` / `=` | Volume up (+10) |\n| `-` / `_` | Volume down (−10) |\n| `R` | Force refresh display |\n| `Q` / `X` | Quit autoplay mode |\n\n\u003c/details\u003e\n\n---\n\n### Utility\n\n| Command | Description |\n|---------|-------------|\n| `latency` | Check network latency |\n| `clear` / `cls` | Clear the screen and redraw the banner |\n| `help` | Show the help screen |\n| `exit` | Quit PX7 Music |\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow It Works\u003c/b\u003e\u003c/summary\u003e\n\n1. `search` queries YouTube via `yt-dlp` in metadata-only mode (fast, no download)\n2. Results are stored as \"last results\"; `play \u003cindex\u003e` loads them into the queue and starts streaming\n3. `play \u003cindex\u003e` fetches the direct audio stream URL and pipes it to mpv or vlc\n4. Auto-play uses a thread-safe event queue to advance tracks without blocking the input loop\n5. Favorites and playlists are saved to `~/.px7/` and persist between sessions\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eProject Structure\u003c/b\u003e\u003c/summary\u003e\n\n```\npx7_music/\n├── config.py               # yt-dlp options, defaults, file paths\n├── main.py                 # entry point, command registration, main loop\n├── core/\n│   ├── handler.py          # command handlers (search, play, volume, fav, pl)\n│   ├── parser.py           # command parser and flag parser\n│   ├── latency.py          # network latency check\n│   ├── seek_handler.py     # seek command parsing and dispatch\n│   └── youtube.py          # yt-dlp search and stream URL extraction\n├── library/\n│   ├── favorites.py        # favorites persistence (load, save, add, remove)\n│   └── playlists.py        # playlists persistence (create, delete, rename, add, remove)\n├── player/\n│   ├── player_base.py      # abstract Player interface\n│   ├── player.py           # MPV and VLC backend implementations\n│   ├── playback.py         # queue state, playback control, autoplay events\n│   └── auto_play_mode.py   # autoplay UI and input listener thread\n└── utility/\n    ├── docs.py             # help text and installation guide\n    └── utils.py            # ANSI codes, spinner, screen utilities\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDependencies\u003c/b\u003e\u003c/summary\u003e\n\n| Package | Purpose |\n|---------|---------|\n| `yt-dlp` | YouTube search and stream URL extraction |\n| `python-mpv` | MPV player bindings *(optional)* |\n| `python-vlc` | VLC player bindings *(optional)* |\n\n\u003e At least one of `python-mpv` or `python-vlc` must be installed and its corresponding player binary must be present on your system.\n\n\u003c/details\u003e\n\n\n## Known Limitations\n\n- Streams directly from YouTube; subject to rate limiting or regional restrictions\n\n\n## License\n\nMIT — do whatever you want, just don't remove the header.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpx7nn%2Fpx7-music","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpx7nn%2Fpx7-music","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpx7nn%2Fpx7-music/lists"}