Configuration

Configuration

Beatra is configured with environment variables, usually written in a file named .env in the bot folder. Only DISCORD_TOKEN is required; every other setting has a sensible default.

• Start from .env.example: it lists the common settings with comments.
• The .env file is read from the bot folder (next to index.js), wherever you start the bot from.
• On hosting panels you can set the same names as environment variables instead. If a name exists in both places, the real environment variable wins (.env never overwrites an existing variable).
• Values are trimmed. An empty value (NAME=) means "use the default".
• Restart the bot after changing a setting.

Note: On/off settings accept true, 1, yes or on for "on". Anything else counts as "off".

---

Discord

Setting	Default	What it does
DISCORD_TOKEN	(none)	Required. Your bot token (Developer Portal > your application > Bot > Reset Token).
CLIENT_ID	detected from the token	The application id. The startup check reads it from Discord, so you can leave it empty. If you set a different id, the check warns you and uses the token's own id. Only npm run deploy needs it in .env, because that script skips the startup check.
GUILD_ID	(empty)	Register slash commands only in this server (a 17-20 digit server id). Useful while developing: changes appear there right away. Leave empty to register commands everywhere. The bot must be in that server.

---

Bot

Setting	Default	What it does
STATUS	/play	Text of the bot's status, shown as "Listening to ...".
EMBED_COLOR	#5865F2	Accent color of the panels, as a 6-digit hex color (# optional). An invalid value falls back to #5865F2.
SUPPORT_SERVER	(empty)	When set to an http(s) link, /help shows a Support button.
WEBSITE	(empty)	When set to an http(s) link, /help shows a Website button.
DEFAULT_LANGUAGE	en	Language used when nothing else decides (see Features). Must be a file name from languages/ without .json, for example tr, de or zh_CN. Unknown codes fall back to en.
DEFAULT_VOLUME	100	Starting volume of a new queue. Kept between 1 and 100.
MAX_QUEUE_SIZE	500	Most songs a server's queue can hold. Playlists that do not fit are cut and the user is told.
MAX_PLAYLIST_SIZE	200	Most songs read from one YouTube playlist, or from a playlist on another yt-dlp site.
LEAVE_ON_EMPTY	60	Seconds to wait before leaving when no one (except bots) is left in the voice channel. The music pauses meanwhile and resumes if someone comes back. 0 turns this off: the bot keeps playing in an empty channel.
LEAVE_ON_FINISH	120	Seconds to stay in the voice channel after the queue ends. 0 = never leave.
PANEL_REFRESH	20	Seconds between progress bar updates on the player panel while music plays. 0 = update only when something changes.

---

Spotify

Setting	Default	What it does
SPOTIFY_CLIENT_ID	(empty)	Spotify API client id.
SPOTIFY_CLIENT_SECRET	(empty)	Spotify API client secret.

Both are optional. Without them, Spotify links still work using public data, but large Spotify playlists load only their first 100 songs. To lift that limit, create an app in the Spotify developer dashboard and fill in both values. The startup check prints an [INFO] line while they are missing.

---

YouTube and yt-dlp

All of these are optional. The first three are the fixes for YouTube's "Sign in to confirm you're not a bot"; use one of them. The full guide is on YouTube Access.

Setting	Default	What it does
COOKIES_FILE	(empty)	Path to a YouTube cookies.txt file, for example ./cookies.txt (relative to the bot folder). The startup check stops if the file does not exist.
COOKIES_FROM_BROWSER	(empty)	Read YouTube cookies straight from a browser on the same machine. Supported: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale. A browser profile can follow a colon, as yt-dlp expects (for example chrome:Profile 1). Ignored when COOKIES_FILE is set.
YOUTUBE_PO_TOKEN	(empty)	A YouTube PO token (advanced).
YTDLP_EXTRACTOR_ARGS	(empty)	Extra value for yt-dlp's --extractor-args (advanced). Example from .env.example: youtube:player_client=web_safari
YOUTUBE_FALLBACK	soundcloud	When YouTube fails for a song (blocked, 403, removed), the same song is searched and played from SoundCloud, and the listener is told. Set to off to show the YouTube error instead.
YTDLP_PATH	downloaded automatically	Use your own yt-dlp program instead of the one in bin/. The daily automatic update is skipped when this is set.
FFMPEG_PATH	downloaded automatically	Use your own ffmpeg program.
YTDLP_CONCURRENCY	4	How many yt-dlp processes may run at the same time per shard (1-32). User requests go before background prefetching.
YTDLP_TIMEOUT	30	Seconds before a yt-dlp lookup is cancelled (minimum 5). Not listed in .env.example.

---

Proxy

Setting	Default	What it does
PROXY_URL	(empty)	Proxy used for YouTube and all audio downloads. http://, https://, socks4://, socks5:// and socks5h:// work. Several proxies can be separated by commas.

PROXY_URL=http://user:password@host:port
PROXY_URL=http://proxy-a:8080,http://proxy-b:8080

YouTube locks a stream to the IP address that requested it, so with several proxies each Discord server always uses the same proxy from the list. The startup check stops if an entry is not a valid proxy address.

---

Sharding

The bot always runs under discord.js' sharding manager. The defaults suit almost everyone; see Deployment for details.

Setting	Default	What it does
TOTAL_SHARDS	auto	Number of shards. auto uses the number Discord recommends for your bot.
SHARD_LIST	auto	Which shard ids this process starts, as a comma-separated list (for example 0,1). auto = all of them. Not listed in .env.example.
SHARD_MODE	process	process (each shard is a child process) or worker (each shard is a worker thread).
SHARD_RESPAWN	true	Restart a shard automatically when it exits or crashes. Not listed in .env.example.
SHARD_SPAWN_DELAY	5500	Milliseconds to wait between starting two shards.
SHARD_SPAWN_TIMEOUT	60000	Milliseconds a shard may take to become ready (minimum 5000).

---

Logs and folders

Setting	Default	What it does
DEBUG	false	Detailed logs, including DisTube and ffmpeg debug output. Turn it on when you troubleshoot.
NO_COLOR	(not set)	When set to any non-empty value, console output has no colors. Set it as a real environment variable if the startup checklist should also be plain, because the checklist starts before .env is read. Colors are always off when the output is not a terminal (for example when it is written to a file).
DATA_DIR	data	Folder for settings, saved queues and temporary relay files (relative to the bot folder, or an absolute path).
BIN_DIR	bin	Folder where yt-dlp is downloaded (relative to the bot folder, or an absolute path).

Note: There is also YTDLP_DOWNLOAD_BASE, the address the yt-dlp ZIP is downloaded from. It defaults to the latest official yt-dlp release on GitHub and is meant for testing; you normally never set it.

---

Example .env files

The minimum:

DISCORD_TOKEN=paste_your_token_here

A VPS that YouTube blocks:

DISCORD_TOKEN=paste_your_token_here
COOKIES_FILE=./cookies.txt
YOUTUBE_FALLBACK=soundcloud

A personalised bot:

DISCORD_TOKEN=paste_your_token_here
STATUS=/play | /help
EMBED_COLOR=#8B5CF6
DEFAULT_LANGUAGE=tr
DEFAULT_VOLUME=60
SUPPORT_SERVER=https://discord.gg/your-invite
WEBSITE=https://example.com
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

Developing new commands on a test server:

DISCORD_TOKEN=paste_your_token_here
GUILD_ID=123456789012345678
DEBUG=true

---

Settings changed in Discord, not in .env

What	Where	Stored in
Server language	/language (needs Manage Server)	data/guilds/<server id>.json
Volume, loop mode, autoplay, filter	Commands or panel buttons, per queue	data/sessions/<server id>.json while music plays

---

Next: Commands · YouTube Access · Deployment