VoiceClient

Represents a client what is joined to a voice channel.

Attributes

call_after : callable(awaitable)

A coroutine function what is awaited, when the voice clients' current audio finishes playing. By default this attribute is set to the ._play_next function of the voice client (plays the next audio at the voice clients' .queue as expected.

This attribute of the client can be modified freely. To it 2 parameters are passed:

Respective name	Type
client	`VoiceClient`
last_source	`None`, `AudioSource`

The VoiceClient also includes some other predefined function for setting as call_after:

channel_id : int

The channel's identifier where the voice client currently is.

client : Client

The voice client's owner client.

gateway : DiscordGatewayVoice

The gateway through what the voice client communicates with Discord.

guild_id : int

The guild's identifier where the voice client is.

lock : Lock

A lock used meanwhile changing the currently playing audio to not modifying it parallelly.

player : AudioPlayer

The actual player of the VoiceClient. If the voice client is not playing nor paused, then set as None.

queue : list of AudioSource

A list of the scheduled audios.

reader : None, AudioReader

Meanwhile the received audio is collected, this attribute is set to a running AudioReader.

region : VoiceRegion

The actual voice region of the voice client.

running : bool

Whether the voice client plans to reconnect and it's reader and player should not be stopped.

speaking : int

Whether the client is showed by Discord as speaking, then this attribute should is set as 1. Can be modified, with the .set_speaking, however it is always adjusted to the voice client's current playing state.

_audio_source : int

An identifier sent by Discord what should be sent back with every voice packet.

_audio_sources : dict of (int, int) items

user_id- audio_source mapping used by AudioStream-s.

_audio_streams : None, dict of (int, (AudioStream or (list of AudioStream)) items

user_id- AudioStream(s) mapping for linking AudioStream to their respective user.

_connected : bool

Whether the voice client is connected.

_connected_waiters : None | set<Future>

Waiter futures waiting for the voice client to be connected again.

_encoder : OpusEncoder

Encode not opus encoded audio data.

_endpoint : None, str

The endpoint, where the voice client sends the audio data.

_endpoint_ip : None, tuple of int

The ip version of the ._endpoint attribute.

_endpoint_port : int

The port, where the voice client should send the audio data.

_handshake_complete : Future

Used for awaiting the connecting handshake with Discord.

_ip : None | str

The ip to what the voice client's gateway connects.

_port : None, int

The port to what the voice client's gateway connects.

_preferred_volume : float

The preferred volume of the voice client. can be between 0.0 and 2.0.

_protocol : None, DatagramMergerReadProtocol

Asynchronous protocol of the voice client to communicate with it's socket.

_secret_box : None, nacl.secret.SecretBox

Data encoder of the voice client.

_sequence : int

Counter to define the sent data's sequence for Discord.

_set_speaking_task : None, Task

Synchronization task for the .set_speaking coroutine.

_socket : None, socket.socket

The socket through what the VoiceClient sends the voice data to Discord. Created by the ._create_socket method, when the client's gateway receives response after connecting. If the client leaves the voice channel, then the socket is closed and set back to None.

_timestamp : int

A timestamp identifier to tell Discord how much frames we sent to it.

_token : str

Token received by the voice client's owner client's gateway. Used to authorize the voice client.

_transport : None, _SelectorDatagramTransport

Asynchronous transport of the voice client to communicate with it's socket.

_video_source : int

An identifier sent by Discord what should be sent back with every video packet.

_video_sources : dict of (int, int) items

user_id- video_source mapping. Not used for now.

Properties

channel

Returns the voice client's channel.

Returns

channel : Channel

guild

Returns the voice client's guild.

Returns

guild : None, Guild

source

Returns the voice client's player's source if applicable.

Returns

source : None, AudioSource

voice_state

Returns the voice state of the client.

Returns

voice_state : None, VoiceState

volume

Get-set property for accessing the voice client's volume.

Can be between 0.0 and 2.0.

Methods

new(client, guild_id, channel_id)

Creates a VoiceClient. If any of the required libraries are not present, raises RuntimeError.

If the voice client was successfully created, returns a Future, what is a waiter for it's ._connect method. If connecting failed, then the future will raise TimeoutError.

Parameter	Type	Description
client	`Client`	The parent client.
guild_id	`int`	the guild's identifier, where the the client will connect to.
channel_id	`int`	The channel's identifier where the client will connect to.

Raises

RuntimeError

If PyNaCl is not loaded. If Opus is not loaded.

append(source)

Starts playing the given audio source. If the voice client is already playing, puts it on it's queue instead.

Parameter	Type	Description
source	`AudioSource`	The audio source to put on the queue.

Returns

started_playing : bool

Whether the source is started playing and not put on queue.

clear_connected()

Sets the voice client's state to be not connected.

disconnect()

Disconnects the voice client.

This method is a coroutine.

get_audio_streams()

Returns the audio streams of the voice client within a list.

Returns

streams : list of tuple(ClientUserBase, AudioStream)

Audio streams as a list of tuples of their respective listened user and stream.

is_connected()

Returns whether the voice client is connected to a Channel.

Returns

is_connected : bool

is_paused()

Returns whether the voice client is currently paused (or not playing).

Returns

is_paused : bool

is_playing()

Returns whether the voice client is currently playing audio.

Returns

is_playing : bool

join_audience()

Joins the audience in the voice client's voice channel. Only applicable for stage channels.

This method is a coroutine.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

join_speakers(...)

Requests to speak at the voice client's voice channel. Only applicable for stage channels.

This method is a coroutine.

Parameter	Type	Optional	Keyword only	Default	Description
request	`bool`			`False`	Whether the client should only request to speak.

Raises

ConnectionError

No internet connection.

DiscordException

If any exception was received from the Discord API.

listen_to(user, ...)

Creates an audio stream for the given user.

Parameter	Type	Description
user	`UserBase`	The user, who's voice will be captured.
**keyword_parameters	Keyword parameters	Additional keyword parameters.
auto_decode	`bool`	Whether the received packets should be auto decoded.
yield_decoded	`bool`	Whether the audio stream should yield encoded data.

Returns

audio_stream : AudioStream

move_to(channel)

Move the voice client to an another voice channel.

This method is a coroutine.

Parameter	Type	Description
channel	`Channel`, `int`	The channel where the voice client will move to.

Returns

moved : bool

Returns False if the voice client is already in the channel.

Raises

TypeError

If channel was not given as Channel not int.

pause()

Pauses the currently played audio if applicable.

play_next()

Skips the currently playing audio.

Familiar to .skip, but it return when the operation id done.

This method is a coroutine.

resume()

Resumes the currently stopped audio if applicable.

send_packet(packet)

Sends the given packet to Discord with the voice client's socket.

Parameter	Type	Description
packet	`bytes-like`	The packet to send.

set_connected()

Sets the voice client's state to be connected.

set_speaking(value)

A coroutine, what is used when changing the .speaking state of the voice client. By default when audio is played, the speaking state is changed to True and meanwhile not, then to False.

This method is a coroutine.

Parameter	Type
value	`int`(`0`, `1`)

Notes

Tinkering with this method is not recommended.

skip(...)

Skips the currently played audio at the given index and returns it.

Skipping nothing yields to returning None.

Parameter	Type	Optional	Default	Description
index	`int`		`0`	The index of the audio to skip. Defaults to `0`, what causes the currently playing source to skipped.

Returns

source : None, AudioSource

start()

Starts the voice client and returns a waiter than can be awaited to wait for connection.

Returns

waiter : Future<bool>

stop()

Stops the currently playing audio and clears the audio queue.

wait_connected(timeout)

Waits until the voice client is connected.

Parameter	Type	Description
timeout	`None \| float`	Timeout to apply while waiting for connection.

Returns

connected : bool

Whether the voice client connected or disconnected before timeout.

Raises

TimeoutError

_close_socket()

Closes the voice client's socket and transport if they are set.

_create_connected_waiter()

Creates a connected state waiter.

Returns

connected_waiter : Future

_create_socket(event)

Called when voice server update data is received from Discord.

If full data was received, closes the actual socket if exists and creates a new one connected to the received address.

If the voice client is already connected reconnects it, if not then marks it as connected.

This method is a coroutine.

Parameter	Type	Description
event	`VoiceServerUpdateEvent`	Voice server update event.

_disconnect(...)

Disconnects the voice client.

If you want to disconnect a voice client, then you should use .disconnect. Passing bad parameters to this method the can cause misbehaviour.

This method is a coroutine.

Parameter	Type	Optional	Default	Description
force	`bool`		`False`	Whether the voice client should disconnect only if it is not connected (for example when it is connecting).
terminate	`bool`		`True`	Whether it is an internal disconnect. If the Disconnect comes from Discord's side, then `terminate` is `False`, what means, we do not need to terminate the gateway handshake.

_kill_ghost(client, voice_state)

When a client is restarted, it might happen that it will be in still in some voice channels. At this case this function is ensured to kill the ghost connection.

This method is a coroutine.

Parameter	Type	Description
client	`Client`	The owner client of the ghost connection.
voice_state	`VoiceState`	The ghost voice client's voice state.

_link_audio_stream(stream)

Links the given AudioStream to self causing to start receiving audio.

Parameter	Type
stream	`AudioStream`

_loop_actual(self, last_source)

Repeats the last played audio if applicable.

Should be used inside of .lock to ensure that the voice client is not modified parallelly.

This function is a coroutine.

Parameter	Type	Description
self	`VoiceClient`	The respective voice client.
last_source	`None`, `AudioSource`	The audio what was played.

_loop_queue(self, last_source)

Puts the last played audio back on the voice client's queue.

Should be used inside of .lock to ensure that the voice client is not modified parallelly.

This function is a coroutine.

Parameter	Type	Description
self	`VoiceClient`	The respective voice client.
last_source	`None`, `AudioSource`	The audio what was played.

_maybe_change_voice_region()

Resets the voice region of the voice client.

Returns

changed: bool

Whether voice region changed.

_play_next(self, last_source)

Starts to play the next audio object on .queue and cancels the actual one if applicable. Should be used inside of .lock to ensure that the voice client is not modified parallelly.

This function is a coroutine.

Parameter	Type	Description
self	`VoiceClient`	The respective voice client.
last_source	`None`, `AudioSource`	The audio what was played.

_remove_audio_source(user_id)

Un-links the audio streams' source listening to the given user (id), causing the affected audio stream(s) to stop receiving audio data at the meanwhile.

Parameter	Type	Description
user_id	`int`	The respective user's id.

_remove_connected_waiter(connected_waiter)

Removes the given connected state waiter.

Parameter	Type	Description
connected_waiter	`Future`	The connection waiter to remove.

_remove_video_source(user_id)

Un-links a video stream's source.

Parameter	Type	Description
user_id	`int`	The respective user's id.

_run(...)

Connects the voice client to Discord and keeps receiving the gateway events.

This method is a coroutine.

Parameter	Type	Optional	Default	Description
waiter	`None`, `Future`		`None`	A Waiter what's result is set (or is raised to), when the voice client connects (or failed to connect).

_set_connected_waiters(result)

Sets the connection waiter's result.

Parameter	Type	Description
result	`bool`	The value to set the waiter's result to.

_start_handshake()

Requests a gateway handshake from Discord. If we get answer on it, means, we can open the socket to send audio data.

This method is a coroutine.

Raises

TimeoutError

We did not receive answer in time.

_stop_player_and_reader()

Stops the voice client's player and reader.

_terminate_handshake()

Called when connecting to Discord fails. Ensures, that everything is aborted correctly.

This method is a coroutine.

_unlink_audio_stream(audio_stream)

Un-links the given audio stream from the voice client causing it to stop receiving audio.

Parameter	Type
audio_stream	`AudioStream`

_update_audio_source(user_id, audio_source)

Updates (or adds) an user-id- audio-source relation to the voice client causing the affected audio streams to listen to their new source.

Parameter	Type	Description
user_id	`int`	The respective user's id.
audio_source	`int`	Audio source identifier of the user.

_update_video_source(user_id, video_source)

Updates (or adds) an user-id- video-source relation to the voice client.

Parameter	Type	Description
user_id	`int`	The respective user's id.
video_source	`int`	Video source identifier of the user.

del()

Stops and unallocates the resources by the voice client, if was not done already.

getattr()

Drops a rich attribute error.

repr()

Returns the voice client's representation.

VoiceClient

Attributes

Properties

channel

Returns

guild

Returns

source

Returns

voice_state

Returns

volume

Methods

__new__(client, guild_id, channel_id)

Raises

append(source)

Returns

clear_connected()

disconnect()

get_audio_streams()

Returns

is_connected()

Returns

is_paused()

Returns

is_playing()

Returns

join_audience()

Raises

join_speakers(...)

Raises

listen_to(user, ...)

Returns

move_to(channel)

Returns

Raises

pause()

play_next()

resume()

send_packet(packet)

set_connected()

set_speaking(value)

Notes

skip(...)

Returns

start()

Returns

stop()

wait_connected(timeout)

Returns

Raises

_close_socket()

_create_connected_waiter()

Returns

_create_socket(event)

_disconnect(...)

_kill_ghost(client, voice_state)

_link_audio_stream(stream)

_loop_actual(self, last_source)

_loop_queue(self, last_source)

_maybe_change_voice_region()

Returns

_play_next(self, last_source)

_remove_audio_source(user_id)

_remove_connected_waiter(connected_waiter)

_remove_video_source(user_id)

_run(...)

_set_connected_waiters(result)

_start_handshake()

Raises

_stop_player_and_reader()

_terminate_handshake()

_unlink_audio_stream(audio_stream)

_update_audio_source(user_id, audio_source)

_update_video_source(user_id, video_source)

__del__()

__getattr__()

__repr__()

new(client, guild_id, channel_id)

del()

getattr()

repr()