# jamesondh/chimera-vocal-synth architecture

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

- Interactive diagram: https://gitdiagram.com/jamesondh/chimera-vocal-synth
- Repository: https://github.com/jamesondh/chimera-vocal-synth

## Overview

CHIMERA is a browser-based physical-model voice synthesizer, with a Rust engine compiled to WebAssembly and run in an AudioWorklet. The user workflow runs from interactive controls or speech, song, and beatbox inputs through gesture planning and real-time synthesis to audio playback and live visualizations. The graph also includes the creature catalog, duet display, and native CLI for offline renders and acoustic comparison. Several internal links are supported only by the README or the source index; unsampled implementation details are not inferred.

Main entry points: [`crates/chimera/src/engine.rs`](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/engine.rs) (Voice engine), [`src/ui/App.tsx`](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/App.tsx) (App surface), [`crates/chimera-cli/src/main.rs`](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/main.rs) (CLI commands), [`crates/chimera/src/voice/human_voice.rs`](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/voice/human_voice.rs) (Human voice)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Browser app"]
  node_app["App surface<br/>[App.tsx]"]
  node_controls["Play controls"]
  node_visuals["Live displays"]
  node_vector["Vector rendering<br/>[vector.ts]"]
  node_duet["Duet display<br/>[DuetPage.tsx]"]
end

subgraph group_audio["Audio runtime"]
  node_audio["Audio engine<br/>[AudioEngine.ts]"]
  node_worklet["AudioWorklet<br/>[processor.ts]"]
  node_wasmboundary["Wasm bridge<br/>[chimera.ts]"]
end

subgraph group_synthesis["Synthesis engine"]
  node_engine["Voice engine<br/>[engine.rs]"]
  node_humanvoice["Human voice<br/>[human_voice.rs]"]
  node_airway["Airway network<br/>[network.rs]"]
  node_anatomy["Human anatomy<br/>[human.rs]"]
  node_creatures["Creature voices<br/>[voice.rs]"]
end

subgraph group_language["Language and music"]
  node_speech["Speech input<br/>[speech.ts]"]
  node_singing["Singing<br/>[singing.ts]"]
  node_songfit["Tune fitting<br/>[fit.ts]"]
  node_beatbox["Beatbox<br/>[beatbox.rs]"]
  node_planner["Gesture planner<br/>[planner.rs]"]
end

subgraph group_offline["Offline tools"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_render["Offline rendering<br/>[render.rs]"]
  node_compare["Voice comparison<br/>[compare.rs]"]
  node_diagnose["Voice diagnostics<br/>[diagnose.rs]"]
  node_wav["WAV output<br/>[wav.rs]"]
end

node_performer(("Performer"))

node_performer -->|"uses"| node_app
node_app -->|"presents"| node_controls
node_performer -->|"enters text"| node_speech
node_performer -->|"enters lyrics"| node_singing
node_performer -->|"plays pads"| node_beatbox
node_singing -->|"fits phrases"| node_songfit
node_speech -->|"plans gestures"| node_planner
node_singing -.->|"plans gestures"| node_planner
node_app -->|"controls playback"| node_audio
node_audio -->|"loads worklet"| node_worklet
node_worklet -->|"uses bridge"| node_wasmboundary
node_wasmboundary -->|"invokes engine"| node_engine
node_planner -.->|"supplies gestures"| node_engine
node_engine -->|"drives voice"| node_humanvoice
node_engine -->|"selects creature"| node_creatures
node_humanvoice -->|"uses network"| node_airway
node_humanvoice -->|"uses geometry"| node_anatomy
node_app -->|"shows state"| node_visuals
node_visuals -->|"draws with"| node_vector
node_performer -->|"opens show"| node_duet
node_cli -->|"dispatches render"| node_render
node_cli -->|"dispatches compare"| node_compare
node_cli -->|"dispatches diagnose"| node_diagnose
node_render -.->|"renders audio"| node_engine
node_render -.->|"writes WAV"| node_wav

click node_app "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/App.tsx"
click node_controls "https://github.com/jamesondh/chimera-vocal-synth/tree/main/src/ui/components"
click node_speech "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/speech.ts"
click node_singing "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/singing.ts"
click node_songfit "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/song/fit.ts"
click node_beatbox "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/phonetics/beatbox.rs"
click node_planner "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/phonetics/planner.rs"
click node_audio "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/audio/AudioEngine.ts"
click node_worklet "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/worklet/processor.ts"
click node_wasmboundary "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/wasm/chimera.ts"
click node_engine "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/engine.rs"
click node_humanvoice "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/voice/human_voice.rs"
click node_airway "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/airway/network.rs"
click node_anatomy "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/anatomy/human.rs"
click node_creatures "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/creatures/voice.rs"
click node_visuals "https://github.com/jamesondh/chimera-vocal-synth/tree/main/src/ui/components"
click node_vector "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/render/vector.ts"
click node_duet "https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/components/DuetPage.tsx"
click node_cli "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/main.rs"
click node_render "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/render.rs"
click node_compare "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/compare.rs"
click node_diagnose "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/diagnose.rs"
click node_wav "https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/wav.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_app,node_controls,node_visuals,node_vector,node_duet toneBlue
class node_audio,node_worklet,node_wasmboundary toneAmber
class node_engine,node_humanvoice,node_airway,node_anatomy,node_creatures toneMint
class node_speech,node_singing,node_songfit,node_beatbox,node_planner toneRose
class node_cli,node_render,node_compare,node_diagnose,node_wav,node_performer toneIndigo
```

## Components

### Browser app

- [App surface](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/App.tsx): `src/ui/App.tsx`
- [Play controls](https://github.com/jamesondh/chimera-vocal-synth/tree/main/src/ui/components): `src/ui/components`
- [Live displays](https://github.com/jamesondh/chimera-vocal-synth/tree/main/src/ui/components): `src/ui/components`
- [Vector rendering](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/render/vector.ts): `src/ui/render/vector.ts`
- [Duet display](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/components/DuetPage.tsx): `src/ui/components/DuetPage.tsx`

### Audio runtime

- [Audio engine](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/audio/AudioEngine.ts): `src/audio/AudioEngine.ts`
- [AudioWorklet](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/worklet/processor.ts): `src/worklet/processor.ts`
- [Wasm bridge](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/wasm/chimera.ts): `src/wasm/chimera.ts`

### Synthesis engine

- [Voice engine](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/engine.rs): `crates/chimera/src/engine.rs`
- [Human voice](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/voice/human_voice.rs): `crates/chimera/src/voice/human_voice.rs`
- [Airway network](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/airway/network.rs): `crates/chimera/src/airway/network.rs`
- [Human anatomy](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/anatomy/human.rs): `crates/chimera/src/anatomy/human.rs`
- [Creature voices](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/creatures/voice.rs): `crates/chimera/src/creatures/voice.rs`

### Language and music

- [Speech input](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/speech.ts): `src/ui/speech.ts`
- [Singing](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/ui/singing.ts): `src/ui/singing.ts`
- [Tune fitting](https://github.com/jamesondh/chimera-vocal-synth/blob/main/src/song/fit.ts): `src/song/fit.ts`
- [Beatbox](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/phonetics/beatbox.rs): `crates/chimera/src/phonetics/beatbox.rs`
- [Gesture planner](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera/src/phonetics/planner.rs): `crates/chimera/src/phonetics/planner.rs`

### Offline tools

- [CLI commands](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/main.rs): `crates/chimera-cli/src/main.rs`
- [Offline rendering](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/render.rs): `crates/chimera-cli/src/render.rs`
- [Voice comparison](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/compare.rs): `crates/chimera-cli/src/compare.rs`
- [Voice diagnostics](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/diagnose.rs): `crates/chimera-cli/src/diagnose.rs`
- [WAV output](https://github.com/jamesondh/chimera-vocal-synth/blob/main/crates/chimera-cli/src/wav.rs): `crates/chimera-cli/src/wav.rs`

### Other components

- **Performer**

## Connections

- Performer → App surface: uses (evidence: `README.md`)
- App surface → Play controls: presents (evidence: `src/ui/App.tsx`)
- Performer → Speech input: enters text (evidence: `README.md`)
- Performer → Singing: enters lyrics (evidence: `README.md`)
- Performer → Beatbox: plays pads (evidence: `README.md`)
- Singing → Tune fitting: fits phrases (evidence: `README.md`)
- Speech input → Gesture planner: plans gestures (evidence: `README.md`)
- Singing → Gesture planner: plans gestures
- App surface → Audio engine: controls playback (evidence: `src/ui/App.tsx`)
- Audio engine → AudioWorklet: loads worklet (evidence: `src/audio/AudioEngine.ts`)
- AudioWorklet → Wasm bridge: uses bridge (evidence: `README.md`)
- Wasm bridge → Voice engine: invokes engine (evidence: `README.md`)
- Gesture planner → Voice engine: supplies gestures
- Voice engine → Human voice: drives voice (evidence: `crates/chimera/src/engine.rs`)
- Voice engine → Creature voices: selects creature (evidence: `crates/chimera/src/engine.rs`)
- Human voice → Airway network: uses network (evidence: `crates/chimera/src/voice/human_voice.rs`)
- Human voice → Human anatomy: uses geometry (evidence: `crates/chimera/src/voice/human_voice.rs`)
- App surface → Live displays: shows state (evidence: `src/ui/App.tsx`)
- Live displays → Vector rendering: draws with (evidence: `src/ui/components/CreatureView.tsx`)
- Performer → Duet display: opens show (evidence: `README.md`)
- CLI commands → Offline rendering: dispatches render (evidence: `crates/chimera-cli/src/main.rs`)
- CLI commands → Voice comparison: dispatches compare (evidence: `crates/chimera-cli/src/main.rs`)
- CLI commands → Voice diagnostics: dispatches diagnose (evidence: `crates/chimera-cli/src/main.rs`)
- Offline rendering → Voice engine: renders audio
- Offline rendering → WAV output: writes WAV
