MusicBot logo MusicBot

Using the bot

Commands

This page contains a list of all commands that can be used to control the MusicBot.
Every command must start with the prefix that is configured for your bot.
The default prefix for MusicBot is ! but we omit it in this documentation.
In usage descriptions, < > denotes a required parameter, [ ] denotes an optional parameter, and | denotes multiple choices for the parameter.
Parameters or terms in lower-case are literal, and used as the argument value.
While upper-case parameters are just placeholders, you put in your own value(s).

Take this usage for example:
autoplaylist <add | remove> [URL]
It means you can use add or remove as the first parameter. The second parameter is a value you provide. With the default prefix, an example of using the command would be:
!autoplaylist add https://link.to/my/song.mp3

General Commands

Show/Hide All

autoplaylist Example usage:
autoplaylist <add | remove> [URL]
    Adds or removes the specified song or currently playing song to/from the current playlist.

autoplaylist add all
    Adds the entire queue to the guilds playlist.

autoplaylist show
    Show a list of existing playlist files.

autoplaylist restart
    Reset the auto playlist queue, restarting at the first track unless randomized.

autoplaylist set <NAME>
    Set a playlist as default for this guild and reloads the guild auto playlist.
Description:
Manage auto playlist files and per-guild settings.
blocksong Example usage:
blocksong <add | remove> [SUBJECT]
Description:
Manage a block list applied to song requests and extracted song data.
A subject may be a song URL or a word or phrase found in the track title.
If subject is omitted, any currently playing track URL will be added instead.

The song block list matches loosely, but is case-sensitive.
This means adding 'Pie' will match 'cherry Pie' but not 'piecrust' in checks.
blockuser Example usage:
blockuser add <@USER>
    Block a mentioned user.
blockuser remove <@USER>
    Unblock a mentioned user.
blockuser status <@USER>
    Show the block status of a mentioned user.
Description:
Manage the users in the user block list.
Blocked users are forbidden from using all bot commands.
botversion Example usage:
botversion
Description:
Display MusicBot version number in the chat.
clean Example usage:
clean [RANGE]
Description:
Search for and remove bot messages and commands from the calling text channel.
Optionally supply a number of messages to search through, 50 by default 500 max.
This command may be slow if larger ranges are given.
clear Example usage:
clear
Description:
Removes all songs currently in the queue.
disconnect Example usage:
disconnect
Description:
Force MusicBot to disconnect from the discord server.
follow Example usage:
follow
Description:
Makes MusicBot follow a user when they change channels in a server.
help Example usage:
help [COMMAND]
Description:
Show usage and description of a command, or list all available commands.
id Example usage:
id [@USER]
Description:
Display your Discord User ID, or the ID of a mentioned user.
This command is deprecated in favor of Developer Mode in Discord clients.
karaoke Example usage:
karaoke
Description:
Toggle karaoke mode on or off. While enabled, only karaoke members may queue songs.
Groups with BypassKaraokeMode permission control which members are Karaoke members.
latency Example usage:
latency
Description:
Display API latency and Voice latency if MusicBot is connected.
leaveserver Example usage:
leaveserver <NAME | ID>
   Leave the discord server given by name or server ID.
Description:
Force MusicBot to leave the given Discord server.
Names are case-sensitive, so using an ID number is more reliable.
listids Example usage:
listids [all | users | roles | channels]
Description:
List the Discord IDs for the selected category.
Returns all ID data by default, but one or more categories may be selected.
This command is deprecated in favor of using Developer mode in Discord clients.
move Example usage:
move <FROM> <TO>
    Move song at position FROM to position TO.
Description:
Swap existing songs in the queue using their position numbers.
Use the queue command to find track position numbers.
np Example usage:
np
Description:
Show information on what is currently playing.
pause Example usage:
pause
Description:
Pause playback if a track is currently playing.
perms Example usage:
perms [@USER]
Description:
Get a list of your permissions, or the permissions of the mentioned user.
play Example usage:
play <URL | SEARCH>
Description:
Add a song to be played in the queue. If no song is playing or paused, playback will be started.

You may supply a URL to a video or audio file or the URL of a service supported by yt-dlp.
Playlist links will be extracted into multiple links and added to the queue.
If you enter a non-URL, the input will be used as search criteria on YouTube and the first result played.
MusicBot also supports Spotify URIs and URLs, but audio is fetched from YouTube regardless.
playnext Example usage:
playnext <URL | SEARCH>
Description:
A play command that adds the song as the next to play rather than last.
Read help for the play command for information on supported inputs.
playnow Example usage:
playnow <URL | SEARCH>
Description:
A play command which skips any current song and plays immediately.
Read help for the play command for information on supported inputs.
pldump Example usage:
pldump <URL>
Description:
Dump the individual URLs of a playlist to a file.
queue Example usage:
queue [PAGE]
Description:
Display information about the current player queue.
Optional page number shows later entries in the queue.
remove Example usage:
remove [POSITION]
Description:
Remove a song from the queue, optionally at the given queue position.
If the position is omitted, the song at the end of the queue is removed.
Use the queue command to find position number of your track.
However, positions of all songs are changed when a new song starts playing.
repeat Example usage:
repeat [all | song | playlist | on | off]
Description:
Toggles playlist or song looping.
If no option is provided the current song will be repeated.
If no option is provided and the song is already repeating, repeating will be turned off.
resetplaylist Example usage:
resetplaylist
Description:
Reset the auto playlist queue by copying it back into player memory.
This command will be removed in a future version, replaced by the autoplaylist command(s).
restart Example usage:
restart [soft]
    Attempt to reload without process restart. The default tion.

restart full
    Attempt to restart the entire MusicBot process, reloading everything.

restart uppip
    Full restart, but attempt to update pip packages before restart.

restart upgit
    Full restart, but update MusicBot source code with git first.

restart upgrade
    Attempt to update all dependency and source code before fully restarting.
Description:
Attempts to restart the MusicBot in a number of different ways.
With no option supplied, a `soft` restart is implied.
It can be used to remotely update a MusicBot installation, but should be used with care.
If you have a service manager, we recommend using it instead of this command for restarts.
resume Example usage:
resume
Description:
Resumes playback if the player was previously paused.
search Example usage:
search [SERVICE] [NUMBER] <QUERY>
    Search with service for a number of results with the search query.

search [NUMBER] "<QUERY>"
    Search YouTube for query but get a custom number of results.
    Note: the double-quotes are required in this case.
Description:
Search a supported service and select from results to add to queue.
Service and number arguments can be omitted, default number is 3 results.
Select from these services:
- yt, youtube (default)
- sc, soundcloud
- yh, yahoo
seek Example usage:
seek <TIME>
Description:
Restarts the current song at the given time.
If time starts with + or - seek will be relative to current playback time.
Time should be given in seconds, fractional seconds are accepted.
Due to codec specifics in ffmpeg, this may not be accurate.
setnick Example usage:
setnick <NICK>
Description:
Change the MusicBot's nickname.
setprefix Example usage:
setprefix <PREFIX>
    Set a per-server command prefix.
setprefix clear
    Clear the per-server command prefix.
Description:
Override the default command prefix in the server.
The option EnablePrefixPerGuild must be enabled first.
shuffle Example usage:
shuffle
Description:
Shuffle all current tracks in the queue.
shuffleplay Example usage:
shuffleplay [URL]
Description:
Play command that shuffles playlist entries before adding them to the queue.
shutdown Example usage:
shutdown
Description:
Disconnect from all voice channels and close the MusicBot process.
skip Example usage:
skip [force | f]
Description:
Skip or vote to skip the current playing song.
Members with InstaSkip permission may use force parameter to bypass voting.
If LegacySkip option is enabled, the force parameter can be ignored.
speed Example usage:
speed [RATE]
Description:
Change the playback speed of the currently playing track only.
The rate must be between 0.5 and 100.0 due to ffmpeg limits.
Streaming playback does not support speed adjustments.
stream Example usage:
stream <URL>
Description:
Add a media URL to the queue as a Stream.
The URL may be actual streaming media, like Twitch, Youtube, or a shoutcast like service.
You can also use non-streamed media to play it without downloading it.
Note: FFmpeg may drop the stream randomly or if connection hiccups happen.
summon Example usage:
summon
Description:
Tell MusicBot to join the channel you're in.
uptime Example usage:
uptime
Description:
Displays the MusicBot uptime, or time since last start / restart.
volume Example usage:
volume [VOLUME]
Description:
Set the output volume level of MusicBot from 1 to 100.
Volume parameter allows a leading + or - for relative adjustments.
The volume setting is retained until MusicBot is restarted.

Owner Commands

botlatency Example usage:
botlatency
Description:
Display latency information for Discord API and all connected voice clients.
cache Example usage:
cache <info | clear | update>
Description:
Display information about cache storage or clear cache according to configured limits.
Using update option will scan the cache for external changes before displaying details.
checkupdates Example usage:
checkupdates
Description:
Display the current bot version and check for updates to MusicBot or dependencies.
config Example usage:
config missing
    Shows help text about any missing config options.

config diff
    Lists the names of options which have been changed since loading config file.

config list
    List the available config options and their sections.

config reload
    Reload the options.ini file from disk.

config help <SECTION> <OPTION>
    Shows help text for a specific option.

config show <SECTION> <OPTION>
    Display the current value of the option.

config save <SECTION> <OPTION>
    Saves the current value to the options file.

config set <SECTION> <OPTION> <VALUE>
    Validates the option and sets the config for the session, but not to file.

config reset <SECTION> <OPTION>
    Reset the option to its default value.
Description:
Manage options.ini configuration from within Discord.
joinserver Example usage:
joinserver
Description:
Generate an invite link that can be used to add this bot to another server.
option Example usage:
option
Description:
Deprecated command, use the config command instead.
setalias Example usage:
setalias + <ALIAS> <CMD> [ARGS]
    Add an new alias with optional arguments.

setalias - <ALIAS>
    Remove an alias with the given name.
setalias <save | load>
    Reload or save aliases from/to the config file.
Description:
Allows management of aliases from discord. To see aliases use the help command.
setavatar Example usage:
setavatar [URL]
Description:
Change MusicBot's avatar.
Attaching a file and omitting the url parameter also works.
setcookies Example usage:
setcookies
    Update the cookies.txt file using a cookies.txt attachment.
setcookies [off | on]
    Enable or disable cookies.txt file without deleting it.
Description:
Allows management of the cookies feature in yt-dlp.
When updating cookies, you must upload a file named cookies.txt
If cookies are disabled, uploading will enable the feature.
Uploads will delete existing cookies, including disabled cookies file.

WARNING:
Copying cookies can risk exposing your personal information or accounts,
and may result in account bans or theft if you are not careful.
It is not recommended due to these risks, and you should not use this
feature if you do not understand how to avoid the risks.
setname Example usage:
setname <NAME>
Description:
Change the bot's username on discord.
Note: The API may limit name changes to twice per hour.
setperms Example usage:
setperms list
    Show loaded groups and list permission options.

setperms reload
    Reloads permissions from the permissions.ini file.

setperms add <GROUP>
    Add new group with defaults.

setperms remove <GROUP>
    Remove existing group.

setperms help <PERMISSION>
    Show help text for the permission option.

setperms show <GROUP> <PERMISSION>
    Show permission value for given group and permission.

setperms save <GROUP>
    Save permissions group to file.

setperms set <GROUP> <PERMISSION> [VALUE]
    Set permission value for the group.
Description:
Manage permissions.ini configuration from within discord.

Dev Commands

breakpoint Example usage:
breakpoint
Description:
This command issues a log at level CRITICAL, but does nothing else.
Can be used to manually pinpoint events in the MusicBot log file.
debug Example usage:
debug [PYCODE]
Description:
This command will execute arbitrary python code in the command scope.
First eval() is attempted, if exceptions are thrown exec() is tried next.
If eval is successful, it's return value is displayed.
If exec is successful, a value can be set to local variable `result` and that value will be returned.

Multi-line code can be executed if wrapped in code-block.
Otherwise only a single line may be executed.

This command may be removed in a future version, and is used by developers to debug MusicBot behaviour.
The danger of this command cannot be understated. Do not use it or give access to it if you do not understand the risks!
makeini Example usage:
makeini
Description:
Makes default INI files.
makemarkdown Example usage:
makemarkdown < opts | perms | help >
Description:
Create 'markdown' for options, permissions, or commands from the code.
The output is used to update GitHub Pages and is thus unsuitable for normal reference use.
objgraph Example usage:
objgraph
    View most common types reported by objgraph.

objgraph growth
    View limited objgraph.show_growth() output.

objgraph leaks
    View most common types of leaking objects.

objgraph leakstats
    View typestats of leaking objects.

objgraph [objgraph.function(...)]
    Evaluate the given function and arguments on objgraph.
Description:
Interact with objgraph, if it is installed, to gain insight into memory usage.
You can pass an arbitrary method with arguments (but no spaces!) that is a member of objgraph.
Since this method evaluates arbitrary code, it is considered dangerous like the debug command.
testready Example usage:
testready [dry]
Description:
Command used for testing. It prints a list of commands which can be verified by a test suite.

Show/Hide All