diff --git a/.github/labeler.yml b/.github/labeler.yml index f31fc49d5..a27da3e81 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -10,7 +10,10 @@ - docs/cog_guides/alias.rst "Category: Audio Cog": - any: + # Source - redbot/cogs/audio/**/* + # Docs + - docs/cog_guides/audio.rst all: - "!redbot/cogs/audio/**/locales/*" "Category: Bank API": diff --git a/docs/changelog_3_3_0.rst b/docs/changelog_3_3_0.rst index 72536402b..7f8f2046a 100644 --- a/docs/changelog_3_3_0.rst +++ b/docs/changelog_3_3_0.rst @@ -423,7 +423,7 @@ Audio ***** - Age-restricted tracks, live streams, and mix playlists from YouTube should work in Audio again (:issue:`3791`) -- Soundcloud's sets and playlists with more than 50 tracks should work in Audio again (:issue:`3791`) +- SoundCloud sets and playlists with more than 50 tracks should work in Audio again (:issue:`3791`) CustomCommands ************** diff --git a/docs/changelog_3_4_0.rst b/docs/changelog_3_4_0.rst index bb0b32acb..5764d6eb7 100644 --- a/docs/changelog_3_4_0.rst +++ b/docs/changelog_3_4_0.rst @@ -226,7 +226,7 @@ Audio - Enabled JDA-NAS on all system architectures which should limit stuttering/buffering issues on some machines (:issue:`5474`) - The bot will now disconnect from the voice channel when all members are bots if the auto-disconnect setting is enabled (:issue:`5421`) - Fixed an issue with resuming playback after changing voice channels (:issue:`5170`) -- Fixed issues with Soundcloud private playlists and mobile links (:issue:`5474`) +- Fixed issues with SoundCloud private playlists and mobile links (:issue:`5474`) - Fixed searching music with some of the queries containing quotes or backslashes (:issue:`5474`) - Fixed an exception caused by unavailable YT tracks in Mix playlists (:issue:`5474`) - Fixed ``IndexError`` in ``[p]queue`` command which occurred when the user provides negative integer as the page number (:issue:`5429`) @@ -576,7 +576,7 @@ Audio - The cog will now check whether it has speak permissions in the channel before performing any actions (:issue:`5012`) - Fixed an issue with Audio failing when it's missing permissions to send a message in the notification channel (:issue:`4960`) - Fixed fetching of age-restricted tracks (:issue:`5085`) -- Fixed an issue with Soundcloud URLs that ended with a slash (``/``) character (:issue:`5085`) +- Fixed an issue with SoundCloud URLs that ended with a slash (``/``) character (:issue:`5085`) Custom Commands *************** @@ -1046,7 +1046,7 @@ Audio ***** - Fixed ``[p]llset java`` failing to set the Java executable path (:issue:`4621`, :issue:`4624`) -- Fixed Soundcloud playback (:issue:`4683`) +- Fixed SoundCloud playback (:issue:`4683`) - Fixed YouTube age-restricted track playback (:issue:`4683`) - Added more friendly messages for 429 errors to let users know they have been temporarily banned from accessing the service instead of a generic Lavalink error (:issue:`4683`) - Environment information will now be appended to Lavalink tracebacks in the spring.log (:issue:`4683`) diff --git a/docs/cog_guides/audio.rst b/docs/cog_guides/audio.rst new file mode 100644 index 000000000..13ae74729 --- /dev/null +++ b/docs/cog_guides/audio.rst @@ -0,0 +1,3757 @@ +.. _audio: + +===== +Audio +===== + +This is the cog guide for the audio cog. You will +find detailed docs about usage and commands. + +``[p]`` is considered as your prefix. + +.. note:: To use this cog, load it by typing this:: + + [p]load audio + + +You can see additional help for any command in this guide by using ``[p]help`` with the +command name, like ``[p]help playlist append``. + +In this guide, you will see references to "Lavalink" or the "Lavalink.jar". `Lavalink `_ is the +Java-based audio backend we use to be able to play music through the bot. Most users will +not have to worry much about Lavalink or what it is, as Audio manages this process for you +by default. Advanced users can read more about Lavalink and special cases under the +:ref:`Lavalink - Red Community-Supported Advanced Usage` section below. + +You will also see references to ``managed`` or ``unmanaged`` in regards to the Lavalink.jar. +The default is ``managed``, as Audio manages the Lavalink.jar in this state. If it is run as an +``unmanaged`` process, this means you as the bot owner will be managing the Lavalink process yourself. + +When the Audio cog is first loaded, it will contact GitHub and download the newest Lavalink.jar file +for your bot to use. Any time Red is updated and you update your bot, it will probably download a new, +updated Lavalink.jar for your bot. It is important to keep your bot updated as fixes are provided for Lavalink frequently. + +.. warning:: + + All commands should be used in a Discord server, and not in Direct Messages as Audio is not available there. + +.. _basic-audio-use: + +---------------- +Basic Audio Use +---------------- + +The following commands are used for controlling the audio being played, such as starting, stopping, and altering volume. + +* ``[p]play`` - Play a single song or a playlist URL or use this command with words to search for a song. +* ``[p]search`` - Search for a track on YouTube. Searching on Soundcloud can be done with ``[p]search sc`` and the keywords to search for. +* ``[p]stop`` - Stops playback and clears the queue. +* ``[p]pause`` - This is a toggle. Use ``[p]pause`` again to resume the music. +* ``[p]prev`` - Stops playback of the current song and returns to the start of the previous song played. +* ``[p]skip`` - Skip to the next song in the queue, if there is one. +* ``[p]seek`` - Seek ahead to a specific track time, or seek ahead by seconds. +* ``[p]now`` - Show what song is currently playing. +* ``[p]volume`` - Set the volume from 0% to 150%. 100% is the default. Discord server owners can set a limit to the volume with ``[p]audioset maxvolume``. + +.. note:: + + The following services are currently supported through ``[p]play``: + + * Bandcamp + * HTTPS Icecast Streams + * HTTPS Shoutcast Streams + * Local file playback (:ref:`see here`) + * SoundCloud + * Spotify links via YouTube (:ref:`see here`) + * Twitch + * Vimeo + * YouTube + * Other AAC, MP3, or OGG-encoded streams + +.. note:: + + ``[p]audioset restrict`` is a toggle that only allows commercial site (YouTube, Soundcloud, etc) playback by default. + When toggled off, users will be able to play songs from HTTPS streams or arbitrary sites, but this could be a + security issue as your bot's IP address will be sent to any site it's connecting to, per standard internet protocol. + +.. _faq: + +-------------------------- +Frequently Asked Questions +-------------------------- + +**Q: I used a playlist link with some of the playlist related commands and it tells me that it can't find it. +How can I use this playlist link with playlist commands in audio?** + + Audio uses Red playlists in its commands that take playlist arguments. + These playlists can be created and modified using the ``[p]playlist`` group command. + When a playlist or song(s) are saved as a Red playlist, it is assigned an ID automatically, + and it is also assigned the one-word name you provided it when creating the playlist. + Either one of these identifiers can be used with playlist-related commands. + + .. tip:: + + If you have a playlist URL, use ``[p]playlist save `` to save it as a Playlist + with Audio. + +**Q: How do I turn off autoplay?** + + Use the ``[p]audioset autoplay toggle`` command. + +**Q: How do I get the bot to disconnect from the channel when it's done playing?** + + ``[p]audioset dc`` will make the bot auto-disconnect when playback completes and the + queue is empty. + ``[p]audioset emptydisconnect`` with a seconds argument greater than 0 will make the bot + auto-disconnect once it's alone in the channel, after the amount of seconds given to the + command. This setting takes precedence over ``[p]audioset dc`` if both settings are active. + +**Q: How do I use localtracks?** + + See the :ref:`local tracks section`. + +**Q: My console is saying that "Port 2333 is already in use". How can I fix this?** + + If you are trying to run multiple bots with Audio, you should follow our guide on + :ref:`setting up Audio for multiple bots`. Otherwise, another process is using the + port, so you need to figure out what is using port 2333 and terminate/disconnect it yourself. + +**Q: My terminal is saying that I "must install Java 11 for Lavalink to run". How can I fix this?** + + You are getting this error because you have a different version of Java installed, or you don't have + Java installed at all. As the error states, Java 11 is required, and can be installed from + `here `__. + + If you have Java 11 installed, and are still getting this error, you will have to manually tell Audio where your Java install is located. + Use ``[p]llset java ``, to make Audio launch Lavalink with a + specific Java binary. To do this, you will need to locate your ``java.exe``/``java`` file + in your **Java 11 install**. + + Alternatively, update your PATH settings so that Java 11 is the one used by ``java``. However, + you should confirm that nothing other than Red is running on the machine that requires Java. + +.. _queue_commands: + +---------------------- +Queue Related Commands +---------------------- + +* ``[p]queue`` - Shows the queue of playing songs and current settings for the server for shuffle and repeat. +* ``[p]remove`` - Remove a song from the queue. This command uses the track position in the queue for identification, e.g. ``[p]remove 10`` will remove + the 10th song in the queue. +* ``[p]shuffle`` - Toggle random song playback from the queue. +* ``[p]queue shuffle`` - Shuffles the queue. +* ``[p]repeat`` - Toggle adding songs back into the queue when they are finished playing. +* ``[p]playlist queue`` - Save the current queue to a Red playlist. +* ``[p]audioset persistqueue`` - Can be used to reinstate existing queues when the bot is restarted. This is an owner-only command. +* ``[p]audioset globaldailyqueue`` - Will toggle saving the day's worth of tracks to a Global-level Red playlist, for every day. This is an owner-only command. + +.. _playlist_commands: + +----------------- +Playlist Commands +----------------- + +Playlists can be saved locally on the bot in a variety of different scopes: + +* Global - The playlist will be available on all servers. +* Guild (default scope) - The playlist will be available only in a specified guild. +* User - The playlist will be available in any guild that the user shares with the bot. + +Some of the most relevant playlist commands include: + +* ``[p]playlist append`` - Add a track URL, playlist link, or quick search to a playlist. +* ``[p]playlist create`` - Creates an empty playlist. +* ``[p]playlist delete`` - Delete a saved playlist. +* ``[p]playlist info`` - Retrieve information about a saved playlist. +* ``[p]playlist list`` - List saved playlists. +* ``[p]playlist queue`` - Save the currently playing queue to a playlist. +* ``[p]playlist remove`` - Remove a track from a playlist by URL. + +As always, you can run ``[p]help playlist `` for more information. + +.. _owner-audioset-commands: + +---------------------------- +Owner-Only Audioset Commands +---------------------------- + +* ``[p]audioset cache`` - This sets the local metadata caching level for Audio. By default, this is set to on as it helps + reduce 429 Forbidden errors from song services, and also caches Spotify song lookups. Most users will not need to touch this option. +* ``[p]audioset cacheage`` - How long the entries in the cache last. By default, song metadata is cached for 365 days (1 year). +* ``[p]audioset status`` - Show the now playing song in the bot's status, or show how many servers the bot is playing music on, if more than one. +* ``[p]audioset restrictions global`` - Manage the keyword blocklist/allowlist for the whole bot. + +.. _guild-audioset-commands: + +----------------------------- +Guild-based Audioset Commands +----------------------------- + +* ``[p]audioset notify`` - Toggle extra messages: Audio will display a notification message when a track starts, + showing the song title, artist, and the thumbnail (if enabled and present). This notify message follows the last + invoking Audio command - if an Audio command is used in one channel and this setting is on, the notify messages + will start to appear in the channel where the command was used. If another Audio command is used in another + channel, notify messages will start appearing in the second channel instead of the first command channel. +* ``[p]audioset maxvolume`` - Set the max volume for the guild. +* ``[p]audioset autodeafen`` - Toggle the bot being auto-deafened upon voice channel join. +* ``[p]audioset restrictions`` - Manage the keyword blocklist/allowlist for the guild. +* ``[p]audioset lyrics`` - Searching for tracks will prefer songs with 'lyrics' in the name, to avoid videos with long story intros or outros. + +.. _spotify-playback-and-api-keys: + +------------------------------ +Spotify Playback and API Keys +------------------------------ + +We will never be able to play directly from Spotify itself as it is against their Terms of Service. Audio can play +single tracks or playlists from Spotify by looking up the song(s) on YouTube and playing those tracks instead. +This is possible by providing your bot with a YouTube API key and a Spotify API key. Instructions for setting both +can be found under ``[p]audioset youtubeapi`` and ``[p]audioset spotifyapi``. + +The YouTube API keys that are being given out currently only have 10000 units of quota per day, which is equivalent to +100 Spotify song lookups. There is a local metadata cache that Audio uses to be able to retain information about song +lookups. For example, with a 500 song Spotify playlist, the bot will be able to fetch the first 100 songs the +first day the Spotify playlist URL is used with Audio, then the next day it will be able to use the first 100 lookups +from the local cache, and use the API credits to look up the next 100 songs. After 5 days of playing the Spotify playlist +through Audio, that playlist will be fully cached locally until the cached entries are set to expire and will not require +any API credits to play songs. + +The following commands are relevant: + +* ``[p]genre`` - Lets users pick a Spotify music genre to queue music from. +* ``[p]audioset countrycode`` - Lets guild owners specify what country code to prefer for Spotify searches, for the guild. +* ``[p]audioset mycountrycode`` - Lets individual users pick what country code to prefer for Spotify searches of their own. + +.. _local-tracks: + +------------ +Local Tracks +------------ + +Audio can play music from a ``localtracks`` folder on the device where the bot is hosted. This feature is only available +if your bot and your Lavalink.jar are on the same host, which is the default setup. + +To use this feature: + +1. Create a "localtracks" folder anywhere where Lavalink/your bot user has permissions to access, on the system. +2. Use ``[p]audioset localpath `` to set the folder created above as the localtracks folder. +3. Create/move/copy/symlink your album folders (Subfolders containing your tracks) to the folder created in Step 1. +4. Put any of Audio's supported files in the following folders: + + * ``localtracks//song.mp3`` + * ``localtracks///song.mp3`` + +When using this localtracks feature, use ``[p]local`` commands. Use ``[p]play /song.mp3`` to play +single songs. Use ``[p]local folder /`` to play the entire folder. + +The following formats are supported: + +* MP3 +* FLAC +* Matroska/WebM (AAC, Opus or Vorbis codecs) +* MP4/M4A (AAC codec) +* OGG streams (Opus, Vorbis and FLAC codecs) +* AAC streams + +The following files are partially supported: + +* .ra +* .wav +* .opus +* .wma +* .ts +* .au +* .mov +* .flv +* .mkv +* .wmv +* .3gp +* .m4v +* .mk3d +* .mka +* .mks + +The following files are **NOT** supported: + +* .mid +* .mka +* .amr +* .aiff +* .ac3 +* .voc +* .dsf +* .vob +* .mts +* .avi +* .mpg +* .mpeg +* .swf + +.. _dj-role-and-voteskip: + +-------------------- +DJ Role and Voteskip +-------------------- + +Audio has an internal permissions system for restrictions to audio commands while other people are listening to +music with the bot. Bot owners, server admins and mods bypass these restrictions when they are in use. + +``[p]audioset dj`` will turn on the DJ role restriction system, ``[p]audioset role`` will let you choose or +reassign the DJ role, and if you wish to make non-privileged users vote to skip songs, voteskip can be enabled +with ``[p]audioset vote``. + +If a non-privileged user is listening to music alone in the channel, they can use commands without restrictions, +even if DJ role or voteskip settings are active. + +.. _sound-quality-issues: + +-------------------- +Sound Quality Issues +-------------------- + +Laggy audio is most likely caused by: + +* A problem with the connection between the machine that is hosting Lavalink and the Discord voice server. +* Issues with Discord. + +You can try the following to resolve poor sound quality: + +* Don't host on home internet, especially over a WiFi connection. Try hosting your bot elsewhere. +* Try the web browser instead of the desktop client for listening. +* Simply wait, as audio quality may improve in due course. +* Restart your bot. +* Check to make sure it's not just a bad quality song (try a different song). +* Try to listen on a different Discord server or server region. +* If not everyone is experiencing the issue, it's a Discord client issue. + +.. _no-sound: + +^^^^^^^^ +No Sound +^^^^^^^^ + +If the bot's speaking light is active, but there is no sound, troubleshoot the following: + +1. Is the bot's user volume turned up? (right click on the bot in Discord, see the slider). +2. Is the bot muted or deafened? Are you deafened? Are you deaf? +3. Check Discord audio device settings and volume (cog icon next to your username in the bottom left, click "Voice and Video"). +4. Try dragging and dropping the bot back to the voice channel. +5. Check system audio device settings and volume. +6. Ask another member to come into the voice channel to confirm that it's not just you. + +If the track progress is stuck on 00:00 when you run ``[p]now``: + +1. Try to run ``[p]disconnect`` and replay the song. +2. Try to reload the audio cog with ``[p]audioset restart``. +3. Make sure the firewall on the host is configured properly. + +.. _advanced-usage: + +------------------------------------------------- +Lavalink - Red Community-Supported Advanced Usage +------------------------------------------------- + +.. _multibots: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Setting up Multiple Red Instances with Audio on the Same Host +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + This section provides instructions for setting up an unmanaged Lavalink node that is on the same machine + as the Red bot(s) that need to connect to it. This configuration is supported by the Red community, so + if you need additional help, feel free to join the `Red Support Server `__ and ask in the #support channel. + + If you are looking to set up a remote, unmanaged Lavalink node on a different vps or host than the Red + bot(s) that will connect to it, we provide basic instructions in this guide :ref:`here`, but that + configuration is partially unsupported as we do not provide help with network configuration or system + administration. You will be responsible for configuring your network, firewall, and other system + properties to enable playback and for the bot to connect to the remote unmanaged Lavalink server. + +If you are wanting to use multiple bots with Audio on the same machine, you'll need to make a few +necessary modifications. + +Firstly, stop all Red bots. For each bot using Audio: + +1. Start the bot. +2. Run the command ``[p]llset external``. +3. Stop the bot. + +Next, open a command prompt/terminal window. Navigate to ``/cogs/Audio`` for any of your bot +instances - it doesn't matter which bot as all your bots will now use this single instance of Lavalink. +You can find your ```` with the ``[p]datapath`` command. + +Now you need to determine your RAM needs. If your bot has 1GB RAM available, Lavalink should be restricted +to perhaps 384MB -> 768MB, depending on the cogs you have installed. If your bot has 2GB of RAM available, +a good amount may be 512MB -> 1GB. + +Run the following command, where ``Xmx`` specifies the RAM value you have just determined. The MB suffix +is M and the GB suffix is G. + +.. code-block:: ini + + java -jar -Xmx768M Lavalink.jar -Djdk.tls.client.protocols=TLSv1.2 + +Leave this command prompt/terminal window open (you will need to do this every time you want to start Lavalink +for your bots). Once Lavalink says it has fully started, you can start your bots back up. + +.. note:: + + If you are on Linux, this process can be automated using systemd, for unmanaged + Lavalink backends **only**. See :ref:`here` for details. + +.. warning:: + + By running multiple bots that use Audio, the responsibility for keeping the Lavalink.jar updated will now be + in your hands, as Red will no longer manage it through the Audio cog. See :ref:`here` for guidance. + +.. _linux-audio-autorestart: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Linux Lavalink Auto-Restart +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Auto-restarting Lavalink is possible on Linux with systemd, for unmanaged Lavalink backends. + +Firstly, find out what your datapath is with the ``[p]datapath`` command. Your Lavalink path is +``/cogs/Audio``. Create a file named ``auto_update.sh`` in your Lavalink path. + +Inside this newly created file, paste the following text: + +.. code-block:: sh + + curl -LOz Lavalink.jar https://github.com/Cog-Creators/Lavalink-Jars/releases/latest/download/Lavalink.jar + +Run the following, replacing ```` with the Lavalink path you generated earlier (``/cogs/Audio``). + +.. code-block:: sh + + chmod a+rx /auto_update.sh + +Now we need to create a service file so that systemd can do its magic. Run the following command: + +.. code-block:: sh + + sudo -e /etc/systemd/system/lavalink.service + +Next, paste in the example below, but replacing the following: + +* ```` - You can find your Java path by running ``which java``. +* ```` - The parent folder where your Lavalink executable can be located (usually in ``/cogs/Audio``). +* ```` - Your username on the host machine (run ``echo $USER``). + +.. code-block:: ini + + [Unit] + Description=lavalink + After=multi-user.target + + [Service] + ExecStart= -Djdk.tls.client.protocols=TLSv1.2 -jar < Lavalink path >/Lavalink.jar + WorkingDirectory= + User= + Group= + ExecStartPre=/bin/bash /auto_update.sh # Comment this line out if you did not create the auto_update.sh + Type=idle + Restart=always + RestartSec=15 + + [Install] + WantedBy=multi-user.target + +Finally, we need to start and enable the service. Run the following commands, separately. + +.. code-block:: sh + + sudo systemctl start lavalink + sudo systemctl enable lavalink + +These commands always need to be ran when starting the lavalink service to ensure that the +service runs in the background. + +Finally, you can run the following to retrieve logs for the service, when you need them: + +.. code-block:: sh + + sudo journalctl -u lavalink + +.. _obtaining-the-latest-lavalink: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Obtaining the latest Lavalink.jar on a Red update +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**To manually download the jar** + +Stop your bot. Download the Lavalink.jar file from `here `__, +which could alternatively be downloaded by running the following command: + +.. code-block:: sh + + curl -LOz Lavalink.jar https://github.com/Cog-Creators/Lavalink-Jars/releases/latest/download/Lavalink.jar + +Next, stop all instances of Red running on the host, and stop the Lavalink process. Move the new Lavalink.jar +to where your old Lavalink.jar is located, overwriting the old file. + +Finally, start up the new Lavalink.jar process via a process manager like systemd, or by running the following command: + +.. code-block:: sh + + java -jar Lavalink.jar -Djdk.tls.client.protocols=TLSv1.2 + +Start up your bots, and now they will use the latest Lavalink.jar! + +.. _remote-lavalink: + +--------------------------------------------------------------- +Setting up an unmanaged Lavalink node on a remote VPS or server +--------------------------------------------------------------- + +.. attention:: + + We'd like to thank BreezeQS, as this guide is a supersession of their unofficial bare-bones guide. + +This guide explains how to set up an unmanaged Lavalink node on a separate server running Ubuntu 20.04 LTS. +It is assumed your bot currently uses a managed Lavalink server (Red's default). + +.. warning:: + + This guide is provided for advice on this topic and this is generally not a supported configuration for + Red's usage of Lavalink, as it involves system administration and network configuration. However, if you + run into any issues, feel free to ask for help in the `Red Support Server `__, in the #general channel. + +.. warning:: + + For security purposes DO NOT follow this guide while logged in as the root user. You should create + a separate non-root user instead. You can follow + `this guide `__ + from DigitalOcean if you need help about how this is done. + +^^^^^^^^^^^^^^^^^^^^^^^^^ +Prerequisite Installation +^^^^^^^^^^^^^^^^^^^^^^^^^ + +We will first install Lavalink and lay the foundation for our finished server. There are some prerequisites +that must be installed on the server you aim to use for running Lavalink. To set those up, run each of the +following commands one by one. + +.. code-block:: sh + + sudo apt update + sudo apt upgrade -y + sudo apt install curl nano -y + +If you have no preference in which Java version you install on your target system, Red +uses OpenJDK 11 in the managed Lavalink configuration. It can be installed by running: + +.. code-block:: sh + + sudo apt install openjdk-11-jre-headless -y + +Otherwise, Lavalink works well with most versions of Java 11, 13, 15, 16, 17, and 18. Azul +Zulu builds are suggested, see `here `__ for more information. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Setting Up The Lavalink Folder +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Lavalink itself, its configuration, and its logs will all be kept in a single directory. In this guide, +we will simply call this directory lavalink and it will be located in the home directory of the user you +are logged in as. + +We need to create a new directory called **lavalink**, and then switch to it as the upcoming sections of +this guide require your current directory to be the **lavalink** folder. We can achieve this by running +the following commands one by one: + +.. code-block:: sh + + cd + mkdir lavalink + cd lavalink + +^^^^^^^^^^^^^^^^^^^ +Installing Lavalink +^^^^^^^^^^^^^^^^^^^ + +The Lavalink executable used in Red-Discordbot is slightly modified and is not the same as stock Lavalink, +it ensures proper operation when used with Red-Discordbot and compatibility with systems and libraries that +Red uses to operate. It's required to use this Lavalink.jar when running unmanaged Lavalink servers to not +void your privilege to receive support. Assuming your current directory is the lavalink folder as you ran +the ``cd lavalink`` command in the previous section, you can run the following commands one by one to install it: + +.. code-block:: sh + + curl https://raw.githubusercontent.com/freyacodes/Lavalink/master/LavalinkServer/application.yml.example > application.yml + curl -LOz Lavalink.jar https://github.com/Cog-Creators/Lavalink-Jars/releases/latest/download/Lavalink.jar + +If you did it properly, the files ``Lavalink.jar`` and ``application.yml`` will show up when we run ``ls``, the Linux command +to list the contents of the current directory. + +^^^^^^^^^^^^^^^^^^^^ +Configuring Lavalink +^^^^^^^^^^^^^^^^^^^^ + +Lavalink stores its settings inside the ``application.yml`` file located in the same directory as the executable jar itself. +You have to edit this file and change some settings for security purposes. + +First, let's open the file. You can use any text editor you want, but in this guide we will use nano. +Run the following command: + +.. code-block:: sh + + nano application.yml + +You will be dropped into the nano text editor with ``application.yml`` opened. The two important fields that we will modify +are the ``port`` and ``password`` fields. + +The ``port`` field is the TCP port your Lavalink server will be accessible at. The default value is 2333, and you can set this +to any positive integer smaller than 65535 and greater than 1000. It is advised to change it to aid in security. + +The ``password`` field is the password that will be required for accessing your Lavalink server and by default the password is +``youshallnotpass``. You should absolutely change this to a secure password. + +Those two fields are important and you should take note of the new values you entered, as +they will be later required to connect your bot to the Lavalink server. + +At the bottom of the screen, the nano text editor displays some keys that can be used to carry out various tasks. +In this case, we want to save and exit. Keys prefixed with the caret (^) sign means they are used in conjunction +with the ctrl key. So we press Ctrl+X to exit. + +Nano will ask if you want to save the changes that were made. Answer with ``y`` and hit enter to exit. + +^^^^^^^^^^^^^^^^^ +Starting Lavalink +^^^^^^^^^^^^^^^^^ + +Now that Lavalink has been installed and configured, we can start it up. To do so, run the following command, making sure +that you are inside the lavalink folder, of course: + +.. code-block:: sh + + java -Djdk.tls.client.protocols=TLSv1.2 -jar Lavalink.jar + +On successful start, Lavalink will greet you with a line mentioning that it is ready to accept connections and you can now +try connecting to it with your bot. + +Since we did not configure autostart for Lavalink, you will have to keep the console window open or it will be shut down +and all connections will be dropped. This is similar to how it happens in Red-Discordbot itself. + +This also means that you will have to restart Lavalink manually each time you log on. This is often done in testing environments. +You can restart Lavalink manually by running the following commands one by one: + +.. code-block:: sh + + cd + cd lavalink + java -Djdk.tls.client.protocols=TLSv1.2 -jar Lavalink.jar + +You can stop Lavalink and reclaim the console by hitting ``CTRL+C``. + +^^^^^^^^^^^^^^^^^ +Updating Lavalink +^^^^^^^^^^^^^^^^^ + +With new releases of Red-Discordbot, sometimes new Lavalink jars are also released. Using an obsolete version of Lavalink +with newer versions of Red-Discordbot can cause all sorts of problems. + +Normally, users do not have to worry about this as when Red-Discordbot is configured to use a managed Lavalink server +(the default setting) Lavalink is automatically updated when a new release comes out. + +However, since you are running a Lavalink instance yourself you are responsible for keeping it up to date. +When a new release of Red-Discordbot also requires a update to the Lavalink jar, you will be informed in the changelogs +posted in our documentation. + +When a new Lavalink.jar comes out, you can easily update the existing one. First, you should stop Lavalink if it's currently +running. Once you have done this, you can follow the instructions on how to :ref:`obtain the latest Lavalink.jar on a Red update`. + +In the next section we will see how you can configure Lavalink to automatically update, automatically start, and run as +a background process which is much more convenient for non-testing deployments. + +^^^^^^^^^^^^^^^^^^^^^^ +Setting up Auto Update +^^^^^^^^^^^^^^^^^^^^^^ + +As previously covered, running Lavalink in a simple terminal session is fragile. Not only does it need you to manually +intervene each time you login, reboot, or just have to restart Lavalink for any reason you also have to update it manually +when a new Lavalink jar comes out. + +First of all, we will configure a script for updating Lavalink that runs before each time Lavalink starts. This step is +highly recommended. But if you know what you are doing, you can skip it if you want to update Lavalink manually. + +First, run the following commands: + +.. code-block:: sh + + cd + cd lavalink + nano auto_update.sh + +You'll see that running nano has opened a file. Paste the following code into the file: + +.. code-block:: sh + + #!/bin/sh + curl -LOz Lavalink.jar https://github.com/Cog-Creators/Lavalink-Jars/releases/latest/download/Lavalink.jar + +Now save the file and exit (``CTRL+X``, then ``y``). + +Now, run the following command, which will make the script possible to run: + +.. code-block:: sh + + chmod a+rx auto_update.sh + +If you did it right, the command itself will not output anything. And when running ``ls``, the script will show up in green. + +"""""""""""""""""""""""""""""" +Setting Up the Systemd Service +"""""""""""""""""""""""""""""" + +We will now register Lavalink as a system service, allowing it to run in the background without user intervention. +But before that, we need to gather some information. While in the lavalink folder, run the following commands one by one +and note their output somewhere, because we will need them: + +.. code-block:: sh + + pwd + which java + echo "$USER" + +Now run the following command: + +.. code-block:: sh + + sudo -e /etc/systemd/system/lavalink.service + +On new systems it may ask for a choice of editor. Nano is the best choice. To select it, press 1 and hit enter. +The nano text editor will now open. Now copy and paste the following text into it: + +.. code-block:: ini + + [Unit] + Description=lavalink + After=multi-user.target + + [Service] + ExecStart=< Java executable path > -Djdk.tls.client.protocols=TLSv1.2 -jar < Lavalink path >/Lavalink.jar + WorkingDirectory=< Lavalink path > + User=< username > + Group=< username > + ExecStartPre=/bin/bash < Lavalink path >/auto_update.sh # Comment this line out if you did not create the auto_update.sh + Type=idle + Restart=always + RestartSec=15 + + [Install] + WantedBy=multi-user.target + +* Replace all occurrences of ``< Lavalink path >`` with the output of ``pwd`` you noted earlier. +* Replace all occurrences of ``< Java executable path >`` with the output of ``which java`` you noted earlier. +* Replace all occurrences of ``< username >`` with the output of echo ``"$USER"`` you noted earlier. + +Hit ``CTRL+X``, ``y`` and then ENTER to save and exit. We have now registered Lavalink as a service. + +"""""""""""""""""""""""""""""""""""""""""" +Starting and Enabling the Lavalink Service +"""""""""""""""""""""""""""""""""""""""""" + +Now run the following command to start the Lavalink service and wait for 10-15 seconds: + +.. code-block:: sh + + sudo systemctl start lavalink + +You can check the service status with the following command: + +.. code-block:: sh + + sudo journalctl -u lavalink + +Keep in mind this will occupy your terminal and you have to hit CTRL+C to stop it before doing something else. +This will only close the log viewer, Lavalink itself will continue to run in the background. + +You may now run the following to make Lavalink auto-restart each boot: + +.. code-block:: sh + + sudo systemctl enable lavalink + +.. tip:: + + You can stop the Lavalink service with the following when you need to e.g. for troubleshooting: + + .. code-block:: sh + + sudo systemctl stop lavalink + + You can also check the logs Lavalink persists by checking the ``spring.log`` file in the ``lavalink/logs/`` folder. + +Congratulations, you are almost ready. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Connecting to Your New Lavalink Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If your Red instance and Lavalink server will communicate over the Internet, make sure the Lavalink port is accessible +from the internet. Click `here `__ and test if the port you set in the ``application.yml`` +is accessible on the public ip address of your Lavalink server. This step isn't necessary if your Lavalink server and Red +instance will communicate over LAN. If you get connectivity errors, make sure there are no firewalls blocking the port and +you are using the correct port. + +If successful, run each of the following commands one by one on your bot. Replace ``"yourlavalinkip"`` with the ip of your Lavalink server. +Change ``"port"`` with the port you set up in the application.yml. Change ``"password"`` with the password you set up in the application.yml. +Do not use quotes in these commands. For example, ``[p]llset host 192.168.10.101`` or ``[p]llset password ahyesverysecure``. + +.. code-block:: none + + [p]llset external + [p]llset host "yourlavalinkip" + [p]llset port "port" + [p]llset password "password" + +Reload audio with ``[p]reload audio`` and give it a few seconds to connect. + +You now (hopefully) have a functioning Lavalink server on a machine separate to the one running your Red instance. Good luck! + +.. _audio-commands: + +-------- +Commands +-------- + +.. _audio-command-audioset: + +^^^^^^^^ +audioset +^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]audioset + +**Description** + +Music configuration options. + +.. _audio-command-audioset-autodeafen: + +""""""""""""""""""" +audioset autodeafen +""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset autodeafen + +**Description** + +Toggle whether the bot will be auto deafened upon joining the voice channel. + +.. _audio-command-audioset-autoplay: + +""""""""""""""""" +audioset autoplay +""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset autoplay + +**Description** + +Change auto-play setting. + +.. _audio-command-audioset-autoplay-playlist: + +"""""""""""""""""""""""""" +audioset autoplay playlist +"""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset autoplay playlist [args] + +**Description** + +Set a playlist to auto-play songs from. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example Usage** + +* ``[p]audioset autoplay playlist MyGuildPlaylist`` +* ``[p]audioset autoplay playlist MyGlobalPlaylist --scope Global`` +* ``[p]audioset autoplay playlist PersonalPlaylist --scope User --author Draper`` + +.. _audio-command-audioset-autoplay-reset: + +""""""""""""""""""""""" +audioset autoplay reset +""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset autoplay reset + +**Description** + +Resets auto-play to the default playlist. + +.. _audio-command-audioset-autoplay-toggle: + +"""""""""""""""""""""""" +audioset autoplay toggle +"""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset autoplay toggle + +**Description** + +Toggle auto-play when there are no songs in the queue. + +.. _audio-command-audioset-cache: + +"""""""""""""" +audioset cache +"""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset cache [level] + +**Description** + +Sets the caching level. + +Level can be one of the following: + +* ``0``: Disables all caching +* ``1``: Enables Spotify Cache +* ``2``: Enables YouTube Cache +* ``3``: Enables Lavalink Cache +* ``5``: Enables all Caches + +If you wish to disable a specific cache use a negative number. + +.. _audio-command-audioset-cacheage: + +""""""""""""""""" +audioset cacheage +""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset cacheage + +**Description** + +Sets the cache max age. This commands allows you to set the max number of +days before an entry in the cache becomes invalid. + +.. _audio-command-audioset-countrycode: + +"""""""""""""""""""" +audioset countrycode +"""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset countrycode + +**Description** + +Set the country code for Spotify searches. + +.. _audio-command-audioset-dailyqueue: + +""""""""""""""""""" +audioset dailyqueue +""""""""""""""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset dailyqueue + +**Description** + +Toggle daily queues. Daily queues creates a playlist for all tracks played today. + +.. _audio-command-audioset-dc: + +""""""""""" +audioset dc +""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset dc + +**Description** + +Toggle the bot auto-disconnecting when done playing. This setting takes precedence +over ``[p]audioset emptydisconnect``. + +.. _audio-command-audioset-dj: + +""""""""""" +audioset dj +""""""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset dj + +**Description** + +Toggle DJ mode. DJ mode allows users with the DJ role to use audio commands. + +.. _audio-command-audioset-emptydisconnect: + +"""""""""""""""""""""""" +audioset emptydisconnect +"""""""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset emptydisconnect + +**Description** + +Auto-disconnect from channel when bot is alone in it for x seconds, 0 to disable. +``[p]audioset dc`` takes precedence over this setting. + +.. _audio-command-audioset-emptypause: + +""""""""""""""""""" +audioset emptypause +""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset emptypause + +**Description** + +Auto-pause after x seconds when the channel is empty, 0 to disable. + +.. _audio-command-audioset-globaldailyqueue: + +""""""""""""""""""""""""" +audioset globaldailyqueue +""""""""""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset globaldailyqueue + +**Description** + +Toggle global daily queues. Global daily queues creates a playlist +for all tracks played today. + +.. _audio-command-audioset-jukebox: + +"""""""""""""""" +audioset jukebox +"""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset jukebox + +**Description** + +Set a price for queueing tracks for non-mods, 0 to disable. + +.. _audio-command-audioset-localpath: + +"""""""""""""""""" +audioset localpath +"""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset localpath [local_path] + +**Description** + +Set the localtracks path if the Lavalink.jar is not run from the Audio data folder. +Leave the path blank to reset the path to the default, the Audio data directory. + +.. _audio-command-audioset-logs: + +""""""""""""" +audioset logs +""""""""""""" + +.. note:: |owner-lock| + +.. note:: + + This command is only available for managed Lavalink servers. + +**Syntax** + +.. code-block:: none + + [p]audioset logs + +**Description** + +Sends the Lavalink server logs to your DMs. + +.. _audio-command-audioset-lyrics: + +""""""""""""""" +audioset lyrics +""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset lyrics + +**Description** + +Prioritise tracks with lyrics. + +.. _audio-command-audioset-maxlength: + +"""""""""""""""""" +audioset maxlength +"""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset maxlength + +**Description** + +Max length of a track to queue in seconds, 0 to disable. Accepts seconds or a value +formatted like 00:00:00 (``hh:mm:ss``) or 00:00 (``mm:ss``). Invalid input will turn +the max length setting off. + +.. _audio-command-audioset-maxvolume: + +"""""""""""""""""" +audioset maxvolume +"""""""""""""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset maxvolume + +**Description** + +Set the maximum volume allowed in this server. + +.. _audio-command-audioset-mycountrycode: + +"""""""""""""""""""""" +audioset mycountrycode +"""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset mycountrycode + +**Description** + +Set the country code for Spotify searches. + +.. _audio-command-audioset-notify: + +""""""""""""""" +audioset notify +""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset notify + +**Description** + +Toggle track announcement and other bot messages. + +.. _audio-command-audioset-persistqueue: + +""""""""""""""""""""" +audioset persistqueue +""""""""""""""""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset persistqueue + +**Description** + +Toggle persistent queues. Persistent queues allows the current queue +to be restored when the queue closes. + +.. _audio-command-audioset-restart: + +"""""""""""""""" +audioset restart +"""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset restart + +**Description** + +Restarts the lavalink connection. + +.. _audio-command-audioset-restrict: + +""""""""""""""""" +audioset restrict +""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset restrict + +**Description** + +Toggle the domain restriction on Audio. + +When toggled off, users will be able to play songs from non-commercial websites and links. +When toggled on, users are restricted to YouTube, SoundCloud, Vimeo, Twitch, and +Bandcamp links. + +.. _audio-command-audioset-restrictions: + +""""""""""""""""""""" +audioset restrictions +""""""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions + +**Description** + +Manages the keyword whitelist and blacklist. + +.. _audio-command-audioset-restrictions-blacklist: + +""""""""""""""""""""""""""""""" +audioset restrictions blacklist +""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions blacklist + +**Description** + +Manages the keyword blacklist. + +.. _audio-command-audioset-restrictions-blacklist-add: + +""""""""""""""""""""""""""""""""""" +audioset restrictions blacklist add +""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions blacklist add + +**Description** + +Adds a keyword to the blacklist. + +.. _audio-command-audioset-restrictions-blacklist-clear: + +""""""""""""""""""""""""""""""""""""" +audioset restrictions blacklist clear +""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions blacklist clear + +**Description** + +Clear all keywords added to the blacklist. + +.. _audio-command-audioset-restrictions-blacklist-delete: + +"""""""""""""""""""""""""""""""""""""" +audioset restrictions blacklist delete +"""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions blacklist delete + +**Description** + +Removes a keyword from the blacklist. + +.. _audio-command-audioset-restrictions-blacklist-list: + +"""""""""""""""""""""""""""""""""""" +audioset restrictions blacklist list +"""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions blacklist list + +**Description** + +List all keywords added to the blacklist. + +.. _audio-command-audioset-restrictions-global: + +"""""""""""""""""""""""""""" +audioset restrictions global +"""""""""""""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global + +**Description** + +Manages the global keyword whitelist/blacklist. + +.. _audio-command-audioset-restrictions-global-blacklist: + +"""""""""""""""""""""""""""""""""""""" +audioset restrictions global blacklist +"""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global blacklist + +**Description** + +Manages the global keyword blacklist. + +.. _audio-command-audioset-restrictions-global-blacklist-add: + +"""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global blacklist add +"""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global blacklist add + +**Description** + +Adds a keyword to the blacklist. + +.. _audio-command-audioset-restrictions-global-blacklist-clear: + +"""""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global blacklist clear +"""""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global blacklist clear + +**Description** + +Clear all keywords added to the blacklist. + +.. _audio-command-audioset-restrictions-global-blacklist-delete: + +""""""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global blacklist delete +""""""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global blacklist delete + +**Description** + +Removes a keyword from the blacklist. + +.. _audio-command-audioset-restrictions-global-blacklist-list: + +""""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global blacklist list +""""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global blacklist list + +**Description** + +List all keywords added to the blacklist. + +.. _audio-command-audioset-restrictions-global-whitelist: + +"""""""""""""""""""""""""""""""""""""" +audioset restrictions global whitelist +"""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global whitelist + +**Description** + +Manages the global keyword whitelist. + +.. _audio-command-audioset-restrictions-global-whitelist-add: + +"""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global whitelist add +"""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global whitelist add + +**Description** + +Adds a keyword to the whitelist. If anything is added to whitelist, +it will blacklist everything else. + +.. _audio-command-audioset-restrictions-global-whitelist-clear: + +"""""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global whitelist clear +"""""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global whitelist clear + +**Description** + +Clear all keywords from the whitelist. + +.. _audio-command-audioset-restrictions-global-whitelist-delete: + +""""""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global whitelist delete +""""""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global whitelist delete + +**Description** + +Removes a keyword from the whitelist. + +.. _audio-command-audioset-restrictions-global-whitelist-list: + +""""""""""""""""""""""""""""""""""""""""""" +audioset restrictions global whitelist list +""""""""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions global whitelist list + +**Description** + +List all keywords added to the whitelist. + +.. _audio-command-audioset-restrictions-whitelist: + +""""""""""""""""""""""""""""""" +audioset restrictions whitelist +""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions whitelist + +**Description** + +Manages the keyword whitelist. + +.. _audio-command-audioset-restrictions-whitelist-add: + +""""""""""""""""""""""""""""""""""" +audioset restrictions whitelist add +""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions whitelist add + +**Description** + +Adds a keyword to the whitelist. If anything is added to whitelist, +it will blacklist everything else. + +.. _audio-command-audioset-restrictions-whitelist-clear: + +""""""""""""""""""""""""""""""""""""" +audioset restrictions whitelist clear +""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions whitelist clear + +**Description** + +Clear all keywords from the whitelist. + +.. _audio-command-audioset-restrictions-whitelist-delete: + +"""""""""""""""""""""""""""""""""""""" +audioset restrictions whitelist delete +"""""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions whitelist delete + +**Description** + +Removes a keyword from the whitelist. + +.. _audio-command-audioset-restrictions-whitelist-list: + +"""""""""""""""""""""""""""""""""""" +audioset restrictions whitelist list +"""""""""""""""""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset restrictions whitelist list + +**Description** + +List all keywords added to the whitelist. + +.. _audio-command-audioset-role: + +""""""""""""" +audioset role +""""""""""""" + +.. note:: |admin-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset role + +**Description** + +Set the role to use for DJ mode. + +.. _audio-command-audioset-settings: + +""""""""""""""""" +audioset settings +""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]audioset settings + +**Description** + +Show the current settings. + +.. _audio-command-audioset-spotifyapi: + +""""""""""""""""""" +audioset spotifyapi +""""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset spotifyapi + +**Description** + +Instructions to set the Spotify API tokens. + +.. _audio-command-audioset-status: + +""""""""""""""" +audioset status +""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset status + +**Description** + +Enable/disable tracks' titles as status. + +.. _audio-command-audioset-thumbnail: + +"""""""""""""""""" +audioset thumbnail +"""""""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset thumbnail + +**Description** + +Toggle displaying a thumbnail on audio messages. + +.. _audio-command-audioset-vote: + +""""""""""""" +audioset vote +""""""""""""" + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset vote + +**Description** + +Percentage needed for non-mods to skip tracks, 0 to disable. + +.. _audio-command-audioset-youtubeapi: + +""""""""""""""""""" +audioset youtubeapi +""""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audioset youtubeapi + +**Description** + +Instructions to set the YouTube API key. + +.. _audio-command-audiostats: + +^^^^^^^^^^ +audiostats +^^^^^^^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]audiostats + +**Description** + +Audio stats. + +.. _audio-command-autoplay: + +^^^^^^^^ +autoplay +^^^^^^^^ + +.. note:: |mod-lock| + +**Syntax** + +.. code-block:: none + + [p]autoplay + +**Description** + +Starts auto play. + +.. _audio-command-bump: + +^^^^ +bump +^^^^ + +**Syntax** + +.. code-block:: none + + [p]bump + +**Description** + +Bump a track number to the top of the queue. + +.. _audio-command-bumpplay: + +^^^^^^^^ +bumpplay +^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]bumpplay [play_now=False] + +**Description** + +Force play a URL or search for a track. + +.. _audio-command-disconnect: + +^^^^^^^^^^ +disconnect +^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]disconnect + +**Description** + +Disconnect from the voice channel. + +.. _audio-command-eq: + +^^ +eq +^^ + +**Syntax** + +.. code-block:: none + + [p]eq + +**Description** + +Equalizer management. + +Band positions are 1-15 and values have a range of -0.25 to 1.0. +Band names are 25, 40, 63, 100, 160, 250, 400, 630, 1k, 1.6k, 2.5k, 4k, +6.3k, 10k, and 16k Hz. +Setting a band value to -0.25 nullifies it while +0.25 is double. + +.. _audio-command-eq-delete: + +""""""""" +eq delete +""""""""" + +**Syntax** + +.. code-block:: none + + [p]eq delete + +**Description** + +Delete a saved eq preset. + +.. _audio-command-eq-list: + +""""""" +eq list +""""""" + +**Syntax** + +.. code-block:: none + + [p]eq list + +**Description** + +List saved eq presets. + +.. _audio-command-eq-load: + +""""""" +eq load +""""""" + +**Syntax** + +.. code-block:: none + + [p]eq load + +**Description** + +Load a saved eq preset. + +.. _audio-command-eq-reset: + +"""""""" +eq reset +"""""""" + +**Syntax** + +.. code-block:: none + + [p]eq reset + +**Description** + +Reset the eq to 0 across all bands. + +.. _audio-command-eq-save: + +""""""" +eq save +""""""" + +**Syntax** + +.. code-block:: none + + [p]eq save [eq_preset] + +**Description** + +Save the current eq settings to a preset. + +.. _audio-command-eq-set: + +"""""" +eq set +"""""" + +**Syntax** + +.. code-block:: none + + [p]eq set + +**Description** + +Set an eq band with a band number or name and value. + +Band positions are 1-15 and values have a range of -0.25 to 1.0. +Band names are 25, 40, 63, 100, 160, 250, 400, 630, 1k, 1.6k, 2.5k, 4k, +6.3k, 10k, and 16k Hz. +Setting a band value to -0.25 nullifies it while +0.25 is double. + +.. _audio-command-genre: + +^^^^^ +genre +^^^^^ + +**Syntax** + +.. code-block:: none + + [p]genre + +**Description** + +Pick a Spotify playlist from a list of categories to start playing. + +.. _audio-command-local: + +^^^^^ +local +^^^^^ + +**Syntax** + +.. code-block:: none + + [p]local + +**Description** + +Local playback commands. + +.. _audio-command-local-folder: + +"""""""""""" +local folder +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]local folder [folder] + +**Description** + +Play all songs in a localtracks folder. + +**Example usage** + +* ``[p]local folder`` - Open a menu to pick a folder to queue. +* ``[p]local folder folder_name`` - Queues all of the tracks inside the folder_name folder. + +.. _audio-command-local-play: + +"""""""""" +local play +"""""""""" + +**Syntax** + +.. code-block:: none + + [p]local play + +**Description** + +Play a local track. + +To play a local track, either use the menu to choose a track or enter in the track path directly +with the play command. To play an entire folder, use ``[p]help local folder`` for instructions. + +**Example usage** + +* ``[p]local play`` - Open a menu to pick a track. +* ``[p]play localtracks\album_folder\song_name.mp3`` +* ``[p]play album_folder\song_name.mp3`` - Use a direct link relative to the localtracks folder. + +.. _audio-command-local-search: + +"""""""""""" +local search +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]local search + +**Description** + +Search for songs across all localtracks folders. + +.. _audio-command-now: + +^^^ +now +^^^ + +**Syntax** + +.. code-block:: none + + [p]now + +**Description** + +Now playing. + +.. _audio-command-pause: + +^^^^^ +pause +^^^^^ + +**Syntax** + +.. code-block:: none + + [p]pause + +**Description** + +Pause or resume a playing track. + +.. _audio-command-percent: + +^^^^^^^ +percent +^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]percent + +**Description** + +Queue percentage. + +.. _audio-command-play: + +^^^^ +play +^^^^ + +**Syntax** + +.. code-block:: none + + [p]play + +**Description** + +Play the specified track or search for a close match. + +To play a local track, the query should be ``\``. +If you are the bot owner, use ``[p]audioset info`` to display your localtracks path. + +.. _audio-command-playlist: + +^^^^^^^^ +playlist +^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]playlist + +**Description** + +Playlist configuration options. + +**Scope information** + +* Global: Visible to all users of this bot. Only editable by bot owner. +* Guild: Visible to all users in this guild. Editable by bot owner, guild owner, + guild admins, guild mods, DJ role and playlist creator. +* User: Visible to all bot users, if ``--author`` is passed. Editable by bot owner and playlist creator. + +.. _audio-command-playlist-append: + +""""""""""""""" +playlist append +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist append [args] + +**Description** + +Add a track URL, playlist link, or quick search to a playlist. The track(s) will be +appended to the end of the playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist append MyGuildPlaylist Hello by Adele`` +* ``[p]playlist append MyGlobalPlaylist Hello by Adele --scope Global`` +* ``[p]playlist append MyGlobalPlaylist Hello by Adele --scope Global --Author Draper#6666`` + +.. _audio-command-playlist-copy: + +""""""""""""" +playlist copy +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist copy [args] + +**Description** + +Copy a playlist from one scope to another. + +**Args** + +The following are all optional: + +* --from-scope +* --from-author [user] +* --from-guild [guild] (**only the bot owner can use this**) +* --to-scope +* --to-author [user] +* --to-guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist copy MyGuildPlaylist --from-scope Guild --to-scope Global`` +* ``[p]playlist copy MyGlobalPlaylist --from-scope Global --to-author Draper#6666 --to-scope User`` +* ``[p]playlist copy MyPersonalPlaylist --from-scope user --to-author Draper#6666 --to-scope Guild --to-guild Red - Discord Bot`` + +.. _audio-command-playlist-create: + +""""""""""""""" +playlist create +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist create [args] + +**Description** + +Create an empty playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist create MyGuildPlaylist`` +* ``[p]playlist create MyGlobalPlaylist --scope Global`` +* ``[p]playlist create MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-dedupe: + +""""""""""""""" +playlist dedupe +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist dedupe [args] + +**Description** + +Remove duplicate tracks from a saved playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist dedupe MyGuildPlaylist`` +* ``[p]playlist dedupe MyGlobalPlaylist --scope Global`` +* ``[p]playlist dedupe MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-delete: + +""""""""""""""" +playlist delete +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist delete [args] + +**Description** + +Delete a saved playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist delete MyGuildPlaylist`` +* ``[p]playlist delete MyGlobalPlaylist --scope Global`` +* ``[p]playlist delete MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-download: + +""""""""""""""""" +playlist download +""""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]playlist download [v2=False] [args] + +**Description** + +Download a copy of a playlist. + +These files can be used with the ``[p]playlist upload`` command. +Red v2-compatible playlists can be generated by passing True +for the v2 variable. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist download MyGuildPlaylist True`` +* ``[p]playlist download MyGlobalPlaylist False --scope Global`` +* ``[p]playlist download MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-info: + +""""""""""""" +playlist info +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist info [args] + +**Description** + +Retrieve information from a saved playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist info MyGuildPlaylist`` +* ``[p]playlist info MyGlobalPlaylist --scope Global`` +* ``[p]playlist info MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-list: + +""""""""""""" +playlist list +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist list [args] + +**Description** + +List saved playlists. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist list`` +* ``[p]playlist list --scope Global`` +* ``[p]playlist list --scope User`` + +.. _audio-command-playlist-queue: + +"""""""""""""" +playlist queue +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist queue [args] + +**Description** + +Save the queue to a playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist queue MyGuildPlaylist`` +* ``[p]playlist queue MyGlobalPlaylist --scope Global`` +* ``[p]playlist queue MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-remove: + +""""""""""""""" +playlist remove +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist remove [args] + +**Description** + +Remove a track from a playlist by URL. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist remove MyGuildPlaylist https://www.youtube.com/watch?v=MN3x-kAbgFU`` +* ``[p]playlist remove MyGlobalPlaylist https://www.youtube.com/watch?v=MN3x-kAbgFU --scope Global`` +* ``[p]playlist remove MyPersonalPlaylist https://www.youtube.com/watch?v=MN3x-kAbgFU --scope User`` + +.. _audio-command-playlist-rename: + +""""""""""""""" +playlist rename +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist rename [args] + +**Description** + +Rename an existing playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist rename MyGuildPlaylist RenamedGuildPlaylist`` +* ``[p]playlist rename MyGlobalPlaylist RenamedGlobalPlaylist --scope Global`` +* ``[p]playlist rename MyPersonalPlaylist RenamedPersonalPlaylist --scope User`` + +.. _audio-command-playlist-save: + +""""""""""""" +playlist save +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist save [args] + +**Description** + +Save a playlist from a URL. + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist save MyGuildPlaylist https://www.youtube.com/playlist?list=PLx0sYbCqOb8Q_CLZC2BdBSKEEB59BOPUM`` +* ``[p]playlist save MyGlobalPlaylist https://www.youtube.com/playlist?list=PLx0sYbCqOb8Q_CLZC2BdBSKEEB59BOPUM --scope Global`` +* ``[p]playlist save MyPersonalPlaylist https://open.spotify.com/playlist/1RyeIbyFeIJVnNzlGr5KkR --scope User`` + +.. _audio-command-playlist-start: + +"""""""""""""" +playlist start +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist start [args] + +**Description** + +Load a playlist into the queue. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist start MyGuildPlaylist`` +* ``[p]playlist start MyGlobalPlaylist --scope Global`` +* ``[p]playlist start MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-update: + +""""""""""""""" +playlist update +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]playlist update [args] + +**Description** + +Updates all tracks in a playlist. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist update MyGuildPlaylist`` +* ``[p]playlist update MyGlobalPlaylist --scope Global`` +* ``[p]playlist update MyPersonalPlaylist --scope User`` + +.. _audio-command-playlist-upload: + +""""""""""""""" +playlist upload +""""""""""""""" + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]playlist upload [args] + +**Description** + +Uploads a playlist file as a playlist for the bot. + +V2 and old V3 playlist will be slow. +V3 Playlist made with ``[p]playlist download`` will load a lot faster. + +**Args** + +The following are all optional: + +* --scope +* --author [user] +* --guild [guild] (**only the bot owner can use this**) + +**Scope** is one of the following: + +* Global +* Guild +* User + +**Author** can be one of the following: + +* User ID +* User Mention +* User Name#123 + +**Guild** can be one of the following: + +* Guild ID +* Exact guild name + +**Example usage** + +* ``[p]playlist upload`` +* ``[p]playlist upload --scope Global`` +* ``[p]playlist upload --scope User`` + +.. _audio-command-prev: + +^^^^ +prev +^^^^ + +**Syntax** + +.. code-block:: none + + [p]prev + +**Description** + +Skip to the start of the previously played track. + +.. _audio-command-queue: + +^^^^^ +queue +^^^^^ + +**Syntax** + +.. code-block:: none + + [p]queue [page=1] + +**Description** + +List the songs in the queue. + +.. _audio-command-queue-clean: + +""""""""""" +queue clean +""""""""""" + +**Syntax** + +.. code-block:: none + + [p]queue clean + +**Description** + +Removes songs from the queue if the requester is not in the voice channel. + +.. _audio-command-queue-cleanself: + +""""""""""""""" +queue cleanself +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]queue cleanself + +**Description** + +Removes all tracks you requested from the queue. + +.. _audio-command-queue-clear: + +""""""""""" +queue clear +""""""""""" + +**Syntax** + +.. code-block:: none + + [p]queue clear + +**Description** + +Clears the queue. + +.. _audio-command-queue-search: + +"""""""""""" +queue search +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]queue search + +**Description** + +Search the queue. + +.. _audio-command-queue-shuffle: + +""""""""""""" +queue shuffle +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]queue shuffle + +**Description** + +Shuffles the queue. + +.. _audio-command-remove: + +^^^^^^ +remove +^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]remove + +**Description** + +Remove a specific track number from the queue. + +.. _audio-command-repeat: + +^^^^^^ +repeat +^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]repeat + +**Description** + +Toggle repeat. + +.. _audio-command-search: + +^^^^^^ +search +^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]search + +**Description** + +Pick a track with a search. + +Use ``[p]search list `` to queue all tracks found on YouTube. Use ``[p]search sc +`` to search on SoundCloud instead of YouTube. + +.. _audio-command-seek: + +^^^^ +seek +^^^^ + +**Syntax** + +.. code-block:: none + + [p]seek + +**Description** + +Seek ahead or behind on a track by seconds or to a specific time. Accepts seconds or +a value formatted like 00:00:00 (``hh:mm:ss``) or 00:00 (``mm:ss``). + +.. _audio-command-shuffle: + +^^^^^^^ +shuffle +^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]shuffle + +**Description** + +Toggle shuffle. + +.. _audio-command-shuffle-bumped: + +"""""""""""""" +shuffle bumped +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]shuffle bumped + +**Description** + +Toggle bumped track shuffle. + +Set this to disabled if you wish to avoid bumped songs being shuffled. This takes priority +over ``[p]shuffle``. + +.. _audio-command-sing: + +^^^^ +sing +^^^^ + +**Syntax** + +.. code-block:: none + + [p]sing + +**Description** + +Make Red sing one of her songs. + +.. _audio-command-skip: + +^^^^ +skip +^^^^ + +**Syntax** + +.. code-block:: none + + [p]skip [skip_to_track] + +**Description** + +Skip to the next track, or to a given track number. + +.. _audio-command-stop: + +^^^^ +stop +^^^^ + +**Syntax** + +.. code-block:: none + + [p]stop + +**Description** + +Stop playback and clear the queue. + +.. _audio-command-summon: + +^^^^^^ +summon +^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]summon + +**Description** + +Summon the bot to a voice channel. + +.. _audio-command-volume: + +^^^^^^ +volume +^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]volume [vol] + +**Description** + +Set the volume, 1% - 150%. + +.. _llset-commands: + +----------------------- +Lavalink Setup Commands +----------------------- + +``[p]llsetup`` group commands are used for advanced management of the connection to the Lavalink +server. The subcommands are dynamically available depending on whether Red is managing your +Lavalink node or if you are connecting to one you manage yourself, or a service that offers Lavalink +nodes. + +Commands specifically for managed Lavalink nodes can be found in :ref:`this section`, +whilst commands for unmanaged Lavalink nodes can be found :ref:`here`. + +.. _audio-command-llsetup: + +^^^^^^^ +llsetup +^^^^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]llsetup + +**Description** + +Manage Lavalink node configuration settings. This command holds all commands to +manage an unmanaged (external) or managed Lavalink node. + +.. warning:: + + You should not change any command settings in this group command unless you + have a valid reason to, e.g. been told by someone in the Red-Discord Bot support + server to do so. Changing llsetup command settings have the potential to break + Audio cog connection and playback if the wrong settings are used. + +"""""""""""""""" +llsetup external +"""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]llsetup external + +**Description** + +Toggle using external Lavalink nodes - requires an existing external Lavalink node for +Audio to work, if enabled. This command disables the managed Lavalink server: if you do +not have an external Lavalink node you will be unable to use Audio while this is enabled. + +"""""""""""" +llsetup info +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]llsetup info + +**Description** + +Display Lavalink connection settings. + +""""""""""""" +llsetup reset +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]llsetup reset + +**Description** + +Reset all ``[p]llset`` changes back to their default values. + +.. _managed-node-management-commands: + +-------------------------------- +Managed Node Management Commands +-------------------------------- + +.. _audio-command-llsetup-config: + +^^^^^^^^^^^^^^ +llsetup config +^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config + +**Description** + +Configure the managed Lavalink node runtime options. + +All settings under this group will likely cause Audio to malfunction if changed +from their defaults, only change settings here if you have been advised to by #support. + +.. _audio-command-llsetup-config-bind: + +^^^^^^^^^^^^^^^^^^^ +llsetup config bind +^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config bind [host=localhost] + +**Description** + +Set the managed Lavalink node's binding IP address. + +**Arguments** + +* ``[host]``: The node's binding IP address, defaulting to "localhost". + +.. _audio-command-llsetup-config-port: + +^^^^^^^^^^^^^^^^^^^ +llsetup config port +^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config port [port=2333] + +**Description** + +Set the managed Lavalink node's connection port. + +This port is the port the managed Lavalink node binds to, you should +only change this if there is a conflict with the default port because +you already have an application using port 2333 on this device. + +**Arguments** + +* ``[port]``: The node's connection port, defaulting to 2333. + +.. _audio-command-llsetup-config-server: + +^^^^^^^^^^^^^^^^^^^^^ +llsetup config server +^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config server + +**Description** + +Configure the managed node authorization and connection settings. + +.. _audio-command-llsetup-config-server-buffer: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config server buffer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config server buffer [milliseconds=400] + +**Description** + +Set the managed Lavalink node JDA-NAS buffer size. Only +change this if you have been directly advised to, +changing it can cause significant playback issues. + +**Arguments** + +* ``[milliseconds]`` - The buffer size, defaults to 400. + +.. _audio-command-llsetup-config-server-framebuffer: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config server framebuffer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config server framebuffer [milliseconds=1000] + +**Description** + +Set the managed Lavalink node framebuffer size. Only +change this if you have been directly advised to, +changing it can cause significant playback issues. + +**Arguments** + +* ``[milliseconds]`` - The framebuffer size, defaults to 1000. + +.. _audio-command-llsetup-config-source: + +^^^^^^^^^^^^^^^^^^^^^ +llsetup config source +^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source + +**Description** + +Toggle audio sources on/off. + +By default, all sources are enabled, you should only use commands here to +disable a specific source if you have been advised to, disabling sources +without background knowledge can cause Audio to break. + +.. _audio-command-llsetup-config-source-bandcamp: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source bandcamp +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source bandcamp + +**Description** + +Toggle Bandcamp source on or off. This toggle controls the playback +of all Bandcamp related content. + +.. _audio-command-llsetup-config-source-http: + +^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source http +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source http + +**Description** + +Toggle HTTP direct URL usage on or off. This source is used to +allow playback from direct HTTP streams (this does not affect direct URL +playback for the other sources). + +.. _audio-command-llsetup-config-source-local: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source local +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source local + +**Description** + +Toggle local file usage on or off. +This toggle controls the playback of all local track content, +usually found inside the ``localtracks`` folder. + +.. _audio-command-llsetup-config-source-soundcloud: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source soundcloud +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source soundcloud + +**Description** + +Toggle SoundCloud source on or off. +This toggle controls the playback of all SoundCloud related content. + +.. _audio-command-llsetup-config-source-twitch: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source twitch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source twitch + +**Description** + +Toggle Twitch source on or off. +This toggle controls the playback of all Twitch related content. + +.. _audio-command-llsetup-config-source-vimeo: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source vimeo +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source vimeo + +**Description** + +Toggle Vimeo source on or off. +This toggle controls the playback of all Vimeo related content. + +.. _audio-command-llsetup-config-source-youtube: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +llsetup config source youtube +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config source youtube + +**Description** + +Toggle YouTube source on or off (**this includes Spotify**). +This toggle controls the playback of all YouTube and Spotify related content. + +.. _audio-command-llsetup-config-token: + +^^^^^^^^^^^^^^^^^^^^ +llsetup config token +^^^^^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup config token [password=youshallnotpass] + +**Description** + +Set the managed Lavalink node's connection password. +This is the password required for Audio to connect to the managed Lavalink node. +The value by default is ``youshallnotpass``. + +**Arguments** + +* ``[password]`` - The node's connection password, defaulting to ``youshallnotpass``. + +.. _audio-command-llsetup-heapsize: + +^^^^^^^^^^^^^^^^ +llsetup heapsize +^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup heapsize [size=3G] + +**Description** + +Set the managed Lavalink node maximum heap-size. + +By default, this value is 50% of available RAM in the host machine +represented by [1-1024][M|G] (256M, 256G for example). + +This value only represents the maximum amount of RAM allowed to be +used at any given point, and does not mean that the managed Lavalink +node will always use this amount of RAM. + +**Arguments** + +* ``[size]`` - The node's maximum heap-size, defaulting to ``3G``. + +.. _audio-command-llsetup-java: + +^^^^^^^^^^^^ +llsetup java +^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup java [javapath] + +**Description** + +Change your Java executable path. + +This command shouldn't need to be used most of the time, +and is only useful if the host machine has conflicting Java versions. + +If changing this make sure that the Java executable you set is supported by Audio. +The current supported version is Java 11. + +**Arguments** + +* ``[java]`` - The java executable path, leave blank to reset it back to default. + +.. _audio-command-llsetup-yaml: + +^^^^^^^^^^^^ +llsetup yaml +^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup yaml + +**Description** + +Uploads a copy of the application.yml file used by the managed Lavalink node. + +.. _unmanaged-node-management-commands: + +---------------------------------- +Unmanaged Node Management Commands +---------------------------------- + +.. note:: + + A normal Red user should never have to use these commands unless they are :ref:`managing multiple Red bots with Audio`. + +.. _audio-command-llsetup-host: + +^^^^^^^^^^^^ +llsetup host +^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup host [host=localhost] + +**Description** + +Set the Lavalink node host. This command sets the connection host which +Audio will use to connect to an external Lavalink node. + +**Arguments** + +* ``[host]`` - The connection host, defaulting to "localhost". + +.. _audio-command-llsetup-password: + +^^^^^^^^^^^^^^^^ +llsetup password +^^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup password [password=youshallnotpass] + +**Description** + +Set the Lavalink node password. This command sets the connection password which +Audio will use to connect to an external Lavalink node. + +**Arguments** + +* ``[password]`` - The connection password, defaulting to "youshallnotpass". + +.. _audio-command-llsetup-port: + +^^^^^^^^^^^^ +llsetup port +^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup port [port=2333] + +**Description** + +Set the Lavalink node port. This command sets the connection port which +Audio will use to connect to an external Lavalink node. + +**Arguments** + +* ``[password]`` - The connection password, defaulting to 2333. + +.. _audio-command-llsetup-secured: + +^^^^^^^^^^^^^^^ +llsetup secured +^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]llsetup secured + +**Description** + +Set the Lavalink node connection to secured. This toggle sets the connection type +to secured or unsecured when connecting to an external Lavalink node. diff --git a/docs/index.rst b/docs/index.rst index eebef1d5b..8e23f3799 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,6 +35,7 @@ Welcome to Red - Discord Bot's documentation! intents cog_guides/admin cog_guides/alias + cog_guides/audio cog_guides/cleanup cog_guides/cog_manager_ui cog_guides/core diff --git a/docs/install_guides/windows.rst b/docs/install_guides/windows.rst index 5cd117ba3..d6ce2fe1c 100644 --- a/docs/install_guides/windows.rst +++ b/docs/install_guides/windows.rst @@ -66,7 +66,7 @@ Manually installing dependencies .. attention:: Please choose the option to "Git from the command line and also from 3rd-party software" in Git's setup. -* `Java 11 `_ - needed for Audio +* `Java 11 `_ - needed for Audio From here, continue onto `creating-venv-windows`. diff --git a/docs/prolog.txt b/docs/prolog.txt index c70a05fbb..06e5356f1 100644 --- a/docs/prolog.txt +++ b/docs/prolog.txt @@ -25,7 +25,7 @@ .. |role-input| replace:: Please give **the exact role name or ID**, or it won't be detected. .. |role-input-quotes| replace:: Please give **the exact role name or ID**, or it won't be detected. - If the role name has spaces, provide it enclosed in quotes like this: ``"my role with spaces"`` + If the role name has spaces, provide it enclosed in quotes like this: ``"my role with spaces"``. .. |member-input| replace:: You can either mention the member, provide their ID, their exact name with the tag or not, or their nickname. @@ -51,4 +51,4 @@ .. These are the comments for parameter types such as `bool`. -.. |bool-input| replace:: You should provide either 'true' or 'false'. \ No newline at end of file +.. |bool-input| replace:: You should provide either 'true' or 'false'. diff --git a/redbot/cogs/audio/core/commands/llset.py b/redbot/cogs/audio/core/commands/llset.py index 22a3118e4..b5bfc9a51 100644 --- a/redbot/cogs/audio/core/commands/llset.py +++ b/redbot/cogs/audio/core/commands/llset.py @@ -152,7 +152,7 @@ class LavalinkSetupCommands(MixinMeta, metaclass=CompositeMetaClass): ), ) - @command_llsetup.command(name="external") + @command_llsetup.command(name="external", aliases=["unmanaged"]) async def command_llsetup_external(self, ctx: commands.Context): """Toggle using external Lavalink nodes - requires an existing external Lavalink node for Audio to work, if enabled. @@ -457,7 +457,7 @@ class LavalinkSetupCommands(MixinMeta, metaclass=CompositeMetaClass): async def command_llsetup_config_source_http(self, ctx: commands.Context): """Toggle HTTP direct URL usage on or off. - This source is used to allow playback from direct http streams (This does not affect direct url playback for the other sources) + This source is used to allow playback from direct HTTP streams (this does not affect direct URL playback for the other sources). """ state = await self.config.yaml.lavalink.server.sources.http() await self.config.yaml.lavalink.server.sources.http.set(not state) @@ -538,7 +538,7 @@ class LavalinkSetupCommands(MixinMeta, metaclass=CompositeMetaClass): async def command_llsetup_config_source_soundcloud(self, ctx: commands.Context): """Toggle Soundcloud source on or off. - This toggle controls the playback of all Soundcloud related content. + This toggle controls the playback of all SoundCloud related content. """ state = await self.config.yaml.lavalink.server.sources.soundcloud() await self.config.yaml.lavalink.server.sources.soundcloud.set(not state) diff --git a/redbot/cogs/audio/core/commands/playlists.py b/redbot/cogs/audio/core/commands/playlists.py index d6e20e351..746b45881 100644 --- a/redbot/cogs/audio/core/commands/playlists.py +++ b/redbot/cogs/audio/core/commands/playlists.py @@ -52,7 +52,7 @@ class PlaylistCommands(MixinMeta, metaclass=CompositeMetaClass): ​ ​ ​ ​ ​ ​ ​ ​ Editable by bot owner, guild owner, guild admins, guild mods, DJ role and playlist creator. ​ ​ ​ ​ **User**: ​ ​ ​ ​ ​ ​ ​ ​ Visible to all bot users, if --author is passed. - ​ ​ ​ ​ ​ ​ ​ ​ Editable by bot owner and creator. + ​ ​ ​ ​ ​ ​ ​ ​ Editable by bot owner and the playlist creator. """ @command_playlist.command( diff --git a/redbot/cogs/audio/core/events/dpy.py b/redbot/cogs/audio/core/events/dpy.py index 9eb94babf..bd7bd55b4 100644 --- a/redbot/cogs/audio/core/events/dpy.py +++ b/redbot/cogs/audio/core/events/dpy.py @@ -133,9 +133,9 @@ DANGEROUS_COMMANDS = { "disabling this will make the bot unable to play any local track content." ), "command_llsetup_config_source_soundcloud": _( - "This command toggles the support of Soundcloud playback. " + "This command toggles the support of SoundCloud playback. " "An example is ; " - "disabling this will make the bot unable to play any Soundcloud content." + "disabling this will make the bot unable to play any SoundCloud content." ), "command_llsetup_config_source_youtube": _( "This command toggles the support of YouTube playback (Spotify depends on YouTube). " diff --git a/redbot/cogs/audio/core/utilities/player.py b/redbot/cogs/audio/core/utilities/player.py index cd305937e..45edc01e7 100644 --- a/redbot/cogs/audio/core/utilities/player.py +++ b/redbot/cogs/audio/core/utilities/player.py @@ -435,7 +435,7 @@ class PlayerUtilities(MixinMeta, metaclass=CompositeMetaClass): # a list of Tracks where all should be enqueued # this is a Spotify playlist already made into a list of Tracks or a # url where Lavalink handles providing all Track objects to use, like a - # YouTube or Soundcloud playlist + # YouTube or SoundCloud playlist if len(player.queue) >= 10000: return await self.send_embed_msg(ctx, title=_("Queue size limit reached.")) track_len = 0