From 2f5d5105c03b97a8e64cbc5ee3bef97462f4f27d Mon Sep 17 00:00:00 2001 From: evilchili Date: Sun, 14 Sep 2025 15:51:42 -0700 Subject: [PATCH] update README --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 510193e..8399d64 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,29 @@ # Croaker -A shoutcast server designed primarily for streaming D&D session music. +Croaker is a Linux desktop audio player controlled from a TCP server. It is designed specifically to play background music during TTRPG sessions. ### Features -* Native streaming of MP3 sources direct to your clients -* Transcoding of anything your local `ffmpeg` installation can convert to mp3 +* Audio playback using VLC * Playlists are built using symlinks * Randomizes playlist order the first time it is cached * Always plays `_theme.mp3` first upon switching to a playlist, if it exists -* Falls back to silence if the stream encounters an error +* Controlled by issuing commands over a TCP socket ### Requirements * A functioning shoutcast / icecast server -* Python >= 3.10 -* ffmpeg -* libshout3-dev +* Python >= 3.11 +* python3.11-dev ## What? Why? -Because I run an online D&D game, which includes a background music stream for my players. The stream used to be served by liquidsoap and icecast and controlled by a bunch of bash scripts I cobbled together which are functional but brittle, and liquidsoap is a nightmare for the small use case. Also, this required me to have a terminal window open to my media server to control liquidsoap directly, and I'd rather integrate the music controls directly with the rest of my DM tools, all of which run on my laptop. +I run an online D&D game. For years I have provided my players with an internet radio station playing the session background music. The first version was built using liquidsoap and icecast. The second version replaced liquidsoap with a custom streamer implementation (which is still available on the `shoutcast` branch, warts and all). + +Both of these solutions were functional but high maintenance, and I wanted something simpler both for me and my players. + +This version of Croaker usees VLC (via python-vlc) to play audio locally, and pops up a read-only desktop interface to display what is playing. I share this app using screen sharing during our online games, and control it using my DM tools. *Now that is a powerful yak! -- Aesop Rock (misquoted)* @@ -31,7 +33,6 @@ Because I run an online D&D game, which includes a background music stream f This assumes you have a functioning icecast2/whatever installation already. ``` -% sudo apt install libshout3-dev % mkdir -p ~/.dnd/croaker % croaker setup > ~/.dnd/croaker/defaults % vi ~/.dnd/croaker/defaults # adjust to taste @@ -58,8 +59,9 @@ Escape character is '^]'. help -PLAY PLAYLIST - Switch to the specified playlist. -LIST [PLAYLIST] - List playlists or contents of the specified list. +PLAY PLAYLIST - Load and play the specified playlist. +LIST [PLAYLIST] - List all lplaylists or the contents of a single playlist. +BACK - Return to the previous track in the playlist FFWD - Skip to the next track in the playlist. HELP - Display command help. KTHX - Close the current connection.