ytm-cli 0.7.0

YouTube Music CLI tool with interactive terminal interface

YTM - YouTube Music CLI

🎵 A simple, interactive command-line tool for YouTube Music

Stream music directly from YouTube Music in your terminal with intuitive controls, playlist management, and smart filtering.

✨ Features

• 🔍 Smart Search: Search and play any song from YouTube Music
• 🎮 Interactive Controls: Play/pause, skip, go back with simple key presses
• 📱 Vim-like Navigation: Use j/k keys or arrow keys to navigate
• 📋 Local Playlists: Create and manage personal playlists
• 👎 Smart Filtering: Dislike songs to filter them from future results
• 📜 Synced Lyrics: Live-highlighted lyrics with auto-scroll (press l)
• 🎯 Radio Mode: Automatic playlist generation based on your selection
• 🤖 AI-Powered: Natural language music requests and AI-generated playlists

🚀 Quick Start

Requirements

• Python 3.8+
• mpv media player (must be installed system-wide)

Installation

One command with uv (recommended):

# Install from PyPI
uvx ytm-cli "song name"

# Or from source (no clone needed)
uvx --from git+https://github.com/thieuluan1618/ytm.git ytm-cli "song name"

Alternative: clone and run locally

git clone https://github.com/thieuluan1618/ytm.git
cd ytm
uv run ytm-cli "song name"

Alternative: one-shot setup scripts

git clone https://github.com/thieuluan1618/ytm.git
cd ytm

These create the virtual environment, install dependencies, and configure the ytm command globally.

Linux/macOS:

./setup.sh
source ~/.zshrc  # or ~/.bashrc for bash

Windows PowerShell:

.\setup.ps1
. $PROFILE

Windows Command Prompt:

setup.bat

After setup, use ytm (alias for ytm-cli) from anywhere.

Alternative: manual install

git clone https://github.com/thieuluan1618/ytm.git
cd ytm
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
./setup_alias.sh          # or setup_alias.ps1 / setup_alias.bat

Basic Usage

Interactive search:

ytm-cli
# Enter search query when prompted

Direct search:

ytm-cli "your favorite song"

Non-interactive mode (automation/scripting):

ytm-cli search "song name" --select 1           # Auto-select first result
ytm-cli search "song" -s 1 -v                   # With verbose output
ytm-cli search "song" -s 1 -v --log-file debug.log  # Save debug logs

Tip: Set up the shell alias to use ytm as a shortcut for ytm-cli. See the setup scripts above.

🎮 Controls

During Song Selection

• ↑/↓ or j/k - Navigate through results
• Enter - Select and play song
• q - Quit

During Playback

• Space - Play/pause
• n - Next song
• b - Previous song
• l - Show lyrics (synced highlighting with auto-scroll)
• a - Add to playlist
• d - Dislike song (skip and filter from future results)
• q - Quit

During Lyrics View

• j/k or ↑/↓ - Manual scroll
• Space - Re-enable auto-scroll
• q or Esc - Back to player
• PgUp/PgDn - Page scroll
• Home/End - Jump to top/bottom

📋 Playlist Management

Create and manage playlists:

ytm-cli playlist list              # List all playlists
ytm-cli playlist create            # Create new playlist
ytm-cli playlist show "My Songs"   # View playlist contents
ytm-cli playlist play "My Songs"   # Play entire playlist
ytm-cli playlist delete "My Songs" # Delete playlist

Add songs to playlists:

• Press a during song selection or playback
• Choose existing playlist or create new one
• Song added without interrupting playback

🤖 AI Music Assistant

Use natural language to search and create playlists powered by AI (supports Google Gemini, OpenAI, Anthropic):

ytm-cli llm ask "play something chill for studying"       # AI picks and auto-plays
ytm-cli llm ask "upbeat pop songs for a workout"           # Natural language search
ytm-cli llm playlist "lo-fi beats for rainy days" --play   # AI-generated playlist
ytm-cli llm playlist "90s rock classics" -n 20             # 20-song playlist

Configure your provider in config.ini:

[llm]
provider = google       # google, openai, or anthropic
model = gemini-2.5-pro

🛠️ Configuration

The app uses config.ini for customization:

[general]
songs_to_display = 10
show_thumbnails = true

[mpv]
# Add custom mpv flags
flags = --no-video

[playlists]
directory = playlists

🎯 Philosophy

Keep it simple for the listener to enjoy music. Features are designed to be:

• Intuitive: Single-key shortcuts during playback
• Non-disruptive: Actions don't interrupt your listening experience
• Consistent: Same navigation patterns across all screens
• Quick: Important features accessible with simple key presses

🐛 Troubleshooting

Having issues? Check out the Troubleshooting Guide for solutions to common problems:

• 🔧 Songs Skipping Continuously
• 📦 MPV Not Found
• 💻 Terminal/Curses Errors
• 📝 Using Verbose Logging

Quick diagnosis:

# Enable verbose logging to see what's happening
ytm-cli search "test" -s 1 -v --log-file debug.log

# Check versions
mpv --version
yt-dlp --version

📄 License

This project is open source. Please check the license file for details.

---

Enjoy your music! 🎵