Companion API

The Companion API is an optional Python FastAPI server that runs alongside Navidrome to handle heavy lifting, metadata writes, and real-time push events.

Features

Smart DJ Analysis: Pre-computes BPM, silence boundaries, and LUFS.
Visualizer Pre-computation: Generates FFT frames on the server to save iOS battery life.
Metadata & Uploads: Mutagen-powered remote ID3 editing, and ZIP extraction/upload handling.
WebSocket Push & SyncEngine: Edits and uploads trigger real-time WebSocket pings (.companionMetadataUpdated, .companionTrackUploaded), instantly kicking off a delta-sync on iOS without waiting for background refresh cycles.

Docker Setup (`docker-compose.yml`)

Place the companion adjacent to your Navidrome container. Note: Ensure the volume mount maps directly to the music root (e.g., MUSIC_DIR=/music).

services:
  navidrome:
    image: deluan/navidrome:latest
    ports:
      - "4533:4533"
    volumes:
      - /home/pi/navidrome:/music:ro
      - ./navidrome_data:/data

  music-companion:
    build: ./companion_api
    ports:
      - "8000:8000"
    volumes:
      - /home/pi/navidrome/music:/music:rw
      - ./companion_data:/app/data
    environment:
      - MUSIC_DIR=/music
      - DB_PATH=/app/data/smart_dj.db
      - VIS_CACHE_DIR=/app/data/vis_cache
      - NAVIDROME_URL=http://navidrome:4533/navidrome
      - SUBSONIC_USER=your_username
      - SUBSONIC_TOKEN=your_token
      - SUBSONIC_SALT=your_salt

CLI Commands

Start: docker compose up -d
Analyze All Missing: docker compose exec music-companion python pre_analyze.py
Force Re-analyze All: docker compose exec music-companion python pre_analyze.py --force

API Endpoints

GET /health - Status and metrics.
PATCH /edit-metadata - Edit ID3 tags.
POST /upload-track - Upload and tag new audio files.
GET /smart-dj/profile & /bulk-profiles - Fetch analysis data.
GET /visualizer/frames - Fetch FFT frames.
WS /ws/push - Real-time client updates.

Companion API

Features

Docker Setup (docker-compose.yml)

CLI Commands

API Endpoints

Docker Setup (`docker-compose.yml`)