Configuration

This page describes MusicBot’s primary configuration file.
The main configuration file is config/options.ini, which is typically copied from config/example_options.ini file.

Editing your configuration file using Notepad or WordPad may result in broken config files.
An editor that is aware of encoding and line-endings is recommended. (Notepad++, VS Code, etc.)

First Time Setup

Before you can configure MusicBot, you need to set up a Bot application on the Discord Developer Portal.
This section will guide you through all those steps:

How to make a Discord Bot and Configure MusicBot.

Make a new Bot and Token

First, log in to the official Discord Developer Portal and access the Applications page.

Create a new application, then open the "Bot" page from the menu.
Find the Token section to reveal and copy your new Bot Token.
Notice: If you have 2FA enabled, you may need to "Reset Token" before you can see it.
Warning: Keep the Token safe! Don't share it or lose it or you'll need to regenerate it!
Next set the privileged intents. You need to enable each of the Gateway Intents.
- Enable Presence Intent
- Enable Server Members Intent
- Enable Message Content Intent

Configure MusicBot

You should now have your token and can now copy it into your config file.
To finish setting up:

Open your bot folder and then the config folder within it.
Copy example_options.ini and rename it to options.ini.
Open options.ini then find the "Token" option under [Credentials].
Update the value of "Token" with the token you copied from Discord Applications.
Save, close, and try running MusicBot!

If everything is working, make sure to review the rest of the options and make changes as needed.

How to Run MusicBot

MusicBot provides a collection of scripts to start the bot.
For Windows you'll usually use run.bat to start the bot.
For various Linux-like OS, use run.sh instead.
You may also launch run.py by passing it to python directly.
All of these scripts support the same command line arguments.

Documentation for options.ini

Show/Hide All

[Credentials]

Token

Discord bot authentication token for your Bot.
Visit Discord Developer Portal to create a bot App and generate your Token.
Never publish your bot token!
Default Value: *empty*

Spotify_ClientID

Provide your own Spotify Client ID to enable MusicBot to interact with Spotify API.
MusicBot will try to use the web player API (guest mode) if nothing is set here.
Using your own API credentials grants higher usage limits than guest mode.
Default Value: *empty*

Spotify_ClientSecret

Provide your Spotify Client Secret to enable MusicBot to interact with Spotify API.
This is required if you set the Spotify_ClientID option above.
Default Value: *empty*

[Permissions]

OwnerID

Provide a Discord User ID number to set the owner of this bot.
The word 'auto' or number 0 will set the owner based on App information.
Only one owner ID can be set here. Generally, setting 'auto' is recommended.
Default Value: 0

DevIDs

A list of Discord User IDs who can use the dev-only commands.
Warning: dev-only commands can allow arbitrary remote code execution.
Use spaces to separate multiple IDs.
Most users should leave this setting blank.
Default Value: *empty*

BotExceptionIDs

Discord Member IDs for other bots that MusicBot should not ignore.
Use spaces to separate multiple IDs.
All bots are ignored by default.
Default Value: *empty*

[Chat]

CommandPrefix

Command prefix is how all MusicBot commands must be started in Discord messages.
E.g., if you set this to * the play command is trigger by *play ...
Default Value: !

CommandsByMention

Enable using commands with @[YourBotNameHere]
The CommandPrefix is still available, but can be replaced with @ mention.
Default Value: yes

BindToChannels

ID numbers for text channels that MusicBot should exclusively use for commands.
This can contain IDs for channels in multiple servers.
Use spaces to separate multiple IDs.
All channels are used if this is not set.
Default Value: *empty*

AllowUnboundServers

Allow responses in all channels while no specific channel is set for a server.
Only used when BindToChannels is missing an ID for a server.
Default Value: no

AutojoinChannels

A list of Voice Channel IDs that MusicBot should automatically join on start up.
Use spaces to separate multiple IDs.
Default Value: *empty*

DMNowPlaying

MusicBot will try to send Now Playing notices directly to the member who requested the song instead of posting in a server channel.
Default Value: no

DisableNowPlayingAutomatic

Disable now playing messages for songs played via auto playlist.
Default Value: no

NowPlayingChannels

Forces MusicBot to use a specific channel to send now playing messages.
Only one text channel ID can be used per server.
Default Value: *empty*

DeleteNowPlaying

MusicBot will automatically delete Now Playing messages.
Default Value: yes

[MusicBot]

DebugLevel

Set the log verbosity of MusicBot. Normally this should be set to INFO.
It can be set to one of the following:
CRITICAL, ERROR, WARNING, INFO, DEBUG, VOICEDEBUG, FFMPEG, NOISY, or EVERYTHING
Default Value: INFO

DefaultVolume

Sets the default volume level MusicBot will play songs at.
You can use any value from 0 to 1, or 0% to 100% volume.
Default Value: 0.15

DefaultSpeed

Sets the default speed MusicBot will play songs at.
Must be a value from 0.5 to 100.0 for ffmpeg to use it.
A value of 1 is normal playback speed.
Note: Streamed media does not support speed adjustments.
Default Value: 1.000

SkipsRequired

Number of channel member votes required to skip a song.
Acts as a minimum when SkipRatio would require more votes.
Default Value: 4

SkipRatio

This percent of listeners in voice must vote for skip.
If SkipsRequired is lower than the computed value, it will be used instead.
You can set this from 0 to 1, or 0% to 100%.
Default Value: 0.5

SaveVideos

Allow MusicBot to keep downloaded media, or delete it right away.
Default Value: yes

StorageLimitBytes

If SaveVideos is enabled, set a limit on how much storage space should be used.
Default Value: 0

StorageLimitDays

If SaveVideos is enabled, set a limit on how long files should be kept.
Default Value: 0

StorageRetainAutoPlay

If SaveVideos is enabled, never purge auto playlist songs from the cache regardless of limits.
Default Value: yes

NowPlayingMentions

Mention the user who added the song when it is played.
Default Value: no

AutoSummon

Automatically join the owner if they are in an accessible voice channel when bot starts.
Default Value: yes

UseAutoPlaylist

Enable MusicBot to automatically play music from the auto playlist when the queue is empty.
Default Value: yes

AutoPlaylistRandom

Shuffles the auto playlist tracks before playing them.
Default Value: yes

AutoPlaylistAutoSkip

Enable automatic skip of auto playlist songs when a user plays a new song.
This only applies to the current playing song if it was added by the auto playlist.
Default Value: no

AutoPlaylistRemoveBlocked

Remove songs from the auto playlist if they are found in the song block list.
Default Value: no

AutoPause

MusicBot will automatically pause playback when no users are listening.
Default Value: yes

DeleteMessages

Allow MusicBot to automatically delete messages it sends, after a delay.
Delay period is controlled by DeleteDelayShort and DeleteDelayLong.
Default Value: yes

DeleteInvoking

Auto delete valid commands after a delay.
Default Value: no

DeleteDelayShort

Sets the short period of seconds before deleting messages.
This period is used by messages that require no further interaction.
Default Value: 0:00:30

DeleteDelayLong

Sets the long delay period before deleting messages.
This period is used by interactive or long-winded messages, like search and help.
Default Value: 0:01:00

PersistentQueue

Allow MusicBot to save the song queue, so queued songs will survive restarts.
Default Value: yes

PreDownloadNextSong

Enable MusicBot to download the next song in the queue while a song is playing.
Currently this option does not apply to auto playlist or songs added to an empty queue.
Default Value: yes

StatusMessage

Specify a custom message to use as the bot's status. If left empty, the bot
will display dynamic info about music currently being played in its status instead.
Status messages may also use the following variables:
{n_playing} = Number of currently Playing music players.
{n_paused} = Number of currently Paused music players.
{n_connected} = Number of connected music players, in any player state.

The following variables give access to information about the player and track.
These variables may not be accurate in multi-guild bots:
{p0_length} = The total duration of the track, if available. Ex: [2:34]
{p0_title} = The track title for the currently playing track.
{p0_url} = The track URL for the currently playing track.
Default Value: *empty*

StatusIncludePaused

If enabled, status messages will report info on paused players.
Default Value: no

WriteCurrentSong

If enabled, MusicBot will save the track title to: data/[Server ID]/current.txt
Default Value: no

AllowAuthorSkip

Allow the member who requested the song to skip it, bypassing votes.
Default Value: yes

UseExperimentalEqualization

Tries to use ffmpeg to get volume normalizing options for use in playback.
This option can cause delay between playing songs, as the whole track must be processed.
Default Value: no

UseEmbeds

Allow MusicBot to format its messages as embeds.
Default Value: yes

QueueLength

The number of entries to show per-page when using q command to list the queue.
Default Value: 10

RemoveFromAPOnError

Enable MusicBot to automatically remove unplayable entries from the auto playlist.
Default Value: yes

ShowConfigOnLaunch

Display MusicBot config settings in the logs at startup.
Default Value: no

LegacySkip

Enable users with the InstaSkip permission to bypass skip voting and force skips.
Default Value: no

LeaveServersWithoutOwner

If enabled, MusicBot will leave servers if the owner is not in their member list.
Default Value: no

UseAlias

If enabled, MusicBot will allow commands to have multiple names using data in: config/aliases.json
Default Value: yes

CustomEmbedFooter

Replace MusicBot name/version in embed footer with custom text.
Only applied when UseEmbeds is enabled and it is not blank.
Default Value: Just-Some-Bots/MusicBot (release-250723-1014-gaba00dea-modded)

RemoveEmbedFooter

Completely remove the footer from embeds.
Default Value: no

SelfDeafen

MusicBot will automatically deafen itself when entering a voice channel.
Default Value: yes

LeaveInactiveVC

If enabled, MusicBot will leave a voice channel when no users are listening,
after waiting for a period set in LeaveInactiveVCTimeOut option.
Listeners are channel members, excluding bots, who are not deafened.
Default Value: no

LeaveInactiveVCTimeOut

Set a period of time to wait before leaving an inactive voice channel.
You can set this to a number of seconds or phrase like: 4 hours
Default Value: 0:05:00

LeaveAfterQueueEmpty

If enabled, MusicBot will leave the channel immediately when the song queue is empty.
Default Value: no

LeavePlayerInactiveFor

When paused or no longer playing, wait for this amount of time then leave voice.
You can set this to a number of seconds of phrase like: 15 minutes
Set it to 0 to disable leaving in this way.
Default Value: 0:00:00

SearchList

If enabled, users must indicate search result choices by sending a message instead of using reactions.
Default Value: no

DefaultSearchResults

Sets the default number of search results to fetch when using the search command without a specific number.
Default Value: 3

EnablePrefixPerGuild

Allow MusicBot to save a per-server command prefix, and enables the setprefix command.
Default Value: no

RoundRobinQueue

If enabled and multiple members are adding songs, MusicBot will organize playback for one song per member.
Default Value: no

EnableNetworkChecker

Allow MusicBot to use timed pings to detect network outage and availability.
This may be useful if you keep the bot joined to a channel or playing music 24/7.
MusicBot must be restarted to enable network testing.
By default this is disabled.
Default Value: no

SavePlayedHistoryGlobal

Enable saving all songs played by MusicBot to a global playlist file: config/playlists/history.txt
This will contain all songs from all servers.
Default Value: no

SavePlayedHistoryGuilds

Enable saving songs played per-server to a playlist file: config/playlists/history[Server ID].txt
Default Value: no

EnableLocalMedia

Enable playback of local media files using the play command.
When enabled, users can use: `play file://path/to/file.ext`
to play files from the local MediaFileDirectory path.
Default Value: no

UnpausePlayerOnPlay

Allow MusicBot to automatically unpause when play commands are used.
Default Value: no

YtdlpProxy

Experimental, HTTP/HTTPS proxy settings to use with ytdlp media downloader.
The value set here is passed to `ytdlp --proxy` and aiohttp header checking.
Leave blank to disable.
Default Value: *empty*

YtdlpUserAgent

Experimental option to set a static User-Agent header in yt-dlp.
It is not typically recommended by yt-dlp to change the UA string.
For examples of what you might put here, check the following two links:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent
https://www.useragents.me/
Leave blank to use default, dynamically generated UA strings.
Default Value: *empty*

YtdlpUseOAuth2

Experimental option to enable yt-dlp to use a YouTube account via OAuth2.
When enabled, you must use the generated URL and code to authorize an account.
The authorization token is then stored in the `data//oauth2.token` file.
This option should not be used when cookies are enabled.
Using a personal account may not be recommended.
Set yes to enable or no to disable.
Default Value: no

YtdlpOAuth2URL

Optional YouTube video URL used at start-up for triggering OAuth2 authorization.
This starts the OAuth2 prompt early, rather than waiting for a song request.
The URL set here should be an accessible YouTube video URL.
Authorization must be completed before start-up will continue when this is set.
Default Value: *empty*

EnableUserBlocklist

Toggle the user block list feature, without emptying the block list.
Default Value: yes

EnableSongBlocklist

Enable the song block list feature, without emptying the block list.
Default Value: no

UseOpusAudio

Potentially reduces CPU usage, but disables volume and speed controls.
This option will disable UseExperimentalEqualization option as well.
Default Value: no

[Files]

UserBlocklistFile

An optional file path to a text file listing Discord User IDs, one per line.
Default Value: config/blocklist_users.txt

SongBlocklistFile

An optional file path to a text file that lists URLs, words, or phrases one per line.
Any song title or URL that contains any line in the list will be blocked.
Default Value: config/blocklist_songs.txt

AutoPlaylistDirectory

An optional path to a directory containing auto playlist files.
Each file should contain a list of playable URLs or terms, one track per line.
Default Value: config/playlists

MediaFileDirectory

An optional directory path where playable media files can be stored.
All files and sub-directories can then be accessed by using 'file://' as a protocol.
Example: file://some/folder/name/file.ext
Maps to: ./media/some/folder/name/file.ext
Default Value: media

AudioCachePath

An optional directory path where MusicBot will store long and short-term cache for playback.
Default Value: audio_cache

LogsMaxKept

Configure automatic log file rotation at restart, and limit the number of files kept.
When disabled, only one log is kept and its contents are replaced each run.
Set to 0 to disable. Maximum allowed number is 100.
Default Value: 0

LogsDateFormat

Configure the log file date format used when LogsMaxKept is enabled.
If left blank, a warning is logged and the default will be used instead.
Learn more about time format codes from the tables and data here:
https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior
Default Value: .ended-%Y-%j-%H%m%S