🎵 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.

• 🔍 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

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

1. Clone the repository

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

2. Set up virtual environment

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

3. Install dependencies

   pip install -r requirements.txt

4. Quick alias setup (Optional but recommended)

   For easier access with just ytm command:

   Linux/macOS:

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

   Windows PowerShell:

   .\setup_alias.ps1
   . $PROFILE

   Windows Command Prompt:

   setup_alias.bat

   After setup, use ytm from anywhere instead of python -m ytm_cli

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

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

• 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

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

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

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

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

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

Enjoy your music! 🎵