# serenity-rs/songbird architecture

> Architecture diagram of the GitHub repository serenity-rs/songbird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/serenity-rs/songbird
- Repository: https://github.com/serenity-rs/songbird

## Overview

Songbird is a Rust voice system for Discord, combining gateway integration, audio input and playback, and a voice driver. A typical flow starts with a bot joining a guild voice channel, supplying an audio source, and playing it as a controllable track; the driver mixes and sends audio to Discord. Separate capabilities include queues, event handling, optional voice receive, and multiple gateway frontends. The source excerpts show key message dispatch and connection links; some indexed runtime modules were not sampled, so uncertain internal links are omitted.

Main entry points: [`src/driver/mod.rs`](https://github.com/serenity-rs/songbird/blob/current/src/driver/mod.rs) (Voice driver), [`src/driver/tasks/mixer/mix_logic.rs`](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/mixer/mix_logic.rs) (Audio mixer), [`src/driver/tasks/mod.rs`](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/mod.rs) (Core task dispatcher), [`src/manager.rs`](https://github.com/serenity-rs/songbird/blob/current/src/manager.rs) (Call manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway integration"]
  node_manager["Call manager<br/>[manager.rs]"]
  node_handler["Call handler<br/>[handler.rs]"]
  node_serenity["Serenity adapter<br/>[serenity.rs]"]
  node_shards["Shard integration<br/>[shards.rs]"]
  node_id_types["Guild identifiers<br/>[id.rs]"]
end

subgraph group_media["Audio inputs"]
  node_input_sources["Audio sources<br/>[mod.rs]"]
  node_input["Playable input<br/>[mod.rs]"]
  node_input_metadata["Source metadata<br/>[mod.rs]"]
end

subgraph group_playback["Track playback"]
  node_tracks["Track model<br/>[mod.rs]"]
  node_track_handle["Track controls<br/>[handle.rs]"]
  node_queue["Track queue<br/>[queue.rs]"]
end

subgraph group_runtime["Voice runtime"]
  node_config["Driver configuration<br/>[config.rs]"]
  node_connection["Voice connection<br/>[mod.rs]"]
  node_crypto["Voice crypto<br/>[crypto.rs]"]
  node_driver["Voice driver<br/>[mod.rs]"]
  node_core_tasks["Core task dispatcher<br/>[mod.rs]"]
  node_mixer["Audio mixer<br/>[mix_logic.rs]"]
  node_scheduler_idle["Idle scheduler<br/>[idle.rs]"]
  node_scheduler_live["Live scheduler<br/>[live.rs]"]
  node_ws_task["Gateway socket task<br/>[ws.rs]"]
end

subgraph group_events["Events and receive"]
  node_event_processor["Event processor<br/>[events.rs]"]
  node_event_api["Event API<br/>[mod.rs]"]
  node_udp_receive["Voice receive<br/>[mod.rs]"]
end

node_bot(("Bot application"))
node_discord(("Discord voice service"))

node_bot -->|"uses gateway"| node_manager
node_manager -->|"updates call"| node_handler
node_manager -->|"uses sharder"| node_shards
node_serenity -->|"integrates gateway"| node_manager
node_handler -->|"controls driver"| node_driver
node_driver -->|"dispatches messages"| node_core_tasks
node_core_tasks -->|"opens connection"| node_connection
node_core_tasks -->|"sends mixer messages"| node_mixer
node_core_tasks -->|"sends event messages"| node_event_processor
node_connection -->|"sets connection"| node_mixer
node_connection -->|"delivers socket messages"| node_ws_task
node_discord -->|"voice protocol"| node_connection
node_bot -->|"selects audio"| node_input_sources
node_input_sources -->|"creates input"| node_input
node_input -->|"exposes metadata"| node_input_metadata
node_input -->|"provides audio"| node_tracks
node_tracks -->|"plays track"| node_driver
node_driver -->|"enqueues track"| node_queue
node_tracks -->|"creates controls"| node_track_handle
node_mixer -->|"sends track events"| node_event_processor
node_event_api -->|"defines handlers"| node_event_processor
node_discord -.->|"sends voice packets"| node_udp_receive
node_driver -.->|"uses encryption"| node_crypto
node_driver -.->|"uses settings"| node_config
node_mixer -.->|"scheduled by"| node_scheduler_idle
node_mixer -.->|"scheduled by"| node_scheduler_live
node_bot -->|"registers listeners"| node_event_api

click node_manager "https://github.com/serenity-rs/songbird/blob/current/src/manager.rs"
click node_handler "https://github.com/serenity-rs/songbird/blob/current/src/handler.rs"
click node_serenity "https://github.com/serenity-rs/songbird/blob/current/src/serenity.rs"
click node_shards "https://github.com/serenity-rs/songbird/blob/current/src/shards.rs"
click node_config "https://github.com/serenity-rs/songbird/blob/current/src/config.rs"
click node_connection "https://github.com/serenity-rs/songbird/blob/current/src/driver/connection/mod.rs"
click node_crypto "https://github.com/serenity-rs/songbird/blob/current/src/driver/crypto.rs"
click node_driver "https://github.com/serenity-rs/songbird/blob/current/src/driver/mod.rs"
click node_core_tasks "https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/mod.rs"
click node_mixer "https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/mixer/mix_logic.rs"
click node_scheduler_idle "https://github.com/serenity-rs/songbird/blob/current/src/driver/scheduler/idle.rs"
click node_scheduler_live "https://github.com/serenity-rs/songbird/blob/current/src/driver/scheduler/live.rs"
click node_ws_task "https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/ws.rs"
click node_input_sources "https://github.com/serenity-rs/songbird/blob/current/src/input/sources/mod.rs"
click node_input "https://github.com/serenity-rs/songbird/blob/current/src/input/mod.rs"
click node_input_metadata "https://github.com/serenity-rs/songbird/blob/current/src/input/metadata/mod.rs"
click node_tracks "https://github.com/serenity-rs/songbird/blob/current/src/tracks/mod.rs"
click node_track_handle "https://github.com/serenity-rs/songbird/blob/current/src/tracks/handle.rs"
click node_queue "https://github.com/serenity-rs/songbird/blob/current/src/tracks/queue.rs"
click node_event_processor "https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/events.rs"
click node_event_api "https://github.com/serenity-rs/songbird/blob/current/src/events/mod.rs"
click node_udp_receive "https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/udp_rx/mod.rs"
click node_id_types "https://github.com/serenity-rs/songbird/blob/current/src/id.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manager,node_handler,node_serenity,node_shards,node_id_types toneBlue
class node_input_sources,node_input,node_input_metadata toneAmber
class node_tracks,node_track_handle,node_queue toneMint
class node_config,node_connection,node_crypto,node_driver,node_core_tasks,node_mixer,node_scheduler_idle,node_scheduler_live,node_ws_task toneRose
class node_event_processor,node_event_api,node_udp_receive,node_bot,node_discord toneIndigo
```

## Components

### Gateway integration

- [Call manager](https://github.com/serenity-rs/songbird/blob/current/src/manager.rs): `src/manager.rs`
- [Call handler](https://github.com/serenity-rs/songbird/blob/current/src/handler.rs): `src/handler.rs`
- [Serenity adapter](https://github.com/serenity-rs/songbird/blob/current/src/serenity.rs): `src/serenity.rs`
- [Shard integration](https://github.com/serenity-rs/songbird/blob/current/src/shards.rs): `src/shards.rs`
- [Guild identifiers](https://github.com/serenity-rs/songbird/blob/current/src/id.rs): `src/id.rs`

### Audio inputs

- [Audio sources](https://github.com/serenity-rs/songbird/blob/current/src/input/sources/mod.rs): `src/input/sources/mod.rs`
- [Playable input](https://github.com/serenity-rs/songbird/blob/current/src/input/mod.rs): `src/input/mod.rs`
- [Source metadata](https://github.com/serenity-rs/songbird/blob/current/src/input/metadata/mod.rs): `src/input/metadata/mod.rs`

### Track playback

- [Track model](https://github.com/serenity-rs/songbird/blob/current/src/tracks/mod.rs): `src/tracks/mod.rs`
- [Track controls](https://github.com/serenity-rs/songbird/blob/current/src/tracks/handle.rs): `src/tracks/handle.rs`
- [Track queue](https://github.com/serenity-rs/songbird/blob/current/src/tracks/queue.rs): `src/tracks/queue.rs`

### Voice runtime

- [Driver configuration](https://github.com/serenity-rs/songbird/blob/current/src/config.rs): `src/config.rs`
- [Voice connection](https://github.com/serenity-rs/songbird/blob/current/src/driver/connection/mod.rs): `src/driver/connection/mod.rs`
- [Voice crypto](https://github.com/serenity-rs/songbird/blob/current/src/driver/crypto.rs): `src/driver/crypto.rs`
- [Voice driver](https://github.com/serenity-rs/songbird/blob/current/src/driver/mod.rs): `src/driver/mod.rs`
- [Core task dispatcher](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/mod.rs): `src/driver/tasks/mod.rs`
- [Audio mixer](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/mixer/mix_logic.rs): `src/driver/tasks/mixer/mix_logic.rs`
- [Idle scheduler](https://github.com/serenity-rs/songbird/blob/current/src/driver/scheduler/idle.rs): `src/driver/scheduler/idle.rs`
- [Live scheduler](https://github.com/serenity-rs/songbird/blob/current/src/driver/scheduler/live.rs): `src/driver/scheduler/live.rs`
- [Gateway socket task](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/ws.rs): `src/driver/tasks/ws.rs`

### Events and receive

- [Event processor](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/events.rs): `src/driver/tasks/events.rs`
- [Event API](https://github.com/serenity-rs/songbird/blob/current/src/events/mod.rs): `src/events/mod.rs`
- [Voice receive](https://github.com/serenity-rs/songbird/blob/current/src/driver/tasks/udp_rx/mod.rs): `src/driver/tasks/udp_rx/mod.rs`

### Other components

- **Bot application**
- **Discord voice service**

## Connections

- Bot application → Call manager: uses gateway (evidence: `README.md`)
- Call manager → Call handler: updates call (evidence: `src/manager.rs`)
- Call manager → Shard integration: uses sharder (evidence: `src/manager.rs`)
- Serenity adapter → Call manager: integrates gateway (evidence: `src/manager.rs`)
- Call handler → Voice driver: controls driver (evidence: `src/handler.rs`)
- Voice driver → Core task dispatcher: dispatches messages (evidence: `src/driver/mod.rs`)
- Core task dispatcher → Voice connection: opens connection (evidence: `src/driver/tasks/mod.rs`)
- Core task dispatcher → Audio mixer: sends mixer messages (evidence: `src/driver/tasks/mod.rs`)
- Core task dispatcher → Event processor: sends event messages (evidence: `src/driver/tasks/mod.rs`)
- Voice connection → Audio mixer: sets connection (evidence: `src/driver/connection/mod.rs`)
- Voice connection → Gateway socket task: delivers socket messages (evidence: `src/driver/connection/mod.rs`)
- Discord voice service → Voice connection: voice protocol (evidence: `README.md`)
- Bot application → Audio sources: selects audio (evidence: `README.md`)
- Audio sources → Playable input: creates input (evidence: `src/input/sources/mod.rs`)
- Playable input → Source metadata: exposes metadata (evidence: `src/input/metadata/mod.rs`)
- Playable input → Track model: provides audio (evidence: `src/tracks/mod.rs`)
- Track model → Voice driver: plays track (evidence: `src/driver/mod.rs`)
- Voice driver → Track queue: enqueues track (evidence: `src/driver/mod.rs`)
- Track model → Track controls: creates controls (evidence: `src/tracks/mod.rs`)
- Audio mixer → Event processor: sends track events
- Event API → Event processor: defines handlers (evidence: `src/events/mod.rs`)
- Discord voice service → Voice receive: sends voice packets
- Voice driver → Voice crypto: uses encryption (evidence: `src/driver/mod.rs`)
- Voice driver → Driver configuration: uses settings
- Audio mixer → Idle scheduler: scheduled by
- Audio mixer → Live scheduler: scheduled by
- Bot application → Event API: registers listeners (evidence: `README.md`)
