documentation
This commit is contained in:
Connor Johnstone
@@ -0,0 +1,461 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user