Audio¶
This API acts as a wrapper for Red-LavaLink and allows developers to interact with the audio cog
Note
First attempt of creating an API for redbots audio module. This is not in any way production ready/stable yet. Use at your own risk
Many features of the core audio cog have been moved to the API’s code, thus the audio cog depends on it now This API however doesn’t depend on the audio cog being loaded
Basic Usage¶
from redbot.core import commands, audio
class MyAudioCog(commands.Cog):
def __init__(self, bot):
self.bot = bot
self.bot.loop.create_task(self.initialize())
#This function starts the lavalink server and established a lavalink and database connection
async def initialize(self):
await self.bot.wait_until_red_ready() #needed to ensure `bot` is fully initialized
await audio.initialize(self.bot, "MyAudioCog", 365911945565569036)
async def shutdown(self):
await audio.shutdown("MyAudioCog", 365911945565569036)
def cog_unload(self):
self.bot.loop.create_task(self.shutdown())
@commands.command()
async def connect(self, ctx, channel: discord.VoiceChannel):
player = audio.get_player(ctx.guild.id)
if not player: #not currently connected to a voice channel
player = await audio.connect(self.bot, ctx.author.voice.channel)
await ctx.send(f"Successfully connected to {channel.mention}")
@commands.command()
async def play(self, ctx, query: str):
player = audio.get_player(ctx.guild.id)
if not player:
return #use audio.connect first
await player.play(ctx.author, query)
now_playing = await player.current
await ctx.send(f"Now playing: {now_playing.title}")
Event Reference¶
- on_red_lavalink_server_started(java_path)¶
Dispatched when the lavalink server has been started
- Parameters
java_path (str) – The java executable used to start the server
- on_red_lavalink_server_stopped()¶
Dispatched when the lavalink server has been stopped
- on_red_lavalink_connection_established(host, password, ws_port)¶
Dispatched when the lavalink connection has been established
- on_red_audio_track_start(guild, track, requester)¶
Dispatched when a track has started
- Parameters
guild (discord.Guild) – The guild in which the track has been started
track (lavalink.Track) – The track which have been started
requester (discord.Member) – The requester of the track
- on_red_audio_track_enqueue(guild, track, requester)¶
Dispatched when a track is enqueued
- Parameters
guild (discord.Guild) – The guild in which the track has been enqueued
track (lavalink.Track) – The tracks which have been enqueued
requester (discord.Member) – The requester of the tracks
- on_red_audio_track_end(guild, track, requester, reason)¶
Dispatched when a track has ended
- Parameters
guild (discord.Guild) – The guild in which the track has ended
track (lavalink.Track) – The track which has ended
requester (discord.Member) – The requester of the track
reason (lavalink.TrackEndReason) – The reason why the track has ended
- on_red_audio_queue_end(guild, track, requester)¶
Dispatched when the queue has ended
- Parameters
guild (discord.Guild) – The guild in which the queue has ended
track (lavalink.Track) – The last played track
requester (discord.Member) – The requester of the last track
- on_red_audio_track_skip(guild, track, requester)¶
Dispatched when a track is skipped
- Parameters
guild (discord.Guild) – The guild in which the track has been skipped
track (lavalink.Track) – The current track
requester (discord.Member) – The user who requested the skip
- on_red_audio_track_exception(guild, track, requester, exception)¶
- Parameters
guild (discord.Guild) – The guild in which the exception occurred
track (lavalink.Track) – The track which got stuck
requester (discord.Member) – The user who requested the track
exception (str) – The exception
- on_red_audio_track_stuck(guild, track, requester, threshold)¶
- Parameters
guild (discord.Guild) – The guild in which the track has been stuck
track (lavalink.Track) – The track which got stuck
requester (discord.Member) – The user who requested the track
threshold (int) – Threshold milliseconds that the track has been stuck for
- on_red_audio_audio_paused(guild, paused)¶
Dispatched when the player is paused/resumed
- Parameters
guild (discord.Guild) – The guild in which the player has been stopped/resumed
paused (bool) – True if the player has been paused, False if resumed
- on_red_audio_audio_stop(guild)¶
Dispatched when the player has been manually stopped
- Parameters
guild (discord.Guild) – The guild in which the player disconnected
- on_red_audio_audio_disconnect(guild)¶
Dispatched when the player disconnects from a voice channel
- Parameters
guild (discord.Guild) – The guild in which the player disconnected
API Reference¶
audio¶
- await redbot.core.audio.connect(bot, channel, deafen=False)[source]¶
Connects to a voice channel
- Parameters
bot (Red) – The bot object
channel (discord.VoiceChannel) – The channel to connect to
deafen (bool) – Overwrites the configs auto_deafen value if given
- Returns
Player – A player object
- Return type
- await redbot.core.audio.dj_enabled(guild)[source]¶
Whether or not DJ controls are enabled
- Parameters
guild (discord.Guild) – The guild for which to check
- Returns
Whether or not DJ controls are enabled
- Return type
- redbot.core.audio.get_player(guild_id)[source]¶
Get the Player object of the given guild
- Parameters
guild (discord.Guild) – The guild to get the Player object from
- Returns
Player – The Player object of this guild
- Return type
Optional[Player]
- await redbot.core.audio.initialize(bot, cog_name, identifier, force_restart_ll_server=False, force_reset_db_conn=False)[source]¶
Initializes the api and establishes all connections
- Parameters
- await redbot.core.audio.is_dj(user)[source]¶
Whether ot not a user has the DJ role
- Parameters
user (discord.Member) – The user to check for
- Returns
Whether or not the user has the DJ role
- Return type
Player¶
Note
This class wraps various lavalink.Player methods and meanwhile interacts with RED’s
inbuilt config and databases. This class shouldn’t be instantiated manually. Use
audio.connect() to do so. The presence of this object guarantees that the
bot is connected to a voice channel in the current guild
- class redbot.core.audio.Player(bot, channel)[source]¶
Bases:
object- property channel¶
The current voice channel
- Type
- property current¶
The current track
- Type
lavalink.Track
- property guild¶
The player’s guild
- Type
- property is_playing¶
Whether or not the player is playing :type: bool
- property volume¶
The player’s volume :type: int
- await get_tracks(query, local_folder=None)[source]¶
Queries the local apis for a track and falls back to lavalink if none was found Note: falling back to lavalink is only possible if the bot is connected to a voice channel
- Parameters
query (str) – The query to search for. Supports everything core audio supports
local_folder (pathlib.Path) – Local folder if track is a local track
- Returns
- Return type
List[lavalink.Track], playlist_data
- await get_local_tracks(query)[source]¶
Converts a localtrack into a lavalink.Track object which can then be used in Player.play
- Parameters
query (pathlib.Path) – path to the music file
- Returns
- Return type
List[lavalink.Track], playlist_data
- fetch(key, default=None)[source]¶
Returns a stored metadata value.
- Parameters
key – Key used to store metadata.
default – Optional, used if the key doesn’t exist.
- await is_requester(member)[source]¶
Whether a user is the requester of the current song
- Parameters
member (discord.Member) – Member to check
- Returns
- Return type
- await move_to(channel, deafen=True)[source]¶
Move the player to another voice channel
- Parameters
channel (discord.VoiceChannel) – The channel to move the player to
deafen (bool) – Whether or not the player deafens
- await play(requester, query=None, track=None, local_folder=None, bump=False, bump_and_skip=False)[source]¶
Plays a track
- Parameters
requester (discord.Member) – The requester of the song
query (str) – The query to search for. Supports everything core audio supports
track (lavalink.Track) – A track object to be enqueued
local_folder (pathlib.Path) – Local folder if track is a local track
bump (bool) – Puts the song at queue position 0 if True
bump_and_skip (bool) – acts like bump but also skips the current song
- Returns
- Return type
List[lavalink.Track], playlist_data
- await seek(seconds=None, timestamp=None)[source]¶
Skip to a given position or skips a given amount of seconds
- await skip(requester, skip_to_track=None)[source]¶
Skips a track
- Parameters
requester (discord.Member) – The requester of the skip
skip_to_track (int) – Amount of tracks you want to skip
- Returns
The current track
- Return type
lavalink.Track
ServerManager¶
Note
This class handles the lavalink server subprocess. While the properties provided by this class may be useful,
one shouldn’t interact with any other function since starting of the server and dealing with the jar is
handled by audio.initialize(). Shutting down is handled by audio.shutdown()
