# 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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  metadata:
    lyrics_source: lrclib
  ```

#### `metadata.cover_art_source`
- **Type:** string
- **Default:** `coverartarchive`
- **Description:** Source for album cover art.
- **Options:** `coverartarchive`
- **Example:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  scheduling:
    monitor_enabled: false
  ```

#### `scheduling.monitor_interval_hours`
- **Type:** integer
- **Default:** `12`
- **Description:** Hours between automatic monitor checks.
- **Example:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  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:**
  ```yaml
  musicbrainz:
    auto_update: true
  ```

---

## Full Example Config

```yaml
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
```