CLI Music: A Terminal-Based Music Player for Seamless Audio Exploration
Primary Purpose:
CLI Music is a terminal-based music player designed to facilitate intuitive searching, discovery, streaming, and downloading of audio content directly from the command line.
Key Features:
Efficient Search Functionality: Users can search for tracks using free-text queries, enabling quick access to desired songs.
Genre and Mood-Based Discovery: Discover new tracks by selecting specific genres and moods, enhancing the exploration experience.
Batch Result Loading: Fetch additional results for the same query without interrupting the workflow.
YouTube Integration: Play or download music from YouTube URLs, supporting both single videos and playlists.
Keyboard Controls: Navigate playback with intuitive shortcuts such as Next (N), Previous (P), Quit (Q), and Download (D).
Audience & Benefit:
Ideal for developers, command-line enthusiasts, and anyone seeking a distraction-free audio experience within their terminal environment. CLI Music empowers users to explore music efficiently without context switching, enhancing productivity and focus.
Installation:
Install via winget for seamless setup and integration into your workflow.
README
CLI Music Player
A terminal-based music player that searches and streams audio, and supports downloads.
Features
Search songs by free text query.
Discover songs by genre + mood.
Load more results for the same query in batches.
Play from a pasted YouTube URL (playlist or single video).
De-duplicate songs by normalized title + artist/uploader.
Keyboard controls during playback:
N: Next song
P: Previous song
Q: Quit player
S: Back to search/mode selection
D: Download current song
D then P quickly: Download all songs in current queue
Requirements
Python 3.10+
One installed audio player:
mpv (recommended)
VLC
ffplay (from ffmpeg)
Install
Create and activate a virtual environment (optional but recommended).
Install dependencies:
pip install -r requirements.txt
Run
From the project root:
python cli/stream.py
Modes
Search Song
Enter any query.
Optionally include mixes/playlists.
Optionally sort by year.
Use "[ Load more results ]" in picker to fetch more songs.
Discover by Genre + Mood
Pick genre and mood, then proceed the same way as Search Song.
Play from YouTube URL
Paste a YouTube playlist URL or a single video URL.
Songs are loaded directly.
This mode skips query/mood/sort prompts.
Downloads
Song downloads are stored in the Downloads/music/ directory.
Audio is converted to MP3 at 192 kbps using ffmpeg post-processing.
Notes
Duplicate entries are filtered using normalized title + artist/uploader fields.
Only one playback process is allowed at a time; the current song is terminated before next/previous playback starts.
Troubleshooting
If no audio plays, ensure mpv/VLC/ffplay is installed and available on PATH.
If imports fail in editor diagnostics, install dependencies from in the active Python environment.