+
-Installation on CentOS is **majorly untested and is not officially supported** due to issues. Please keep this in mind when seeking support.
+
+Debian 11 (bullseye) install steps.
-For Debian version 11 (bullseye), the Python 3.8+ is available as a system package, so installing is pretty simple.+For Debian version 11 (bullseye), Python 3.9 or higher is available as a system package, so installing is pretty simple.
Just follow these commands: {% highlight bash %} @@ -102,7 +102,7 @@ After configuring you can use the command
./run.sh to start the bot
Debian 10 (buster) install steps.
-For Debian version 10 (buster) and earlier versions, you will need to compile a version of Python 3.8 or higher as well as installing pip.+For Debian version 10 (buster) and earlier versions, you will need to compile a version of Python 3.9 or higher as well as installing pip.
This can take a bit of time to complete and may require a little troubleshooting know-how if these steps are out-of-date or incomplete in some way.
If you're willing to carefully follow along, these steps should get MusicBot working: diff --git a/_docs/installing/mac.md b/_docs/installing/mac.md index 32470f9ac..8d4424de0 100644 --- a/_docs/installing/mac.md +++ b/_docs/installing/mac.md @@ -3,34 +3,43 @@ title: MacOS category: Installing the bot order: 4 --- -
+
+Installing MusicBot on Mac is simple using homebrew and xcode.
-Installing MusicBot on Mac is quite simple.
+> Note: On ARM-based mac (M1, M4, etc.) you may encounter an issue with Opus not loading.
+You can bypass this by enabling `UseOpusAudio` in your options.ini file.
-> **The steps below are for macOS Catalina and above. They may not work on older versions of macOS.**
-You will need to open Terminal and run the following commands:
+### Catalina & above
+These steps were made for macOS Catalina and above.
+
+To install, you will need to open Terminal and use the following commands (adjust them as needed for your system):
```bash
-# Install Homebrew and Xcode command line tools
+# Install Homebrew and Xcode command line tools.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/$(id -un)/.zprofile \
eval "$(/opt/homebrew/bin/brew shellenv)" # To fix "zsh: command not found: brew"
-brew update
+
+# set up xcode.
xcode-select --install
-# Install dependencies
-brew install python libsodium libffi opus ffmpeg git
+# update brew package index.
+brew update
+
+# Install system dependencies
+brew install libsodium libffi ffmpeg git opus-tools
+# Install python using version 3.10, or any version from 3.9 to 3.13
+brew install python@3.10
-# Clone the MusicBot
+# Clone the MusicBot using master branch, you may also use review or dev.
cd desktop
-git clone https://github.com/Just-Some-Bots/MusicBot.git MusicBot -b master
+git clone https://github.com/Just-Some-Bots/MusicBot.git MusicBot -b master
# Install Python dependencies
cd MusicBot
-python3 -m pip install -U pip
python3 -m pip install -U -r requirements.txt
```
diff --git a/_docs/installing/openbsd.md b/_docs/installing/openbsd.md
index 89831e202..8b88bd9ec 100644
--- a/_docs/installing/openbsd.md
+++ b/_docs/installing/openbsd.md
@@ -3,13 +3,17 @@ title: OpenBSD
category: Installing the bot
order: 11
---
+
+
MusicBot can run on OpenBSD systems as well. Note that the X11 sets must be installed, due to the `ffmpeg` dependency.
+> Note: These steps are out of date, and must be changed for modern versions of OpenBSD. Please consider sharing up-to-date install steps.
+
## OpenBSD 6.6
~~~bash
# Install Python and libraries available as packages
-doas pkg_add python # select version 3.8 or above
+doas pkg_add python # select version 3.9 or above
doas pkg_add py3-aiohttp youtube-dl ffmpeg libsodium git
# Ensure pip is set up
diff --git a/_docs/installing/raspbian.md b/_docs/installing/raspbian.md
index 2526b1693..d4be3c7a9 100644
--- a/_docs/installing/raspbian.md
+++ b/_docs/installing/raspbian.md
@@ -4,7 +4,7 @@ category: Installing the bot
order: 6
---
-
+
MusicBot can be installed on Raspbian and Raspberry Pi OS. Older versions of Pi OS (known as Raspbian) may require some manual steps.
This guide is broken into three sections depending on your version of Raspberry Pi OS or Raspbian.
@@ -69,7 +69,7 @@ If you need to manually update python libraries for MusicBot, you will need to a
Raspberry Pi OS 11 (bullseye) install steps.
-For Pi OS version 11 (bullseye), the Python 3.8+ is available as a system package, so installing is pretty simple.+For Pi OS version 11 (bullseye), Python 3.9 or higher is available as a system package, so installing is pretty simple.
Just follow these commands: {% highlight bash %} @@ -101,7 +101,7 @@ After configuring you can use the command
./run.sh to start the bot
Raspbian 10 (buster) install steps.
-For Raspbian version 10 (buster) and earlier versions, you will need to compile a version of Python 3.8 or higher as well as installing pip.+For Raspbian version 10 (buster) and earlier versions, you will need to compile a version of Python 3.9 or higher as well as installing pip.
This can take a bit of time to complete and may require a little troubleshooting know-how if these steps are out-of-date or incomplete in some way.
If you're willing to carefully follow along, these steps should get MusicBot working: diff --git a/_docs/installing/rocky.md b/_docs/installing/rocky.md index e148fb528..79be8c991 100644 --- a/_docs/installing/rocky.md +++ b/_docs/installing/rocky.md @@ -4,8 +4,7 @@ category: Installing the bot order: 12 --- -
-
+
Installing the bot on Rocky is similar to [Ubuntu]({{ site.baseurl }}/installing/ubuntu), but requires a different package manager.
@@ -24,7 +23,7 @@ sudo dnf config-manager --set-enabled crb
sudo dnf -y install ffmpeg
-# Install Python (skip this if `python3 --version` shows python 3.8.x or newer is installed)
+# Install Python (skip this if `python3 --version` shows python 3.9.x or newer is installed)
sudo dnf install -y python3
# Install pip
diff --git a/_docs/installing/ubuntu.md b/_docs/installing/ubuntu.md
index 365db8644..59ba580db 100644
--- a/_docs/installing/ubuntu.md
+++ b/_docs/installing/ubuntu.md
@@ -4,7 +4,7 @@ category: Installing the bot
order: 3
---
-
+
Installing MusicBot on Ubuntu is simple, and we have steps for several LTS versions.
While this guide leaves out non-LTS versions of Ubuntu, the steps here are a good place to start for interim versions.
@@ -80,7 +80,7 @@ After configuring you can use the command ./run.sh to start the bot
Install steps.
-For Ubuntu 20.04 and 22.04, the Python 3 packages should be 3.8 or newer which makes install pretty simple. +For Ubuntu 20.04 and 22.04, the Python 3 packages should be 3.9 or newer which makes install pretty simple. {% highlight bash %} # Update system packages first diff --git a/_docs/installing/windows.md b/_docs/installing/windows.md index 5f9075b24..232fb8e06 100644 --- a/_docs/installing/windows.md +++ b/_docs/installing/windows.md @@ -3,7 +3,7 @@ title: Windows category: Installing the bot order: 2 --- -
+
> If you do not clone the bot using Git, and instead download the ZIP file from GitHub and attempt to run it, you will receive an error.
diff --git a/_docs/using/commands.md b/_docs/using/commands.md
index 09f0d18c3..bb05de4d2 100644
--- a/_docs/using/commands.md
+++ b/_docs/using/commands.md
@@ -439,6 +439,9 @@ Select from these services:- yt, youtube (default)
- sc, soundcloud
- yh, yahoo
+- gv, google
+- nv, nico
+- bb, bili
CommandPrefix
@@ -150,15 +153,24 @@ All channels are used if this is not set.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
+Default Value: yes
-
-Use spaces to separate multiple IDs.
-Default Value: *empty* +If enabled, MusicBot will allow commands to have multiple names using data in: config/aliases.json
+Default Value:
+AutojoinChannels
+UseAlias
-A list of Voice Channel IDs that MusicBot should automatically join on start up.-Use spaces to separate multiple IDs.
-Default Value: *empty* +If enabled, MusicBot will allow commands to have multiple names using data in: config/aliases.json
+Default Value:
yes
+
+
+Default Value:
+
+
+#### [ChatResponses]
+
EnablePrefixPerGuild
+ +Allow MusicBot to save a per-server command prefix, and enables the setprefix command.+Default Value:
no
DMNowPlaying
@@ -184,18 +196,86 @@ Only one text channel ID can be used per server.MusicBot will automatically delete Now Playing messages.
Default Value:
yes
+
+Default Value:
+NowPlayingMentions
+Mention the user who added the song when it is played.+Default Value:
no
+
+
+Delay period is controlled by DeleteDelayShort and DeleteDelayLong.
+Default Value:
+DeleteMessages
-#### [MusicBot] +Allow MusicBot to automatically delete messages it sends, after a delay.+Delay period is controlled by DeleteDelayShort and DeleteDelayLong.
+Default Value:
yes
+
+
+Default Value:
DeleteInvoking
+Auto delete valid commands after a delay.+Default Value:
no
+
-
-It can be set to one of the following:
- CRITICAL, ERROR, WARNING, INFO, DEBUG, VOICEDEBUG, FFMPEG, NOISY, or EVERYTHING
-Default Value:
+This period is used by messages that require no further interaction.
+Default Value:
+DebugLevel
+DeleteDelayShort
-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
+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
+
+
+This period is used by interactive or long-winded messages, like search and help.
+Default Value:
+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
+
+
+Default Value:
+UseEmbeds
+ +Allow MusicBot to format its messages as embeds.+Default Value:
yes
+
+
+Only applied when UseEmbeds is enabled and it is not blank.
+Default Value:
+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 (alpha-050125-18-g1ef01294-config-cli-tool)
+
+
+Default Value:
+RemoveEmbedFooter
+ +Completely remove the footer from embeds.+Default Value:
no
+
+
+Default Value:
+SearchList
+ +If enabled, users must indicate search result choices by sending a message instead of using reactions.+Default Value:
no
+
+
+Default Value:
+DefaultSearchResults
+ +Sets the default number of search results to fetch when using the search command without a specific number.+Default Value:
3
+
+
+Default Value:
+QueueLength
+ +The number of entries to show per-page when using q command to list the queue.+Default Value:
10
+
+Default Value:
+
+
+#### [Playback]
+
ReplyAndMention
+ +Command responses will also mention or notify the user.+Default Value:
yes
+DefaultVolume
@@ -228,41 +308,91 @@ You can set this from 0 to 1, or 0% to 100%.Default Value:
0.5
-
+Allow the member who requested the song to skip it, bypassing votes.
Default Value:
SaveVideos
+AllowAuthorSkip
-Allow MusicBot to keep downloaded media, or delete it right away.+Allow the member who requested the song to skip it, bypassing votes.
Default Value:
yes
-
-Default Value:
+Default Value:
StorageLimitBytes
+LegacySkip
-If SaveVideos is enabled, set a limit on how much storage space should be used.-Default Value:
0
+Enable users with the InstaSkip permission to bypass skip voting and force skips.+Default Value:
no
-
-Default Value:
+Default Value:
StorageLimitDays
+AutoPause
-If SaveVideos is enabled, set a limit on how long files should be kept.-Default Value:
0
+MusicBot will automatically pause playback when no users are listening.+Default Value:
yes
-
+Allow MusicBot to save the song queue, so queued songs will survive restarts.
Default Value:
StorageRetainAutoPlay
+PersistentQueue
-If SaveVideos is enabled, never purge auto playlist songs from the cache regardless of limits.+Allow MusicBot to save the song queue, so queued songs will survive restarts.
Default Value:
yes
-
+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:
+NowPlayingMentions
+PreDownloadNextSong
-Mention the user who added the song when it is played.+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
+
+
+This option can cause delay between playing songs, as the whole track must be processed.
Default Value:
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
-
+If enabled and multiple members are adding songs, MusicBot will organize playback for one song per member.
+Default Value:
+AutoSummon
+RoundRobinQueue
-Automatically join the owner if they are in an accessible voice channel when bot starts.+If enabled and multiple members are adding songs, MusicBot will organize playback for one song per member.
+Default Value:
no
+
+
+When enabled, users can use: `play file://path/to/file.ext`
+to play files from the local MediaFileDirectory path.
+Default Value:
+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
+
+
+Default Value:
+UnpausePlayerOnPlay
+ +Allow MusicBot to automatically unpause when play commands are used.+Default Value:
no
+
+
+When enabled, volume is controlled via FFmpeg filter instead of python.
+May cause a short delay when tracks first start for bitrate discovery.
Default Value:
+UseOpusAudio
+ +May reduce CPU usage by avoiding PCM-to-Opus encoding in python.+When enabled, volume is controlled via FFmpeg filter instead of python.
+May cause a short delay when tracks first start for bitrate discovery.
Default Value:
yes
+
+If the media is already Opus encoded (like YouTube) no re-encoding is done.
+This option will disable speed, volume, and UseExperimentalEqualization options.
+Default Value:
+UseOpusProbe
+ +Similar to UseOpusAudio, but reduces CPU usage even more where possible.+If the media is already Opus encoded (like YouTube) no re-encoding is done.
+This option will disable speed, volume, and UseExperimentalEqualization options.
+Default Value:
no
+
+
+Read ytdlp's list of supported sites to find supported prefixes you can use here.
+Some prefix examples: ytsearch, scsearch, gvsearch, yvsearch, bilisearch, nicosearch
+Default Value:
+
+
+#### [AutoPlaylist]
+
DefaultSearchService
+ +This option sets the default search service used by MusicBot through ytdlp.+Read ytdlp's list of supported sites to find supported prefixes you can use here.
+Some prefix examples: ytsearch, scsearch, gvsearch, yvsearch, bilisearch, nicosearch
+Default Value:
ytsearch
+UseAutoPlaylist
@@ -289,49 +419,71 @@ Remove songs from the auto playlist if they are found in the song block list.Default Value:
no
-
-Default Value:
+This will contain all songs from all servers.
+Default Value:
AutoPause
+SavePlayedHistoryGlobal
-MusicBot will automatically pause playback when no users are listening.-Default Value:
yes
+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
-
-Delay period is controlled by DeleteDelayShort and DeleteDelayLong.
+Enable saving songs played per-server to a playlist file: config/playlists/history[Server ID].txt
+Default Value:
+DeleteMessages
+SavePlayedHistoryGuilds
-Allow MusicBot to automatically delete messages it sends, after a delay.-Delay period is controlled by DeleteDelayShort and DeleteDelayLong.
+Enable saving songs played per-server to a playlist file: config/playlists/history[Server ID].txt
+Default Value:
no
+
+
Default Value:
+
+
+#### [MusicBot]
+
RemoveFromAPOnError
+ +Enable MusicBot to automatically remove unplayable entries from the auto playlist.Default Value:
yes
-
-Default Value:
+It can be set to one of the following:
+ CRITICAL, ERROR, WARNING, INFO, DEBUG, VOICEDEBUG, FFMPEG, NOISY, or EVERYTHING
+Default Value:
DeleteInvoking
+DebugLevel
-Auto delete valid commands after a delay.-Default Value:
no
+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
-
-This period is used by messages that require no further interaction.
-Default Value:
+Use spaces to separate multiple IDs.
+Default Value: *empty*
DeleteDelayShort
+AutojoinChannels
-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
+A list of Voice Channel IDs that MusicBot should automatically join on start up.+Use spaces to separate multiple IDs.
+Default Value: *empty*
-
-This period is used by interactive or long-winded messages, like search and help.
-Default Value:
+Default Value:
DeleteDelayLong
+SaveVideos
-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
+Allow MusicBot to keep downloaded media, or delete it right away.+Default Value:
yes
-
+If SaveVideos is enabled, set a limit on how much storage space should be used.
+Default Value:
+PersistentQueue
+StorageLimitBytes
-Allow MusicBot to save the song queue, so queued songs will survive restarts.+If SaveVideos is enabled, set a limit on how much storage space should be used.
+Default Value:
0
+
+
+Default Value:
+StorageLimitDays
+ +If SaveVideos is enabled, set a limit on how long files should be kept.+Default Value:
0
+
+
Default Value:
StorageRetainAutoPlay
+ +If SaveVideos is enabled, never purge auto playlist songs from the cache regardless of limits.Default Value:
yes
-
-Currently this option does not apply to auto playlist or songs added to an empty queue.
+Automatically join the owner if they are in an accessible voice channel when bot starts.
Default Value:
PreDownloadNextSong
+AutoSummon
-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.
+Automatically join the owner if they are in an accessible voice channel when bot starts.
Default Value:
yes
@@ -363,74 +515,18 @@ If enabled, status messages will report info on paused players.
If enabled, MusicBot will save the track title to: data/[Server ID]/current.txt
Default Value:
-If enabled, MusicBot will save the track title to: data/[Server ID]/current.txt
Default Value:
no
-
-Default Value:
-AllowAuthorSkip
- -Allow the member who requested the song to skip it, bypassing votes.-Default Value:
yes
-
-
-This option can cause delay between playing songs, as the whole track must be processed.
-Default Value:
-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
-
-
-Default Value:
-UseEmbeds
- -Allow MusicBot to format its messages as embeds.-Default Value:
yes
-
-
-Default Value:
-QueueLength
- -The number of entries to show per-page when using q command to list the queue.-Default Value:
10
-
-
-Default Value:
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
-
-Default Value:
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
-
-Default Value:
-UseAlias
- -If enabled, MusicBot will allow commands to have multiple names using data in: config/aliases.json-Default Value:
yes
-
-
-Only applied when UseEmbeds is enabled and it is not blank.
-Default Value:
-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-190-g7719f30f)
-
-
-Default Value:
RemoveEmbedFooter
- -Completely remove the footer from embeds.-Default Value:
no
-SelfDeafen
@@ -466,30 +562,6 @@ You can set this to a number of seconds of phrase like: 15 minutesSet it to 0 to disable leaving in this way.
Default Value:
0:00:00
-
-Default Value:
-SearchList
- -If enabled, users must indicate search result choices by sending a message instead of using reactions.-Default Value:
no
-
-
-Default Value:
-DefaultSearchResults
- -Sets the default number of search results to fetch when using the search command without a specific number.-Default Value:
3
-
-
-Default Value:
-EnablePrefixPerGuild
- -Allow MusicBot to save a per-server command prefix, and enables the setprefix command.-Default Value:
no
-
-
-Default Value:
RoundRobinQueue
- -If enabled and multiple members are adding songs, MusicBot will organize playback for one song per member.-Default Value:
no
-EnableNetworkChecker
@@ -499,33 +571,6 @@ MusicBot must be restarted to enable network testing.By default this is disabled.
Default Value:
no
-
-This will contain all songs from all servers.
-Default Value:
-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
-
-
-Default Value:
-SavePlayedHistoryGuilds
- -Enable saving songs played per-server to a playlist file: config/playlists/history[Server ID].txt-Default Value:
no
-
-
-When enabled, users can use: `play file://path/to/file.ext`
-to play files from the local MediaFileDirectory path.
-Default Value:
-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
-
-
-Default Value:
UnpausePlayerOnPlay
- -Allow MusicBot to automatically unpause when play commands are used.-Default Value:
no
-YtdlpProxy
@@ -546,24 +591,13 @@ Leave blank to use default, dynamically generated UA strings.Default Value: *empty*
-
-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:
-YtdlpUseOAuth2
+YtdlpSourceAddress
-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
-
-
-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* +Force yt-dlp to bind to a specific IP address or IP version on your system.
+To force any available IPv4, set this to: 0.0.0.0
+To force any available IPv6, set this to: ::
+To allow either IPv4 or v6, set this to: *
+Default Value:
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* +Force yt-dlp to bind to a specific IP address or IP version on your system.
+To force any available IPv4, set this to: 0.0.0.0
+To force any available IPv6, set this to: ::
+To allow either IPv4 or v6, set this to: *
+Default Value:
*
EnableUserBlocklist
@@ -577,13 +611,6 @@ Toggle the user block list feature, without emptying the block list.Enable the song block list feature, without emptying the block list.
Default Value:
no
-
-This option will disable UseExperimentalEqualization option as well.
-Default Value:
#### [Files]
@@ -629,7 +656,7 @@ An optional directory path where MusicBot will store long and short-term cache f
Configure automatic log file rotation at restart, and limit the number of files kept.UseOpusAudio
- -Potentially reduces CPU usage, but disables volume and speed controls.-This option will disable UseExperimentalEqualization option as well.
-Default Value:
no
-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
+Default Value: 3
LogsDateFormat
diff --git a/_docs/using/faq.md b/_docs/using/faq.md index 516dc4e64..bb566e7a0 100644 --- a/_docs/using/faq.md +++ b/_docs/using/faq.md @@ -4,28 +4,33 @@ category: Using the bot order: 7 --- -#### How do I get an ID? +## How do I get an ID? -
+
The bot has a `!listids` command that you can use to obtain IDs, or you can turn on Developer Mode in the Discord client by going to User Settings -> Appearance. Afterwards, you can right-click on any user, channel, role, whatever and you will get a Copy ID option on the context menu. The GIF demonstrates this.
-#### What can the bot play?
+## What can the bot play?
-The bot was developed to support YouTube and SoundCloud URLs, but it can theoretically support most of what yt-dlp [supports](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md). If there is a site that isn't supported by the bot but is by yt-dlp, create an [issue](https://github.com/Just-Some-Bots/MusicBot/issues/new) and let us know you want support added for it. The bot supports also streams like Twitch and internet radio (provided you give it a direct URL), however it is an experimental feature. To do this, use the `!stream` command instead of `!play`.
+MusicBot depends on yt-dlp and ffmpeg to get and play media.
+In theory, you can play any media ffmpeg can play from any service listed on [yt-dlp supported sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).
-Currently, the bot can't play music that is saved on your computer locally, though it is a [planned feature](https://github.com/Just-Some-Bots/MusicBot/issues/168).
+MusicBot also supports playing streams like Twitch and internet radio streams.
+To do this, use the `!stream` command instead of `!play` and provide a direct URL
+to the media stream.
-#### How can I sign into youtube?
+In recent `dev` branch versions, MusicBot optionally supports playing media files
+which can be manually uploaded to the `media` directory at the root of MusicBot directory.
-By using the experimental OAuth2 integration, you can use a youtube/google account to sign in.
-First enable `YtdlpUseOauth2` in your options file.
-Next, update the `YtdlpOauth2URL` option with a youtube video URL.
-While the URL is set, you should be prompted to verify at MusicBot startup. Otherwise MusicBot will prompt when a youtube video is requested.
+If you supply an attachment to the `!play` command, MusicBot will also attempt to play the first attachment.
-In most cases you should only need to verify once. MusicBot will update the oauth token as needed while making requests to youtube.
+## How can I sign into youtube?
-#### Can I modify the bot?
+You'll need to research what the maintainers of ytdlp recommend as the modern method of choice.
+Typically, if a method works for stand-alone ytdlp, then it can usually work for MusicBot.
+The solution seems to be different for everyone, as YouTube takes active steps to stop bots.
+
+## Can I modify the bot?
MusicBot is provided under an MIT License.
Under this license you are allowed to modify the source code as you please!
@@ -34,17 +39,19 @@ It is recommended that you are familiar with Python and the Asyncio library firs
If your modifications are general improvements, please consider contributing your changes to improve MusicBot for everyone.
-#### Can I change the bot's responses?
+## Can I change the bot's responses?
Short answer is yes!
+There are several options which impact how bot responds, in addition to using translation
+files to modify the content or format of messages sent by the bot.
-##### After the UI/i18n PR #2436
+#### After the UI/i18n PR #2436
MusicBot is almost fully translation ready, allowing you to translate or modify
text used by MusicBot in both Discord messages and MusicBot logs.
Translations use the Gettext format. For more information, see the [i18n readme](https://github.com/Just-Some-Bots/MusicBot/blob/dev/i18n/readme.md).
-##### Before the UI/i18n PR #2436
+#### Before the UI/i18n PR #2436
If you would like to change the bot's responses, perhaps because your users have a different native language, it is possible without editing the bot's source code. As long as you have a basic understanding of JSON, you can create a new i18n file. Open up the `config/i18n` folder, copy `en.json` to `whatever.json`, and then open it up with a code editor (such as Notepad++, Atom, or Visual Studio Code).
diff --git a/_docs/using/troubleshooting.md b/_docs/using/troubleshooting.md
index 259e7004b..812f4a330 100644
--- a/_docs/using/troubleshooting.md
+++ b/_docs/using/troubleshooting.md
@@ -6,59 +6,79 @@ order: 6
This is a table of common issues and solutions for the bot. Please check here before leaving an issue on GitHub or asking for help in our [support server](https://discord.gg/bots).
-Issue - Solution
+---
+
+## MusicBot was not installed using Git.
+
+This can happen if you did not use `git clone ...` to download MusicBot.
+The fix in this case is simply follow one of the guides or use the install scripts to get set up.
+
+This may also happen if you mess up file permissions in some way.
+The fix for this depends on the system you use, but typically you want to examine ownership and read/write access permissions and make sure they don't deny access from the user who launches MusicBot.
---
-`Bot was not installed using Git`
+## Failed environment check, ...
-You didn't install the bot correctly. Rather than downloading a ZIP, you must install using Git. Use our official installation guides rather than a YouTube video.
+These checks may fail if you have moved files around, broken file permissions, or have tried to start the bot outside of its cloned directory.
+It is recommended to use the bundled `run.bat` or `run.sh` as these will automatically change directory.
+Double check your file permissions are correct and if all else fails, re-install using a guide on this site.
---
-`Lagging while playing music`
+## Lagging while playing music
-Check your CPU and disk usage. Ensure that you have enough bandwidth. Check your voice channel's bitrate. Check there isn't a [Discord issue](https://status.discordapp.com).
+This can happen for a number of reasons, usually involving network quality and/or CPU load.
+Newer versions of MusicBot make use of newer methods in discord.py which should help reduce CPU load.
+If your version is new enough, you can use the options `UseOpusProbe` or `UseOpusAudio` to adjust how audio is processed and reduce CPU load.
---
-`Bot can't login, bad credentials`
+## Bot can't login, bad credentials
Check you copied the correct token from your [bot application page](https://discordapp.com/developers/applications/me) into your config file. It is called **Token**, not Client Secret.
---
-`WebSocket connection is closed`
+## WebSocket connection is closed
The bot tries to handle websocket disconnects, but sometimes there can be a problem, for example if Discord's voice servers go down. Try restarting the bot or switching server region if this error is persistent.
---
-`./run.sh: command not found`
+## ./run.sh: command not found
While Git *should* preserve file permissions, you may need to set `run.sh` to be executable by running `chmod a+x run.sh`.
---
-`Your config file is missing some options.`
+## Your config file is missing some options.
-This will usually occur if you have updated the bot. In order to avoid issues, bot updates do **not** update your config file with new options, but **do** update `example_options.ini`. Therefore, you should check that file and copy new options to your config file when you can (or delete your config file and re-configure entirely). The bot will use default settings for the missing options until you configure them, so the message is only a warning and will not impact the bot's performance.
+This typically shows up after you update the bot.
+The warning just indicates your current options file is missing newly available options.
+Default settings are used for all missing options.
+
+Updates will usually include changes in `example_options.ini` file, so you can copy
+the new options from that file. Alternatively, in newer versions, you can use the `config` command to manage missing options.
---
-`git: unable to access 'https://github.com/Just-Some-Bots/MusicBot.git'
-SSL certificate problem: self signed certificate in certificate chain`
+## NameError: name 'everything' is not defined
-Try disabling your antivirus. Some antivirus software is known to interfere with git.
+Caused by using Python 3.13 with older versions of MusicBot.
+To fix this you can either downgrade Python, or upgrade MusicBot.
+At time of writing this issue is resolved in the `dev` branch.
+Please note Python 3.13 "free-threaded" is not currently supported.
---
-`ValueError: Invalid format '.' for '%' style`
-
-You're likely using Python 3.8 with the master branch of the bot. Resolving this is as simple as either installing [Python 3.7](https://www.python.org/ftp/python/3.7.0/python-3.7.0.exe), or updating to review by running `git checkout review`
+## Download failed due to ...
----
+As MusicBot depends almost entirely on yt-dlp, these errors can cover a broad range of causes.
+To deal with these, you'll want to make sure you have yt-dlp up-to-date, first and foremost.
-`TypeError: __new__() got an unexpected keyword argument 'deny_new'`
+If the service you are using requires authorization of some sort, be sure to set
+that up or update it following the guides/docs provided by yt-dlp.
+In some cases, modifications to MusicBot may be required to enable new or existing
+options in yt-dlp. Feel free to bring those to our attention or contribute your changes to add the option for everyone.
-This occurs due to an outdated version of `discord.py`. To resolve this, update `discord.py` with the following command: `python -m pip install -U discord.py[voice]`
diff --git a/_docs/using/updating.md b/_docs/using/updating.md
index dbded8bba..4f6ed0ff3 100644
--- a/_docs/using/updating.md
+++ b/_docs/using/updating.md
@@ -6,10 +6,10 @@ order: 5
[](https://github.com/Just-Some-Bots/MusicBot/stargazers)
[](https://github.com/Just-Some-Bots/MusicBot/network)
-[](https://python.org)
+[](https://python.org)
-> MucicBot requires Python 3.8 or higher.
+> MucicBot requires Python 3.9 or higher.
Before updating, make sure to read the [latest changes](/MusicBot/changelog), as some behaviour may have changed significantly.
diff --git a/_posts/2025-01-13-dev-config-tool.md b/_posts/2025-01-13-dev-config-tool.md
new file mode 100644
index 000000000..36a86afe9
--- /dev/null
+++ b/_posts/2025-01-13-dev-config-tool.md
@@ -0,0 +1,60 @@
+---
+title: Config, Tools & More!
+type: major
+---
+
+> **Notice:** This update is not backwards compatible! It will update your config and create a backup of the original, just in case.
+
+**Python support changes**
+
+In this version, MusicBot officially no longer supports Python 3.8.
+The reason behind this is simple, Python 3.8 has reached End-of-life status and our most important dependency `yt-dlp` no longer supports it.
+To keep using MusicBot, you'll want to upgrade to python 3.9 or any version up to 3.12. If you are a `dev` branch enjoyer, you may also use python 3.13 (GIL only, free-thread not supported.)
+
+
+**OAuth2 integration removed**
+
+MusicBot previously provided an integration for yt-dlp OAuth2 authorization.
+As this is no longer supported, we have removed the integration and related options
+from MusicBot to help reduce confusion and clutter.
+If somehow that feature was still working for you, another minor change related to
+yt-dlp logging may now allow you to use yt-dlp plugins to replace that feature.
+
+
+**Config re-organization**
+
+The file `config/options.ini` and its example file now have more sections, and
+several options have been moved around to better organize the options and hopefully
+make it easier to find options you're looking for.
+Specifically, four new sections have been added:
+
+ - `[ChatCommands]` For options related to how MusicBot accepts commands.
+ - `[ChatResponses]` For options that control how MusicBot responds.
+ - `[Playback]` For media source and player behavior controls.
+ - `[AutoPlaylist]` For control of auto-playlist features.
+
+
+**Configuration tool**
+
+A new python tool has been added to MusicBot which replaces the old installer config steps entirely.
+The `configure.py` tool is basically a specialized editor for making configuration changes to MusicBot.
+It can be used at install or the user can call the script under the same python envrionment MusicBot uses to change configurations at any time.
+All changes are saved directly to the config files, and some validation is done on inputs. Changes made while a MusicBot instance is running must be reloaded manually however, by either restarting or using appropriate config/perms reload commands.
+
+As this is a brand-new tool, it probably has bugs and may not work for every situation. Please consider contributing to improve it as you see fit!
+
+
+**More changes**
+
+Other noteworthy changes include some new options, defaults, or general improvements.
+
+ - The `play` command(s) can now be used while attaching a file to play it. Previously you needed to copy the link into the play command. This will play only the first attached file.
+ - The `search` command now supports more search services supported by yt-dlp.
+ - New option `DefaultSearchService` can be used to set which service is used for search-based play commands.
+ - New option `ReplyAndMention` can be used to disable author-mentions on responses.
+ - Default of `UseOpusAudio` is now set to yes, as it seems to perform better than PCM.
+ - Removed cookies warning, since it should be obvious...
+ - Fixed `config missing` command producing too much text.
+ - Updated `i18n/lang.py` with new options `-L` and `-A`, check the i18n readme or `--help` option for details.
+ - Updated i18n POT/PO files with new strings and caller related info.
+
diff --git a/_sass/_layout.scss b/_sass/_layout.scss
index 54a4692bf..0ddcbbad1 100644
--- a/_sass/_layout.scss
+++ b/_sass/_layout.scss
@@ -441,11 +441,28 @@ blockquote {
img {
max-width: 100%;
height: auto;
-
- @media (prefers-color-scheme: dark) {
+}
+@media (prefers-color-scheme: dark) {
+ img {
filter: invert(100%) hue-rotate(180deg);
}
}
+.os-icon {
+ width: 75px;
+ float: right;
+ position: relative;
+ top: -6em;
+}
+
+.doc-img {
+ width: 70%;
+}
+
+.doc-img-right {
+ width: 33%;
+ float: right;
+ margin-bottom: 1em;
+}
.editor-link {
display: none;
diff --git a/images/openbsd.svg b/images/openbsd.svg
new file mode 100644
index 000000000..e7b32aafa
--- /dev/null
+++ b/images/openbsd.svg
@@ -0,0 +1,37 @@
+
+
+
diff --git a/index.md b/index.md
index 3d18d55e5..b9b9bf4af 100644
--- a/index.md
+++ b/index.md
@@ -2,7 +2,7 @@
title: Introduction
---
-
+
MusicBot is the original Discord music bot written for Python 3 using [discord.py](https://github.com/Rapptz/discord.py).
For an overview of what MusicBot is, and for the code history, see the [repository](https://github.com/Just-Some-Bots/MusicBot).