# Configuration For remote providers (Navidrome, Plex, Jellyfin, Emby, Spotify, Qobuz, NetEase, YouTube Music), the fastest path is the interactive wizard: ```sh cliamp setup ``` It validates your credentials live and writes the right TOML block without touching the rest of your config. See [cli.md](https://developers.contextowl.co/w/cliamp/cli-flags#setup-wizard) for details. ## Config directory cliamp resolves its config directory in this order: - `CLIAMP_CONFIG_DIR` - `XDG_CONFIG_HOME/cliamp` - `HOME/.config/cliamp` - on Windows, `%APPDATA%\cliamp` when `HOME` is not set The examples below use `~/.config/cliamp` for brevity. On Windows without `HOME`, replace that path with `%APPDATA%\cliamp`. For everything else, copy the example config and edit by hand: ```sh mkdir -p ~/.config/cliamp cp config.toml.example ~/.config/cliamp/config.toml ``` ## Options ```toml # Default volume in dB (range: volume_min to 6) volume = 0 # Minimum volume floor in dB (range: -90 to 0, default: -50) # Controls how low the volume control can go. volume_min = -50 # Repeat mode: "off", "all", or "one" repeat = "off" # Start with shuffle enabled shuffle = false # Start with mono output (L+R downmix) mono = false # Initial directory for the file browser ('o' key) initial_directory = "~/Music" # Shift+Left/Right seek jump in seconds seek_large_step_sec = 30 # EQ preset: "Flat", "Rock", "Pop", "Jazz", "Classical", # "Bass Boost", "Treble Boost", "Vocal", "Electronic", "Acoustic" # Leave empty or "Custom" to use manual eq values below eq_preset = "Flat" # 10-band EQ gains in dB (range: -12 to 12) # Bands: 70Hz, 180Hz, 320Hz, 600Hz, 1kHz, 3kHz, 6kHz, 12kHz, 14kHz, 16kHz # Only used when eq_preset is "Custom" or empty eq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] # Visualizer mode (leave empty for default Bars) # Options: Bars, BarsDot, Rain, BarsOutline, Bricks, Columns, ClassicPeak, Wave, Scatter, Flame, Retro, Pulse, Matrix, Binary, Sakura, Firework, Bubbles, Logo, Terrain, Scope, Heartbeat, Butterfly, Ascii, Firefly, Mosaic, Sand, Geyser, ClassicLED, None visualizer = "Bars" # Visualizer volume linking (default: true) # When true, bar height follows the current volume level (classic behavior). # Set to false to decouple the visualizer from volume — bars stay visible # even at very low volume levels. vis_volume_linked = true # Reduce CPU usage by lowering UI cadence and disabling visualization. # This has the same effect as starting with --low-power. low_power = false # Compact mode: cap UI width at 80 columns (default: fluid/full-width) compact = false # UI theme name (see available themes in ~/.config/cliamp/themes/) theme = "Tokyo Night" # Log level: "debug", "info", "warn", or "error" (default "info") # Logs are written to ~/.config/cliamp/cliamp.log log_level = "info" ``` ## Secrets from Environment Variables Any string value in `config.toml` can be read from an environment variable by setting the value to `$VAR_NAME` or `${VAR_NAME}`. This keeps passwords, tokens, and client secrets out of the file itself. ```toml [navidrome] url = "https://music.example.com" user = "alice" password = "${NAVIDROME_PASSWORD}" [plex] url = "http://plex.local:32400" token = "$PLEX_TOKEN" [jellyfin] url = "https://jelly.example.com" token = "${JELLYFIN_TOKEN}" [emby] url = "https://emby.example.com" token = "${EMBY_TOKEN}" [ytmusic] client_id = "${YTMUSIC_CLIENT_ID}" client_secret = "${YTMUSIC_CLIENT_SECRET}" ``` Rules: - Interpolation only happens when the **entire** value is `$NAME` or `${NAME}`. Mixed values like `"p@$$word"` are kept literally — no escaping needed. - Variable names match `[A-Za-z_][A-Za-z0-9_]*`. - If the variable is unset, the value is empty (the same as if you had left it blank). - Works for any string field, including plugin config under `[plugins.]`. ## Default Provider Set which provider to start with: ```toml provider = "radio" ``` Valid values: `radio` (default), `navidrome`, `spotify`, `plex`, `jellyfin`, `emby`, `qobuz`, `soundcloud`, `netease`, `yt`, `youtube`, `ytmusic`. You can also override from the CLI: `cliamp --provider jellyfin`. ## SoundCloud SoundCloud is opt-in. Add the section to `~/.config/cliamp/config.toml` to register the provider: ```toml [soundcloud] enabled = true ``` Once enabled, search works via `Ctrl+F`, pasted SoundCloud URLs play through yt-dlp, and the empty browse view is seeded with a curated set of search-backed genre playlists (**Trending**, **Hip-Hop**, **Electronic**, **House**, **Lo-Fi**, **Indie**, **Pop**) so there's something to explore on first launch. > SoundCloud's official charts/discover endpoints all 404 through yt-dlp at present, so cliamp can't surface real chart data anonymously. The genre playlists are search-backed (results vary in quality but reflect current uploads). ### Browse a profile Set a username to expose that profile's tracks, likes, and reposts in the browse view: ```toml [soundcloud] enabled = true user = "yourname" ``` Three playlists appear: **Tracks**, **Likes**, and **Reposts** for `soundcloud.com/yourname`. Works for any public profile. ### Sign in via browser cookies SoundCloud closed its OAuth program in 2014, so the bring-your-own-client_id pattern Spotify uses isn't available. Instead, point yt-dlp at your existing browser session — it picks up your SoundCloud login from the browser cookie jar: ```toml [soundcloud] enabled = true user = "yourname" cookies_from = "firefox" # or chrome, chromium, brave, edge, opera, safari, vivaldi ``` With cookies set, yt-dlp can stream subscriber-gated tracks (SoundCloud Go+) and access private likes/playlists your account is authorized for. The same cookies also apply to the player's yt-dlp invocations, so playback uses your signed-in session. Requires `yt-dlp` on `PATH`. ## NetEase Cloud Music NetEase is opt-in and uses your existing browser session. Sign in at `music.163.com`, then run: ```sh cliamp setup ``` Pick **NetEase Cloud Music** and choose the browser you used to sign in. Common browsers are shown as menu choices; select the custom option only for profile-specific values. The setup wizard validates the session and writes: ```toml [netease] enabled = true cookies_from = "chrome" user_id = "your-account-user-id" ``` Once enabled, the provider shows your liked songs, created playlists, saved playlists, and public charts. Search works with `Ctrl+F`, and playback uses `yt-dlp` with the same browser cookie source. ## Custom Radio Stations Add your own stations to `~/.config/cliamp/radios.toml`: ```toml [[station]] name = "Jazz FM" url = "https://jazz.example.com/stream" [[station]] name = "Ambient Radio" url = "https://ambient.example.com/stream.m3u" ``` These appear alongside the built-in cliamp radio in the Radio provider. See [audio-quality.md](https://developers.contextowl.co/w/cliamp/audio-quality) for sample rate, buffer, bit depth, and resample quality settings. ## WSL2 (Windows Subsystem for Linux) cliamp uses ALSA for audio on Linux. WSL2 doesn't expose ALSA hardware directly, but WSLg provides a PulseAudio server that ALSA can route through. If you see errors like `ALSA lib pcm.c: Unknown PCM default`, fix it with two steps: **1. Install the ALSA PulseAudio plugin:** ```sh sudo apt install libasound2-plugins ``` **2. Create `~/.asoundrc` to route ALSA through PulseAudio:** ```sh cat > ~/.asoundrc << 'EOF' pcm.default pulse ctl.default pulse EOF ``` WSLg must be active (`echo $PULSE_SERVER` should print a path). If it's empty, ensure you're on Windows 11 with WSLg enabled and run `wsl --shutdown` then reopen your terminal. ## ffmpeg (optional) AAC, ALAC (`.m4a`), Opus, and WMA playback requires [ffmpeg](https://ffmpeg.org/): ```sh # Arch sudo pacman -S ffmpeg # Debian/Ubuntu sudo apt install ffmpeg # macOS brew install ffmpeg ``` MP3, WAV, FLAC, and OGG work without ffmpeg.