Qotplayer

A lightweight, headless Python audio player designed as a fast drop-in replacement for mpv.

This player is specifically built to act as a backend player for Navidrome (in Jukebox mode) feeding into Snapcast. It avoids the overhead of full mpv while maintaining compatibility with its IPC protocol.

This removes about 5 seconds of audio playback lag and UI seeking lag.

What it does

• Decodes and resamples common audio formats to 48000Hz, stereo, s16 PCM.
• 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).
• Maps 0-100 volume levels to 25-100 and applies log scale (for human hearing).

Setup

docker-compose.yml:

services:
  navidrome:
    build: .
    user: 1000:1000 # should be owner of volumes
    ports:
      - "4533:4533"
    restart: unless-stopped
    environment:
      ND_JUKEBOX_ENABLED: true
      ND_MPVCMDTEMPLATE: '/opt/qotplayer/env/bin/python /opt/qotplayer/main.py %f --input-ipc-server=%s'
      ND_LOGLEVEL: info
    volumes:
      - "./data:/data"
      - "/mnt/music-combined:/music:ro"
      - "/tmp/snapfifo:/tmp/snapfifo"

Dockerfile:

FROM deluan/navidrome:latest

RUN apk add --no-cache git curl && \
    curl -LsSf https://astral.sh/uv/install.sh | sh

ENV PATH="/root/.local/bin:$PATH"

WORKDIR /opt
RUN git clone https://git.tanner.vc/tanner/qotplayer.git

WORKDIR /opt/qotplayer
RUN uv venv --python=3.12 env && \
    . env/bin/activate && \
    uv pip install -r requirements.txt

RUN chmod 755 /root

Build and run with:

$ sudo docker compose build --no-cache
$ sudo docker compose up