Struct serenity::voice::Handler

pub struct Handler {
    pub channel_id: Option<ChannelId>,
    pub endpoint: Option<String>,
    pub guild_id: GuildId,
    pub self_deaf: bool,
    pub self_mute: bool,
    pub session_id: Option<String>,
    pub token: Option<String>,
    pub user_id: UserId,
    // some fields omitted
}

The handler is responsible for "handling" a single voice connection, acting as a clean API above the inner connection.

Look into the Manager for a slightly higher-level interface for managing the existence of handlers.

Note: You should not manually mutate any struct fields. You should only read them. Use methods to mutate them.

Examples

Assuming that you already have a Manager, most likely retrieved via a Shard, you can join a guild's voice channel and deafen yourself like so:

// assuming a `manager` has already been bound, hopefully retrieved through
// a websocket's connection.
use serenity::model::{ChannelId, GuildId};

let guild_id = GuildId(81384788765712384);
let channel_id = ChannelId(85482585546833920);

let handler = manager.join(Some(guild_id), channel_id);
handler.deafen(true);

Fields

channel_id: Option<ChannelId>

The ChannelId to be connected to, if any.

Note: This must not be manually mutated. Call switch_to to mutate this value.

endpoint: Option<String>

The voice server endpoint.

guild_id: GuildId

The Id of the guild to be connected to.

self_deaf: bool

Whether the current handler is set to deafen voice connections.

Note: This must not be manually mutated. Call deafen to mutate this value.

self_mute: bool

Whether the current handler is set to mute voice connections.

Note: This must not be manually mutated. Call mute to mutate this value.

session_id: Option<String>

The session Id of the current voice connection, if any.

Note: This should be set through an update_state call.

token: Option<String>

The token of the current voice connection, if any.

Note: This should be set through an update_server call.

user_id: UserId

The Id of the current user.

This is configured via new or standalone.

Implementations

impl Handler

pub fn standalone(guild_id: GuildId, user_id: UserId) -> Self

Creates a new, standalone Handler which is not connected to the primary WebSocket to the Gateway.

Actions such as muting, deafening, and switching channels will not function through this Handler and must be done through some other method, as the values will only be internally updated.

For most use cases you do not want this. Only use it if you are using the voice component standalone from the rest of the library.

pub fn connect(&mut self) -> bool

Connects to the voice channel if the following are present:

• endpoint
• session_id
• token

If they are all present, then true is returned. Otherwise, false is.

This will automatically be called by update_server or update_state when all three values become present.

pub fn deafen(&mut self, deaf: bool)

Sets whether the current connection to be deafened.

If there is no live voice connection, then this only acts as a settings update for future connections.

Note: Unlike in the official client, you can be deafened while not being muted.

Note: If the Handler was created via standalone, then this will only update whether the connection is internally deafened.

pub fn join(&mut self, channel_id: ChannelId)

Connect - or switch - to the given voice channel by its Id.

pub fn leave(&mut self)

Leaves the current voice channel, disconnecting from it.

This does not forget settings, like whether to be self-deafened or self-muted.

Note: If the Handler was created via standalone, then this will only update whether the connection is internally connected to a voice channel.

pub fn listen(&mut self, receiver: Option<Box<dyn AudioReceiver>>)

Sets a receiver, i.e. a way to receive audio. Most use cases for bots do not require this.

The receiver argument can be thought of as an "optional Option". You can pass in just a boxed receiver, and do not need to specify Some.

Pass None to drop the current receiver, if one exists.

pub fn mute(&mut self, mute: bool)

Sets whether the current connection is to be muted.

If there is no live voice connection, then this only acts as a settings update for future connections.

Note: If the Handler was created via standalone, then this will only update whether the connection is internally muted.

pub fn play(&mut self, source: Box<dyn AudioSource>)

Plays audio from a source.

This can be a source created via voice::ffmpeg or voice::ytdl.

pub fn play_returning(&mut self, source: Box<dyn AudioSource>) -> LockedAudio

Plays audio from a source, returning the locked audio source.

pub fn play_only(&mut self, source: Box<dyn AudioSource>) -> LockedAudio

Plays audio from a source.

Unlike play or play_returning, this stops all other sources attached to the channel.

pub fn set_bitrate(&mut self, bitrate: Bitrate)

Sets the bitrate for encoding Opus packets sent along the channel being managed.

The default rate is 128 kbps. Sensible values range between Bits(512) and Bits(512_000) bits per second. Alternatively, Auto and Max remain available.

pub fn stop(&mut self)

Stops playing audio from a source, if one is set.

pub fn switch_to(&mut self, channel_id: ChannelId)

Switches the current connected voice channel to the given channel_id.

This has 3 separate behaviors:

• if the given channel_id is equivalent to the current connected channel_id, then do nothing;
• if the given channel_id is not equivalent to the current connected channel_id, then switch to the given channel_id;
• if not currently connected to a voice channel, connect to the given one.

If you are dealing with switching from one group to another, then open another handler, and optionally drop this one via Manager::remove.

Note: The given channel_id, if in a guild, must be in the current handler's associated guild.

Note: If the Handler was created via standalone, then this will only update whether the connection is internally switched to a different channel.

pub fn update_server(&mut self, endpoint: &Option<String>, token: &str)

Updates the voice server data.

You should only need to use this if you initialized the Handler via standalone.

Refer to the documentation for connect for when this will automatically connect to a voice channel.

pub fn update_state(&mut self, voice_state: &VoiceState)

Updates the internal voice state of the current user.

You should only need to use this if you initialized the Handler via standalone.

refer to the documentation for connect for when this will automatically connect to a voice channel.

Trait Implementations

impl Clone for Handler

fn clone(&self) -> Handler

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Handler

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Drop for Handler

fn drop(&mut self)

Leaves the current connected voice channel, if connected to one, and forgets all configurations relevant to this Handler.