# imayhaveborkedit/discord-ext-voice-recv architecture

> Architecture diagram of the GitHub repository imayhaveborkedit/discord-ext-voice-recv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imayhaveborkedit/discord-ext-voice-recv
- Repository: https://github.com/imayhaveborkedit/discord-ext-voice-recv

## Overview

##### Project Type and Purpose
- Type: Python library (extension) that plugs into `discord.py` to enable voice‐receive capabilities.
- Purpose: Intercept Discord voice gateway events and RTP streams, buffer/decode them, and feed audio “sinks” (user-provided or built-in handlers).

##### Top-Level Components
a. Bot Application (User Code)
b. discord.py Core
c. VoiceRecv Extension (this project)
d. External Services/Libraries

- VoiceRecvClient (custom subclass of `discord.VoiceClient`)
- Gateway Layer (`gateway.py`) – handles new voice websocket events
- RTP Layer (`rtp.py`) – receives raw UDP packets
- Jitter Buffer & Opus Decoder (`buffer.py`, `opus.py`, `silence.py`)
- Router (`router.py`) – maps SSRC to sinks, tracks speaking state
- AudioSink Pipeline (`sinks.py`) – chainable handlers
- Extras (`extras/…`) – optional sinks (e.g. speech recognition)
- Utilities (`utils.py`, `types.py`, `enums.py`, `video.py`)

##### External Dependencies
– discord.py (with voice support, `pynacl`)
– Optional: `speech_recognition`, other sink-specific libraries

##### Interactions & Data Flow
1. Bot calls `voice_channel.connect(cls=VoiceRecvClient)`
2. VoiceRecvClient opens WebSocket + UDP socket
3. WebSocket → Gateway Layer → dispatch new events (connect, speaking_state, flags, video, etc.)
4. UDP RTP packets → RTP Layer → jitter buffer → optional decoder → `VoiceData`
5. Router tags each `VoiceData` with member SSRC and speaking state
6. `VoiceData` flows into the AudioSink pipeline (zero or more sinks chained)
7. Sinks call `write()`, emit virtual events, or pass to child sinks
8. After completion or error, `cleanup()` on sinks and `stop_listening()` on client

##### Architectural Patterns & Principles
- Extension/Plugin Pattern – subclassing and event hooks
- Pipeline Pattern – sinks as composable processing stages
- Publisher-Subscriber – voice events emitted via `on_voice_…` listeners
- Separation of Concerns – distinct layers for gateway, RTP, buffering, routing, processing

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Code"
        BotApp["Bot Application"]:::user
    end

    subgraph "discord.py Core"
        DiscordPy["discord.py (voice & pynacl)"]:::core
    end

    subgraph "VoiceRecv Extension"
        VoiceRecvClient["VoiceRecvClient"]:::core
        subgraph "Gateway Layer"
            Gateway["gateway.py"]:::core
        end
        subgraph "RTP Layer"
            RTP["rtp.py"]:::core
        end
        subgraph "Buffer & Decoder"
            JBuffer["buffer.py"]:::pipeline
            Opus["opus.py"]:::pipeline
            Silence["silence.py"]:::pipeline
        end
        Router["router.py"]:::core
        Sinks["sinks.py"]:::pipeline
        subgraph "Extras"
            ExtraSR["speechrecognition.py"]:::external
        end
        subgraph "Utilities & Types"
            Utils["utils.py"]:::core
            Types["types.py"]:::core
            Enums["enums.py"]:::core
            Video["video.py"]:::core
            Reader["reader.py"]:::core
            Init["__init__.py"]:::core
        end
    end

    subgraph "External Libraries"
        ExtSpeechRec["speech_recognition"]:::external
    end

    BotApp -->|"voice_channel.connect(cls=VoiceRecvClient)"| VoiceRecvClient
    VoiceRecvClient -->|"uses voice support"| DiscordPy
    VoiceRecvClient -->|"opens WebSocket"| Gateway
    VoiceRecvClient -->|"opens UDP socket"| RTP

    Gateway -->|"dispatch events"| Router
    RTP -->|"RTP packets"| JBuffer
    JBuffer -->|"buffered data"| Opus
    JBuffer -->|"silence frames"| Silence
    Opus -->|"decoded audio"| Router
    Silence -->|"silence frames"| Router
    Router -->|"VoiceData"| Sinks
    Sinks -->|"pipeline to extras or user sinks"| ExtraSR
    ExtraSR -->|"optional sink libs"| ExtSpeechRec
    Sinks -->|"cleanup() on finish"| VoiceRecvClient
    VoiceRecvClient -->|"stop_listening()"| BotApp

    click VoiceRecvClient "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/voice_client.py"
    click Gateway "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/gateway.py"
    click RTP "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/rtp.py"
    click JBuffer "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/buffer.py"
    click Opus "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/opus.py"
    click Silence "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/silence.py"
    click Router "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/router.py"
    click Sinks "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/sinks.py"
    click ExtraSR "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/extras/speechrecognition.py"
    click Utils "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/utils.py"
    click Types "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/types.py"
    click Enums "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/enums.py"
    click Video "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/video.py"
    click Reader "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/reader.py"
    click Init "https://github.com/imayhaveborkedit/discord-ext-voice-recv/blob/main/discord/ext/voice_recv/__init__.py"

    classDef core fill:#e0f7fa,stroke:#006064
    classDef user fill:#fff3e0,stroke:#e65100
    classDef external fill:#e8f5e9,stroke:#2e7d32
    classDef pipeline fill:#fff59d,stroke:#f9a825
```
