Configuration

You can configure Blanco using either a YAML file or environment variables. When you have both, configuration from environment variables takes precedence over configuration from the YAML file.

Environment variables

The following table lists the environment variables that Blanco uses to configure himself:

Variable name	Description	Type	Required?
BLANCO_DB_FILE	Path to SQLite database file	String	✅
BLANCO_TOKEN	Discord bot token	String	✅
BLANCO_SPOTIFY_ID	Spotify client ID	String	✅
BLANCO_SPOTIFY_SECRET	Spotify client secret	String	✅
BLANCO_MATCH_AHEAD	Whether to enable ahead-of-time track matching ¹	true or false
BLANCO_REENQUEUE_PAUSED	Whether to re-enqueue stale paused tracks ²	true or false

¹ New in Release 0.5.0. When enabled, Blanco will attempt to find a playable Lavalink track for the next track in the queue when a new song starts playing. This lets the next song start playing sooner.

² New in Release 0.5.3. When enabled, Blanco will check if the track being unpaused has been paused for at least X seconds. If true, Blanco will re-enqueue the same track at around the same playback position instead of simply unpausing it. This is a workaround for a bug in Lavalink where the audio server finishes playback prematurely if a paused track is unpaused after a significant amount of time. X is 60 (1 minute) as of Release 0.5.x.

Lavalink nodes

Blanco expects the following environment variables to be set for each Lavalink node, where n in the variable name is an integer incrementing from 1:

Variable name	Description	Required?	Format	Example
BLANCO_NODE_n	Node connection details	✅	label:password@host:port	main:youshallnotpass@localhost:2333
BLANCO_NODE_n_REGIONS	Node regions	✅	Comma-separated list of strings	us-central,us-east
BLANCO_NODE_n_SECURE	Whether the node supports SSL		true or false	false
BLANCO_NODE_n_DEEZER	Whether the node supports playback from Deezer via LavaSrc		true or false	false

Make sure n is a unique integer for each node, and that you don't skip values of n.

Web server

Blanco has an integrated web server that allows users to link their Last.fm and Spotify accounts. To enable the web server, set the following environment variables:

Variable name	Description	Type	Required?
BLANCO_ENABLE_SERVER	Whether to enable the webserver	true or false
BLANCO_SERVER_PORT	Port that the webserver listens on	Integer
BLANCO_BASE_URL	Webserver base URL	String	✅ if BLANCO_ENABLE_SERVER is true
BLANCO_OAUTH_ID	Discord OAuth client ID	String	✅ if BLANCO_ENABLE_SERVER is true
BLANCO_OAUTH_SECRET	Discord OAuth client secret	String	✅ if BLANCO_ENABLE_SERVER is true

BLANCO_SERVER_PORT defaults to 8080. Having this configurable is especially useful when running Blanco in host networking mode, e.g., when running Lavalink and Blanco in the same Docker host with IPv6 support enabled.

Last.fm scrobbling support

Blanco can scrobble tracks that have been played for long enough for all users in the voice channel. To enable this functionality, set the following environment variables:

Variable name	Description	Type
BLANCO_LASTFM_KEY	Last.fm API key	String
BLANCO_LASTFM_SECRET	Last.fm API shared secret	String

Sentry support

Blanco can forward errors and critical errors to Sentry. Set the following environment variables to enable this integration:

Variable name	Description	Type
BLANCO_SENTRY_DSN	Sentry data source name	URL
BLANCO_SENTRY_ENV	Sentry environment name	String

Redis support

Blanco can cache API responses from MusicBrainz, Spotify, and Lavalink to increase speed and help the bot stay within rate limits. Set the following environment variables to enable caching with Redis:

Variable name	Description	Type
BLANCO_REDIS_HOST	Redis server hostname	URL or IP address
BLANCO_REDIS_PORT	Redis server port	Integer
BLANCO_REDIS_PASSWORD	Redis server password (optional, but recommended)	String

Debugging mode

Blanco's debugging mode is used to

• register slash commands in a specified guild instead of globally like normal, and
• print additional messages to the console, such as the songs played in every guild.

It is not recommended to enable debugging mode outside of testing, as the bot will also print sensitive information such as your Discord bot token and Spotify secrets to the console. To enable debugging mode, set the following environment variables:

Variable name	Description	Type
BLANCO_DEBUG	Whether to enable debug mode	true or false
BLANCO_DEBUG_GUILDS	Guild IDs to register slash commands in when debug mode is enabled	Comma-separated list of integers

YAML file

Create an empty directory and create a file named config.yml in it, with the following contents:

bot:
  database: blanco.db
  discord_token: <your Discord bot token>
  debug: # Optional
    enabled: true
    guild_ids:
      - 123456789012345678
  match_ahead: false
  reenqueue_paused: false
sentry: # Optional
  dsn: https://...ingest.sentry.io/...
  environment: <environment>      # example: production, staging, etc.
redis: # Optional
  host:
  port:
  password:
server: # Optional
  enabled: false
  port: 8080
  base_url: http://localhost:8080
  oauth_id: <your Discord OAuth client ID>
  oauth_secret: <your Discord OAuth client secret>
spotify:
  client_id: <your client id>
  client_secret: <your client secret>
lastfm: # Optional
  api_key: <your Last.fm API key>
  shared_secret: <your Last.fm API shared secret>
lavalink:
  - id: main
    server: localhost
    port: 2333
    password: youshallnotpass
    regions: 
      - us-central
      - us-east

    # Set to true if node supports SSL (https://, wss://)
    ssl: false
    
    # Set to true if node supports playback from Deezer using LavaSrc
    deezer: false
# You may add more than one node here
# - id: backup
#   ...

Database

We also need to create an empty database file which will be used by the bot to store settings. Open a terminal in a folder of your choosing and run the following command:

# Windows cmd
type nul > blanco.db

# Linux, macOS, etc.
touch blanco.db

Then point the bot to the database file path by setting either the BLANCO_DB_FILE environment variable or the bot.database key in the YAML file.