Voice Subsystem Keeper
Developmentvoice-subsystem-keeperVoice Subsystem Keeper is an Agent Skill for development published in the discord-php/DiscordPHP repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Work with DiscordPHP's voice subsystem — voice gateway protocol opcodes, encryption (VoiceGroupCrypto), voice packets, audio streaming, and Discord.php voice integration. Use when touching Voice/*, joinVoiceChannel, or voice encryption/packet logic.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/discord-php/DiscordPHP/blob/HEAD/.agents/skills/voice-subsystem-keeper/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/voice-subsystem-keeper, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Skill: voice-subsystem-keeper
Use this skill when work touches src/Discord/Voice/*, Discord::joinVoiceChannel(), voice event handlers in Discord.php, or anything involving audio encryption and packets.
Architecture overview
Voice support is split across three locations. Understand the boundary before touching any of them:
| Location | What lives here |
|---|---|
src/Discord/Voice/* | Internal protocol types: opcodes (Hello, Ready, Speaking), session description, voice packets, encryption classes and traits. These are pure data/crypto — no audio I/O. |
src/Discord/Discord.php | Runtime integration: joinVoiceChannel(), voice state update handlers, voice server update handlers. This is where the external voice client is wired to gateway events. |
discord-php-helpers/voice (external package) | Manager and VoiceClient: actual audio I/O, Opus encoding, UDP transport, stream management. DiscordPHP delegates audio work here. |
Rule: do not blur these boundaries. Protocol types belong in Voice/*, audio I/O belongs in the external package, and wiring belongs in Discord.php.
Read in this order
src/Discord/Voice/VoiceGroupCrypto.php— encryption/decryption base classsrc/Discord/Voice/VoiceGroupCryptoTrait.php— mixin providing group-based AEAD cryptosrc/Discord/Voice/VoiceGroupCryptoInterface.php— contractsrc/Discord/Voice/VoicePacket.php— encrypted RTP packet encapsulationsrc/Discord/Voice/SessionDescription.php— session key and mode negotiationsrc/Discord/Voice/Speaking.php,src/Discord/Voice/Hello.php,src/Discord/Voice/Ready.php,src/Discord/Voice/Resumed.php— voice gateway opcodessrc/Discord/Voice/Platform.php,src/Discord/Voice/Region.php— enum helperssrc/Discord/Discord.php— search forjoinVoiceChannel,VOICE_STATE_UPDATE,VOICE_SERVER_UPDATEsrc/Discord/Helpers/Buffer.php— writable stream for audio buffering (extends EventEmitter)
Core concepts
Voice gateway protocol
Discord voice uses a separate WebSocket gateway from the main gateway. The handshake sequence is:
Hello— server sends heartbeat intervalIdentify— client sends token + sessionReady— server sends UDP endpoint + SSRCSelect Protocol— client sends chosen encryption modeSession Description— server sends secret keySpeaking— sent before/after transmitting audio
The classes in src/Discord/Voice/ model these protocol steps as typed value objects.
Encryption
VoiceGroupCrypto provides AEAD encryption for RTP packets. It depends on libsodium (ext-sodium). The trait VoiceGroupCryptoTrait provides the implementation; concrete classes select the cipher mode (e.g., aead_xchacha20poly1305_ietf).
LibSodiumNotFoundExceptionis thrown at runtime if the extension is absent — do not suppress it- Cipher mode is negotiated via
SessionDescription
VoicePacket
VoicePacket encapsulates an encrypted RTP packet:
- SSRC identifies the audio source
- Sequence number and timestamp are required for RTP ordering
- The packet is encrypted before transmission using the session secret key
Audio I/O (external package)
discord-php-helpers/voice owns all audio work:
- Opus codec encoding/decoding
- UDP socket management
- OGG/Opus stream handling
- FFmpeg process integration
Do not replicate any of this in src/Discord/Voice/. If you need to add audio capability, contribute to the external package or wrap it.
Old* files
OldVoiceClient.php, OldBuffer.php, OldOggStream.php, OldOggPage.php, OldOpusHead.php, OldOpusTags.php, OldReceiveStream.php are legacy implementations. They are preserved for compatibility only.
Do not extend, copy patterns from, or add new features to any Old* class. Fix bugs in them only when the fix is isolated and does not require architectural change.
Companion surfaces
When touching voice code, also inspect:
| Touching | Also inspect |
|---|---|
VoiceGroupCrypto or crypto mode | SessionDescription, VoicePacket, VoiceGroupCryptoInterface, LibSodiumNotFoundException |
Speaking or voice gateway opcode | Hello, Ready, Resumed, SessionDescription — full handshake chain |
Discord.php voice handlers | Voice gateway opcodes, Buffer, external voice package Manager |
Buffer.php | Multipart.php (similar streaming pattern), external voice package stream classes |
| Any new voice encryption mode | VoiceGroupCryptoInterface, crypto trait, SessionDescription mode list |
Playbook: adding a new voice encryption mode
- Add the mode constant to
SessionDescription. - Implement the mode in a class using
VoiceGroupCryptoTraitor extendingVoiceGroupCrypto. - Register the mode in the external voice package's cipher negotiation if needed.
- Update
VoiceGroupCryptoInterfaceif the contract changes. - Verify libsodium function availability — throw
LibSodiumNotFoundExceptionif missing. - Add tests for encrypt/decrypt round-trip.
Playbook: adding a voice gateway opcode
- Create a typed value class under
src/Discord/Voice/mirroring the Discord voice gateway docs. - Wire the opcode handler in
Discord.php(find the voice WebSocket message handler). - Document the opcode sequence in the class docblock.
- Do not put audio I/O logic in the opcode class — keep it as a typed payload.
Design tripwires
- Adding audio codec, UDP, or FFmpeg logic inside
src/Discord/Voice/— that belongs in the external voice package - Extending any
Old*class for new features - Skipping libsodium availability check before using sodium functions
- Hard-coding a cipher mode instead of reading it from
SessionDescription - Blocking I/O inside voice packet or stream handlers — everything must be async/Promise-based
- Catching
LibSodiumNotFoundExceptionsilently instead of surfacing it to the caller
Reference files
src/Discord/Voice/VoiceGroupCrypto.php— encryption basesrc/Discord/Voice/VoicePacket.php— RTP packet wrappersrc/Discord/Voice/SessionDescription.php— session key/modesrc/Discord/Voice/Speaking.php— voice speaking opcodesrc/Discord/Helpers/Buffer.php— writable stream helpersrc/Discord/Exceptions/LibSodiumNotFoundException.php— crypto dependency guardsrc/Discord/Exceptions/OpusNotFoundException.php— codec dependency guardsrc/Discord/Exceptions/FFmpegNotFoundException.php— audio tool dependency guard