Configuration reference
BeetstreamNext settings can be set from various ways:
-
Explicit sources:
- via CLI flag
- via an environment variable
- in plugin mode: via Beets’
config.yaml, under abeetstreamnext:block (see Installation) - in standalone mode: via BeetstreamNext’s config YAML (see Installation)
-
The Admin WebUI: Only for settings that aren’t already pinned by one of the explicit sources above. When a setting is pinned by any of those sources, its field in the Admin panel is locked/disabled.
Settings resolve order (first one set takes precedence):
- in plugin mode:
flowchart LR
A("CLI flag") --> B("environment variable") --> C("Beets' config's <code>beetstreamnext:</code> block") --> D("WebUI setting") --> E("Built-in default")
style A fill:#ffffff12,stroke:#808080
style B fill:#ffffff12,stroke:#808080
style C fill:#ffffff12,stroke:#808080
style D fill:#ffffff12,stroke:#808080
style E fill:#ffffff12,stroke:#808080
- in standalone mode:
flowchart LR
A("CLI flag") --> B("environment variable") --> C("BeetstreamNext's YAML config file") --> D("Beets' config file<br/><br/>(if you point it at one, and only for <code>library-db</code> and <code>music-root</code>)") --> E("WebUI setting") --> F("Built-in default")
style A fill:#ffffff12,stroke:#808080
style B fill:#ffffff12,stroke:#808080
style C fill:#ffffff12,stroke:#808080
style D fill:#ffffff12,stroke:#808080
style E fill:#ffffff12,stroke:#808080
style F fill:#ffffff12,stroke:#808080
For list-based settings (like for example ip_whitelist/ip_blacklist): pinning is per individual entry.
Settings marked requires restart only take effect after the server is restarted. Settings marked standalone only are not used when running as a Beets plugin.
Note
BeetstreamNext checks at startup whether the music folder and the beets library database are writable on disk.
If either isn’t (for example when they’re bind-mounted
:ro, as in the Betanin example stack), the WebUI will show a red “read-only” pill next to any setting that would otherwise need write access.
External services
lastfm_api_key
Last.fm API key for fetching metadata.
sensitive
type: str
default: (empty)
env: BSN_LASTFM_API_KEY
lastfm_shared_secret
Last.fm API shared secret (only needed for Last.fm and Libre.fm scrobbling, with the API key above).
sensitive
type: str
default: (empty)
env: BSN_LASTFM_SHARED_SECRET
external_scrobbling
Let users connect their external scrobbling accounts (ListenBrainz, Last.fm, Libre.fm) and share what they play.
type: bool
default: True
env: BSN_EXTERNAL_SCROBBLING
audiomuse_api_token
API token for your AudioMuse-AI instance.
sensitive
type: str
default: (empty)
env: BSN_AUDIOMUSE_API_TOKEN
audiomuse_url
URL to your AudioMuse-AI instance (e.g. http://localhost:8000) to enable sonic similarity endpoints.
type: str
default: (empty)
podcastindex_api_key
API key for the Podcast Index, used for podcast channel discovery.
sensitive
type: str
default: (empty)
env: BSN_PODCASTINDEX_API_KEY
podcastindex_api_secret
API secret for the Podcast Index.
sensitive
type: str
default: (empty)
env: BSN_PODCASTINDEX_API_SECRET
Server & network
host
Host(s) to listen on (comma-separated for multiple), or unix:/path/to/socket (to use a Unix socket, reverse_proxy has to be enabled)
requires restart
type: list[str]
default: 0.0.0.0
env: BSN_HOST
port
Port to listen on.
requires restart
type: int
default: 8080
env: BSN_PORT
public_hosts
Addresses of host that only serve public pages (shares, tokenised links, health check, homepage). Not compatible with a wildcard host (0.0.0.0).
requires restart
type: list[str]
default: (empty)
env: BSN_PUBLIC_HOSTS
public_port
Extra port that only serves public pages on the other addresses of host. 0 disables it.
requires restart
type: int
default: 0
env: BSN_PUBLIC_PORT
admin_hosts
Addresses of host that serve the admin panel and control API.
requires restart
type: list[str]
default: (empty)
env: BSN_ADMIN_HOSTS
admin_port
Extra port that serves the admin panel and control API on the other addresses of host. 0 disables it.
requires restart
type: int
default: 0
env: BSN_ADMIN_PORT
external_hostname
Public hostname for share links and tokenised stream/image URLs (e.g. public.example.com). If unset, the users-accessible address is used (unless reverse_proxy is on), then the hostname of the request.
type: str
default: (empty)
env: BSN_EXTERNAL_HOSTNAME
threads
Worker threads for serving requests. Each open admin panel tab holds one thread for its live updates, so raise this if several admins are expected.
requires restart
type: int
default: 16
env: BSN_THREADS
channel_timeout
Seconds of inactivity allowed on a connection before Waitress closes it. Lower this on low-resource environments to free up connections faster.
requires restart
type: int
default: 120
connection_limit
Maximum number of simultaneous connections Waitress will accept. Lower this on low-resource environments to cap memory/socket usage.
requires restart
type: int
default: 100
cors_origins
Allowed CORS origins (comma-separated, * for all). Empty to disable CORS.
requires restart
type: str
default: (empty)
env: BSN_CORS_ORIGINS
cors_supports_credentials
Allow CORS requests with credentials (cookies, HTTP auth).
requires restart
type: bool
default: False
env: BSN_CORS_CREDENTIALS
reverse_proxy
Server is behind a reverse proxy (Nginx, Caddy, Traefik, etc.).
requires restart
type: bool
default: False
env: BSN_REVERSE_PROXY
proxy_hops
Number of trusted reverse proxies in front of the server. Only used if reverse_proxy is enabled
requires restart
type: int
default: 1
env: BSN_PROXY_HOPS
trusted_proxies
IPs/CIDR ranges of reverse proxies allowed to set X-Forwarded-* headers. Headers from requests from other addresses are ignored.
Only used if reverse_proxy is enabled. If empty, every peer is trusted. Unix sockets are always trusted.
requires restart
type: list[str]
default: (empty)
env: BSN_TRUSTED_PROXIES
sendfile_method
Offload direct (non-transcoded) file serving to the reverse proxy instead of streaming bytes through Python. Use x-accel-redirect for Nginx, x-sendfile for Apache.
Only takes effect when reverse_proxy is enabled and the proxy is configured to honor the header.
type: str
default: off, choices: off, x-accel-redirect, x-sendfile
env: BSN_SENDFILE_METHOD
sendfile_internal_prefix
Internal URI prefix your Nginx config maps, via an internal-only location block, to the music root directory.
Only used when sendfile_method is x-accel-redirect.
type: str
default: /_bsn_internal
env: BSN_SENDFILE_INTERNAL_PREFIX
trusted_hosts
Allowed Host headers (domain names/IPs, comma-separated).
If empty, all hosts are allowed. Setting this is recommended if the server reachable beyond your own machine.
Loopback is always allowed.
type: str
default: (empty)
env: BSN_TRUSTED_HOSTS
legacy_auth
Allow legacy MD5 token / cleartext password authentication. API-key authentication always works.
type: bool
default: False
env: BSN_LEGACY_AUTH
api_user_management
Allow admins to create, update and delete users, and change other users’ passwords, through the Subsonic API (createUser, updateUser, deleteUser, changePassword). The admin panel is not affected.
type: bool
default: False
env: BSN_API_USER_MANAGEMENT
public_now_playing
Show the currently playing song on the public home page.
type: bool
default: False
homepage_github_link
Show the “View on GitHub” link on the public home page.
type: bool
default: True
homepage_docs_link
Show the “Read the docs” link on the public home page.
type: bool
default: True
homepage_connect_hint
Show the “Connect your favourite client using this URL” hint and server URL on the public home page.
type: bool
default: True
homepage_stats
Show the artists / albums / songs counters on the public homepage.
type: bool
default: True
homepage_subtitle
Subtitle shown under the title on the public homepage. Leave empty to hide it.
type: str
default: Your Beets library, streaming anywhere.
music_root
Root directory your beets library’s file paths are relative to.
standalone only, requires restart
type: str
default: (empty)
library_path
Path to the beets library.db to serve.
standalone only, requires restart
type: str
default: (empty)
library_remote_path
Optional, mount point used by another container that accesses the beets library (e.g. Betanin), if it differs from where ‘music_root’ mounts it in the BeetstreamNext container. Leave empty if both containers mount the music volume at the same path.
standalone only
type: str
default: (empty)
env: BSN_LIBRARY_REMOTE_PATH
playlist_dir
Directory where BeetstreamNext writes its playlists as .m3u files (per-user subfolders for user playlists). Existing files in it are imported once.
Leave empty to disable.
requires restart
type: str
default: (empty)
env: BSN_PLAYLIST_DIR
strict_beets_version_check
Refuse to start on beets version mismatch (see Server Info) instead of just warning.
standalone only, requires restart
type: bool
default: False
Library & metadata
allow_disk_writes
Required to allow beet import scans to modify content on disk (writing tags in the files or copying/moving files). Not needed when the loaded Beets config already has write/copy/move all disabled.
type: bool
default: False
env: BSN_ALLOW_DISK_WRITES
allow_beets_config_edit
Allow editing the Beets config file from the admin panel.
A Beets config could load plugins and run shell commands when an import runs,so whoever can edit it could run code on the server.
This setting is not modifiable from the Web UI.
type: bool
default: False
env: BSN_ALLOW_BEETS_CONFIG_EDIT
control_api_token
Token for the control API (/control-api), which lets external tools and scripts trigger actions on this server (e.g. a Beets import triggered by a download client when a download finishes).
The control API is disabled if this is empty.
sensitive
type: str
default: (empty)
env: BSN_CONTROL_API_TOKEN
import_watch_enabled
Enable automatic Beets import for new files in configured watched folders.
type: bool
default: False
env: BSN_IMPORTWATCH_ENABLED
import_watch_settle
How long to wait (in seconds) for a watched folder to stop changing before importing it (to avoid importing half-copied or half-downloaded albums).
type: int
default: 60
env: BSN_IMPORTWATCH_SETTLE
never_transcode
Never transcode files, always stream the original.
type: bool
default: False
env: BSN_NEVER_TRANSCODE
fetch_artists_images
Fetch missing artist images from external services.
type: bool
default: False
env: BSN_FETCH_ARTISTS_IMAGES
fetch_artists_biographies
Fetch artist short biography from Wikipedia.
type: bool
default: False
save_album_art
Also save fetched album art on disk, alongside music files (in addition to the cache).
type: bool
default: False
env: BSN_SAVE_ALBUM_ART
follow_playlist_embedded_urls
Fetch external images from foreign playlists’ #EXTALBUMARTURL lines (for albums that have no art locally). Only enable this if you trust the source of your imported playlists.
type: bool
default: False
fetch_lyrics
Fetch missing song lyrics using Beets’ Lyrics plugin.
type: bool
default: False
save_lyrics
Save fetched lyrics to the beets library database (this never writes tags into the music files, only to the Beets database).
type: bool
default: False
fetch_album_version
Fetch album version info (“Deluxe Edition”, “Japanese Expanded Edition”, etc.) from MusicBrainz.
type: bool
default: False
save_album_version
Save fetched album version info to the beets database (this never writes tags into the music files, only to the Beets database).
type: bool
default: False
discogs_ratings
Use Discogs’ public community rating for an album’s average rating.fallback: Only use Discogs when nobody on this server has rated the album locally. It never overrides a local rating.prefer: Always uses Discogs when available (falling back to the local average when it isn’t).
type: str
default: off, choices: off, fallback, prefer
ignored_articles
Space-separated articles (across any language) to ignore when sorting artists alphabetically (for instance, “The Beatles” -> B).
type: str
default: The A An Der Die Das Ein Eine El La Los Las Un Una Le Les Il Lo Gli Uno O Os As Um Uma De Het Den Det
ratings_writeback_user
Commit this user’s Likes and Ratings into the Beets library so they survive outside BeetstreamNext. Beets has no concept of per-user data, so only one user’s changes can be committed this way (this never writes tags into the music files, only to the Beets database).
Leave unset to disable.
type: str
default: (empty)
external_playlists_editors
Who can rename/edit/delete non-BeetstreamNext playlists (from Beets’ playlist plugin directory). smartplaylist-generated playlists are always read-only.
type: list[str]
default: (empty)
enable_radio_discovery
Enable Radio Browser API for station discovery.
type: bool
default: False
fetch_radio_images
Automatically fetch station icon when adding a new radio station.
type: bool
default: True
Podcasts
podcast_storage_dir
Directory to store downloaded podcast episode audio. Leave empty to use the default data location.
type: str
default: (empty)
podcast_auto_download_count
Number of episodes to download of a channel’s most recent episodes when added. Set to 0 to disable and only download episodes on request.
type: int
default: 3
enable_podcast_discovery
Enable Podcast Index API for channel discovery.
type: bool
default: False
Audio & jukebox
replaygain_enabled
Apply ReplayGain normalization on the server side.
type: bool
default: False
replaygain_preamp
Additional gain (dB) to apply.
type: int
default: 0
replaygain_fallback
Gain (dB) to apply to tracks without ReplayGain tags in beets’ library.
type: int
default: -6
audio_peak_limit
Always prevent audio peaks from exceeding 0 dB (prevent clipping).
type: bool
default: False
ffmpeg_path
Path to the ffmpeg binary, if it isn’t on the system PATH (e.g. /usr/local/bin/ffmpeg).
Leave empty to auto-detect from PATH.
This setting is not modifiable from the Web UI.
type: str
default: (empty)
env: BSN_FFMPEG_PATH
jukebox_allowed
Allow jukebox mode: the server can play audio on its own hardware, or on a Sonos/Chromecast compatible speaker (client apps act as remote controls).
type: bool
default: False
jukebox_backend
Defines where jukebox mode will play audio from.server_hardware plays on this server’s own audio hardware using mpv.sonos or chromecast stream to a speaker on the local network.
type: str
default: server_hardware, choices: server_hardware, sonos, chromecast
jukebox_hardware_device
Which hardware jukebox mode plays audio on.
For server_hardware, this is the audio output device as mpv’s –audio-device expects (e.g. alsa/hw:0,0 or coreaudio/BuiltInSpeakerDevice), or empty to use the system default.
For sonos, the speaker’s IP address.
For chromecast, either the device’s UUID (found via mDNS/Zeroconf discovery), or its IP address/hostname to connect to it directly.
type: str
default: (empty)
mpv_path
For server_hardware backend only. Path to the mpv binary, if it isn’t on the system PATH (e.g. /usr/local/bin/mpv).
Leave empty to auto-detect from PATH.
This setting is not modifiable from the Web UI.
type: str
default: (empty)
env: BSN_MPV_PATH
Security
restrict_control_api
Only serve the control API (/control-api) on the admin scope listeners. Turn off to also serve it on the users scope.
type: bool
default: True
env: BSN_RESTRICT_CONTROL_API
local_services
Services on the local network that may be contacted: hostnames, IP addresses or CIDR ranges (comma-separated), for example localhost, 192.168.1.0/24.
Connections to private addresses are refused unless they are listed here. Ports are not restricted.
type: list[str]
default: (empty)
env: BSN_LOCAL_SERVICES
ip_whitelist
Allowed IPs (empty = allow all except blacklist).
type: list[str]
default: (empty)
env: BSN_IP_WHITELIST
ip_blacklist
Banned IPs.
type: list[str]
default: (empty)
env: BSN_IP_BLACKLIST
rate_limit_max_failures
Failed attempts before an IP is rate-limited.
type: int
default: 5
rate_limit_block_window
Seconds before failures roll off.
type: int
default: 300
rate_limit_ip_max_failures
Failed attempts from a single IP (across any usernames tried) before that IP is blocked outright. Catches attackers rotating usernames to dodge the per-user limit above.
type: int
default: 20
rate_limit_ip_block_window
Seconds before an IP-wide failure count rolls off.
type: int
default: 3600
Shares
share_default_expiry_days
Days until new shares expire, unless the client sets an expiry (0 = never).
type: int
default: 0
share_default_max_downloads
Download limit for new shares (0 = unlimited).
type: int
default: 0
share_link_previews
Add metadata to share pages to allow chat apps (Discord, Slack, Telegram, …) show a preview with the title and cover art (their servers fetch the page and cover without logging in).
type: bool
default: True
env: BSN_SHARE_LINK_PREVIEWS
share_default_password
Password for new shares (visible to share owners on their account page).
type: str
default: (empty)