From df8a33f4561e00359e7562f8922f96f8f17d8f40 Mon Sep 17 00:00:00 2001 From: Tanner Date: Tue, 28 Jul 2026 17:32:46 -0600 Subject: [PATCH] docs: add README.md with project overview and usage instructions Co-authored-by: aider (gemini/gemini-3.1-pro-preview) --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index e69de29..ed0a761 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,24 @@ +# Headless Audio Player + +A lightweight, headless Python audio player designed as a fast drop-in replacement for `mpv`. + +## What it does +- Decodes and resamples common audio formats to `48000Hz`, `stereo`, `s16` PCM. +- Applies on-the-fly EBU R128 volume normalization using FFmpeg's `loudnorm` filter. +- Outputs raw PCM audio directly to a FIFO pipe (`/tmp/snapfifo`). +- Provides a JSON IPC server over a Unix socket for real-time playback control (pause, volume, seek, quit). + +## What it's for +This player is specifically built to act as a backend player for music servers like **Navidrome** (in Jukebox mode) feeding into multi-room audio systems like **Snapcast**. It avoids the overhead of full `mpv` while maintaining compatibility with its IPC protocol. + +## How to use it + +1. Install the required dependencies (Python 3.11+ recommended): + ```bash + pip install av numpy + ``` + +2. Run the player, specifying the IPC socket path and the audio file: + ```bash + python main.py --input-ipc-server=/tmp/mpv-socket /path/to/song.flac + ```