ytmusic-cli

A local terminal-based music player that allows you to provide a YouTube playlist URL and stream the songs sequentially.

It acts like a lightweight terminal music player without permanently downloading tracks to your disk. It delegates audio streaming and playback to mpv while resolving YouTube URLs using yt-dlp.

Requirements

• Python 3.12+
• mpv (must be installed and available in your system PATH)

Installation

1. Clone this repository.
2. Set up a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Ensure mpv is installed:
   • Windows: winget install mpv.net or scoop install mpv
   • macOS: brew install mpv
   • Linux: sudo apt install mpv

Global Installation (Like npm)

If you want to use the ytmusic command from anywhere on your machine (similar to a global npm package), we recommend using pipx.

# From inside the project folder:
pipx install .

(If you don't have pipx, you can install it first with pip install pipx)

Once installed globally, you can just run:

ytmusic "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID"

Local Usage

If you prefer to run it locally without a global install:

• play - Start or resume playback
• pause - Pause playback
• stop - Stop the current track
• next / n - Skip to the next track
• previous / prev / b - Go back to the previous track
• queue - Display the upcoming queue
• current - Print the current player UI state
• seek <seconds> - Seek forward or backward (e.g., seek +30 or seek -10)
• volume <0-100> - Set the playback volume
• quit / q - Exit the player

Authentication

If you need to access private playlists or YouTube Premium features, yt-dlp supports extracting cookies from your local browser session.

Create a configuration file at ~/.ytmusic/config.toml (e.g., C:\Users\YourName\.ytmusic\config.toml on Windows):

browser = "chrome"
volume = 80
autoplay = true
shuffle = false

Supported browsers: chrome, firefox, edge, brave, opera, safari, etc.

Testing

Run tests with pytest:

pytest tests/