API Reference#
Music Clients#
MusicClient#
- class discord.ext.music.MusicClient(client, channel)#
Same like
discord.VoiceClient
but with playback controls for music.Each coroutine functions are thread-safe.
You usually don’t create these, you can get it from
discord.VoiceChannel.connect()
Warning
It is important to add parameter
cls
with valueMusicClient
todiscord.VoiceChannel.connect()
, otherwise you wont get these features. For example:# Use this method music_client = await voice_channel.connect(cls=MusicClient) # But not this method music_client = await voice_channel.connect()
- on_disconnect(func)#
A decorator that register a callable function as hook when disconnected
Note
The function must be coroutine / async, otherwise it will raise error. The function must be not take any parameters.
- Parameters:
func – a callable function (must be a coroutine function)
- Raises:
TypeError – The function is not coroutine or async
- on_player_error(func)#
A decorator that register a callable function as hook when player encountered error.
The function can be normal function or coroutine (async) function.
- async disconnect(*, force=False)#
Disconnects this voice client from voice.
- async move_to(channel)#
Moves you to a different voice channel.
- Parameters:
channel (
discord.VoiceChannel
) – The channel to move to. Must be a voice channel.
- async reconnect(reconnect=True, timeout=10)#
Disconnect forcefully from voice channel and connect it again
- async set_playlist(playlist, stop_player=False)#
Replace current playlist with given playlist
- before_play_next(func)#
A decorator that register callable function (can be coroutine function) as a pre-play next track
This is useful for checking a streamable url or any type of set up required.
The
func
callable must accept 1 parameterTrack
that is the next track that want to be played.
- after_play_next(func)#
A decorator that register callable function (can be coroutine function) as a post-play next track
This is useful for sending announcement or any type of clean up required.
The
func
callable must accept 1 parameterTrack
that is the next track that want to be played.
- add_track(track)#
Add a track to playlist
- Parameters:
track (
Track
) – Audio Track that we’re gonna add to playlist.
- async play(track)#
Play a Track
This function is automatically add track to playlist, even it still playing songs.
- Parameters:
track (
Track
) – Audio Track that we’re gonna play.- Raises:
NotConnected – Not connected to voice
- async play_track_from_pos(pos)#
Play track from given pos
- Parameters:
pos (
int
) – Track position that we want to play.- Raises:
NotConnected – Not connected to voice
TrackNotExist – Given track position is not exist
- async stop()#
Stop playing audio
- Raises:
MusicNotPlaying – Not playing any audio
- async pause(play_silence=True)#
Pauses the audio playing.
- Parameters:
play_silence (
bool
) – if True play silence audio.- Raises:
MusicNotPlaying – Not playing any audio
- async resume()#
Resumes the audio playing.
- Raises:
MusicAlreadyPlaying – Already playing audio
MusicNotPlaying – Not playing any audio
- async seek(seconds)#
Jump forward to specified durations
- Parameters:
- Raises:
MusicNotPlaying – Not playing any audio
- async rewind(seconds)#
Jump back to specified durations
- Parameters:
- Raises:
MusicNotPlaying – Not playing any audio
- async next_track()#
Play next track
- Raises:
NotConnected – Not connected to voice.
NoMoreSongs – No more songs in playlist.
- async previous_track()#
Play previous track
- Raises:
NotConnected – Not connected a voice.
NoMoreSongs – No more songs in playlist.
- async remove_track(track)#
Remove a track and stop the player (if given track same as playing track)
- Parameters:
track (
Track
) – A Track you want to remove- Raises:
TrackNotExist – Given track is not exist
- async remove_track_from_pos(pos)#
Remove a track from given position and stop the player (if given pos same as playing track pos)
- Parameters:
pos (
int
) – Track position that we want to remove.- Raises:
TrackNotExist – Given track is not exist
- async remove_all_tracks()#
Remove all tracks and stop the player (if playing)
- property equalizer#
Return current equalizer music source being played (if playing).
- Type:
Optional[
Equalizer
]
- set_equalizer(equalizer)#
Set equalizer for music source
Note
This will apply equalizer to all music sources to this playlist. music sources that don’t support equalizer or volume adjust will be ignored.
- Parameters:
equalier (
Equalizer
) – Equalizer that want to be setted in music source- Raises:
MusicNotPlaying – Not playing any audio
MusicClientException – current music source does not support equalizer
- property volume#
Return current volume music source being played (if playing).
- Type:
Optional[
float
]
- set_volume(volume)#
Set volume for music source for this channel.
Note
This will apply volume to all music sources to this playlist. music sources that don’t support equalizer or volume adjust will be ignored.
- Parameters:
volume (
float
) – Volume that want to be setted in music source- Raises:
MusicNotPlaying – Not playing any audio
MusicClientException – current music source does not support volume adjust
- property source#
The audio source being played, if playing.
- Type:
Optional[
MusicSource
]
Tracks#
Track#
- class discord.ext.music.Track(source, name, url=None, thumbnail=None, **kwargs)#
A audio track containing audio source, name, url, thumbnail
- Parameters:
source (
MusicSource
) – The audio source of this trackname (
str
) – Name of this trackurl (
str
) – Webpage url of this trackthumbnail (
str
) – Valid thumbnail url of this track
- source#
The audio source of this track
- Type:
Playlists#
Playlist#
- class discord.ext.music.Playlist#
a class representing playlist for tracks
This class is thread-safe.
- property pos#
Return current position of the playlist.
- add_track(track)#
Add a track
- Parameters:
track (
Track
) – The audio track that we want to put in playlist.
- jump_to_pos(pos)#
Change playlist pos and return
Track
from given position- Parameters:
pos (
int
) – Track position that we want jump to- Raises:
TrackNotExist – Given track position is not exist
- Returns:
The audio track from given position
- Return type:
- remove_track(track)#
Remove a track
- Parameters:
track (
Track
) – The audio track that we want to remove from playlist.- Raises:
TrackNotExist – Given track is not exist
- remove_track_from_pos(pos)#
Remove a track from given position
- Parameters:
pos (
int
) – Track position that we want remove from playlist- Raises:
TrackNotExist – Given track position is not exist
- remove_all_tracks()#
Remove all tracks from playlist
- reset_pos_tracks()#
Reset current position playlist
- is_track_exist(track)#
Check if given track is exist in this playlist
- get_all_tracks()#
Get all tracks in this playlist
- Returns:
All tracks in playlist
- Return type:
List[
Track
]
- get_current_track()#
Get current track in current position
- Returns:
The current track in current position
- Return type:
- get_pos_from_track(track)#
Get a position track from given track
- Parameters:
track (
Track
) – Track that we want to retrieve from playlist- Raises:
TrackNotExist – Given track position is not exist
- Returns:
The track position from given track
- Return type:
- get_track_from_pos(pos)#
Get a track from given position
- Parameters:
pos (
int
) – Track position that we want retrieve from playlist- Raises:
TrackNotExist – Given track position is not exist
- Returns:
The track from given position
- Return type:
Equalizers#
- class discord.ext.music.Equalizer#
Represent a equalizer for converting audio.
Sub-classes must implement this.
- property stream#
Return the audio stream
- Type:
- setup(stream)#
Initialize audio stream to Equalizer
Warning
This is important to call it first, before equalizing audio.
- Parameters:
stream (
io.BufferedIOBase
) – The audio stream that we want to equalize.
- read()#
Read audio stream and return equalized audio data.
- close()#
Close audio stream and do some cleanup to the equalizer.
pydub Equalizer#
- class discord.ext.music.pydubEqualizer(freqs=None)#
A pydub equalizer for Signed-PCM codec
The audio specifications must be 16-bit 48KHz
- Parameters:
freqs (Optional[List[
dict
]]) – a list containing dict, each dict has frequency (in Hz) and gain (in dB) inside it. For example, [{“freq”: 20, “gain”: 20}, …] You cannot add same frequencys, if you try to add it, it will raisepydubError
.- Raises:
pydubError – pydub and scipy is not installed
- add_frequency(freq, gain)#
Add a frequency
- Parameters:
- Raises:
ValueError – given frequency is already exist
- remove_frequency(freq)#
Remove a frequency
- Parameters:
freq (
int
) – The frequency that want to add- Raises:
ValueError – given frequency is not exist
- set_gain(freq, gain)#
Set frequency gain in dB,
- Parameters:
- Raises:
ValueError – given frequency is not exist
- read()#
Read audio stream and return equalized audio data.
- class discord.ext.music.pydubSubwooferEqualizer(volume=0.5)#
An easy to use
pydubEqualizer
for subwooferThe frequency is 60Hz.
- Parameters:
volume (
float
) – Set initial volume as float percent. For example, 0.5 for 50% and 1.75 for 175%.
- property volume#
The subwoofer volume in float numbers
This property can also be used to change the subwoofer volume.
- Type:
Optional[
float
]
- set_gain(dB)#
Set frequency gain in dB.
- setup(stream)#
Initialize audio stream to Equalizer
Warning
This is important to call it first, before equalizing audio.
- Parameters:
stream (
io.BufferedIOBase
) – The audio stream that we want to equalize.
- read()#
Read audio stream and return equalized audio data.
Music sources#
Legacy music sources#
- class discord.ext.music.MusicSource#
same like
discord.AudioSource
, but its have seek, rewind, equalizer and volume built-in to AudioSource- read()#
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty
bytes
to signal this is the way to do so.If
is_opus()
method returnsTrue
, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).- Returns:
A bytes like object that represents the PCM or Opus data.
- Return type:
- recreate()#
Recreate audio source, useful for next and previous playback
- seek(seconds)#
Jump forward to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump forward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- rewind(seconds)#
Jump back to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump backward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- get_stream_durations()#
Get current stream durations in seconds
- Returns:
The current stream duration in seconds
- Return type:
- class discord.ext.music.RawPCMAudio(stream, volume=None)#
Represents raw 16-bit 48KHz stereo PCM audio source.
- Parameters:
stream (
io.BufferedIOBase
) – file-like objectvolume (
float
orNoneType
) – Set initial volume for AudioSource
- stream#
A file-like object that reads byte data representing raw PCM.
- Type:
- read()#
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty
bytes
to signal this is the way to do so.If
is_opus()
method returnsTrue
, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).- Returns:
A bytes like object that represents the PCM or Opus data.
- Return type:
- cleanup()#
Called when clean-up is needed to be done.
Useful for clearing buffer data or processes after it is done playing audio.
- recreate()#
Recreate audio source, useful for next and previous playback
- get_stream_durations()#
Get current stream durations in seconds
- Returns:
The current stream duration in seconds
- Return type:
- set_volume(volume)#
Set volume in float percentage. Set to
None
to disable volume adjust.For example, 0.5 = 50%, 1.5 = 150%
- Parameters:
volume (
float
) – Set volume to music source
- set_equalizer(eq=None)#
Set a
Equalizer
to MusicSource.- Parameters:
equalizer (
Equalizer
) – Set equalizer to music source
- seek(seconds)#
Jump forward to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump forward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- rewind(seconds)#
Jump back to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump backward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- class discord.ext.music.WAVAudio(file, volume=None, **kwargs)#
Represents WAV audio stream
- file: Union[
str
,io.BufferedIOBase
] valid file location or file-like object.
- volume:
float
orNoneType
Set initial volume for AudioSource
- kwargs:
These parameters will be passed in
RawPCMAudio
- file: Union[
Miniaudio music sources#
- class discord.ext.music.Miniaudio(stream, volume)#
Representing miniaudio-based audio source
Audio formats that miniaudio can play:
MP3
FLAC
Vorbis
WAV
Warning
You must have miniaudio installed, otherwise it didn’t work.
- Raises:
MiniaudioError – miniaudio not installed
- class discord.ext.music.MP3toPCMAudio(data, volume=0.5, **kwargs)#
Represents miniaudio-based mp3 to PCM audio source.
This audio source will convert mp3 to pcm format (16-bit 48KHz).
Note
When you initiate this class, the audio data will automatically coverted to pcm. This may cause all asynchronous process is blocked by this process. If you want to avoid this, use
MP3toPCMAudio.from_data
orMP3toPCMAudio.from_file
.- Parameters:
data (
bytes
) – MP3 bytes datavolume (
float
) – Set initial volumekwargs – These parameters will be passed in
RawPCMAudio
- stream#
A file-like object that reads byte data representing raw PCM.
- Type:
- Raises:
InvalidMP3 – The audio data is not mp3 format
- async classmethod from_data(data, volume=0.5)#
Asynchronously convert mp3 data to pcm.
- async classmethod from_file(filename, volume=0.5)#
Asynchronously convert mp3 data to pcm.
- class discord.ext.music.FLACtoPCMAudio(data, volume=0.5, **kwargs)#
Represents miniaudio-based flac to PCM audio source.
This audio source will convert flac to pcm format (16-bit 48KHz).
Note
When you initiate this class, the audio data will automatically coverted to pcm. This may cause all asynchronous process is blocked by this process. If you want to avoid this, use
FLACtoPCMAudio.from_data
orFLACtoPCMAudio.from_file
- Parameters:
data (
bytes
) – FLAC bytes datavolume (
float
) – Set initial volumekwargs – These parameters will be passed in
RawPCMAudio
- stream#
A file-like object that reads byte data representing raw PCM.
- Type:
- Raises:
InvalidFLAC – The audio data is not flac format
- async classmethod from_data(data, volume=0.5)#
Asynchronously convert flac data to pcm.
- async classmethod from_file(filename, volume=0.5)#
Asynchronously convert flac data to pcm.
- class discord.ext.music.VorbistoPCMAudio(data, volume=0.5, **kwargs)#
Represents miniaudio-based vorbis to PCM audio source.
This audio source will convert vorbis to pcm format (16-bit 48KHz).
Note
When you initiate this class, the audio data will automatically coverted to pcm. This may cause all asynchronous process is blocked by this process. If you want to avoid this, use
VorbistoPCMAudio.from_data
orVorbistoPCMAudio.from_file
- Parameters:
data (
bytes
) – Vorbis bytes datavolume (
float
) – Set initial volumekwargs – These parameters will be passed in
RawPCMAudio
- stream#
A file-like object that reads byte data representing raw PCM.
- Type:
- Raises:
InvalidVorbis – The audio data is not vorbis codec
- async classmethod from_data(data, volume=0.5)#
Asynchronously convert vorbis data to pcm.
- async classmethod from_file(filename, volume=0.5)#
Asynchronously convert vorbis data to pcm.
- class discord.ext.music.WAVtoPCMAudio(data, volume=0.5, **kwargs)#
Represents miniaudio-based WAV to PCM audio source.
This audio source will convert wav to pcm format (16-bit 48KHz).
Note
When you initiate this class, the audio data will automatically coverted to pcm. This may cause all asynchronous process is blocked by this process. If you want to avoid this, use
WAVtoPCMAudio.from_data
orWAVtoPCMAudio.from_file
- Parameters:
data (
bytes
) – WAV bytes datavolume (
float
) – Set initial volumekwargs – These parameters will be passed in
RawPCMAudio
- stream#
A file-like object that reads byte data representing raw PCM.
- Type:
- Raises:
InvalidWAV – The audio data is not WAV format
- async classmethod from_data(data, volume=0.5)#
Asynchronously convert WAV data to pcm.
- async classmethod from_file(filename, volume=0.5)#
Asynchronously convert WAV data to pcm.
PyAV / Embedded FFmpeg libraries music sources#
- class discord.ext.music.LibAVOpusAudio(url_or_file)#
Represents embedded FFmpeg-based Opus audio source.
Warning
You must have av installed, otherwise it didn’t work.
- Parameters:
url_or_file (
str
) – Valid URL or file location
- stream#
a file-like object that returning ogg opus encoded data
- Type:
- Raises:
LibAVError – Something happened when opening connection stream url.
- recreate()#
Recreate audio source, useful for next and previous playback
- is_opus()#
Checks if the audio source is already encoded in Opus.
- set_volume(volume)#
Set volume in float percentage. Set to
None
to disable volume adjust.For example, 0.5 = 50%, 1.5 = 150%
- Parameters:
volume (
float
) – Set volume to music source
- set_equalizer(equalizer)#
Set a
Equalizer
to MusicSource.- Parameters:
equalizer (
Equalizer
) – Set equalizer to music source
- read()#
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty
bytes
to signal this is the way to do so.If
is_opus()
method returnsTrue
, then it must return 20ms worth of Opus encoded audio. Otherwise, it must be 20ms worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes per frame (20ms worth of audio).- Returns:
A bytes like object that represents the PCM or Opus data.
- Return type:
- get_stream_durations()#
Get current stream durations in seconds
- Returns:
The current stream duration in seconds
- Return type:
- seek(seconds)#
Jump forward to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump forward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- rewind(seconds)#
Jump back to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump backward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- cleanup()#
Called when clean-up is needed to be done.
Useful for clearing buffer data or processes after it is done playing audio.
- class discord.ext.music.LibAVPCMAudio(url_or_file)#
Represents embedded FFmpeg-based audio source producing pcm packets.
Warning
You must have av installed, otherwise it didn’t work.
- Parameters:
url_or_file (
str
) – Valid URL or file location
- stream#
a file-like object that returning pcm packets.
- Type:
- Raises:
LibAVError – Something happened when opening connection stream url.
- recreate()#
Recreate audio source, useful for next and previous playback
- get_stream_durations()#
Get current stream durations in seconds
- Returns:
The current stream duration in seconds
- Return type:
- seek(seconds)#
Jump forward to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump forward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- rewind(seconds)#
Jump back to specified durations
- Parameters:
seconds (
float
) – The duration in seconds that we want to jump backward- Raises:
IllegalSeek – current stream doesn’t support seek() operations
- cleanup()#
Called when clean-up is needed to be done.
Useful for clearing buffer data or processes after it is done playing audio.
Exceptions#
- exception discord.ext.music.EqualizerError#
Raised when something happened in Equalizer class
- exception discord.ext.music.IllegalSeek#
Raised when MusicSource trying to seek when stream doesn’t support seek() operations
- exception discord.ext.music.InvalidMP3#
Raised when audio data is not mp3 format
- exception discord.ext.music.InvalidFLAC#
Raised when audio data is not flac format
- exception discord.ext.music.InvalidVorbis#
Raised when audio data is not vorbis codec
- exception discord.ext.music.InvalidWAV#
Raised when audio data is not WAV format
- exception discord.ext.music.MiniaudioError#
Raised when something happened in miniaudio module
- exception discord.ext.music.StreamHTTPError#
Raised when something happened in audio HTTP stream
- exception discord.ext.music.TrackNotExist#
Raised when track is trying to be removed while it not exist
- exception discord.ext.music.MusicClientException#
Base exception for MusicClient class
- exception discord.ext.music.MusicNotPlaying#
Music is not playing
- exception discord.ext.music.MusicAlreadyPlaying#
Music is already playing
- exception discord.ext.music.NoMoreSongs#
No more songs in playlist
- exception discord.ext.music.NotConnected#
Not connected to voice