# thomasericb/drama3-offload-studio architecture

> Architecture diagram of the GitHub repository thomasericb/drama3-offload-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomasericb/drama3-offload-studio
- Repository: https://github.com/thomasericb/drama3-offload-studio

## Overview

Drama 3 Offload Studio is a local launcher and server for expressive text-to-speech, offering full-model NVIDIA expert offload, Small GGUF, and experimental Apple Silicon MLX modes. The principal workflow is a user submitting a directed script through the Studio or JSON API; the server selects a backend, applies script and take features, streams generated audio, and supports retakes and edits. The graph preserves documented capabilities even where implementation details were not sampled; arrows are limited to relationships visible in excerpts, the source index, or README.

Main entry points: [`offload/serve.py`](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/serve.py) (Studio server), [`offload/long_takes.py`](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/long_takes.py) (Long takes and edits), [`offload/studio_extras.py`](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/studio_extras.py) (Studio controls), [`offload/pronunciation.py`](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pronunciation.py) (Pronunciation rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Serving and engines"]
  node_server["Studio server<br/>[serve.py]"]
  node_cuda["NVIDIA offload<br/>[drama3_offload.py]"]
  node_small["Small GGUF<br/>[gguf_drama3.py]"]
  node_mlx["Apple MLX<br/>[drama3_mlx.py]"]
  node_portable["Portable engine<br/>[drama3_portable.py]"]
  node_branding["Studio branding<br/>[branding.py]"]
end

subgraph group_script["Script and direction"]
  node_extras["Studio controls<br/>[studio_extras.py]"]
  node_tags["Tag guidance<br/>[tag_guidance.py]"]
  node_pronunciation["Pronunciation rules<br/>[pronunciation.py]"]
end

subgraph group_takes["Take workflow"]
  node_longtakes["Long takes and edits<br/>[long_takes.py]"]
  node_chunking["Script chunking<br/>[chunking.py]"]
  node_infill["Audio infilling<br/>[infill.py]"]
  node_seeds["Repeatable seeds<br/>[seeds.py]"]
  node_subtitles["Subtitle tools<br/>[subtitles.py]"]
end

subgraph group_quality["Quality and audio"]
  node_wordcheck["Word checks<br/>[word_check.py]"]
  node_pause["Pause fix<br/>[pause_fix.py]"]
  node_stall["Stall guard<br/>[stall_guard.py]"]
  node_sampling["Sampling controls"]
  node_prefix["Reference cache<br/>[prefix_cache.py]"]
  node_trim["Reference trimming<br/>[reference_trim.py]"]
end

subgraph group_state["Persistent state"]
  node_dictionary[("Pronunciation cache<br/>[pronunciation.py]")]
end

node_user(("Studio user"))

node_user -->|"submits script"| node_server
node_server -->|"selects backend"| node_cuda
node_server -->|"selects backend"| node_small
node_server -->|"selects backend"| node_mlx
node_server -->|"selects backend"| node_portable
node_server -->|"loads branding"| node_branding
node_server -->|"installs take hooks"| node_longtakes
node_server -->|"installs controls"| node_extras
node_server -->|"loads guidance"| node_tags
node_server -->|"loads rules"| node_pronunciation
node_server -->|"loads checks"| node_wordcheck
node_server -->|"loads seed hooks"| node_seeds
node_server -->|"installs pause fix"| node_pause
node_server -->|"installs cache"| node_prefix
node_server -->|"loads reference trim"| node_trim
node_longtakes -->|"splits scripts"| node_chunking
node_longtakes -->|"uses for edits"| node_infill
node_longtakes -->|"applies rules"| node_pronunciation
node_longtakes -->|"uses take seeds"| node_seeds
node_longtakes -->|"supports subtitles"| node_subtitles
node_longtakes -->|"checks generated words"| node_wordcheck
node_longtakes -->|"uses pause fix"| node_pause
node_pronunciation -->|"reads and writes"| node_dictionary
node_extras -->|"controls take edits"| node_longtakes
node_extras -->|"edits rules"| node_pronunciation
node_extras -->|"offers subtitle tools"| node_subtitles
node_extras -->|"configures checks"| node_wordcheck
node_extras -->|"configures sampling"| node_sampling
node_mlx -->|"applies pause rules"| node_pause
node_portable -->|"applies pause rules"| node_pause
node_server -->|"loads sampling"| node_sampling
node_server -->|"loads stall guard"| node_stall

click node_server "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/serve.py"
click node_cuda "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/drama3_offload.py"
click node_small "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/gguf_drama3.py"
click node_mlx "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/drama3_mlx.py"
click node_portable "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/drama3_portable.py"
click node_branding "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/branding.py"
click node_extras "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/studio_extras.py"
click node_tags "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/tag_guidance.py"
click node_pronunciation "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pronunciation.py"
click node_dictionary "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pronunciation.py"
click node_longtakes "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/long_takes.py"
click node_chunking "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/chunking.py"
click node_infill "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/infill.py"
click node_seeds "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/seeds.py"
click node_subtitles "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/subtitles.py"
click node_wordcheck "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/word_check.py"
click node_pause "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pause_fix.py"
click node_stall "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/stall_guard.py"
click node_sampling "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/upstream_sampling.py"
click node_prefix "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/prefix_cache.py"
click node_trim "https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/reference_trim.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_server,node_cuda,node_small,node_mlx,node_portable,node_branding,node_user toneBlue
class node_extras,node_tags,node_pronunciation toneAmber
class node_longtakes,node_chunking,node_infill,node_seeds,node_subtitles toneMint
class node_wordcheck,node_pause,node_stall,node_sampling,node_prefix,node_trim toneRose
class node_dictionary toneIndigo
```

## Components

### Serving and engines

- [Studio server](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/serve.py): `offload/serve.py`
- [NVIDIA offload](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/drama3_offload.py): `offload/drama3_offload.py`
- [Small GGUF](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/gguf_drama3.py): `offload/gguf_drama3.py`
- [Apple MLX](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/drama3_mlx.py): `offload/drama3_mlx.py`
- [Portable engine](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/drama3_portable.py): `offload/drama3_portable.py`
- [Studio branding](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/branding.py): `offload/branding.py`

### Script and direction

- [Studio controls](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/studio_extras.py): `offload/studio_extras.py`
- [Tag guidance](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/tag_guidance.py): `offload/tag_guidance.py`
- [Pronunciation rules](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pronunciation.py): `offload/pronunciation.py`

### Take workflow

- [Long takes and edits](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/long_takes.py): `offload/long_takes.py`
- [Script chunking](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/chunking.py): `offload/chunking.py`
- [Audio infilling](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/infill.py): `offload/infill.py`
- [Repeatable seeds](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/seeds.py): `offload/seeds.py`
- [Subtitle tools](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/subtitles.py): `offload/subtitles.py`

### Quality and audio

- [Word checks](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/word_check.py): `offload/word_check.py`
- [Pause fix](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pause_fix.py): `offload/pause_fix.py`
- [Stall guard](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/stall_guard.py): `offload/stall_guard.py`
- [Sampling controls](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/upstream_sampling.py): `offload/upstream_sampling.py`
- [Reference cache](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/prefix_cache.py): `offload/prefix_cache.py`
- [Reference trimming](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/reference_trim.py): `offload/reference_trim.py`

### Persistent state

- [Pronunciation cache](https://github.com/thomasericb/drama3-offload-studio/blob/main/offload/pronunciation.py): `offload/pronunciation.py`

### Other components

- **Studio user**

## Connections

- Studio user → Studio server: submits script (evidence: `README.md`)
- Studio server → NVIDIA offload: selects backend (evidence: `offload/serve.py`)
- Studio server → Small GGUF: selects backend (evidence: `offload/serve.py`)
- Studio server → Apple MLX: selects backend (evidence: `offload/serve.py`)
- Studio server → Portable engine: selects backend (evidence: `offload/serve.py`)
- Studio server → Studio branding: loads branding (evidence: `offload/serve.py`)
- Studio server → Long takes and edits: installs take hooks (evidence: `offload/serve.py`)
- Studio server → Studio controls: installs controls (evidence: `offload/serve.py`)
- Studio server → Tag guidance: loads guidance (evidence: `offload/serve.py`)
- Studio server → Pronunciation rules: loads rules (evidence: `offload/serve.py`)
- Studio server → Word checks: loads checks (evidence: `offload/serve.py`)
- Studio server → Repeatable seeds: loads seed hooks (evidence: `offload/serve.py`)
- Studio server → Pause fix: installs pause fix (evidence: `offload/serve.py`)
- Studio server → Reference cache: installs cache (evidence: `offload/serve.py`)
- Studio server → Reference trimming: loads reference trim (evidence: `offload/serve.py`)
- Long takes and edits → Script chunking: splits scripts (evidence: `offload/long_takes.py`)
- Long takes and edits → Audio infilling: uses for edits (evidence: `offload/long_takes.py`)
- Long takes and edits → Pronunciation rules: applies rules (evidence: `offload/long_takes.py`)
- Long takes and edits → Repeatable seeds: uses take seeds (evidence: `offload/long_takes.py`)
- Long takes and edits → Subtitle tools: supports subtitles (evidence: `offload/long_takes.py`)
- Long takes and edits → Word checks: checks generated words (evidence: `offload/long_takes.py`)
- Long takes and edits → Pause fix: uses pause fix (evidence: `offload/long_takes.py`)
- Pronunciation rules → Pronunciation cache: reads and writes (evidence: `offload/pronunciation.py`)
- Studio controls → Long takes and edits: controls take edits (evidence: `offload/studio_extras.py`)
- Studio controls → Pronunciation rules: edits rules (evidence: `offload/studio_extras.py`)
- Studio controls → Subtitle tools: offers subtitle tools (evidence: `offload/studio_extras.py`)
- Studio controls → Word checks: configures checks (evidence: `offload/studio_extras.py`)
- Studio controls → Sampling controls: configures sampling (evidence: `offload/studio_extras.py`)
- Apple MLX → Pause fix: applies pause rules (evidence: `offload/drama3_mlx.py`)
- Portable engine → Pause fix: applies pause rules (evidence: `offload/drama3_portable.py`)
- Studio server → Sampling controls: loads sampling (evidence: `offload/serve.py`)
- Studio server → Stall guard: loads stall guard (evidence: `offload/serve.py`)