r0madev/catunes

Catunes is a terminal-based music player that lets you stream audio from YouTube, internet radio stations, other streaming URLs, or local files, all from the command line. It has a retro visual style and includes a live audio visualizer with several display modes including bars, mirror, oscilloscope, and a plasma effect. Basic controls like play, pause, seek, and volume adjust use single-key shortcuts, and the current track name appears in the terminal title bar. Beyond solo listening, the project includes a room mode where multiple people can join a shared session using a code and listen to the same music in sync. Rooms follow a round-robin DJ rotation, so each participant takes a turn choosing what plays next. The room feature requires a relay server that can be self-hosted using Docker. The client itself runs natively on your machine, since audio playback needs access to your speakers and cannot run inside Docker. Installation requires two external tools: mpv, which handles audio playback, and yt-dlp, which is only needed when playing YouTube or similar sites. Once both are installed, you can install catunes from npm and start playing a URL with a single command. A built-in doctor command checks whether the required tools are present. You can also control a running player from a separate terminal tab without needing any terminal multiplexer. The project is split into two packages: a client that handles the player interface and audio, and a server that acts as the WebSocket relay for rooms. Themes are customizable by editing a JSON config file. The roadmap shows that synced rooms and DJ rotation are still in progress as of the current release. Catunes does not download or store music files, it only streams content. The project is MIT-licensed and available in English and Spanish documentation.