yit-player 0.1.2

YouTube in Terminal - Fire-and-Forget Music CLI

Yit (YouTube in Terminal) Player 🎵

The Fire-and-Forget Music Player for Developers.

Yit (YouTube in Terminal) is a lightweight, headless, terminal-based audio player designed for flow states. It allows you to search, queue, and control music directly from your CLI without ever touching a browser or a heavy GUI.

It runs in the background (daemonized), meaning you can close your terminal, switch tabs, or keep coding while the music plays.

---

🚀 Features

• Daemon Architecture: The player runs as a detached background process. Your terminal is never blocked.
• Instant Search: Uses yt-dlp to fetch metadata in milliseconds.
• Smart Queue: Manage your playlist (add, next, back, Loop) with simple commands.
• Cross-Platform: Works natively on Windows, macOS, and Linux.
• Agent-Native: Built from the ground up to be controlled by AI Agents (Vibe Coding).

---

📦 Installation

pip install yit-player

Requirements

Yit uses mpv as its audio engine.

• Windows: Yit will attempt to auto-install it via winget if missing.
• macOS: brew install mpv
• Linux: sudo apt install mpv (or your distro's equivalent).

---

⚡ Quick Start

1. Search & Play

# Search for a song
yit search "lofi hip hop"

# Auto-play the first result immediately
yit search "daft punk" -p

2. Control Playback

yit pause    # (or 'p')
yit resume   # (or 'r')
yit toggle   # Toggle play/pause
yit stop     # Kill the player

3. Queue Management

yit add 1    # Add result #1 from your last search to the queue (use 1 - 5 to choose from search results)
yit queue    # Show the current queue
yit next     # Skip track (or 'n')
yit back     # Previous track (or 'b')
yit clear    # Wipe the queue

4. Looping

yit loop     # Loop the current track indefinitely
yit unloop   # Return to normal playback

5. Status

yit status   # Check if currently Playing/Paused and Looped

---

🤖 For AI Agents & Vibe Coding

Yit is designed to be self-documenting for AI context. If you are building an AI agent or using an LLM in your IDE:

1. Read context: Point your agent to AI_INSTRUCTIONS.md (included in the repo).
2. Discovery: Run yit commands to get a JSON list of all capabilities.
3. State: Run yit agent to get the full player state (Track, Time, Queue) in pure JSON.

Example Agent Output (yit agent):

{
  "status": "playing",
  "track": {
    "title": "Never Gonna Give You Up",
    "url": "https://..."
  },
  "position": 45.2,
  "duration": 212.0,
  "queue_length": 5
}

---

🛠️ Architecture

• Client: Python CLI (yit) handles argument parsing and user signals.
• Daemon: A detached mpv process handles audio decoding and network streaming.
• Communication: IPC (Inter-Process Communication) via Named Pipes (Windows) or Unix Sockets (Linux/Mac).
• Persistence: ~/.yit/history.json stores your playback history and queue metadata.