qotplayer/README.md

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):

   pip install av numpy
   

2. Run the player, specifying the IPC socket path and the audio file:

   python main.py --input-ipc-server=/tmp/mpv-socket /path/to/song.flac