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 callingNewVoice()
- 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 or not 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 callingNewVoice()
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 anerror
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
, orvoicegateway.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 implementsio.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
- type Session
- func (s *Session) Disconnect() error
- func (s *Session) DisconnectCtx(ctx context.Context) error
- func (s *Session) JoinChannel(gID, cID discord.Snowflake, muted, deafened bool) error
- func (s *Session) JoinChannelCtx(ctx context.Context, gID, cID discord.Snowflake, muted, deafened bool) 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
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.
Functions ¶
This section is empty.
Types ¶
type CloseError ¶ added in v0.7.3
func (*CloseError) Error ¶ added in v0.7.3
func (e *CloseError) Error() string
func (*CloseError) HasError ¶ added in v0.7.3
func (e *CloseError) HasError() bool
type Session ¶
type Session struct { ErrorLog func(err error) // contains filtered or unexported fields }
func (*Session) Disconnect ¶
func (*Session) DisconnectCtx ¶ added in v0.10.0
func (*Session) JoinChannel ¶
func (*Session) JoinChannelCtx ¶ added in v0.10.0
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 (*Session) UpdateServer ¶
func (s *Session) UpdateServer(ev *gateway.VoiceServerUpdateEvent)
func (*Session) UpdateState ¶
func (s *Session) UpdateState(ev *gateway.VoiceStateUpdateEvent)
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 ¶
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 ¶ added in v0.10.0
NewVoiceFromToken creates a new voice session from the given token.
func (*Voice) GetSession ¶
GetSession gets a session for a guild with a read lock.
func (*Voice) JoinChannel ¶
JoinChannel joins the specified channel in the specified guild.
func (*Voice) RemoveSession ¶
RemoveSession removes a session.