Main/docs/configuration.md

Configuration Reference

Shanty is configured via a YAML file and environment variables. Environment variables always override values from the YAML file.

Config File Location

By default, Shanty looks for its config file at:

• Linux: ~/.config/shanty/config.yaml
• Docker: /config/config.yaml
• Custom: Set the SHANTY_CONFIG environment variable to any path.

If no config file exists, Shanty uses sensible defaults for everything. You can also configure most settings from the web UI under Settings, which writes changes back to the YAML file.

Environment Variables

These environment variables override their corresponding YAML settings. In Docker, set them in the environment section of your docker-compose.yml.

Variable	Default	Description
SHANTY_CONFIG	~/.config/shanty/config.yaml	Path to the YAML config file
SHANTY_DATA_DIR	~/.local/share/shanty	Base directory for application data (database, downloads, Firefox profile). In Docker, this is /data.
SHANTY_DATABASE_URL	sqlite://~/.local/share/shanty/shanty.db?mode=rwc	Full SQLite connection string
SHANTY_LIBRARY_PATH	System music directory (~/Music)	Path to your music library
SHANTY_WEB_PORT	8085	HTTP server port
SHANTY_WEB_BIND	0.0.0.0	HTTP server bind address
SHANTY_LASTFM_API_KEY	(none)	Last.fm API key for artist bios and similar-artist playlists. Get one at https://www.last.fm/api/account/create
SHANTY_FANART_API_KEY	(none)	fanart.tv API key for artist images and banners. Get one at https://fanart.tv/get-an-api-key/

Full Config Reference

Below is every configuration option grouped by section.

---

Root Options

These are top-level keys in the YAML file.

library_path

• Type: string (file path)
• Default: System music directory (e.g., ~/Music)
• Env override: SHANTY_LIBRARY_PATH
• Description: The root directory of your music library. Organized files are placed here according to the organization_format template.
• Example: library_path: /home/user/Music

database_url

• Type: string
• Default: sqlite://~/.local/share/shanty/shanty.db?mode=rwc
• Env override: SHANTY_DATABASE_URL
• Description: SQLite database connection string. The ?mode=rwc suffix means read-write-create (the database file is created automatically if it does not exist).
• Example: database_url: sqlite:///data/shanty.db?mode=rwc

download_path

• Type: string (file path)
• Default: ~/.local/share/shanty/downloads
• Description: Temporary directory where yt-dlp stores downloaded files before they are tagged and organized into the library.
• Example: download_path: /tmp/shanty-downloads

organization_format

• Type: string (template)
• Default: {artist}/{album}/{track_number} - {title}.{ext}
• Description: Template for organizing files in the library. Available placeholders: {artist}, {album}, {title}, {track_number}, {ext}, {year}, {genre}.
• Example: organization_format: "{artist}/{album} ({year})/{track_number} - {title}.{ext}"

allowed_secondary_types

• Type: list of strings
• Default: [] (empty, meaning studio albums only)
• Description: Which secondary release group types to include when displaying an artist's discography. By default, only pure studio albums (with no secondary type) are shown. Add types to this list to also see compilations, live albums, etc.
• Options: Compilation, Live, Soundtrack, Remix, DJ-mix, Demo
• Example:

  allowed_secondary_types:
    - Compilation
    - Live
  

log_level

• Type: string
• Default: info
• Description: Log verbosity level. The -v CLI flag overrides this at runtime.
• Options: error, warn, info, debug, trace
• Example: log_level: debug

---

web Section

Controls the HTTP server.

web.port

• Type: integer
• Default: 8085
• Env override: SHANTY_WEB_PORT
• Description: Port the web server listens on.
• Example:

  web:
    port: 9090
  

web.bind

• Type: string
• Default: 0.0.0.0
• Env override: SHANTY_WEB_BIND
• Description: Address the web server binds to. Use 0.0.0.0 to accept connections from any interface, or 127.0.0.1 to restrict to localhost.
• Example:

  web:
    bind: 127.0.0.1
  

---

tagging Section

Controls automatic file tagging behavior.

tagging.auto_tag

• Type: boolean
• Default: false
• Description: Whether to automatically tag files during indexing. When false, tagging must be triggered manually or as part of the pipeline.
• Example:

  tagging:
    auto_tag: true
  

tagging.write_tags

• Type: boolean
• Default: true
• Description: Whether to actually write tags to audio files. When false, the tagger runs in dry-run mode (useful for testing).
• Example:

  tagging:
    write_tags: false
  

tagging.confidence

• Type: float (0.0 to 1.0)
• Default: 0.8
• Description: Minimum confidence threshold for fuzzy matching when the tagger tries to identify a track. Higher values mean stricter matching. Tracks below this threshold are skipped.
• Example:

  tagging:
    confidence: 0.9
  

---

download Section

Controls the download backend (yt-dlp).

download.format

• Type: string
• Default: opus
• Description: Audio format for downloaded files.
• Options: opus, mp3, m4a, flac
• Example:

  download:
    format: mp3
  

download.search_source

• Type: string
• Default: ytmusic
• Description: Search backend for finding tracks to download.
• Options: ytmusic (YouTube Music via ytmusicapi)
• Example:

  download:
    search_source: ytmusic
  

download.cookies_path

• Type: string (file path) or null
• Default: null (no cookies)
• Description: Path to a Netscape-format cookies file for YouTube authentication. Usually managed automatically by the YouTube auth feature. When set, the authenticated rate limit is used.
• Example:

  download:
    cookies_path: /data/cookies.txt
  

download.rate_limit

• Type: integer
• Default: 250
• Description: Maximum download requests per hour when not authenticated. YouTube's actual limit is roughly 300; the default includes a safety margin.
• Example:

  download:
    rate_limit: 200
  

download.rate_limit_auth

• Type: integer
• Default: 1800
• Description: Maximum download requests per hour when authenticated with cookies. YouTube's actual limit is roughly 2000; the default includes a safety margin.
• Example:

  download:
    rate_limit_auth: 1500
  

download.cookie_refresh_enabled

• Type: boolean
• Default: false
• Description: Whether to automatically refresh YouTube cookies using headless Firefox. Enabled automatically when you log in via the YouTube Authentication feature in Settings.
• Example:

  download:
    cookie_refresh_enabled: true
  

download.cookie_refresh_hours

• Type: integer
• Default: 6
• Description: How often (in hours) to refresh YouTube cookies. YouTube cookies typically expire after about 2 weeks, so refreshing every 6 hours keeps them fresh.
• Example:

  download:
    cookie_refresh_hours: 12
  

download.vnc_port

• Type: integer
• Default: 6080
• Description: Port for the noVNC web interface used during interactive YouTube login. This port must be accessible from your browser.
• Example:

  download:
    vnc_port: 6081
  

---

indexing Section

Controls the library scanner.

indexing.concurrency

• Type: integer
• Default: 4
• Description: Number of files to process concurrently during a library scan. Higher values use more CPU and memory but scan faster.
• Example:

  indexing:
    concurrency: 8
  

---

metadata Section

Controls where artist metadata, images, lyrics, and cover art come from.

metadata.metadata_source

• Type: string
• Default: musicbrainz
• Description: Source for structured metadata (artist info, release data, track listings).
• Options: musicbrainz
• Example:

  metadata:
    metadata_source: musicbrainz
  

metadata.artist_image_source

• Type: string
• Default: wikipedia
• Description: Source for artist photos. Wikipedia works without an API key. fanart.tv provides higher quality images and background banners but requires SHANTY_FANART_API_KEY.
• Options: wikipedia, fanarttv
• Example:

  metadata:
    artist_image_source: fanarttv
  

metadata.artist_bio_source

• Type: string
• Default: wikipedia
• Description: Source for artist biographies. Wikipedia works without an API key. Last.fm provides more music-focused bios but requires SHANTY_LASTFM_API_KEY.
• Options: wikipedia, lastfm
• Example:

  metadata:
    artist_bio_source: lastfm
  

metadata.lyrics_source

• Type: string
• Default: lrclib
• Description: Source for song lyrics. LRCLIB provides both plain and time-synced lyrics.
• Options: lrclib
• Example:

  metadata:
    lyrics_source: lrclib
  

metadata.cover_art_source

• Type: string
• Default: coverartarchive
• Description: Source for album cover art.
• Options: coverartarchive
• Example:

  metadata:
    cover_art_source: coverartarchive
  

---

scheduling Section

Controls automatic background tasks.

scheduling.pipeline_enabled

• Type: boolean
• Default: true
• Description: Whether the download pipeline (sync, download, tag, organize) runs automatically on a schedule.
• Example:

  scheduling:
    pipeline_enabled: false
  

scheduling.pipeline_interval_hours

• Type: integer
• Default: 3
• Description: Hours between automatic pipeline runs. The timer starts after the previous run completes.
• Example:

  scheduling:
    pipeline_interval_hours: 6
  

scheduling.monitor_enabled

• Type: boolean
• Default: true
• Description: Whether the monitor automatically checks for new releases from monitored artists.
• Example:

  scheduling:
    monitor_enabled: false
  

scheduling.monitor_interval_hours

• Type: integer
• Default: 12
• Description: Hours between automatic monitor checks.
• Example:

  scheduling:
    monitor_interval_hours: 24
  

---

subsonic Section

Controls the Subsonic-compatible streaming API.

subsonic.enabled

• Type: boolean
• Default: true
• Description: Whether the Subsonic API is active. The API is served at /rest/* on the same port as the web UI.
• Example:

  subsonic:
    enabled: false
  

subsonic.transcoding_enabled

• Type: boolean
• Default: true
• Description: Whether to transcode audio files (e.g., Opus to MP3) when streaming via the Subsonic API. Requires ffmpeg. Disable if your clients natively support your download format.
• Example:

  subsonic:
    transcoding_enabled: false
  

---

musicbrainz Section

Controls the local MusicBrainz database for faster lookups.

musicbrainz.local_db_path

• Type: string (file path) or null
• Default: null (auto-detected at {data_dir}/shanty-mb.db)
• Description: Path to the local MusicBrainz SQLite database. If not set and the file exists at the default location, it is used automatically. If not set and the file does not exist, only the remote MusicBrainz API is used.
• Example:

  musicbrainz:
    local_db_path: /data/shanty-mb.db
  

musicbrainz.auto_update

• Type: boolean
• Default: false
• Description: Whether to automatically re-download and re-import MusicBrainz dumps on a weekly schedule.
• Example:

  musicbrainz:
    auto_update: true
  

---

Full Example Config

library_path: /music
download_path: /data/downloads
organization_format: "{artist}/{album}/{track_number} - {title}.{ext}"
log_level: info

allowed_secondary_types:
  - Compilation

web:
  port: 8085
  bind: 0.0.0.0

tagging:
  write_tags: true
  confidence: 0.8

download:
  format: opus
  search_source: ytmusic
  rate_limit: 250
  rate_limit_auth: 1800

indexing:
  concurrency: 4

metadata:
  metadata_source: musicbrainz
  artist_image_source: wikipedia
  artist_bio_source: wikipedia
  lyrics_source: lrclib
  cover_art_source: coverartarchive

scheduling:
  pipeline_enabled: true
  pipeline_interval_hours: 3
  monitor_enabled: true
  monitor_interval_hours: 12

subsonic:
  enabled: true
  transcoding_enabled: true

musicbrainz:
  auto_update: false