# rany2/edge-tts architecture

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

- Interactive diagram: https://gitdiagram.com/rany2/edge-tts
- Repository: https://github.com/rany2/edge-tts

## Overview

edge-tts is a Python client and command-line tool for Microsoft Edge’s online text-to-speech service, with voice discovery, audio streaming, and subtitle output; edge-playback adds immediate playback. The main workflow is CLI input and settings → synthesis request → streamed audio and timing metadata → audio/subtitle output, optionally followed by playback. Voice discovery is a separate capability. The graph also includes configuration, token generation, and subtitle composition as internal layers. Some modules are indexed but not excerpted; their connections are included only where the index or README supports them.

Main entry points: [`src/edge_tts/communicate.py`](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/communicate.py) (Communicate stream), [`src/edge_tts/util.py`](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py) (TTS CLI), [`src/edge_playback/__main__.py`](https://github.com/rany2/edge-tts/blob/master/src/edge_playback/__main__.py) (Playback launcher), [`src/edge_tts/voices.py`](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/voices.py) (Voice discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_synthesis["Speech synthesis"]
  node_communicate["Communicate stream<br/>[communicate.py]"]
  node_config["TTS configuration<br/>[data_classes.py]"]
  node_protocol["Service constants<br/>[constants.py]"]
  node_drm["Request tokens<br/>[drm.py]"]
  node_errors["TTS errors<br/>[exceptions.py]"]
end

subgraph group_voices["Voice discovery"]
  node_voice_discovery["Voice discovery<br/>[voices.py]"]
end

subgraph group_cli["CLI output"]
  node_tts_cli["TTS CLI<br/>[util.py]"]
  node_submaker["Subtitle maker<br/>[submaker.py]"]
  node_srt["SRT composer<br/>[srt_composer.py]"]
  node_output["Media and subtitle output<br/>[util.py]"]
end

subgraph group_playback["Audio playback"]
  node_playback_cli["Playback launcher<br/>[__main__.py]"]
  node_win_play["Windows playback<br/>[win32_playback.py]"]
end

node_user(("User"))
node_tts_service{{"Microsoft TTS"}}
node_voice_api{{"Voice listing API"}}
node_mpv{{"mpv player"}}

node_user -->|"provides input"| node_tts_cli
node_tts_cli -->|"configures stream"| node_communicate
node_communicate -->|"validates settings"| node_config
node_communicate -->|"uses protocol constants"| node_protocol
node_communicate -->|"generates request tokens"| node_drm
node_communicate -->|"raises service errors"| node_errors
node_communicate -->|"streams synthesis"| node_tts_service
node_tts_cli -->|"feeds boundaries"| node_submaker
node_submaker -->|"composes subtitles"| node_srt
node_tts_cli -->|"writes media"| node_output
node_tts_cli -->|"lists voices"| node_voice_discovery
node_voice_discovery -->|"requests voice list"| node_voice_api
node_voice_discovery -->|"generates request tokens"| node_drm
node_user -->|"starts playback"| node_playback_cli
node_playback_cli -->|"runs synthesis CLI"| node_tts_cli
node_playback_cli -->|"plays media"| node_mpv
node_playback_cli -->|"uses Windows playback"| node_win_play

click node_tts_cli "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py"
click node_communicate "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/communicate.py"
click node_config "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/data_classes.py"
click node_protocol "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/constants.py"
click node_drm "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/drm.py"
click node_errors "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/exceptions.py"
click node_voice_discovery "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/voices.py"
click node_submaker "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/submaker.py"
click node_srt "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/srt_composer.py"
click node_output "https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py"
click node_playback_cli "https://github.com/rany2/edge-tts/blob/master/src/edge_playback/__main__.py"
click node_win_play "https://github.com/rany2/edge-tts/blob/master/src/edge_playback/win32_playback.py"

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_communicate,node_config,node_protocol,node_drm,node_errors,node_user toneBlue
class node_voice_discovery toneAmber
class node_tts_cli,node_submaker,node_srt,node_output,node_voice_api toneMint
class node_playback_cli,node_win_play toneRose
class node_tts_service,node_mpv toneIndigo
```

## Components

### Speech synthesis

- [Communicate stream](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/communicate.py): `src/edge_tts/communicate.py`
- [TTS configuration](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/data_classes.py): `src/edge_tts/data_classes.py`
- [Service constants](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/constants.py): `src/edge_tts/constants.py`
- [Request tokens](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/drm.py): `src/edge_tts/drm.py`
- [TTS errors](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/exceptions.py): `src/edge_tts/exceptions.py`

### Voice discovery

- [Voice discovery](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/voices.py): `src/edge_tts/voices.py`

### CLI output

- [TTS CLI](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py): `src/edge_tts/util.py`
- [Subtitle maker](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/submaker.py): `src/edge_tts/submaker.py`
- [SRT composer](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/srt_composer.py): `src/edge_tts/srt_composer.py`
- [Media and subtitle output](https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py): `src/edge_tts/util.py`

### Audio playback

- [Playback launcher](https://github.com/rany2/edge-tts/blob/master/src/edge_playback/__main__.py): `src/edge_playback/__main__.py`
- [Windows playback](https://github.com/rany2/edge-tts/blob/master/src/edge_playback/win32_playback.py): `src/edge_playback/win32_playback.py`

### Other components

- **User**
- **Microsoft TTS**
- **Voice listing API**
- **mpv player**

## Connections

- User → TTS CLI: provides input (evidence: `README.md`)
- TTS CLI → Communicate stream: configures stream (evidence: `src/edge_tts/util.py`)
- Communicate stream → TTS configuration: validates settings (evidence: `src/edge_tts/communicate.py`)
- Communicate stream → Service constants: uses protocol constants (evidence: `src/edge_tts/communicate.py`)
- Communicate stream → Request tokens: generates request tokens (evidence: `src/edge_tts/communicate.py`)
- Communicate stream → TTS errors: raises service errors (evidence: `src/edge_tts/communicate.py`)
- Communicate stream → Microsoft TTS: streams synthesis (evidence: `src/edge_tts/communicate.py`)
- TTS CLI → Subtitle maker: feeds boundaries (evidence: `src/edge_tts/util.py`)
- Subtitle maker → SRT composer: composes subtitles (evidence: `src/edge_tts/submaker.py`)
- TTS CLI → Media and subtitle output: writes media (evidence: `src/edge_tts/util.py`)
- TTS CLI → Voice discovery: lists voices (evidence: `src/edge_tts/util.py`)
- Voice discovery → Voice listing API: requests voice list (evidence: `src/edge_tts/voices.py`)
- Voice discovery → Request tokens: generates request tokens (evidence: `src/edge_tts/voices.py`)
- User → Playback launcher: starts playback (evidence: `README.md`)
- Playback launcher → TTS CLI: runs synthesis CLI (evidence: `src/edge_playback/__main__.py`)
- Playback launcher → mpv player: plays media (evidence: `src/edge_playback/__main__.py`)
- Playback launcher → Windows playback: uses Windows playback (evidence: `src/edge_playback/__main__.py`)
