Voice Related¶

Objects¶

Attributes

average_latency
channel
endpoint
guild
latency
mode
privacy_code
secret_key
session_id
source
ssrc
timeout
token
user

Methods

asyncdisconnect
defelapsed
defis_connected
defis_dave_connection
defis_paused
defis_playing
defis_recording
defis_speaking
asyncmove_to
defpause
defplay
defresume
defsend_audio_packet
defstart_listening
defstart_recording
defstop
defstop_listening
defstop_recording

class discord.voice.VoiceClient(client, channel)[source]¶

Represents a Discord voice connection.

You do not create these, you typically get them from e.g. VoiceChannel.connect().

session_id¶

The voice connection session ID.

Type:: str

token¶

The voice connection token.

Type:: str

endpoint¶

The endpoint we are connecting to.

Type:: str

channel¶

The channel we are connected to.

Type:: Union[VoiceChannel, StageChannel]

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. using FFmpegOpusAudio) or the library will not be able ot transmit audio.

Parameters:

client (Client)
channel (Connectable)

property guild: Guild¶: Returns the guild the channel we’re connecting to is bound to.

property user: ClientUser¶: The user connected to voice (i.e. ourselves)

property session_id: str | None¶: The session ID of the current voice call.

property token: str | None¶: The token of the voice connection. You should not share this.

property endpoint: str | None¶: The endpoint where the client is connected.

property ssrc: int¶: The SSRC of the current user in the voice call.

property mode: Literal['xsalsa20_poly1305_lite', 'xsalsa20_poly1305_suffix', 'xsalsa20_poly1305', 'aead_xchacha20_poly1305_rtpsize']¶: The encryption / decryption mode the voice client is currently using.

property secret_key: list[int]¶: Returns the secret key of the current connected voice call.

property timeout: float¶: The amount of ms the client waits before killing connect attempts.

is_dave_connection()[source]¶

Whether the voice client is connected to a DAVE call.

Return type:: bool

property latency: float¶

Latency between a HEARTBEAT and a HEARBEAT_ACK in seconds.

This chould be referred to as the Discord Voice WebSocket latency and is and analogue of user’s voice latencies as seen in the Discord client.

Added in version 1.4.

property average_latency: float¶: Average of most recent 20 HEARBEAT latencies in seconds.

Added in version 1.4.

property privacy_code: str | None¶: Returns the current voice session’s privacy code, only available if the call has upgraded to use the DAVE protocol

await disconnect(*, force=False)[source]¶

This function is a coroutine.

Disconnects this voice client from voice.

Parameters:: force (bool)
Return type:: None

await move_to(channel, *, timeout=30.0)[source]¶

This function is a coroutine.

moves you to a different voice channel.

Parameters:

channel (Snowflake | None) – The channel to move to. If this is None, it is an equivalent of calling disconnect().
timeout (float | None) – The maximum time in seconds to wait for the channel move to be completed, defaults to 30. If it is None, then there is no timeout.

Raises:

asyncio.TimeoutError – Waiting for channel move timed out.

Return type:

None

is_connected()[source]¶

Whether the voice client is connected to voice.

Return type:: bool

is_playing()[source]¶

INdicates if we’re playing audio.

Return type:: bool

is_paused()[source]¶

Indicates if we’re playing audio, but if we’re paused.

Return type:: bool

play(source, *, after=None, application='audio', bitrate=128, fec=True, expected_packet_loss=0.15, bandwidth='full', signal_type='auto', wait_finish=False)[source]¶

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 | None], Any] | None) – 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.
application (Literal['audio', 'voip', 'lowdelay']) – The intended application encoder application type. Must be one of audio, voip, or lowdelay. Defaults to audio.
bitrate (int) – The encoder’s bitrate. Must be between 16 and 512. Defaults to 128.
fec (bool) – Configures the encoder’s use of inband forward error correction (fec). Defaults to True.
expected_packet_loss (float) – How much packet loss percentage is expected from the encoder. This requires fec to be set to True. Defaults to 0.15.
bandwidth (Literal['narrow', 'medium', 'wide', 'superwide', 'full']) – The encoder’s bandpass. Must be one of narrow, medium, wide, superwide, or full. Defaults to full.
signal_type (Literal['auto', 'voice', 'music']) – The type of signal being encoded. Must be one of auto, voice, music. Defaults to auto.
wait_finish (bool) –
If True, then an awaitable is returned that waits for the audio source to be exhausted, and will return an optional exception that could have been raised.

If False, None is returned and the function does not block.

Added in version 2.5.

Raises:

ClientException – Already playing audio, or not connected to voice.
TypeError – Source is not a AudioSource, or after is not a callable.
OpusNotLoaded – Source is not opus encoded and opus is not loaded.

Return type:

None | Future[None]

stop()[source]¶

Stops playing audio, if applicable.

Return type:: None

pause()[source]¶

Pauses the audio playing.

Return type:: None

resume()[source]¶

Resumes the audio playing.

Return type:: None

property source: AudioSource | None¶

The audio source being player, if playing.

This property can also be used to change the audio source currently being played.

send_audio_packet(data, *, encode=True)[source]¶

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 if data should be encoded into Opus.

Raises:

ClientException – You are not connected.
opus.OpusError – Encoding the data failed.

Return type:

None

elapsed()[source]¶

Returns the elapsed time of the playing audio.

Return type:: timedelta

start_recording(sink, callback=None, *args, sync_start=...)[source]¶

Start recording the audio from the current connected channel to the provided sink.

Added in version 2.0.

Warning

Recording may not work as expected due to the new DAVE (End-to-End Encryption) for voice calls.

Parameters:

sink (Sink) – A Sink in which all audio packets will be processed in.
callback (Callable[[Exception | None], Any] | None) –
A function which is called after the bot has stopped recording. This must take exactly one positonal(-only) parameter, exception, which is the exception that was raised during the recording of the Sink.

Changed in version 2.7: This parameter is now optional, and must take exactly one parameter, exception.
*args (Any) –
The arguments to pass to the callback coroutine.

Deprecated since version 2.7: Passing custom arguments to the callback is now deprecated and ignored.
sync_start (bool) –
If True, the recordings of subsequent users will start with silence. This is useful for recording audio just as it was heard.

Deprecated since version 2.7: This parameter is now ignored and deprecated.

Raises:

RecordingException – Not connected to a voice channel
TypeError – You did not provide a Sink object.

Return type:

None

start_listening(sink, callback=None, *args, sync_start=...)¶

Start recording the audio from the current connected channel to the provided sink.

Added in version 2.0.

Warning

Recording may not work as expected due to the new DAVE (End-to-End Encryption) for voice calls.

Parameters:

sink (Sink) – A Sink in which all audio packets will be processed in.
callback (Callable[[Exception | None], Any] | None) –
A function which is called after the bot has stopped recording. This must take exactly one positonal(-only) parameter, exception, which is the exception that was raised during the recording of the Sink.

Changed in version 2.7: This parameter is now optional, and must take exactly one parameter, exception.
*args (Any) –
The arguments to pass to the callback coroutine.

Deprecated since version 2.7: Passing custom arguments to the callback is now deprecated and ignored.
sync_start (bool) –
If True, the recordings of subsequent users will start with silence. This is useful for recording audio just as it was heard.

Deprecated since version 2.7: This parameter is now ignored and deprecated.

Raises:

RecordingException – Not connected to a voice channel
TypeError – You did not provide a Sink object.

Return type:

None

stop_recording()[source]¶

Stops the recording of the provided sink, or all recording sinks.

Added in version 2.0.

Raises:: RecordingException – You are not recording.
Return type:: None

stop_listening()¶

Stops the recording of the provided sink, or all recording sinks.

Added in version 2.0.

Raises:: RecordingException – You are not recording.
Return type:: None

is_recording()[source]¶

Whether the current client is recording in any sink.

Return type:: bool

is_speaking(member)[source]¶

Whether a user is speaking.

This is an approximate calculation and may have outdated or wrong data.

If the member speaking status has not been yet saved, it returns None.

Added in version 2.7.

Parameters:: member (Member | User)
Return type:: bool | None

Methods

defcleanup
asyncconnect
asyncdisconnect
asyncon_voice_server_update
asyncon_voice_state_update

class discord.voice.VoiceProtocol(client, channel)[source]¶

A class that represents the Discord voice protocol.

Warning

If you are an end user, you should not construct this manually but instead take it from the return type in abc.Connectable.connect. The parameters and methods being documented here is so third party libraries can refer to it when implementing their own VoiceProtocol types.

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 (TypeVar(ClientT, bound= Client, covariant=True)) – The client (or its subclasses) that started the connection request.
channel (Connectable) – The voice channel that is being connected to.

await on_voice_state_update(data)[source]¶

This function is a coroutine.

A method called when the client’s voice state has changed. This corresponds to the VOICE_STATE_UPDATE event.

Parameters:

data (RawVoiceStateUpdateEvent) –

The voice state payload.

Changed in version 2.7: This now gets passed a RawVoiceStateUpdateEvent object instead of a dict, but accessing keys via data[key] or data.get(key) is still supported, but deprecated.

Return type:

None

await on_voice_server_update(data)[source]¶

This function is a coroutine.

A method called when the client’s intially connecting to voice. This corresponds to the VOICE_SERVER_UPDATE event.

Parameters:

data (RawVoiceServerUpdateEvent) –

The voice server payload.

Changed in version 2.7: This now gets passed a RawVoiceServerUpdateEvent object instead of a dict, but accessing keys via data[key] or data.get(key) is still supported, but deprecated.

Return type:

None

await connect(*, timeout, reconnect)[source]¶

This function is a coroutine.

A method called to initialise the connection.

The library initialises this class and calls __init__, and then connect() when attempting to start a connection to the voice. If an error ocurrs, it calls disconnect(), so if you need to implement any cleanup, you should manually call it in disconnect() as the library will not do so for you.

Within this method, to start the voice connection flow, it is recommened to use Guild.change_voice_state() to start the flow. After which on_voice_server_update() and on_voice_state_update() will be called, although this could vary and cause unexpected behaviour, but that falls under Discord’s way of handling the voice connection.

Parameters:

timeout (float) – The timeout for the connection.
reconnect (bool) – Whether reconnection is expected.

Return type:

None

await disconnect(*, force)[source]¶

This function is a coroutine.

A method called to terminate the voice connection.

This can be either called manually when forcing a disconnection, or when an exception in connect() ocurrs.

It is recommended to call cleanup() here.

Parameters:: force (bool) – Whether the disconnection was forced.
Return type:: None

cleanup()[source]¶

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 the currently alive voice clients. Failure to clean-up will cause subsequent connections to report that it’s still connected.

The library will NOT automatically call this for you, unlike connect() and disconnect().

Return type:: None

Methods

defcleanup
defis_opus
defread

class discord.AudioSource[source]¶

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()[source]¶

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

is_opus()[source]¶

Checks if the audio source is already encoded in Opus.

Return type:: bool

cleanup()[source]¶

Called when clean-up is needed to be done.

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

Return type:: None

Attributes

stream

Methods

defread

class discord.PCMAudio(stream)[source]¶

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

stream¶

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

Type:: file object

Parameters:: stream (BufferedIOBase)

read()[source]¶

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.

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

Methods

defcleanup

class discord.FFmpegAudio(source, *, executable='ffmpeg', args, **subprocess_kwargs)[source]¶

Represents an FFmpeg (or AVConv) based AudioSource.

User created AudioSources using FFmpeg differently from how FFmpegPCMAudio and FFmpegOpusAudio work should subclass this.

Added in version 1.3.

Parameters:

source (str | BufferedIOBase)
executable (str)
args (Any)
subprocess_kwargs (Any)

cleanup()[source]¶

Called when clean-up is needed to be done.

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

Return type:: None

Methods

defis_opus
defread

class discord.FFmpegPCMAudio(source, *, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)[source]¶

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 (str | BufferedIOBase) – The input that ffmpeg will take and convert to PCM bytes. If pipe is True 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 to ffmpeg.

Warning

Since this class spawns a subprocess, care should be taken to not pass in an arbitrary executable name when using this parameter.
pipe (bool) – If True, denotes that source parameter will be passed to the stdin of ffmpeg. Defaults to False.
stderr (IO[bytes] | None) – A file-like object to pass to the Popen constructor.
before_options (str | None) – Extra command line arguments to pass to ffmpeg before the -i flag.
options (str | None) – Extra command line arguments to pass to ffmpeg after the -i flag.

Raises:

ClientException – The subprocess failed to be created.

read()[source]¶

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.

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

is_opus()[source]¶

Checks if the audio source is already encoded in Opus.

Return type:: bool

Methods

asyncfrom_probe
defis_opus
asyncprobe
defread

class discord.FFmpegOpusAudio(source, *, bitrate=None, codec=None, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None)[source]¶

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 passing copy to the codec 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 (str | BufferedIOBase) – The input that ffmpeg will take and convert to Opus bytes. If pipe is True then this is a file-like object that is passed to the stdin of ffmpeg.
bitrate (int | None) – The bitrate in kbps to encode the output to. Defaults to 128.
codec (str | None) –
The codec to use to encode the audio data. Normally this would be just libopus, but is used by FFmpegOpusAudio.from_probe() to opportunistically skip pointlessly re-encoding Opus audio data by passing copy as the codec value. Any values other than copy, opus, or libopus will be considered libopus. Defaults to libopus.

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 to ffmpeg.
pipe (bool) – If True, denotes that source parameter will be passed to the stdin of ffmpeg. Defaults to False.
stderr (IO[bytes] | None) – A file-like object to pass to the Popen constructor.
before_options (str | None) – Extra command line arguments to pass to ffmpeg before the -i flag.
options (str | None) – 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)[source]¶

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 (str) – Identical to the source parameter for the constructor.
method (str | Callable[[str, str], tuple[str | None, int | None]] | None) – The probing method used to determine bitrate and codec information. As a string, valid values are native to use ffprobe (or avprobe) and fallback to use ffmpeg (or avconv). As a callable, it must take two string arguments, source and executable. Both parameters are the same values passed to this factory function. executable will default to ffmpeg if not provided as a keyword argument.
**kwargs (Any) – The remaining parameters to be passed to the FFmpegOpusAudio constructor, excluding bitrate and codec.

Raises:

AttributeError – Invalid probe method, must be 'native' or 'fallback'.
TypeError – Invalid value for probe parameter, must be str or a callable.

Returns:

An instance of this class.

Return type:

Self

classmethod await probe(source, *, method=None, executable=None)[source]¶

This function is a coroutine.

Probes the input source for bitrate and codec information.

Parameters:

source (str) – Identical to the source parameter for FFmpegOpusAudio.
method (str | Callable[[str, str], tuple[str | None, int | None]] | None) – Identical to the method parameter for FFmpegOpusAudio.from_probe().
executable (str | None) – Identical to the executable parameter for FFmpegOpusAudio.

Returns:

A 2-tuple with the codec and bitrate of the input source.

Return type:

tuple[str | None, int | None]

Raises:

AttributeError – Invalid probe method, must be 'native' or 'fallback'.
TypeError – Invalid value for probe parameter, must be str or a callable.

read()[source]¶

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.

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

is_opus()[source]¶

Checks if the audio source is already encoded in Opus.

Return type:: bool

Attributes

volume

Methods

defcleanup
defread

class discord.PCMVolumeTransformer(original, volume=1.0)[source]¶

Transforms a previous AudioSource to have volume controls.

This does not work on audio sources that have AudioSource.is_opus() set to True.

Parameters:

original (TypeVar(AT, bound= AudioSource)) – The original AudioSource to transform.
volume (float) – The initial volume to set it to. See volume for more info.

Raises:

TypeError – Not an audio source.
ClientException – The audio source is opus encoded.

property volume: float¶: Retrieves or sets the volume as a floating point percentage (e.g. 1.0 for 100%).

cleanup()[source]¶

Called when clean-up is needed to be done.

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

Return type:: None

read()[source]¶

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.

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

Opus Library¶

discord.opus.load_opus(name)[source]¶

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.
Return type:: None

discord.opus.is_loaded()[source]¶

Function to check if opus lib is successfully loaded either via the ctypes.util.find_library() call of load_opus().

This must return True for voice to work.

Returns:: Indicates if the opus library has been loaded.
Return type:: bool