screamplay — play audio files over the network with the Scream protocol

AI-generated code. Developed with the assistance of an AI agent (Gemini CLI) with minimal human intervention. Review the code before production use.

What it does

Multi-format. libsndfile decodes WAV, FLAC, OGG, AIFF and MP3 where the local libsndfile supports it.
Intelligent resampling. libsamplerate converts non-standard rates (24 kHz, say) to a receiver-friendly 48 kHz automatically.
High-precision pacing. clock_nanosleep emits packets at exactly the required bitrate, so the stream does not drift.

Build

# Debian/Ubuntu
sudo apt install build-essential pkg-config libsndfile1-dev libsamplerate0-dev
# Fedora/RHEL
sudo dnf install gcc make pkgconf-pkg-config libsndfile-devel libsamplerate-devel
# Arch
sudo pacman -S base-devel pkgconf libsndfile libsamplerate

git clone https://github.com/zirize/screamplay.git
cd screamplay
make
sudo install -m755 screamplay /usr/local/bin/   # optional

Usage

./screamplay [options] <audio_file>

Flag	Long form	Description
`-H <host>`	`--host`	Target receiver IP (default `239.255.77.77`)
`-P <port>`	`--port`	Target UDP port (default `4010`)
`-v`	`--verbose`	Print file info and resampling details
`-h`	`--help`	Show help and exit

# default Scream multicast broadcast
./screamplay music.flac

# a specific receiver
./screamplay -H 192.168.1.100 -P 4010 music.flac

# see what it decided about rate, channels and resampling
./screamplay -v music.ogg

Receivers

Any standard Scream receiver: the Unix receiver from the main Scream repository (./scream -o alsa or -o pulse) on Linux, ScreamReader on Windows. scripts/setup_scream_receiver.sh downloads and builds the Unix receiver into vendor/ for local testing.

Script	Description
`install_libsndfile.sh`	Installs libsndfile on Debian/Ubuntu or Arch
`install_samplerate.sh`	Installs libsamplerate on Debian/Ubuntu or Arch
`setup_scream_receiver.sh`	Builds the official Scream Unix receiver locally
`debug_capture.sh`	Runs a receiver in raw mode and dumps PCM for analysis

Testing

pip install pytest
pytest tests/ -v

The suite generates a dummy WAV, starts a mock UDP receiver, runs screamplay, and validates that the Scream protocol header — sample rate, bit depth, channels — is formed correctly.

Troubleshooting

No audio at the receiver — confirm the IP and port, open the firewall (sudo ufw allow 4010/udp), check the route.
pkg-config error during make — the -dev packages for libsndfile and libsamplerate are missing.
Unsupported sample rate — it resamples to 48 kHz automatically; use -v to confirm.

Licence

GNU Lesser General Public License v2.1.