# metavoiceio/metavoice-src architecture

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

- Interactive diagram: https://gitdiagram.com/metavoiceio/metavoice-src
- Repository: https://github.com/metavoiceio/metavoice-src

## Overview

MetaVoice-1B is a text-to-speech system: users supply text and a reference or preset voice, and receive synthesized speech. Its documented generation stages predict EnCodec tokens with a causal model, predict remaining codebooks with a non-causal model, decode tokens to waveform, and enhance the audio. The repository also provides a web UI, inference server, and first-stage finetuning. Some stage implementations and server wiring were not excerpted, so those connections are included only where the README documents them.

Main entry points: [`fam/llm/fast_inference.py`](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_inference.py) (Fast TTS API), [`fam/llm/fast_inference_utils.py`](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_inference_utils.py) (Generation utilities), [`fam/llm/loaders/training_data.py`](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/loaders/training_data.py) (Training dataset), [`fam/llm/model.py`](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/model.py) (GPT model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web_ui["Web UI<br/>[app.py]"]
  node_inference_server["Inference server<br/>[serving.py]"]
end

subgraph group_generation["Speech generation"]
  node_fast_tts["Fast TTS API<br/>[fast_inference.py]"]
  node_generation_utils["Generation utilities"]
  node_fast_model["Fast transformer<br/>[fast_model.py]"]
  node_quantization["Quantization<br/>[fast_quantize.py]"]
  node_inference_model["Inference model<br/>[inference.py]"]
  node_gpt["GPT model<br/>[model.py]"]
  node_causal["Causal generation<br/>[causal.py]"]
  node_noncausal["Non-causal generation<br/>[non_causal.py]"]
  node_attention["Attention layers<br/>[attn.py]"]
end

subgraph group_audio["Audio and voice"]
  node_adapters["EnCodec token adapters"]
  node_decoder["EnCodec decoder<br/>[decoders.py]"]
  node_enhancer["Audio enhancer<br/>[enhancers.py]"]
  node_speaker_encoder["Speaker encoder<br/>[model.py]"]
  node_speaker_audio["Speaker audio features<br/>[audio.py]"]
  node_tokenizer["Text tokenizer<br/>[tokenise.py]"]
end

subgraph group_training["Training"]
  node_preprocessing["Training preprocessing"]
  node_data_pipeline["Batch preparation<br/>[data_pipeline.py]"]
  node_training_data["Training dataset<br/>[training_data.py]"]
  node_finetuning["First-stage finetuning<br/>[finetune.py]"]
end

subgraph group_support["Runtime support"]
  node_telemetry["Telemetry client<br/>[posthog.py]"]
end

node_user(("User"))
node_posthog["PostHog"]

node_user -->|"provides text"| node_web_ui
node_user -->|"requests synthesis"| node_inference_server
node_web_ui -->|"calls synthesis"| node_fast_tts
node_inference_server -->|"uses inference"| node_fast_tts
node_fast_tts -->|"generates tokens"| node_generation_utils
node_fast_tts -->|"runs second stage"| node_inference_model
node_fast_tts -->|"decodes tokens"| node_adapters
node_fast_tts -->|"builds voice model"| node_speaker_encoder
node_generation_utils -->|"loads model"| node_fast_model
node_generation_utils -->|"configures weights"| node_quantization
node_generation_utils -->|"loads tokenizer"| node_tokenizer
node_generation_utils -->|"loads embedder"| node_speaker_encoder
node_inference_model -->|"constructs model"| node_gpt
node_gpt -->|"uses generation mixin"| node_causal
node_gpt -->|"uses generation mixin"| node_noncausal
node_gpt -->|"uses attention"| node_attention
node_speaker_encoder -->|"extracts features"| node_speaker_audio
node_training_data -->|"encodes captions"| node_tokenizer
node_training_data -->|"embeds audio"| node_speaker_encoder
node_training_data -->|"combines tokens"| node_preprocessing
node_training_data -->|"pads tokens"| node_data_pipeline
node_finetuning -->|"loads batches"| node_training_data
node_finetuning -->|"trains model"| node_gpt
node_fast_tts -->|"decodes waveform"| node_decoder
node_decoder -->|"cleans audio"| node_enhancer
node_fast_tts -->|"records events"| node_telemetry
node_telemetry -->|"sends events"| node_posthog

click node_web_ui "https://github.com/metavoiceio/metavoice-src/blob/main/app.py"
click node_inference_server "https://github.com/metavoiceio/metavoice-src/blob/main/serving.py"
click node_fast_tts "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_inference.py"
click node_generation_utils "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_inference_utils.py"
click node_fast_model "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_model.py"
click node_quantization "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_quantize.py"
click node_inference_model "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/inference.py"
click node_gpt "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/model.py"
click node_causal "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/mixins/causal.py"
click node_noncausal "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/mixins/non_causal.py"
click node_attention "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/layers/attn.py"
click node_adapters "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/adapters/flattened_encodec.py"
click node_decoder "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/decoders.py"
click node_enhancer "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/enhancers.py"
click node_speaker_encoder "https://github.com/metavoiceio/metavoice-src/blob/main/fam/quantiser/audio/speaker_encoder/model.py"
click node_speaker_audio "https://github.com/metavoiceio/metavoice-src/blob/main/fam/quantiser/audio/speaker_encoder/audio.py"
click node_tokenizer "https://github.com/metavoiceio/metavoice-src/blob/main/fam/quantiser/text/tokenise.py"
click node_preprocessing "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/preprocessing/audio_token_mode.py"
click node_data_pipeline "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/preprocessing/data_pipeline.py"
click node_training_data "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/loaders/training_data.py"
click node_finetuning "https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/finetune.py"
click node_telemetry "https://github.com/metavoiceio/metavoice-src/blob/main/fam/telemetry/posthog.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_web_ui,node_inference_server,node_user toneBlue
class node_fast_tts,node_generation_utils,node_fast_model,node_quantization,node_inference_model,node_gpt,node_causal,node_noncausal,node_attention toneAmber
class node_adapters,node_decoder,node_enhancer,node_speaker_encoder,node_speaker_audio,node_tokenizer toneMint
class node_preprocessing,node_data_pipeline,node_training_data,node_finetuning toneRose
class node_telemetry,node_posthog toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/metavoiceio/metavoice-src/blob/main/app.py): `app.py`
- [Inference server](https://github.com/metavoiceio/metavoice-src/blob/main/serving.py): `serving.py`

### Speech generation

- [Fast TTS API](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_inference.py): `fam/llm/fast_inference.py`
- [Generation utilities](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_inference_utils.py): `fam/llm/fast_inference_utils.py`
- [Fast transformer](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_model.py): `fam/llm/fast_model.py`
- [Quantization](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/fast_quantize.py): `fam/llm/fast_quantize.py`
- [Inference model](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/inference.py): `fam/llm/inference.py`
- [GPT model](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/model.py): `fam/llm/model.py`
- [Causal generation](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/mixins/causal.py): `fam/llm/mixins/causal.py`
- [Non-causal generation](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/mixins/non_causal.py): `fam/llm/mixins/non_causal.py`
- [Attention layers](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/layers/attn.py): `fam/llm/layers/attn.py`

### Audio and voice

- [EnCodec token adapters](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/adapters/flattened_encodec.py): `fam/llm/adapters/flattened_encodec.py`
- [EnCodec decoder](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/decoders.py): `fam/llm/decoders.py`
- [Audio enhancer](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/enhancers.py): `fam/llm/enhancers.py`
- [Speaker encoder](https://github.com/metavoiceio/metavoice-src/blob/main/fam/quantiser/audio/speaker_encoder/model.py): `fam/quantiser/audio/speaker_encoder/model.py`
- [Speaker audio features](https://github.com/metavoiceio/metavoice-src/blob/main/fam/quantiser/audio/speaker_encoder/audio.py): `fam/quantiser/audio/speaker_encoder/audio.py`
- [Text tokenizer](https://github.com/metavoiceio/metavoice-src/blob/main/fam/quantiser/text/tokenise.py): `fam/quantiser/text/tokenise.py`

### Training

- [Training preprocessing](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/preprocessing/audio_token_mode.py): `fam/llm/preprocessing/audio_token_mode.py`
- [Batch preparation](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/preprocessing/data_pipeline.py): `fam/llm/preprocessing/data_pipeline.py`
- [Training dataset](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/loaders/training_data.py): `fam/llm/loaders/training_data.py`
- [First-stage finetuning](https://github.com/metavoiceio/metavoice-src/blob/main/fam/llm/finetune.py): `fam/llm/finetune.py`

### Runtime support

- [Telemetry client](https://github.com/metavoiceio/metavoice-src/blob/main/fam/telemetry/posthog.py): `fam/telemetry/posthog.py`

### Other components

- **User**
- **PostHog**

## Connections

- User → Web UI: provides text
- User → Inference server: requests synthesis
- Web UI → Fast TTS API: calls synthesis (evidence: `app.py`)
- Inference server → Fast TTS API: uses inference (evidence: `serving.py`)
- Fast TTS API → Generation utilities: generates tokens (evidence: `fam/llm/fast_inference.py`)
- Fast TTS API → Inference model: runs second stage (evidence: `fam/llm/fast_inference.py`)
- Fast TTS API → EnCodec token adapters: decodes tokens (evidence: `fam/llm/fast_inference.py`)
- Fast TTS API → Speaker encoder: builds voice model
- Generation utilities → Fast transformer: loads model (evidence: `fam/llm/fast_inference_utils.py`)
- Generation utilities → Quantization: configures weights (evidence: `fam/llm/fast_inference_utils.py`)
- Generation utilities → Text tokenizer: loads tokenizer (evidence: `fam/llm/fast_inference_utils.py`)
- Generation utilities → Speaker encoder: loads embedder (evidence: `fam/llm/fast_inference_utils.py`)
- Inference model → GPT model: constructs model (evidence: `fam/llm/inference.py`)
- GPT model → Causal generation: uses generation mixin (evidence: `fam/llm/model.py`)
- GPT model → Non-causal generation: uses generation mixin (evidence: `fam/llm/model.py`)
- GPT model → Attention layers: uses attention (evidence: `fam/llm/model.py`)
- Speaker encoder → Speaker audio features: extracts features (evidence: `fam/quantiser/audio/speaker_encoder/model.py`)
- Training dataset → Text tokenizer: encodes captions (evidence: `fam/llm/loaders/training_data.py`)
- Training dataset → Speaker encoder: embeds audio (evidence: `fam/llm/loaders/training_data.py`)
- Training dataset → Training preprocessing: combines tokens (evidence: `fam/llm/loaders/training_data.py`)
- Training dataset → Batch preparation: pads tokens (evidence: `fam/llm/loaders/training_data.py`)
- First-stage finetuning → Training dataset: loads batches (evidence: `fam/llm/finetune.py`)
- First-stage finetuning → GPT model: trains model (evidence: `fam/llm/finetune.py`)
- Fast TTS API → EnCodec decoder: decodes waveform (evidence: `fam/llm/fast_inference.py`)
- EnCodec decoder → Audio enhancer: cleans audio
- Fast TTS API → Telemetry client: records events (evidence: `fam/llm/fast_inference.py`)
- Telemetry client → PostHog: sends events (evidence: `fam/telemetry/posthog.py`)
