pi-dj 🎧

YouTube streaming, Suno AI generation, Lyria RealTime radio, SoundCloud / Bandcamp / BandLab downloads, mixing, trimming, BPM detection, and ffmpeg music video rendering — all from the terminal.

Works with pi coding agent.

Install

pi install npm:pi-dj

Dependencies are optional. The extension detects what's installed and degrades gracefully.

| Platform | Install | |----------|---------| | Windows | winget install mpv ffmpeg · pip install yt-dlp | | macOS | brew install mpv yt-dlp ffmpeg | | Linux / Raspberry Pi | sudo apt install mpv ffmpeg -y · pip install yt-dlp | | Termux | pkg install mpv ffmpeg python · pip install yt-dlp |

Commands

Playback

| Command | Description | |---------|-------------| | /dj-play <query\|url> | YouTube search, URL, or playlist → stream via mpv | | /pause | Toggle pause / resume | | /stop | Stop + clear queue | | /np | Now playing — title, timestamp, progress bar | | /vol <0-100> | Set volume | | /skip | Skip to next queued track | | /repeat | Toggle repeat current track | | /queue <query\|url> | Add to queue | | /history | Recently played |

Downloads

| Command | Description | |---------|-------------| | /sc <url> | SoundCloud → MP3 | | /bandcamp <url> | Bandcamp track or album → MP3 | | /bandlab <url> | BandLab track, album, or collection → MP3 |

Radio

| Command | Description | |---------|-------------| | /radio <genre\|name> | Search Radio Browser — 30k+ global stations, no API key | | /radio jazz japan | Genre + country filter | | /radio <http url> | Play any stream URL directly | | /radio lyria | Lyria RealTime AI generative radio (preset 1) | | /radio lyria chill | Lyria with preset name or custom prompt | | /radio lyria <1-9> | Lyria by preset number |

Radio Browser has 30k+ stations across every genre and country. Top station by votes plays automatically; alternatives listed.

Lyria requires lyria-cli.

Production

| Command | Description | |---------|-------------| | /mix <a> <b> [secs] | Crossfade two audio files | | /trim <file> <start> [end] | Trim a clip | | /bpm <file> | Detect BPM | | /render <file\|url> [style] | Render a music video with ffmpeg | | /dj-help | Show all commands + dependency status |

Render Styles

/render outputs a 1080×1080 MP4 with animated visualizer and title overlay. Pure ffmpeg — no extra dependencies.

| Style | ffmpeg filter | Notes | |-------|--------------|-------| | bars (default) | showspectrum | Frequency spectrum | | wave | showwaves | Waveform | | circle | avectorscope | Lissajous / stereo field | | cqt | showcqt | Constant-Q transform |

/render ~/Music/track.mp3
/render ~/Music/track.mp3 wave
/render https://youtu.be/xxx cqt

Output: ~/Music/Videos/<title>_<style>.mp4

If a URL is passed, yt-dlp downloads first.

Terminal Visualizer (/viz)

Audio-reactive terminal visualizer bundled as pi-djvj. Reacts to mpv IPC or mic.

/viz         — embedded in pi TUI (side panel)
/viz full    — fullscreen alt-screen mode

16 half-block shaders (Plasma, Tunnel, Starfield, Lissajous, Kaleidoscope…) + 6 Braille modes + ASCII (IBM CP437 luminance ramp). Spectral flux beat detection.

| Key | Action | |-----|--------| | N / P | Next / previous shader | | v | Cycle mode (halfblock → braille → ascii) | | + / - | Sensitivity | | F | Toggle fullscreen | | Q | Quit |

LLM Tools

Two tools the AI can call directly mid-conversation:

| Tool | Description | |------|-------------| | dj_play_music | Stream a YouTube search or URL | | dj_queue_music | Add a track to the queue | | dj_radio | Search and play global radio — genre, country, Lyria AI, or stream URL |

Division of Labour

| Extension | Commands | |-----------|----------| | cliamp | Local files, HTTP streams, Lyria radio — /play /music /lyria | | pi-dj | YouTube, AI, production, radio — /dj-play /radio /subs /render + tools | | pi-djvj | Terminal visualizer — /viz /viz full — bundled with pi-dj |

pi install npm:pi-dj installs both pi-dj and pi-djvj in one shot.

Platforms

Windows · macOS · Linux · Raspberry Pi · Termux

License

MIT