Permissions

This page gives information on how to setup MusicBot permissions file, which controls what users are allowed to do with MusicBot.

When you install the bot, you will get a file inside the config folder named example_permissions.ini. The example file contains the default/built-in permission groups as well as commentary to explain each option you can use in the permission groups.
Edit the example_permission.ini, and then save it as a new file called permissions.ini.

On Windows, file extensions are hidden by default. If you do not see the .ini at the end of the file name, you should enable file extensions in Explorer settings.

Notice: Earlier versions of Windows Notepad may break the .ini and other configuration files when saved, due to ignoring file encoding and line endings. You are encouraged to use an editor like Notepad++ or other editor with code editing features.

The basics of permissions.ini

The permissions file contains only two required sections, but you can add as many sections as you like!

As per the INI file format, each [section] is used as the name of a specific permission group. The [Default] and [Owner (auto)] groups should not be removed or renamed as they are required.
These two built-in groups will ignore the GrantToRoles and UserList options.

The [Default] group contains the default permissions set for users of the bot that are not the owner, and have not been assigned a group via UserList or GrantToRoles options in other groups.

The [Owner (auto)] group contains options applied only to the user set as the OwnerID in the options.ini file. It provides mostly unrestricted access but some options can still be configured to suit your needs. This group does not grant access to owner-only commands.

Control command access

The options CommandWhitelist, CommandBlacklist and AdvancedCommandLists allow you to control command access per-group.

The AdvancedCommandLists option enables mixing CommandWhitelist and CommandBlacklist together which allows you to grant access to a command but revoke access to a sub-command.
For example, to allow all autoplaylist commands except for the autoplaylist clear sub-command:

[Group]
CommandWhitelist = autoplaylist play skip ...
CommandBlacklist = autoplaylist_clear
AdvancedCommandLists = yes

However, if AdvancedCommandLists is disabled (which is the default) the whitelist and blacklist options cannot be used together.
If both options are empty or missing, all commands are allowed.
If CommandWhitelist is set, it will deny access to all commands but those which are listed, ignoring anything in CommandBlacklist.
If CommandBlacklist is used, it will allow access to all commands but those which are listed.

After the November 2024 updates, you may specify sub-commands by using the underscore _ character between a top-level command name and its sub-command name. For example, to allow a user to only use the autoplaylist add sub-command, use the option:
CommandWhiteList = autoplaylist_add

Assigned Groups

When you add extra groups, you need to assign those groups using one or both of UserList or GrantToRoles options.

The UserList option lets you assign individual discord users by using their numeric User ID.
The GrantToRoles option uses Role IDs, so any Member with the identified Role(s) will be assigned the permission group.

Both options may be used, however the UserList option is consulted first, and GrantToRoles may not be checked if the User ID is found in any group.

Here is an example that adds two fictional Users and a single Role to a permission group:

[Group2]
MaxSongs = 200
UserList = 154748625350688768 104766296687656960
GrantToRoles = 173129876679688192

Note: You MUST use a numerical ID for these options. To find the appropriate ID, enable the Settings > Advanced > Developer Mode option in your Discord client or use the id and listids commands to get the IDs you need.

Available Permission Options

Show/Hide All

CommandWhitelist

List of command names allowed for use, separated by spaces.
Sub-command access can be controlled by adding _ and the sub-command name.
That is `config_set` grants only the `set` sub-command of the config command.
This option overrides CommandBlacklist if set.

Default Value: (All allowed)

CommandBlacklist

List of command names denied from use, separated by spaces.
Will not work if CommandWhitelist is set!
Default Value: (None denied)

AdvancedCommandLists

When enabled, CommandBlacklist and CommandWhitelist are used together.
Only commands in the whitelist are allowed, however sub-commands may be denied by the blacklist.

Default Value: no

IgnoreNonVoice

List of command names that can only be used while in the same voice channel as MusicBot.
Some commands will always require the user to be in voice, regardless of this list.
Command names should be separated by spaces.
Default Value: (No commands listed)

GrantToRoles

List of Discord server role IDs that are granted this permission group.
This option is ignored if UserList is set.
Default Value: *empty*

UserList

List of Discord member IDs that are granted permissions in this group.
This option overrides GrantToRoles.
Default Value: *empty*

MaxSongs

Maximum number of songs a user is allowed to queue.
A value of 0 means unlimited.
Default Value: 8

MaxSongLength

Maximum length of a song in seconds. A value of 0 means unlimited.
This permission may not be enforced if song duration is not available.
Default Value: 210

MaxPlaylistLength

Maximum number of songs a playlist is allowed to have when queued.
A value of 0 means unlimited.
Default Value: 0

MaxSearchItems

The maximum number of items that can be returned in a search.
Default Value: 10

AllowPlaylists

Allow users to queue playlists, or multiple songs at once.
Default Value: yes

InstaSkip

Allow users to skip without voting, if LegacySkip config option is enabled.
Default Value: no

SkipLooped

Allows the user to skip a looped song.
Default Value: no

Remove

Allows the user to remove any song from the queue.
Does not remove or skip currently playing songs.
Default Value: no

SkipWhenAbsent

Skip songs added by users who are not in voice when their song is played.
Default Value: yes

BypassKaraokeMode

Allows the user to add songs to the queue when Karaoke Mode is enabled.
Default Value: no

SummonNoVoice

Auto summon to user voice channel when using play commands, if bot isn't in voice already.
The summon command must still be allowed for this group!
Default Value: no

Extractors

Specify yt-dlp extractor names, separated by spaces, that are allowed to be used.
When empty, hard-coded defaults are used. The defaults are displayed above, but may change between versions.
To allow all extractors, add `__` without quotes to the list.

Services/extractors supported by yt-dlp are listed here:
https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

MusicBot also provides one custom service `spotify:musicbot` to enable or disable Spotify API extraction.
NOTICE: MusicBot might not support all services available to yt-dlp!

Default Value: generic, spotify:musicbot, soundcloud, Bandcamp, youtube