Configuration

Tune LibreLyrics' behaviour with a simple JSON config file. Every setting has a sensible default — edit only what you need.

File Location

The config file is created automatically on first run. Location depends on your OS:

# Linux / macOS
~/.config/librelyrics/config.json

# Windows
%APPDATA%\librelyrics\config.json

Tip: Run librelyrics config path to print the exact location on your machine.

Config Keys

Key	Type	Default	Description
`output_dir`	`str`	`"./lyrics"`	Directory where `.lrc` / `.txt` files are saved.
`file_format`	`str`	`"lrc"`	`"lrc"` or `"txt"`.
`naming`	`str`	`"{artist} - {title}"`	Filename template. Variables: `{artist}`, `{title}`, `{album}`, `{track_number}`.
`synced`	`bool`	`true`	Prefer synced (timestamped) lyrics when available.
`rich_sync`	`bool`	`false`	Request word-level (karaoke) timing if supported.
`enhanced_lrc`	`bool`	`false`	Use Enhanced LRC format (word timestamps inside lines).
`include_metadata`	`bool`	`true`	Include [ti:], [ar:], [al:] tags in LRC output.
`retry_count`	`int`	`3`	Number of automatic retries on transient errors.
`retry_delay`	`int`	`2`	Base delay (seconds) between retries. Exponentially backs off.
`verbose`	`bool`	`false`	Enable DEBUG-level console logging.
`plugins`	`object`	`{}`	Per-plugin configuration (see below).

Full Default Config

{
  "output_dir":  "./lyrics",
  "file_format": "lrc",
  "naming":     "{artist} - {title}",
  "synced":     true,
  "rich_sync":  false,
  "enhanced_lrc": false,
  "include_metadata": true,
  "retry_count": 3,
  "retry_delay": 2,
  "verbose":    false,
  "plugins":    {}
}

Plugin Configuration

Plugins declare their own default keys via default_config(). These defaults are merged into the plugins section automatically. To override, add keys under plugins.<plugin_name>:

{
  "plugins": {
    "spotify": {
      "sp_dc": "YOUR_SPOTIFY_SP_DC_COOKIE"
    },
    "musixmatch": {
      "user_token": "YOUR_MUSIXMATCH_TOKEN"
    }
  }
}

Note: Plugin names are lower-cased class names minus any Module suffix. For example, SpotifyModule → spotify.

CLI Config Management

The librelyrics config sub-command lets you manage settings without manually editing the JSON file.

Command	Description
`config show`	Pretty-print the full current config.
`config edit`	Open the interactive config editor.
`config set <key> <value>`	Update a config value and save.
`config path`	Print the config file path.
`config reset`	Restore the default configuration.

Programmatic Access

Read or mutate config via the ConfigManager class (see API reference).

Read

from librelyrics.config import ConfigManager

cfg = ConfigManager()
print(cfg.get("output_dir"))    # ./lyrics
print(cfg.get("naming"))         # {artist} - {title}

Write

cfg.set("output_dir", "~/Music/Lyrics")
cfg.set("synced", False)
cfg.save()   # persist to disk