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 value MusicClient to discord.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()

add_track(track)¶

Add a track to playlist

Parameters: track (Track) – Audio Track that we’re gonna play.

async disconnect(*, force=False)¶

|coro|

Disconnects this voice client from voice.

get_stream_durations()¶: Optional[float]: Get current stream durations in seconds, if playing.

async move_to(channel)¶

|coro|

Moves you to a different voice channel.

Parameters: channel (abc.Snowflake) – The channel to move to. Must be a voice channel.

async next_track()¶

Play next track

Raises

NotConnected – Not connected to voice.
NoMoreSongs – No more songs in playlist.

async pause(play_silence=True)¶

Pauses the audio playing.

Parameters: play_silence (bool (default: True)) – if True play silence audio.
Raises: MusicNotPlaying – Not playing any audio

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
TypeError – “track” paramater is not Track

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 previous_track()¶

Play previous track

Raises

NotConnected – Not connected a voice.
NoMoreSongs – No more songs in playlist.

async reconnect(reconnect=True, timeout=10)¶

Disconnect forcefully from voice channel and connect it again

Parameters

reconnect (bool) – Reconnect when connection is failing.
timeout (float) – The timeout for the connection.

register_after_callback(func)¶

Register a callable function (can be coroutine function) for callback after player has done playing and play the next song or error occured.

Parameters: func (Callable[[Union[Exception, None], Union[Track, None]], Any]) – a callable function (can be coroutine function) that accept 2 parameters: Exception and Track. That Exception is for exception in the player (if error happened) and Track is for the next audio track.
Raises: TypeError – Not a callable function

async remove_all_tracks()¶: Remove all tracks and stop the player (if playing)

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 resume()¶

Resumes the audio playing.

Raises

MusicAlreadyPlaying – Already playing audio
MusicNotPlaying – Not playing any audio

async rewind(seconds)¶

Jump back to specified durations

Parameters: seconds (Union[int, float]) – Time to rewind in seconds
Raises: MusicNotPlaying – Not playing any audio

async seek(seconds)¶

Jump forward to specified durations

Parameters: seconds (Union[int, float]) – Time to seek in seconds
Raises: MusicNotPlaying – Not playing any audio

property source¶

The audio source being played, if playing.

Type: Optional[MusicSource]

async stop()¶

Stop playing audio

Raises: MusicNotPlaying – Not playing any audio

property track¶

The audio track being played, if playing.

Type: Optional[Track]

Tracks¶

Track¶

class discord.ext.music.Track(source, name, url=None, stream_url=None, thumbnail=None, **kwargs)¶

A audio track containing audio source, name, url, stream_url, thumbnail

Parameters

source (MusicSource) – The audio source of this track
name (str) – Name of this track
url (str) – Webpage url of this track
stream_url (str) – Streamable url of this track
thumbnail (str) – Valid thumbnail url of this track

source¶

The audio source of this track

Type: MusicSource

name¶

Name of this track

Type: str

url¶

Webpage url of this track

Type: str

stream_url¶

Streamable url of this track

Type: str

thumbnail¶

Valid thumbnail url of this track

Type: str

Playlists¶

Playlist¶

class discord.ext.music.Playlist¶

a class representing playlist for tracks

This class is thread-safe.

add_track(track)¶

Add a track

Parameters: track (Track) – The audio track that we want to put in 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: Track

get_next_track()¶

Get next track

Returns: The next track of this playlist
Return type: Union[Track, None]

get_previous_track()¶

Get previous track

Returns: The previous track of this playlist
Return type: Union[Track, None]

get_track_from_pos(pos)¶

Get a track from given position

Parameters: pos (int) – Track position that we want remove from playlist
Raises: TrackNotExist – Given track position is not exist
Returns: The track from given position
Return type: Track

is_track_exist(track)¶

Check if given track is exist in this playlist

Parameters: track (Track) – The audio track that we want to check
Returns: True if exist, or False if not exist
Return type: bool

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: Track

remove_all_tracks()¶: Remove all tracks from playlist

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

reset_pos_tracks()¶: Reset current position playlist

Equalizers¶

class discord.ext.music.Equalizer¶

Equalizer class

This was used for converting original audio data to equalized audio data

convert(data)¶

Convert audio data

Subclass must implement this.

class discord.ext.music.PCMEqualizer(freqs=None)¶

A equalizer for Signed-PCM codec

The audio specifications must be 16-bit 48KHz

Warning

You must have scipy and pydub installed, otherwise you will get error.

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 raise EqualizerError.
Raises: EqualizerError – pydub and scipy is not installed

add_frequency(freq, gain)¶

Add a frequency

Parameters

freq (int) – The frequency that want to add
gain (Union[int, float]) – The gain frequency

Raises

EqualizerError – given frequency is already exist

convert(data)¶

Convert audio data to equalized audio data

Parameters: data (bytes) – The audio data

remove_frequency(freq)¶

Remove a frequency

Parameters: freq (int) – The frequency that want to add
Raises: EqualizerError – given frequency is not exist

set_gain(freq, gain)¶

Set frequency gain in dB,

Parameters

freq (int) – The frequency want to increase the gain
gain (Union[int, float]) – The value want to increase or lower

Raises

EqualizerError – given frequency is not exist

class discord.ext.music.SubwooferPCMEqualizer(volume)¶

An easy to use PCMEqualizer for subwoofer

The base frequency is 60Hz.

Parameters: volume (float) – Set initial volume as float percent. For example, 0.5 for 50% and 1.75 for 175%.

add_frequency(freq, gain)¶

Add a frequency

Parameters

freq (int) – The frequency that want to add
gain (Union[int, float]) – The gain frequency

Raises

EqualizerError – given frequency is already exist

remove_frequency(freq)¶

Remove a frequency

Parameters: freq (int) – The frequency that want to add
Raises: EqualizerError – given frequency is not exist

set_gain(dB)¶: Set frequency gain in dB.

property volume¶

The subwoofer volume in float numbers

This property can also be used to change the subwoofer volume.

Type: Optional[float]

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

get_stream_durations()¶

Get current stream durations in seconds

Returns: The current stream duration in seconds
Return type: float

recreate()¶: Recreate audio source, useful for next and previous playback

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

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

seekable()¶

Check if this source support seek() and rewind() operations or not

return bool

set_equalizer(equalizer=None)¶

Set a Equalizer to MusicSource.

Parameters: equalizer (Equalizer) – Set equalizer to music source

set_volume(volume)¶

Set volume in float percentage

For example, 0.5 = 50%, 1.5 = 150%

Parameters: volume (volume) – Set volume to music source

class discord.ext.music.RawPCMAudio(stream, volume=0.5)¶

Represents raw 16-bit 48KHz stereo PCM audio source.

Parameters

stream (io.BufferedIOBase) – file-like object
volume (float or NoneType (Optional, default: 0.5)) – Set initial volume for AudioSource

stream¶

A file-like object that reads byte data representing raw PCM.

Type: py:file object

cleanup()¶

Called when clean-up is needed to be done.

Useful for clearing buffer data or processes after it is done playing audio.

get_stream_durations()¶

Get current stream durations in seconds

Returns: The current stream duration in seconds
Return type: float

read()¶

Reads 20ms worth of audio.

Subclasses must implement this.

If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

If is_opus() method returns True, 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: bytes

recreate()¶: Recreate audio source, useful for next and previous playback

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

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

seekable()¶

Check if this source support seek() and rewind() operations or not

return bool

set_equalizer(eq=None)¶

Set a Equalizer to MusicSource.

Parameters: equalizer (Equalizer) – Set equalizer to music source

set_volume(volume)¶

Set volume in float percentage

For example, 0.5 = 50%, 1.5 = 150%

Parameters: volume (volume) – Set volume to music source

class discord.ext.music.WAVAudio(stream, volume=0.5, **kwargs)¶

Represents WAV audio stream

stream: io.BufferedIOBase: file-like object
volume: float or NoneType (Optional, default: 0.5): Set initial volume for AudioSource
kwargs:: These parameters will be passed in RawPCMAudio

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 or MP3toPCMAudio.from_file.

Parameters

data (bytes) – MP3 bytes data
volume (float) – Set initial volume
kwargs – These parameters will be passed in RawPCMAudio

stream¶

A file-like object that reads byte data representing raw PCM.

Type: py:file object

Raises: InvalidMP3 – The audio data is not mp3 format

async classmethod from_data(data, volume=0.5)¶

Asynchronously convert mp3 data to pcm.

Parameters

data (bytes) – MP3 bytes data
volume (float) – Set initial volume, default to 0.5

async classmethod from_file(filename, volume=0.5)¶

Asynchronously convert mp3 data to pcm.

Parameters

filename (str) – MP3 File
volume (float) – Set initial volume, default to 0.5

seekable()¶

Check if this source support seek() and rewind() operations or not

return bool

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 or FLACtoPCMAudio.from_file

Parameters

data (bytes) – FLAC bytes data
volume (float) – Set initial volume
kwargs – These parameters will be passed in RawPCMAudio

stream¶

A file-like object that reads byte data representing raw PCM.

Type: py:file object

Raises: InvalidFLAC – The audio data is not flac format

async classmethod from_data(data, volume=0.5)¶

Asynchronously convert flac data to pcm.

Parameters

data (bytes) – FLAC bytes data
volume (float) – Set initial volume, default to 0.5

async classmethod from_file(filename, volume=0.5)¶

Asynchronously convert flac data to pcm.

Parameters

filename (str) – FLAC File
volume (float) – Set initial volume, default to 0.5

seekable()¶

Check if this source support seek() and rewind() operations or not

return bool

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 or VorbistoPCMAudio.from_file

Parameters

data (bytes) – Vorbis bytes data
volume (float) – Set initial volume
kwargs – These parameters will be passed in RawPCMAudio

stream¶

A file-like object that reads byte data representing raw PCM.

Type: py:file object

Raises: InvalidVorbis – The audio data is not vorbis codec

async classmethod from_data(data, volume=0.5)¶

Asynchronously convert vorbis data to pcm.

Parameters

data (bytes) – Vorbis bytes data
volume (float) – Set initial volume, default to 0.5

async classmethod from_file(filename, volume=0.5)¶

Asynchronously convert vorbis data to pcm.

Parameters

filename (str) – Vorbis File
volume (float) – Set initial volume, default to 0.5

seekable()¶

Check if this source support seek() and rewind() operations or not

return bool

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 or WAVtoPCMAudio.from_file

Parameters

data (bytes) – WAV bytes data
volume (float) – Set initial volume
kwargs – These parameters will be passed in RawPCMAudio

stream¶

A file-like object that reads byte data representing raw PCM.

Type: py:file object

Raises: InvalidWAV – The audio data is not WAV format

async classmethod from_data(data, volume=0.5)¶

Asynchronously convert WAV data to pcm.

Parameters

data (bytes) – WAV bytes data
volume (float) – Set initial volume, default to 0.5

async classmethod from_file(filename, volume=0.5)¶

Asynchronously convert WAV data to pcm.

Parameters

filename (str) – WAV File
volume (float) – Set initial volume, default to 0.5

seekable()¶

Check if this source support seek() and rewind() operations or not

return bool

PyAV / Embedded FFmpeg libraries music sources¶

class discord.ext.music.LibAVAudio¶

Represents embedded FFmpeg-based audio source.

Warning

You must have av installed, otherwise it didn’t work.

is_opus()¶: Checks if the audio source is already encoded in Opus.

class discord.ext.music.LibAVOpusAudio(url_or_file)¶

Represents embedded FFmpeg-based Opus audio source.

There is no volume adjuster and equalizer for now, because some problems.

Parameters: url_or_file (str) – Valid URL or file location

url¶

Valid URL or file location

Type: str

stream¶

a file-like object that returning ogg opus encoded data

Type: io.RawIOBase

Raises: LibAVError – Something happened when opening connection stream url.

cleanup()¶

Called when clean-up is needed to be done.

Useful for clearing buffer data or processes after it is done playing audio.

get_stream_durations()¶

Get current stream durations in seconds

Returns: The current stream duration in seconds
Return type: float

read()¶

Reads 20ms worth of audio.

Subclasses must implement this.

If the audio is complete, then returning an empty py:bytes-like object to signal this is the way to do so.

Returns: A bytes like object that represents the PCM or Opus data.
Return type: bytes

recreate()¶: Recreate audio source, useful for next and previous playback

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

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

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.LibAVError¶: Raised when something happened in LibAV 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