cstaelen/castafiore-headless repository overview

⁠Features

• Self-hosted web UI for controlling your Navidrome music library
• Control playback from any phone, tablet using the browser
• Stream music directly to your Raspberry Pi speakers
• Flexible audio output: local (browser) or remote (Raspberry Pi via MPD)
• Equalizer powered by CamillaDSP using dedicated web UI

⚠️ WORK IN PROGRESS

⁠Requirements

• Docker with linux/arm64 or linux/amd64 support
• ALSA-compatible audio device

⁠Usage

⁠docker-compose (recommended)

services:
  castafiore-headless:
    image: cstaelen/castafiore-headless:latest
    devices:
      - /dev/snd
    ports:
      - "8899:8899"
    environment:
      ALSA_DEVICE: plughw:0,0 # run `aplay -l` to list available devices
    restart: unless-stopped

⁠docker run

docker run --rm -p 8899:8899 \
  --device /dev/snd \
  -e ALSA_DEVICE="plughw:0,0" \
  cstaelen/castafiore-headless:latest

Then open http://<host>:8899 in your browser and connect to your Navidrome/Subsonic server.

Castafiore UI lets you switch between two output modes:

• Remote: audio routed through MPD (default in headless mode)
• Local: audio played directly in the browser via HTML audio

⁠Equalizer (optional)

A 10-band parametric EQ powered by CamillaDSP⁠ is available at http://<host>:8899/eq.

To enable it, mount a local config/ directory:

volumes:
  - ./config:/config   # optional — required to use the EQ

On first start, default presets (flat, bass, treble, rock...) are copied to config/presets/. The active config is always config/camilladsp.yml.

Directory layout:

config/
├── camilladsp.yml      # active config (written by the EQ UI)
├── dsp-state.json      # enabled/disabled state (auto-managed)
└── presets/
    ├── flat.yml
    ├── bass.yml
    └── custom.yml      # add your own YML files here

Selecting a preset in the UI copies it to camilladsp.yml. Adjusting a slider writes directly to camilladsp.yml and keeps the active preset file in sync.

The ALSA_DEVICE environment variable is automatically injected into all preset files on first start. Run aplay -l inside the container to list available devices.

⁠Environment variables

⁠List available audio devices

docker run --rm --device /dev/snd cstaelen/castafiore-headless:latest aplay -l

⁠Architecture

• Node.js server serves the Castafiore web app (static files) and a REST API on a single port (8899)
• MPD handles audio playback via ALSA, internal to the container (port 6600 is never exposed)
• The browser controls MPD through /api/* endpoints served by the same Node.js server

⁠Build

# Local build
make build

# Multi-arch push (amd64 + arm64)
make push

# arm64 only (Raspberry Pi)
make push-rpi