github.com/diamondburned/arikawa/v2@v2.1.0/voice/README.md (about)

     1  # Voice
     2  
     3  ## Terminology
     4  * **Discord Gateway** - The standard Discord Gateway users connect to and receive update events from
     5  * **Discord Voice Gateway** - The Discord Voice gateway that allows voice connections to be configured
     6  * **Voice Server** - What the Discord Voice Gateway allows connection to for sending of Opus voice packets over UDP
     7  * **Voice Packet** - Opus encoded UDP packet that contains audio
     8  * **Application** - Could be a custom Discord Client or Bot (nothing that is within this package)
     9  * **Library** - Code within this package
    10  
    11  ## Connection Flow
    12  * The **application** would get a new `*Voice` instance by calling `NewVoice()`
    13  * When the **application** wants to connect to a voice channel they would call `JoinChannel()` on
    14  the stored `*Voice` instance
    15  
    16  ---
    17  
    18  * The **library** sends a [Voice State Update](https://discordapp.com/developers/docs/topics/voice-connections#retrieving-voice-server-information-gateway-voice-state-update-example)
    19  to the **Discord Gateway**.
    20  * The **library** waits until it receives a [Voice Server Update](https://discordapp.com/developers/docs/topics/voice-connections#retrieving-voice-server-information-example-voice-server-update-payload)
    21  from the **Discord Gateway**.
    22  * Once a *Voice Server Update* event is received, a new connection is opened to the **Discord Voice Gateway**.
    23  
    24  ---
    25  
    26  * The **Discord Voice Gateway** will first send a [Hello Event](https://discordapp.com/developers/docs/topics/voice-connections#heartbeating-example-hello-payload-since-v3)
    27  which will be used to create a new `*heart.PacemakerLoop` and start sending heartbeats to the **Discord Voice Gateway**.
    28  * Afterwards, an [Identify Command](https://discordapp.com/developers/docs/topics/voice-connections#establishing-a-voice-websocket-connection-example-voice-identify-payload)
    29  or [Resume Command](https://discordapp.com/developers/docs/topics/voice-connections#resuming-voice-connection-example-resume-connection-payload)
    30  is sent to the **Discord Voice Gateway** depending on whether the **library** is reconnecting.
    31  
    32  ---
    33  
    34  * The **Discord Voice Gateway** should then respond with a [Ready Event](https://discordapp.com/developers/docs/topics/voice-connections#establishing-a-voice-websocket-connection-example-voice-ready-payload)
    35  once the connection is opened, providing the required information to connect to a **Voice Server**.
    36  * Using the information provided in the *Ready Event*, a new UDP connection is opened to the **Voice Server**
    37  and [IP Discovery](https://discordapp.com/developers/docs/topics/voice-connections#ip-discovery) occurs.
    38  * After *IP Discovery* returns the **Application**'s external ip and port it connected to the **Voice Server**
    39  with, the **library** sends a [Select Protocol Event](https://discordapp.com/developers/docs/topics/voice-connections#establishing-a-voice-udp-connection-example-select-protocol-payload)
    40  to the **Discord Voice Gateway**.
    41  * The **library** waits until it receives a [Session Description Event](https://discordapp.com/developers/docs/topics/voice-connections#establishing-a-voice-udp-connection-example-session-description-payload)
    42  from the **Discord Voice Gateway**.
    43  * Once the *Session Description Event* is received, [Speaking Events](https://discordapp.com/developers/docs/topics/voice-connections#speaking-example-speaking-payload)
    44  and **Voice Packets** can begin to be sent to the **Discord Voice Gateway** and **Voice Server** respectively.
    45  
    46  ## Usage
    47  * The **application** would get a new `*Voice` instance by calling `NewVoice()` and keep it
    48  stored for when it needs to open voice connections.
    49  * When the **application** wants to connect to a voice channel they would call `JoinChannel()` on
    50  the stored `*Voice` instance.
    51  * `JoinChannel()` will block as it follows the [Connection Flow](#connection-flow), returning an
    52  `error` if one occurs and a `*voice.Session` if it was successful.
    53  * The **application** should now call `(*voice.Session).Speaking()` with the wanted [voice flag](https://discordapp.com/developers/docs/topics/voice-connections#speaking)
    54  (`voicegateway.Microphone`, `voicegateway.Soundshare`, or `voicegateway.Priority`).
    55  * The **application** can now send **Voice Packets** using the `(*voice.Session).Write()` method
    56  which will be sent to the **Voice Server**. `(*voice.Session)` also implements `io.Writer`.
    57  * When the **application** wants to stop sending **Voice Packets** they should call
    58  `(*voice.Session).StopSpeaking()`, then any required voice cleanup (closing streams, etc.), then
    59  `(*voice.Session).Disconnect()`
    60  
    61  ## Examples
    62  
    63  Check the integration tests at [voice/integration_test.go](https://github.com/diamondburned/arikawa/blob/master/voice/integration_test.go).