Struct songbird::Songbird

pub struct Songbird { /* fields omitted */ }

A shard-aware struct responsible for managing Calls.

This manager transparently maps guild state and a source of shard information into individual calls, and forwards state updates which affect call state.

Implementations

impl Songbird

pub fn serenity() -> Arc<Self>

Create a new Songbird instance for serenity.

This must be registered after creation.

pub fn twilight<U>(cluster: Cluster, shard_count: u64, user_id: U) -> Arc<Self> where
    U: Into<UserId>, 

Create a new Songbird instance for twilight.

Twilight handlers do not need to be registered, but users are responsible for passing in any events using process.

pub fn initialise_client_data<U: Into<UserId>>(
    &self,
    shard_count: u64,
    user_id: U
)

Set the bot's user, and the number of shards in use.

If this struct is already initialised (e.g., from ::twilight), or a previous call, then this function is a no-op.

pub fn get<G: Into<GuildId>>(&self, guild_id: G) -> Option<Arc<Mutex<Call>>>

Retrieves a Call for the given guild, if one already exists.

pub fn get_or_insert(&self, guild_id: GuildId) -> Arc<Mutex<Call>>

Retrieves a Call for the given guild, creating a new one if none is found.

This will not join any calls, or cause connection state to change.

pub async fn join<C, G>(
    &self,
    guild_id: G,
    channel_id: C
) -> (Arc<Mutex<Call>>, JoinResult<()>) where
    C: Into<ChannelId>,
    G: Into<GuildId>, 

Connects to a target by retrieving its relevant Call and connecting, or creating the handler if required.

This can also switch to the given channel, if a handler already exists for the target and the current connected channel is not equal to the given channel.

The provided channel ID is used as a connection target. The channel must be in the provided guild. This is not checked by the library, and will result in an error. If there is already a connected handler for the guild, and the provided channel is different from the channel that the connection is already connected to, then the handler will switch the connection to the provided channel.

If you only need to retrieve the handler for a target, then use get.

Twilight users should read the caveats mentioned in process.

pub async fn join_gateway<C, G>(
    &self,
    guild_id: G,
    channel_id: C
) -> (Arc<Mutex<Call>>, JoinResult<ConnectionInfo>) where
    C: Into<ChannelId>,
    G: Into<GuildId>, 

Partially connects to a target by retrieving its relevant Call and connecting, or creating the handler if required.

This method returns the handle and the connection info needed for other libraries or drivers, such as lavalink, and does not actually start or run a voice call.

pub async fn leave<G: Into<GuildId>>(&self, guild_id: G) -> JoinResult<()>

Retrieves the handler for the given target and leaves the associated voice channel, if connected.

This will not drop the handler, and will preserve it and its settings.

This is a wrapper around getting a handler and calling leave on it.

pub async fn remove<G: Into<GuildId>>(&self, guild_id: G) -> JoinResult<()>

Retrieves the Call for the given target and leaves the associated voice channel, if connected.

The handler is then dropped, removing settings for the target.

An Err(...) value implies that the gateway could not be contacted, and that leaving should be attempted again later (i.e., after reconnect).

impl Songbird

pub async fn process(&self, event: &TwilightEvent)

Handle events received on the cluster.

When using twilight, you are required to call this with all inbound (voice) events, i.e., at least VoiceStateUpdates and VoiceServerUpdates.

Users must ensure that calls to this function happen on a separate task to any calls to join, join_gateway. The simplest way to ensure this is to tokio::spawn any command invocation.

Returned futures generally require the inner Call to be updated via this function, and will deadlock if event processing is not carried out on another spawned task.

impl Songbird

pub fn set_config(&self, new_config: Config)

Sets a shared configuration for all drivers created from this manager.

Changes made here will apply to new Call and Driver instances only.

Requires the "driver" feature.

Trait Implementations

impl Debug for Songbird

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

Formats the value using the given formatter.

impl VoiceGatewayManager for Songbird

fn initialise<'life0, 'async_trait>(
    &'life0 self,
    shard_count: u64,
    user_id: SerenityUser
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Performs initial setup at the start of a connection to Discord.

fn register_shard<'life0, 'async_trait>(
    &'life0 self,
    shard_id: u64,
    sender: Sender<InterMessage>
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Handler fired in response to a Ready event.

fn deregister_shard<'life0, 'async_trait>(
    &'life0 self,
    shard_id: u64
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Handler fired in response to a disconnect, reconnection, or rebalance.

fn server_update<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    guild_id: SerenityGuild,
    endpoint: &'life1 Option<String>,
    token: &'life2 str
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Handler for VOICE_SERVER_UPDATE messages.

fn state_update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    guild_id: SerenityGuild,
    voice_state: &'life1 VoiceState
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Handler for VOICE_STATE_UPDATE messages.