ytm-cli 0.8.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.

Player UI with the real-time FFT spectrum visualizer (synthetic demo capture). Click for the higher-quality .webm.

✨ 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
• 📊 Real-time Spectrum Visualizer: 24-band FFT bars driven by an ffmpeg sidecar — bass left, treble right (stereo oscilloscope fallback when ffmpeg is unavailable)
• 🤖 AI-Powered: Natural language music requests and AI-generated playlists

🚀 Quick Start

Requirements

• Python 3.10+ (set in pyproject.toml)
• mpv media player (must be installed system-wide)
• ffmpeg on PATH for the real-time spectrum visualizer (optional — falls back to a stereo oscilloscope if missing)

Installation

One command with uv (recommended):

# Install from PyPI — gets latest version automatically
uvx 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 script (Linux / macOS)

git clone https://github.com/thieuluan1618/ytm.git
cd ytm
./setup.sh
source ~/.zshrc            # or ~/.bashrc for bash

This creates the venv, installs runtime deps from pyproject.toml, and adds a ytm shell alias.

Alternative: manual install

git clone https://github.com/thieuluan1618/ytm.git
cd ytm
uv sync                   # installs runtime deps from pyproject.toml + uv.lock
./setup_alias.sh          # optional: registers the `ytm` alias
# Run with: uv run ytm-cli "song"

Windows users: native Windows is not supported (the codebase uses POSIX-only termios/tty/fcntl). Use WSL2 and follow the Linux instructions above.

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 --verbose                      # With verbose output
ytm-cli search "song" -s 1 --verbose --log-file debug.log # Save debug logs
ytm-cli -v                                                # Print version

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 --verbose --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! 🎵