configuration

freqhole-config.toml is the main config file. the desktop app creates and manages it automatically, but you can edit it directly.

location

platform	location
macOS (app)	~/Library/Application Support/net.freqhole.charnel/freqhole-config.toml
Linux (app)	~/.local/share/net.freqhole.charnel/freqhole-config.toml
CLI	current directory, or in the same directory as binary

---

key settings

data directory

data_dir = "data/"

where databases and blobs are stored. can be absolute or relative to the config file. the desktop setup wizard lets you choose this during first run — it can be on an external drive, a NAS mount, or anywhere else you have write access.

database

[database]
filename = "grimoire.db"
auto_run_migrations = false

• filename: SQLite database file (inside data_dir)
• auto_run_migrations: apply schema updates on startup

media

[media]
supported_audio_formats = ["mp3", "flac", "ogg", "m4a", "wav", "opus"]
skip_duplicates = true

supported formats and deduplication behavior for scanning and upload.

server

[server]
enabled = true
host = "127.0.0.1"
port = 8080

• host: bind address (0.0.0.0 for all interfaces, 127.0.0.1 for localhost only)
• port: HTTP port (default 8080)

authentication

[server.auth]
webauthn_enabled = true
session_cookie_mode = "auto"
allowed_origins = ["http://localhost:1420"]

• webauthn_enabled: enable passkey authentication
• session_cookie_mode: "auto" (recommended), "lax", or "none"
• allowed_origins: origins permitted for CORS and WebAuthn

federation (P2P)

[federation]
enabled = true

enables P2P sharing via iroh. your server gets a unique node ID that friends use to connect — no port forwarding required.

MusicBrainz

[musicbrainz]
enabled = true
preferred_country = "US"

enables the MusicBrainz lookup feature in the album editor. lookups are always initiated manually. preferred_country biases search results toward releases from that country (ISO 3166-1 alpha-2).

see the metadata enrichment guide for details.

last.fm

[lastfm]
enabled = true
api_key = "your-api-key-here"

fetches album wiki summaries, artist bios, top tags (folksonomy), and similar artists. requires a free api key from last.fm/api/account/create.

only the api key is needed — read-only enrichment doesn’t use the shared secret or any of the other oauth values last.fm hands back. paste the api key string and ignore the rest.

LASTFM_API_KEY environment variable overrides the value in the config file.

see the metadata enrichment guide for details.

theaudiodb

[audiodb]
enabled = true
api_key = "123"

fetches artist bios, artist images (thumbnails, banners, fanart), album artwork, and genre/style tags. the default "123" is theaudiodb’s public free test key for low-volume non-commercial use. for heavier use, donate at theaudiodb.com to get a real key.

AUDIODB_API_KEY environment variable overrides the value in the config file.

see the metadata enrichment guide for details.

audio (rodio/cpal buffer)

[audio]
linux_buffer_frames = 4096

improved audio backend tuning + configuration. only consumed when the rodio-playback cargo feature is on (charnel desktop app, cli serve). web-only builds ignore this section.

linux_buffer_frames is linux only — cpal output period size in frames. raise this if you hear stutters or xruns under load (typical culprits: pipewire/pulseaudio on busy desktops, vm guests, low-power boards). each doubling roughly doubles output latency but adds proportional headroom against scheduler jitter.

• default when unset: 2048 (~43ms @ 48kHz)
• try 4096 (~85ms) if 2048 still glitches
• try 8192 (~170ms) for the heaviest cases

---

desktop app: charnel-config.toml

the desktop app has its own config file, charnel-config.toml, which stores app-level preferences and tells the app where to find freqhole-config.toml. it’s written automatically during first-run setup — you don’t normally need to edit it.

# charnel-config.toml (generated by the desktop app)
version = "0.1.12"
server_config_path = "/Users/you/Library/Application Support/net.freqhole.charnel/freqhole-config.toml"
tray_enabled = true
sync_queue_to_local = true

[logging]
file = "charnel.log"
max_lines = 10000

the server_config_path entry is how the app knows where your freqhole-config.toml lives — which can be anywhere you chose during setup. the CLI doesn’t use charnel-config.toml at all.