voice

README

Voice

Terminology

• Discord Gateway - The standard Discord Gateway users connect to and receive update events from
• Discord Voice Gateway - The Discord Voice gateway that allows voice connections to be configured
• Voice Server - What the Discord Voice Gateway allows connection to for sending of Opus voice packets over UDP
• Voice Packet - Opus encoded UDP packet that contains audio
• Application - Could be a custom Discord Client or Bot (nothing that is within this package)
• Library - Code within this package

Connection Flow

• The application would get a new *Voice instance by calling NewVoice()
• When the application wants to connect to a voice channel they would call JoinChannel() on the stored *Voice instance

---

• The library sends a Voice State Update to the Discord Gateway.
• The library waits until it receives a Voice Server Update from the Discord Gateway.
• Once a Voice Server Update event is received, a new connection is opened to the Discord Voice Gateway.

---

• The Discord Voice Gateway will first send a Hello Event which will be used to create a new *heart.PacemakerLoop and start sending heartbeats to the Discord Voice Gateway.
• Afterwards, an Identify Command or Resume Command is sent to the Discord Voice Gateway depending on whether the library is reconnecting.

---

• The Discord Voice Gateway should then respond with a Ready Event once the connection is opened, providing the required information to connect to a Voice Server.
• Using the information provided in the Ready Event, a new UDP connection is opened to the Voice Server and IP Discovery occurs.
• After IP Discovery returns the Application's external ip and port it connected to the Voice Server with, the library sends a Select Protocol Event to the Discord Voice Gateway.
• The library waits until it receives a Session Description Event from the Discord Voice Gateway.
• Once the Session Description Event is received, Speaking Events and Voice Packets can begin to be sent to the Discord Voice Gateway and Voice Server respectively.

Usage

• The application would get a new *Voice instance by calling NewVoice() and keep it stored for when it needs to open voice connections.
• When the application wants to connect to a voice channel they would call JoinChannel() on the stored *Voice instance.
• JoinChannel() will block as it follows the Connection Flow, returning an error if one occurs and a *voice.Session if it was successful.
• The application should now call (*voice.Session).Speaking() with the wanted voice flag (voicegateway.Microphone, voicegateway.Soundshare, or voicegateway.Priority).
• The application can now send Voice Packets using the (*voice.Session).Write() method which will be sent to the Voice Server. (*voice.Session) also implements io.Writer.
• When the application wants to stop sending Voice Packets they should call (*voice.Session).StopSpeaking(), then any required voice cleanup (closing streams, etc.), then (*voice.Session).Disconnect()

Examples

Check the integration tests at voice/integration_test.go.

Documentation

Overview

Package voice handles the Discord voice gateway and UDP connections, as well as managing and keeping track of multiple voice sessions.

This package abstracts the subpackage voice/voicesession and voice/udp.

Index

• Constants
• Variables
• type CloseError
  • func (e *CloseError) Error() string
  • func (e *CloseError) HasError() bool
• type Session
  • func NewSession(ses *session.Session, userID discord.UserID) *Session
  • func (s *Session) Disconnect() error
  • func (s *Session) DisconnectCtx(ctx context.Context) error
  • func (s *Session) JoinChannel(gID discord.GuildID, cID discord.ChannelID, muted, deafened bool) error
  • func (s *Session) JoinChannelCtx(ctx context.Context, gID discord.GuildID, cID discord.ChannelID, ...) error
  • func (s *Session) Speaking(flag voicegateway.SpeakingFlag) error
  • func (s *Session) StopSpeaking() error
  • func (s *Session) UpdateServer(ev *gateway.VoiceServerUpdateEvent)
  • func (s *Session) UpdateState(ev *gateway.VoiceStateUpdateEvent)
  • func (s *Session) Write(b []byte) (int, error)
  • func (s *Session) WriteCtx(ctx context.Context, b []byte) (int, error)
• type Voice
  • func NewVoice(s *state.State) *Voice
  • func NewVoiceFromToken(token string) (*Voice, error)
  • func (v *Voice) Close() error
  • func (v *Voice) GetSession(guildID discord.GuildID) (*Session, bool)
  • func (v *Voice) JoinChannel(gID discord.GuildID, cID discord.ChannelID, muted, deafened bool) (*Session, error)
  • func (v *Voice) RemoveSession(guildID discord.GuildID)

Constants

const Protocol = "xsalsa20_poly1305"

Variables

var (

	// ErrCannotSend is an error when audio is sent to a closed channel.
	ErrCannotSend = errors.New("cannot send audio to closed channel")
)

var OpusSilence = [...]byte{0xF8, 0xFF, 0xFE}

var WSTimeout = 10 * time.Second

WSTimeout is the duration to wait for a gateway operation including Session to complete before erroring out. This only applies to functions that don't take in a context already.

Types

type CloseError

type CloseError struct {
	SessionErrors map[discord.GuildID]error
	StateErr      error
}

func (*CloseError) Error

func (e *CloseError) Error() string

func (*CloseError) HasError

func (e *CloseError) HasError() bool

type Session

type Session struct {
	ErrorLog func(err error)
	// contains filtered or unexported fields
}

func NewSession

func NewSession(ses *session.Session, userID discord.UserID) *Session

func (*Session) Disconnect

func (s *Session) Disconnect() error

func (*Session) DisconnectCtx

func (s *Session) DisconnectCtx(ctx context.Context) error

func (*Session) JoinChannel

func (s *Session) JoinChannel(gID discord.GuildID, cID discord.ChannelID, muted, deafened bool) error

func (*Session) JoinChannelCtx

func (s *Session) JoinChannelCtx(ctx context.Context, gID discord.GuildID, cID discord.ChannelID, muted, deafened bool) error

func (*Session) Speaking

func (s *Session) Speaking(flag voicegateway.SpeakingFlag) error

Speaking tells Discord we're speaking. This calls (*voicegateway.Gateway).Speaking().

func (*Session) StopSpeaking

func (s *Session) StopSpeaking() error

func (*Session) UpdateServer

func (s *Session) UpdateServer(ev *gateway.VoiceServerUpdateEvent)

func (*Session) UpdateState

func (s *Session) UpdateState(ev *gateway.VoiceStateUpdateEvent)

func (*Session) Write

func (s *Session) Write(b []byte) (int, error)

Write writes into the UDP voice connection WITHOUT a timeout.

func (*Session) WriteCtx

func (s *Session) WriteCtx(ctx context.Context, b []byte) (int, error)

WriteCtx writes into the UDP voice connection with a context for timeout.

type Voice

type Voice struct {
	*state.State

	// ErrorLog will be called when an error occurs (defaults to log.Println)
	ErrorLog func(err error)
	// contains filtered or unexported fields
}

Voice represents a Voice Repository used for managing voice sessions.

func NewVoice

func NewVoice(s *state.State) *Voice

NewVoice creates a new Voice repository wrapped around a state. The function will also automatically add the GuildVoiceStates intent, as that is required.

func NewVoiceFromToken

func NewVoiceFromToken(token string) (*Voice, error)

NewVoiceFromToken creates a new voice session from the given token.

func (*Voice) Close

func (v *Voice) Close() error

func (*Voice) GetSession

func (v *Voice) GetSession(guildID discord.GuildID) (*Session, bool)

GetSession gets a session for a guild with a read lock.

func (*Voice) JoinChannel

func (v *Voice) JoinChannel(gID discord.GuildID, cID discord.ChannelID, muted, deafened bool) (*Session, error)

JoinChannel joins the specified channel in the specified guild.

func (*Voice) RemoveSession

func (v *Voice) RemoveSession(guildID discord.GuildID)

RemoveSession removes a session.