Settings file

Your preferences live in one JSON file. Just like themes, it's picked up on the fly.

Location

Linux	`~/.config/sonora/settings.json`
Flatpak	`~/.var/app/io.github.nolight132.sonora/config/sonora/settings.json`
macOS	`~/Library/Application Support/sonora/settings.json`
Windows	`%APPDATA%\sonora\settings.json`

Editing by hand

Missing keys use their defaults. Unknown keys are ignored, and they disappear the next time Sonora saves, because it rewrites the whole file. Here is an example of a valid settings.json:

settings.json

{
  "gapless": true,
  "normalisation": false,
  "close_to_tray": true,
  "startup": "home",
  "local_folders": ["/home/me/Music"],
  "lyrics_providers": ["Local", "Spotify", "LrcLib"],
  "appearance": {
    "theme": "midnight",
    "adaptive_theme": false,
    "icons": "lucide",
    "rounding": "rounded",
    "font_size": 14
  }
}

Break the formatting and Sonora shows Fix line N of settings.json to save changes. It won't save anything until you do. It also won't overwrite the file if something else changed it since Sonora last read it.

Save as UTF-8. Since v0.42.0, a UTF-8 byte order mark, which some Windows editors add, is accepted too.

What isn't in the file

The selected provider, volume, queue resume position, window layout and other runtime state are saved in state.sqlite. Provider sign-in credentials live in separate files in the cache folder. Linked scrobbling accounts, including their tokens and secrets, are stored in settings.json.

Other files

Folder	What's in it
Data	`state.sqlite`, in `~/.local/share/sonora`, `~/Library/Application Support/sonora` or `%LOCALAPPDATA%\sonora`.
Cache	Sign-in credentials, the Widevine module, cached lyrics and artwork, and the local scan index, in `~/.cache/sonora`, `~/Library/Caches/sonora` or `%LOCALAPPDATA%\sonora`. Removing provider credential files signs you out of those providers.

On Windows, data and cache share the same folder. Deleting the whole folder also removes state.sqlite, including local playlists and favorites.

Home Manager

The flake has a Home Manager module. Anything under settings gets merged into settings.json on every switch and every launch. Keys you don't set keep whatever you picked in the app.

home.nix

{
  imports = [ inputs.sonora.homeManagerModules.default ];
  programs.sonora = {
    enable = true;
    settings = {
      gapless = true;
      appearance = {
        theme = "midnight";
        adaptive_theme = false;
      };
    };
  };
}

Use the same preference keys as settings.json. A provider key does not switch services, because the selected provider belongs to runtime state.