Terminal YT Music + AI DJ

Vim Motions + AI DJ.

Probably the best FUCKING thing I've ever coded

Why?

Remember NonStop-POP FM from GTA V? Yes I wanted that for my local music player and I do not use spotify :)

Screenshots

Features

• Terminal Interface: A rich TUI experience using Textual with Vim Motions
• YouTube Music Integration: Search, play, like, and manage playlists.
• Efficient Playback: Lightweight audio playback with python-vlc.
• AI DJ (Kiara): An integrated AI DJ that announces songs and smooths transitions using a local LLM and kokoro TTS.

Requirements

• Python 3.10+
• VLC Media Player: Must be installed on your system (required for python-vlc).
• Dependencies:
  • textual
  • ytmusicapi
  • yt-dlp
  • requests
  • python-vlc
  • kokoro>=0.3.4
  • soundfile
  • onnxruntime-gpu
  • llama-cpp-python

Installation

1. Install Dependencies

pip install -r requirements.txt

2. Configure AI DJ (Optional)

The AI DJ feature uses a local LLM in GGUF format and the kokoro TTS library.

1. Download a GGUF model: Download a suitable GGUF model (e.g., Llama 3 8B Quantized) from Hugging Face.

2. Configure Path: Open src/playback/dj.py and update the MODEL_PATH variable to point to your downloaded model file.

   # src/playback/dj.py
   MODEL_PATH = "path/to/your/model.gguf"

   Note: GPU acceleration for llama-cpp-python and kokoro requires appropriate drivers (e.g., CUDA for NVIDIA GPUs).

Usage

Run the application from the root directory:

python src/main.py

Architecture

The application is structured into three main layers:

1. Render (src/render/)

Responsible for all UI components and screens built with Textual.

• home.py: Displays the main feed (Recommendations, Liked Songs, Library).
• player.py: The audio player interface.
• search.py: Search dialog and playlist selection.
• login.py: OAuth login flow.
• components.py: Shared widgets (e.g., SongWidget).

2. Backend (src/backend/)

Handles data fetching and business logic.

• api.py: Wrappers for ytmusicapi to fetch songs, playlists, and artists.
• auth.py: Manages OAuth tokens and session.

3. Playback (src/playback/)

Handles low-level audio reproduction and AI generation.

• player.py: Singleton wrapper around python-vlc for audio playback and yt-dlp for stream extraction.
• dj.py: Manages the AI DJ "Kiara", generating voice transitions using LLM and TTS.

Entry Point

• src/main.py: The central controller that initializes the backend, authentication, and playback modules, and manages the UI application lifecycle.

Controls

General & Home Screen

• j / k: Navigate lists (Down / Up)
• Space / Enter: Play selected song
• /: Open Search
• l: Next song
• h: Previous song
• m: Mood search
• a: Like song
• s: Dislike song
• p: Add to playlist
• 1: View Recommendations
• 2: View Liked Songs
• 3: View Library Playlists
• r: Refresh content
• Ctrl+Q: Quit App

Player Screen

• Space: Toggle Play/Pause
• l: Next song
• h: Previous song
• q / Esc: Back to previous screen
• a: Toggle Autoplay
• j / k: Navigate Queue/History

Authentication

The app uses OAuth for YouTube Music access. On the first run, if no valid session is found, you will be prompted to follow instructions to authenticate.