pi-raven

Raven is a YouTube audio search, background playback, and playlist management extension built for the Pi coding agent.

It provides both an interactive slash command interface (/raven) and an LLM tool (youtube_audio), allowing you or your AI agent to search YouTube, resolve audio streams, play background music via mpv, and queue tracks for continuous back-to-back playback.

---

Overview and Supported Platforms

Supported Operating Systems

• Linux: Primary supported platform. Tested on Linux distributions (Ubuntu, Debian, Fedora, Arch).
• macOS: Supported when mpv is installed via Homebrew.

Core System Capabilities

• Interactive Slash Command (/raven) for search, playback control, and playlist navigation.
• Autonomous LLM Tool (youtube_audio) allowing AI agents to manage background music and queues.
• Continuous back-to-back queue playback for 20+ tracks.
• Live status bar integration in Pi showing track title, artist, and elapsed duration.
• Automatic installation prompt for yt-dlp binary if missing from system PATH.

---

AI Agent Integration and Capabilities

When Raven is installed, your AI agent gains access to the youtube_audio tool. The AI can execute the following actions autonomously during conversation:

AI Capabilities

• Search and Play (search_and_play): The AI searches YouTube for a requested query and plays the best-ranked audio match based on official audio and video title heuristics.
• Direct Link Playback (play_url): The AI streams audio directly from a provided YouTube video URL or 11-character video ID.
• Playlist Building (playlist_add): The AI ranks and queues songs into an in-memory playlist.
• Back-to-Back Playlist Playback (playlist_play): The AI starts continuous playlist playback, automatically advancing through tracks. It can start from track 1 or a specified track index. If invoked on an empty playlist, it notifies the user to add tracks first.
• Queue Inspection and Management (playlist_list, playlist_remove, playlist_clear): The AI can inspect queued tracks, remove individual items by 1-based index, or wipe the entire playlist.
• Playback Controls (status, stop, next, prev): The AI can report current elapsed time and track details, stop playback, or skip between tracks. Skips operate on the active playlist if a playlist is playing, otherwise on the most recent search results.

Example Prompts for AI Playlist Management

Building Playlists

• "Add 5 relaxing instrumental Lofi tracks to my playlist"
• "Create a playlist with Interstellar Main Theme, Hans Zimmer Time, and Blade Runner 2049 Synthwave"
• "Add 'Chopin Nocturne Op. 9 No. 2' to my queue"
• "Queue 3 coding focus tracks for me"

Controlling Playlist Playback

• "Start playing my playlist back-to-back"
• "Play my playlist starting from track 3"
• "Skip to the next song in the playlist"
• "Go back to the previous track"

Managing and Inspecting the Queue

• "Show me all the songs currently in my playlist"
• "Remove track number 2 from the playlist"
• "Clear my playlist and add fresh synthwave music"
• "What song is currently playing and how much time is remaining?"

---

Technical Constraints and Limitations

• In-Memory Persistence: Playlist queues, active track status, and cached search results exist strictly in memory for the duration of the active session. They do not persist when Pi is restarted or when a session is closed.
• Required Binary Dependencies:
  • mpv: Must be pre-installed on the host system (sudo apt install mpv or brew install mpv). Audio playback will fail if mpv is missing.
  • yt-dlp: Required for stream extraction. Raven can prompt to download the latest binary to ~/.local/bin/yt-dlp if missing.
• Single-Item Tool Invocations: The youtube_audio tool action playlist_add processes one song or search query per tool call. Adding multiple tracks requires sequential tool invocations by the agent.
• Audio-Only Design: Raven does not display video streams or open visual media windows. Playback is strictly background audio.
• Network Dependency: Stream resolution relies on yt-dlp and public YouTube network access.

---

Installation

Install globally in Pi via NPM:

pi install npm:pi-raven

Or test temporarily in a single session:

pi -e npm:pi-raven

---

System Requirements

• Node.js: Version 18.19.0 or higher (or Node 20+).
• mpv: System CLI media player (sudo apt install mpv on Linux or brew install mpv on macOS).
• yt-dlp: Automatically downloaded to ~/.local/bin/yt-dlp on first run with user confirmation, or manually installed via system package manager.

---

Usage

Slash Commands (/raven)

Command	Description
/raven <query>	Search YouTube and select a track from interactive results
/raven play <url_or_id>	Play audio directly from a YouTube video URL or ID
/raven status	Display currently playing track info and elapsed playback time
/raven stop	Stop background audio playback
/raven list	Display menu of recent search results
/raven next / /raven prev	Skip forward or backward (operates on active playlist if playing, otherwise most recent search results)
/raven playlist add <query>	Add a track or URL to the continuous playlist queue
/raven playlist play [index]	Start back-to-back playlist playback (notifies if playlist is empty)
/raven playlist / /raven playlist list	Display current playlist tracks
/raven playlist remove <index>	Remove a track from playlist by 1-based index
/raven playlist clear	Clear all items from the playlist queue

---

Verification and Testing

Run the test suite and type check locally:

npm test
npm run typecheck

---

License

MIT License - Copyright (c) 2026 Aditya Saini