Configuration

Melodee exposes configuration through environment variables, the web UI, and (internally) a dynamic settings registry. This page outlines common areas to tune.

For a comprehensive reference of all configuration options, see the Configuration Reference page.

Configuration Sources

Priority (highest wins):

  1. Environment variables (.env / container env)
  2. UI overrides (persisted in database)
  3. Default appsettings & internal defaults

Core Categories

Server & Network

  • MELODEE_PORT: External port to expose web & API.
  • BASE_URL (planned): Canonical base URL for reverse proxy setups.

Database

Provided via compose. Ensure DB_PASSWORD is strong. For external Postgres, set connection string variables (coming doc expansion).

Libraries

Three logical areas:

  • Inbound: Raw, unprocessed files.
  • Staging: Processed, awaiting review & metadata edits.
  • Storage: Published canonical library (served to users / APIs).

Ensure sufficient disk and backup strategy, especially for storage volume.

Metadata & Enrichment

Providers: MusicBrainz (local cache), Last.FM, Spotify, iTunes, Brave Search.

Typical options (UI section):

  • Enable/disable provider.
  • API keys / tokens (Spotify, Last.FM, Brave Search).
  • Artwork size preferences.
  • Local MusicBrainz database refresh interval.

Brave Search API Configuration

To enable image search via Brave Search API, you’ll need to:

  1. Get a free API key from Brave Search API
  2. Set the following environment variables: 
    BRAVE_SEARCH__ENABLED=true
BRAVE_SEARCH__APIKEY=your_brave_api_key_here
  3. Optionally configure base URL and search path (defaults are usually fine): 
    BRAVE_SEARCH__BASEURL=https://api.search.brave.com
BRAVE_SEARCH__IMAGESEARCHPATH=/res/v1/images/search

Brave Search provides high-quality image results for both artist portraits and album covers.

Ingestion Rules

Rule engine applies deterministic transformations:

  • Remove “(feat. X)” from title -> moves featured artist into artist metadata fields.
  • Normalize numbering (track 1 -> 01 or 1 based on style).
  • Strip stray unicode punctuation / marketing phrases.
  • Enforce required tags (Album, Artist, Title, Track, Duration) else item stays in staging.

Transcoding & Streaming

Settings (some forthcoming in UI):

  • Preferred output format (Opus / MP3) for constrained bandwidth clients.
  • Max concurrent streams per user (enforced by streaming limiter service).
  • Buffered vs direct streaming (SettingRegistry.StreamingUseBufferedResponses). Buffered is safer for some reverse proxies; direct is lower latency.

Jobs & Scheduling

Jobs run on cron‑like schedules (scan inbound, stage promotion, metadata refresh). Adjust intervals balancing freshness vs resource usage.

Security

  • First user is admin—create additional non‑admin accounts for daily use.
  • API keys are GUIDs associated with users; rotate by regenerating user key if compromised.
  • Blacklist service can deny by email or IP (used to mitigate abuse).

Logging

Structured logging via Serilog. Configure sinks (console, file, etc.) in appsettings or environment overrides (documentation forthcoming for custom sinks).

Environment Variable Examples

DB_PASSWORD=supersecret
MELODEE_PORT=8080
# FUTURE (illustrative):
# STREAMING_USE_BUFFERED=true
# MAX_CONCURRENT_STREAMS=3

Observability & Metrics

System statistics endpoint (native API) surfaces counts (songs, albums, artists, etc.) — see /api/ for details. Future metrics (transcoding time, cache hit rates) planned.

Homelab Security & Optimization

Reverse Proxy Setup

For homelab deployments, it’s strongly recommended to put Melodee behind a reverse proxy:

Nginx Example:

server {
    listen 443 ssl http2;
    server_name music.yourdomain.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Increase buffer sizes for media streaming
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
}

Traefik Example:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.melodee.rule=Host(`music.yourdomain.com`)"
  - "traefik.http.routers.melodee.tls=true"
  - "traefik.http.routers.melodee.entrypoints=websecure"
  - "traefik.http.services.melodee.loadbalancer.server.port=8080"

Performance Tuning for Homelabs

Database Connection Pool:

DB_MIN_POOL_SIZE=10
DB_MAX_POOL_SIZE=50

Media Processing:

  • Adjust MaxConcurrentStreams based on your hardware capabilities
  • Configure transcoding quality settings based on your network bandwidth
  • Set appropriate scan intervals to balance freshness with system load

Storage Optimization:

  • Mount media volumes to separate drives for performance
  • Use SSDs for the database volume
  • Consider separate volumes for different library types (lossless vs lossy)

Hardening Checklist

  • Put behind a reverse proxy (nginx / Caddy) with TLS.
  • Restrict inbound port to proxy layer only.
  • Regularly export DB & storage backups.
  • Monitor log volume for anomalous access.

Updating Configuration

  1. Change value in UI or env.
  2. Restart service if an env var (some dynamic settings reload automatically).
  3. Observe logs for validation warnings.

Coming Soon

  • Editable YAML/JSON advanced config export/import.
  • Live reload for transcoding profiles.
  • Per‑user bandwidth caps.

Have a config use‑case not covered? Open an issue so we can expand this section.