evilchili/dnd-music-console
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
evilchili 2025-09-14 15:51:42 -07:00
parent 0539ce321f
commit 2f5d5105c0
1 changed files with 13 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
README.md
View File

@ -1,27 +1,29 @@
# Croaker # 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 ### Features
* Native streaming of MP3 sources direct to your clients * Audio playback using VLC
* Transcoding of anything your local `ffmpeg` installation can convert to mp3
* Playlists are built using symlinks * Playlists are built using symlinks
* Randomizes playlist order the first time it is cached * Randomizes playlist order the first time it is cached
* Always plays `_theme.mp3` first upon switching to a playlist, if it exists * 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 ### Requirements
* A functioning shoutcast / icecast server * A functioning shoutcast / icecast server
* Python >= 3.10 * Python >= 3.11
* ffmpeg * python3.11-dev
* libshout3-dev
## What? Why? ## 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)* *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. This assumes you have a functioning icecast2/whatever installation already.
``` ```
% sudo apt install libshout3-dev
% mkdir -p ~/.dnd/croaker % mkdir -p ~/.dnd/croaker
% croaker setup > ~/.dnd/croaker/defaults % croaker setup > ~/.dnd/croaker/defaults
% vi ~/.dnd/croaker/defaults # adjust to taste % vi ~/.dnd/croaker/defaults # adjust to taste
@ -58,8 +59,9 @@ Escape character is '^]'.
help help
PLAY PLAYLIST - Switch to the specified playlist. PLAY PLAYLIST - Load and play the specified playlist.
LIST [PLAYLIST] - List playlists or contents of the specified list. 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. FFWD - Skip to the next track in the playlist.
HELP - Display command help. HELP - Display command help.
KTHX - Close the current connection. KTHX - Close the current connection.