Skip to main content

​
VoiceClient

Represents a Discord voice connection. You typically get these from VoiceChannel.connect().

​
Attributes

​
session_id
str
The voice connection session ID.
​
token
str
The voice connection token.
​
endpoint
str
The endpoint we are connecting to.
​
channel
abc.Connectable
The voice channel connected to.
​
loop
asyncio.AbstractEventLoop
The event loop that the voice client is running on.
​
guild
Guild | None
The guild we’re connected to, if applicable. (property)
​
user
ClientUser
The user connected to voice (i.e. ourselves). (property)
​
latency
float
Latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. (property)
​
average_latency
float
Average of most recent 20 HEARTBEAT latencies in seconds. (property)
​
source
AudioSource | None
The audio source being played, if playing. Can also be set to change the source. (property)
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 to transmit audio.

​
Methods

​
connect

await connect(*, timeout: float, reconnect: bool) -> None
Initiates the connection to voice.
​
timeout
float
required
The timeout for the connection.
​
reconnect
bool
required
Whether reconnection is expected.

​
disconnect

await disconnect(*, force: bool = False) -> None
Disconnects this voice client from voice.
​
force
bool
default:"False"
Whether the disconnection was forced.

​
move_to

await move_to(channel: abc.Connectable) -> None
Moves you to a different voice channel.
​
channel
abc.Connectable
required
The channel to move to. Must be a voice channel.

​
is_connected

is_connected() -> bool
Indicates if the voice client is connected to voice.

​
play

play(
    source: AudioSource,
    *,
    after: Callable[[Exception | None], Any] | None = None,
    wait_finish: bool = False
) -> None | asyncio.Future
Plays an AudioSource. The finalizer, after, is called after the source has been exhausted or an error occurred.
​
source
AudioSource
required
The audio source we’re reading from.
​
after
Callable[[Optional[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.
​
wait_finish
bool
default:"False"
If True, an awaitable will be returned, which can be used to wait for audio to stop playing. This awaitable will return an exception if raised, or None when no exception is raised.If False, None is returned and the function does not block.
Raises:
  • ClientException - Already playing audio or not connected.
  • TypeError - Source is not an AudioSource or after is not a callable.
  • OpusNotLoaded - Source is not opus encoded and opus is not loaded.

​
is_playing

is_playing() -> bool
Indicates if we’re currently playing audio.

​
is_paused

is_paused() -> bool
Indicates if we’re playing audio, but if we’re paused.

​
stop

stop() -> None
Stops playing audio.

​
pause

pause() -> None
Pauses the audio playing.

​
resume

resume() -> None
Resumes the audio playing.

​
send_audio_packet

send_audio_packet(data: bytes, *, encode: bool = True) -> None
Sends an audio packet composed of the data. You must be connected to play audio.
​
data
bytes
required
The bytes-like object denoting PCM or Opus voice data.
​
encode
bool
default:"True"
Indicates if data should be encoded into Opus.
Raises:
  • ClientException - You are not connected.
  • opus.OpusError - Encoding the data failed.

​
elapsed

elapsed() -> datetime.timedelta
Returns the elapsed time of the playing audio.

​
Recording Methods

​
start_recording

start_recording(
    sink: Sink,
    callback: Coroutine,
    *args,
    sync_start: bool = False
) -> None
The bot will begin recording audio from the current voice channel it is in.
​
sink
Sink
required
A Sink which will “store” all the audio data.
​
callback
coroutine
required
A function which is called after the bot has stopped recording.
​
*args
Args which will be passed to the callback function.
​
sync_start
bool
default:"False"
If True, the recordings of subsequent users will start with silence. This is useful for recording audio just as it was heard.
Raises:
  • RecordingException - Not connected to a voice channel.
  • RecordingException - Already recording.
  • RecordingException - Must provide a Sink object.

​
stop_recording

stop_recording() -> None
Stops the recording. Must be already recording. Raises:
  • RecordingException - Not currently recording.

​
toggle_pause

toggle_pause() -> None
Pauses or unpauses the recording. Must be already recording. Raises:
  • RecordingException - Not currently recording audio.

​
VoiceProtocol

Abstract base class for voice protocol implementations. 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.

​
Methods

​
on_voice_state_update

await on_voice_state_update(data: dict) -> None
An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.
​
data
dict
required
The raw voice state payload.

​
on_voice_server_update

await on_voice_server_update(data: dict) -> None
An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.
​
data
dict
required
The raw voice server update payload.

​
connect

await connect(*, timeout: float, reconnect: bool) -> None
An abstract method called when the client initiates the connection request.

​
disconnect

await disconnect(*, force: bool) -> None
An abstract method called when the client terminates the connection.

​
cleanup

cleanup() -> None
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us