Voice Related
VoiceClient
- asyncconnect
- asyncdisconnect
- defis_connected
- defis_paused
- defis_playing
- asyncmove_to
- asyncon_voice_server_update
- asyncon_voice_state_update
- defpause
- defplay
- defresume
- defsend_audio_packet
- defstart_recording
- defstop
- defstop_recording
- deftoggle_pause
- defunpack_audio
- class discord.VoiceClient
Bases:
VoiceProtocol
Represents a Discord voice connection.
You do not create these, you typically get them from e.g.
VoiceChannel.connect()
.Warning
In order to use PCM based AudioSources, you must have the opus library installed on your system and loaded through
opus.load_opus()
. Otherwise, your AudioSources must be opus encoded (e.g. usingFFmpegOpusAudio
) or the library will not be able to transmit audio.- property guild
The guild we’re connected to, if applicable.
- Type:
Optional[
Guild
]
- await on_voice_state_update(data)
This function is a coroutine.
An abstract method that is called when the client’s voice state has changed. This corresponds to
VOICE_STATE_UPDATE
.- Parameters:
data (
dict
) –The raw voice state payload.
- await on_voice_server_update(data)
This function is a coroutine.
An abstract method that is called when initially connecting to voice. This corresponds to
VOICE_SERVER_UPDATE
.- Parameters:
data (
dict
) –The raw voice server update payload.
- await connect(*, reconnect, timeout)
This function is a coroutine.
An abstract method called when the client initiates the connection request.
When a connection is requested initially, the library calls the constructor under
__init__
and then callsconnect()
. Ifconnect()
fails at some point thendisconnect()
is called.Within this method, to start the voice connection flow it is recommended to use
Guild.change_voice_state()
to start the flow. After which,on_voice_server_update()
andon_voice_state_update()
will be called. The order that these two are called is unspecified.
- property latency
Latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
This could be referred to as the Discord Voice WebSocket latency and is an analogue of user’s voice latencies as seen in the Discord client.
Added in version 1.4.
- Type:
- property average_latency
Average of most recent 20 HEARTBEAT latencies in seconds.
Added in version 1.4.
- Type:
- await disconnect(*, force=False)
This function is a coroutine.
Disconnects this voice client from voice.
- await move_to(channel)
This function is a coroutine.
Moves you to a different voice channel.
- Parameters:
channel (
abc.Snowflake
) – The channel to move to. Must be a voice channel.
- play(source, *, after=None)
Plays an
AudioSource
.The finalizer,
after
is called after the source has been exhausted or an error occurred.If an error happens while the audio player is running, the exception is caught and the audio player is then stopped. If no after callback is passed, any caught exception will be displayed as if it were raised.
- Parameters:
source (
AudioSource
) – The audio source we’re reading from.after (Callable[[
Exception
], Any]) – The finalizer that is called after the stream is exhausted. This function must have a single parameter,error
, that denotes an optional exception that was raised during playing.
- Raises:
ClientException – Already playing audio or not connected.
TypeError – Source is not a
AudioSource
or after is not a callable.OpusNotLoaded – Source is not opus encoded and opus is not loaded.
- property source
The audio source being played, if playing.
This property can also be used to change the audio source currently being played.
- Type:
Optional[
AudioSource
]
- send_audio_packet(data, *, encode=True)
Sends an audio packet composed of the data.
You must be connected to play audio.
- Parameters:
data (
bytes
) – The bytes-like object denoting PCM or Opus voice data.encode (
bool
) – Indicates ifdata
should be encoded into Opus.
- Raises:
ClientException – You are not connected.
opus.OpusError – Encoding the data failed.
- unpack_audio(data)
Takes an audio packet received from Discord and decodes it into pcm audio data. If there are no users talking in the channel, None will be returned. You must be connected to receive audio. :param data: Bytes received by Discord via the UDP connection used for sending and receiving voice data. :type data:
bytes
- start_recording(sink, callback, *args)
The bot will begin recording audio from the current voice channel it is in. This function uses a thread so the current code line will not be stopped. Must be in a voice channel to use. Must not be already recording. :param sink: A Sink which will “store” all the audio data. :type sink:
Sink
:param callback: A function which is called after the bot has stopped recording. :type callback:asynchronous function
:param *args: Args which will be passed to the callback function.- Raises:
RecordingException – Not connected to a voice channel.
RecordingException – Already recording.
RecordingException – Must provide a Sink object.
VoiceProtocol
- defcleanup
- asyncconnect
- asyncdisconnect
- asyncon_voice_server_update
- asyncon_voice_state_update
- class discord.VoiceProtocol(client, channel)
Bases:
object
A class that represents the Discord voice protocol.
This is an abstract class. The library provides a concrete implementation under
VoiceClient
.This class allows you to implement a protocol to allow for an external method of sending voice, such as Lavalink or a native library implementation.
These classes are passed to
abc.Connectable.connect()
.- Parameters:
client (
Client
) – The client (or its subclasses) that started the connection request.channel (
abc.Connectable
) – The voice channel that is being connected to.
- await on_voice_state_update(data)
This function is a coroutine.
An abstract method that is called when the client’s voice state has changed. This corresponds to
VOICE_STATE_UPDATE
.- Parameters:
data (
dict
) –The raw voice state payload.
- await on_voice_server_update(data)
This function is a coroutine.
An abstract method that is called when initially connecting to voice. This corresponds to
VOICE_SERVER_UPDATE
.- Parameters:
data (
dict
) –The raw voice server update payload.
- await connect(*, timeout, reconnect)
This function is a coroutine.
An abstract method called when the client initiates the connection request.
When a connection is requested initially, the library calls the constructor under
__init__
and then callsconnect()
. Ifconnect()
fails at some point thendisconnect()
is called.Within this method, to start the voice connection flow it is recommended to use
Guild.change_voice_state()
to start the flow. After which,on_voice_server_update()
andon_voice_state_update()
will be called. The order that these two are called is unspecified.
- await disconnect(*, force)
This function is a coroutine.
An abstract method called when the client terminates the connection.
See
cleanup()
.- Parameters:
force (
bool
) – Whether the disconnection was forced.
- cleanup()
This method must be called to ensure proper clean-up during a disconnect.
It is advisable to call this from within
disconnect()
when you are completely done with the voice protocol instance.This method removes it from the internal state cache that keeps track of currently alive voice clients. Failure to clean-up will cause subsequent connections to report that it’s still connected.
AudioSource
- class discord.AudioSource
Bases:
object
Represents an audio stream.
The audio stream can be Opus encoded or not, however if the audio stream is not Opus encoded then the audio format must be 16-bit 48KHz stereo PCM.
Warning
The audio source reads are done in a separate thread.
- read()
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty bytes-like object 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:
PCMAudio
- class discord.PCMAudio(stream)
Bases:
AudioSource
Represents raw 16-bit 48KHz stereo PCM audio source.
- read()
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty bytes-like object 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:
FFmpegAudio
- defcleanup
- class discord.FFmpegAudio(source, *, executable='ffmpeg', args, **subprocess_kwargs)
Bases:
AudioSource
Represents an FFmpeg (or AVConv) based AudioSource.
User created AudioSources using FFmpeg differently from how
FFmpegPCMAudio
andFFmpegOpusAudio
work should subclass this.Added in version 1.3.
FFmpegPCMAudio
- class discord.FFmpegPCMAudio(source, *, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)
Bases:
FFmpegAudio
An audio source from FFmpeg (or AVConv).
This launches a sub-process to a specific input file given.
Warning
You must have the ffmpeg or avconv executable in your path environment variable in order for this to work.
- Parameters:
source (Union[
str
,io.BufferedIOBase
]) – The input that ffmpeg will take and convert to PCM bytes. Ifpipe
isTrue
then this is a file-like object that is passed to the stdin of ffmpeg.executable (
str
) – The executable name (and path) to use. Defaults toffmpeg
.pipe (
bool
) – IfTrue
, denotes thatsource
parameter will be passed to the stdin of ffmpeg. Defaults toFalse
.stderr (Optional[file object]) – A file-like object to pass to the Popen constructor. Could also be an instance of
subprocess.PIPE
.before_options (Optional[
str
]) – Extra command line arguments to pass to ffmpeg before the-i
flag.options (Optional[
str
]) – Extra command line arguments to pass to ffmpeg after the-i
flag.
- Raises:
ClientException – The subprocess failed to be created.
- read()
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty bytes-like object 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:
FFmpegOpusAudio
- asyncfrom_probe
- defis_opus
- asyncprobe
- defread
- class discord.FFmpegOpusAudio(source, *, bitrate=128, codec=None, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)
Bases:
FFmpegAudio
An audio source from FFmpeg (or AVConv).
This launches a sub-process to a specific input file given. However, rather than producing PCM packets like
FFmpegPCMAudio
does that need to be encoded to Opus, this class produces Opus packets, skipping the encoding step done by the library.Alternatively, instead of instantiating this class directly, you can use
FFmpegOpusAudio.from_probe()
to probe for bitrate and codec information. This can be used to opportunistically skip pointless re-encoding of existing Opus audio data for a boost in performance at the cost of a short initial delay to gather the information. The same can be achieved by passingcopy
to thecodec
parameter, but only if you know that the input source is Opus encoded beforehand.Added in version 1.3.
Warning
You must have the ffmpeg or avconv executable in your path environment variable in order for this to work.
- Parameters:
source (Union[
str
,io.BufferedIOBase
]) – The input that ffmpeg will take and convert to Opus bytes. Ifpipe
isTrue
then this is a file-like object that is passed to the stdin of ffmpeg.bitrate (
int
) – The bitrate in kbps to encode the output to. Defaults to128
.codec (Optional[
str
]) –The codec to use to encode the audio data. Normally this would be just
libopus
, but is used byFFmpegOpusAudio.from_probe()
to opportunistically skip pointlessly re-encoding Opus audio data by passingcopy
as the codec value. Any values other thancopy
,opus
, orlibopus
will be consideredlibopus
. Defaults tolibopus
.Warning
Do not provide this parameter unless you are certain that the audio input is already Opus encoded. For typical use
FFmpegOpusAudio.from_probe()
should be used to determine the proper value for this parameter.executable (
str
) – The executable name (and path) to use. Defaults toffmpeg
.pipe (
bool
) – IfTrue
, denotes thatsource
parameter will be passed to the stdin of ffmpeg. Defaults toFalse
.stderr (Optional[file object]) – A file-like object to pass to the Popen constructor. Could also be an instance of
subprocess.PIPE
.before_options (Optional[
str
]) – Extra command line arguments to pass to ffmpeg before the-i
flag.options (Optional[
str
]) – Extra command line arguments to pass to ffmpeg after the-i
flag.
- Raises:
ClientException – The subprocess failed to be created.
- classmethod await from_probe(source, *, method=None, **kwargs)
This function is a coroutine.
A factory method that creates a
FFmpegOpusAudio
after probing the input source for audio codec and bitrate information.Examples
Use this function to create an
FFmpegOpusAudio
instance instead of the constructor:source = await discord.FFmpegOpusAudio.from_probe("song.webm") voice_client.play(source)
If you are on Windows and don’t have ffprobe installed, use the
fallback
method to probe using ffmpeg instead:source = await discord.FFmpegOpusAudio.from_probe("song.webm", method='fallback') voice_client.play(source)
Using a custom method of determining codec and bitrate:
def custom_probe(source, executable): # some analysis code here return codec, bitrate source = await discord.FFmpegOpusAudio.from_probe("song.webm", method=custom_probe) voice_client.play(source)
- Parameters:
source – Identical to the
source
parameter for the constructor.method (Optional[Union[
str
, Callable[str
,str
]]]) – The probing method used to determine bitrate and codec information. As a string, valid values arenative
to use ffprobe (or avprobe) andfallback
to use ffmpeg (or avconv). As a callable, it must take two string arguments,source
andexecutable
. Both parameters are the same values passed to this factory function.executable
will default toffmpeg
if not provided as a keyword argument.kwargs – The remaining parameters to be passed to the
FFmpegOpusAudio
constructor, excludingbitrate
andcodec
.
- Raises:
AttributeError – Invalid probe method, must be
'native'
or'fallback'
.TypeError – Invalid value for
probe
parameter, must bestr
or a callable.
- Returns:
An instance of this class.
- Return type:
- classmethod await probe(source, *, method=None, executable=None)
This function is a coroutine.
Probes the input source for bitrate and codec information.
- Parameters:
source – Identical to the
source
parameter forFFmpegOpusAudio
.method – Identical to the
method
parameter forFFmpegOpusAudio.from_probe()
.executable (
str
) – Identical to theexecutable
parameter forFFmpegOpusAudio
.
- Raises:
AttributeError – Invalid probe method, must be
'native'
or'fallback'
.TypeError – Invalid value for
probe
parameter, must bestr
or a callable.
- Returns:
A 2-tuple with the codec and bitrate of the input source.
- Return type:
- read()
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty bytes-like object 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:
PCMVolumeTransformer
- class discord.PCMVolumeTransformer(original, volume=1.0)
Bases:
AudioSource
Transforms a previous
AudioSource
to have volume controls.This does not work on audio sources that have
AudioSource.is_opus()
set toTrue
.- Parameters:
original (
AudioSource
) – The original AudioSource to transform.volume (
float
) – The initial volume to set it to. Seevolume
for more info.
- Raises:
TypeError – Not an audio source.
ClientException – The audio source is opus encoded.
- cleanup()
Called when clean-up is needed to be done.
Useful for clearing buffer data or processes after it is done playing audio.
- read()
Reads 20ms worth of audio.
Subclasses must implement this.
If the audio is complete, then returning an empty bytes-like object 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:
Opus Library
- discord.opus.load_opus(name)
Loads the libopus shared library for use with voice.
If this function is not called then the library uses the function
ctypes.util.find_library()
and then loads that one if available.Not loading a library and attempting to use PCM based AudioSources will lead to voice not working.
This function propagates the exceptions thrown.
Warning
The bitness of the library must match the bitness of your python interpreter. If the library is 64-bit then your python interpreter must be 64-bit as well. Usually if there’s a mismatch in bitness then the load will throw an exception.
Note
On Windows, this function should not need to be called as the binaries are automatically loaded.
Note
On Windows, the .dll extension is not necessary. However, on Linux the full extension is required to load the library, e.g.
libopus.so.1
. On Linux however,ctypes.util.find_library()
will usually find the library automatically without you having to call this.- Parameters:
name (
str
) – The filename of the shared library.
- discord.opus.is_loaded()
Function to check if opus lib is successfully loaded either via the
ctypes.util.find_library()
call ofload_opus()
.This must return
True
for voice to work.- Returns:
Indicates if the opus library has been loaded.
- Return type: