ytm-cli 0.5.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
• 📜 Lyrics Display: View lyrics while listening (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 "song name"

Alternative: clone and run locally

git clone https://github.com/thieuluan1618/ytm.git
cd ytm
uv run ytm "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 from anywhere instead of python -m ytm_cli.

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
# Enter search query when prompted

Direct search:

ytm "your favorite song"

Non-interactive mode (automation/scripting):

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

Note: If you haven't set up the alias, use python -m ytm_cli instead of ytm

🎮 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
• a - Add to playlist
• d - Dislike song (skip and filter from future results)
• q - Quit

📋 Playlist Management

Create and manage playlists:

ytm playlist list              # List all playlists
ytm playlist create            # Create new playlist
ytm playlist show "My Songs"   # View playlist contents
ytm playlist play "My Songs"   # Play entire playlist
ytm 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 llm ask "play something chill for studying"       # AI picks and auto-plays
ytm llm ask "upbeat pop songs for a workout"           # Natural language search
ytm llm playlist "lo-fi beats for rainy days" --play   # AI-generated playlist
ytm 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 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! 🎵