# manifestro/aqyn architecture

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

- Interactive diagram: https://gitdiagram.com/manifestro/aqyn
- Repository: https://github.com/manifestro/aqyn

## Overview

Aqyn is a research speech-model project whose implemented end-to-end product is Stage 1 streaming text-to-speech: prepare speech and word alignments as Mimi-token data, train the frame-rate model, then synthesize or evaluate audio. Its model combines a sliding text window, configurable temporal backbones and within-frame codebook prediction. The README also describes future hearing/turn-taking and a slow LLM cortex, but these are planned rather than implemented, so they are not shown as runtime components. Relationships are based on the README and SOURCE INDEX references; unsampled internals are not inferred.

Main entry points: [`src/aqyn/train.py`](https://github.com/manifestro/aqyn/blob/main/src/aqyn/train.py) (Training loop), [`src/aqyn/cli.py`](https://github.com/manifestro/aqyn/blob/main/src/aqyn/cli.py) (Aqyn CLI), [`src/aqyn/prepare.py`](https://github.com/manifestro/aqyn/blob/main/src/aqyn/prepare.py) (Corpus preparation), [`src/aqyn/evaluate.py`](https://github.com/manifestro/aqyn/blob/main/src/aqyn/evaluate.py) (Speech evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_pipeline["Data preparation"]
  node_prepare["Corpus preparation<br/>[prepare.py]"]
  node_text["Text normalization<br/>[text.py]"]
  node_align["Word alignment<br/>[align.py]"]
  node_codec["Mimi codec<br/>[codec.py]"]
  node_tokens[("Token datasets<br/>[data.py]")]
end

subgraph group_model_runtime["Speech model"]
  node_tts["Frame-rate TTS<br/>[tts.py]"]
  node_blocks["Backbone blocks<br/>[blocks.py]"]
  node_cfc["CfC recurrence<br/>[cfc.py]"]
end

subgraph group_training["Training"]
  node_config["Experiment config<br/>[config.py]"]
  node_trainer["Training loop<br/>[train.py]"]
  node_checkpoint["Model checkpoints<br/>[checkpoint.py]"]
end

subgraph group_inference_eval["Inference and evaluation"]
  node_synthesis["Audio synthesis<br/>[synthesize.py]"]
  node_evaluation["Speech evaluation<br/>[evaluate.py]"]
  node_asr["ASR service"]
  node_benchmark["Model benchmark<br/>[bench.py]"]
end

node_user(("Researcher"))
node_cli["Aqyn CLI<br/>[cli.py]"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches prepare"| node_prepare
node_cli -->|"dispatches train"| node_trainer
node_cli -->|"dispatches synth"| node_synthesis
node_cli -->|"dispatches eval"| node_evaluation
node_cli -->|"dispatches bench"| node_benchmark
node_prepare -->|"builds vocabulary"| node_text
node_prepare -->|"aligns transcripts"| node_align
node_prepare -->|"encodes audio"| node_codec
node_prepare -->|"writes token data"| node_tokens
node_trainer -->|"loads settings"| node_config
node_trainer -->|"loads batches"| node_tokens
node_trainer -->|"trains model"| node_tts
node_trainer -->|"saves state"| node_checkpoint
node_trainer -->|"decodes samples"| node_codec
node_tts -->|"uses blocks"| node_blocks
node_blocks -->|"uses CfC mixer"| node_cfc
node_synthesis -->|"loads model"| node_checkpoint
node_synthesis -->|"decodes tokens"| node_codec
node_evaluation -->|"loads model"| node_checkpoint
node_evaluation -->|"reads held-out data"| node_tokens
node_evaluation -->|"decodes audio"| node_codec
node_evaluation -->|"transcribes audio"| node_asr

click node_cli "https://github.com/manifestro/aqyn/blob/main/src/aqyn/cli.py"
click node_config "https://github.com/manifestro/aqyn/blob/main/src/aqyn/config.py"
click node_prepare "https://github.com/manifestro/aqyn/blob/main/src/aqyn/prepare.py"
click node_text "https://github.com/manifestro/aqyn/blob/main/src/aqyn/text.py"
click node_align "https://github.com/manifestro/aqyn/blob/main/src/aqyn/align.py"
click node_codec "https://github.com/manifestro/aqyn/blob/main/src/aqyn/codec.py"
click node_tokens "https://github.com/manifestro/aqyn/blob/main/src/aqyn/data.py"
click node_trainer "https://github.com/manifestro/aqyn/blob/main/src/aqyn/train.py"
click node_checkpoint "https://github.com/manifestro/aqyn/blob/main/src/aqyn/checkpoint.py"
click node_tts "https://github.com/manifestro/aqyn/blob/main/src/aqyn/models/tts.py"
click node_blocks "https://github.com/manifestro/aqyn/blob/main/src/aqyn/models/blocks.py"
click node_cfc "https://github.com/manifestro/aqyn/blob/main/src/aqyn/models/cfc.py"
click node_synthesis "https://github.com/manifestro/aqyn/blob/main/src/aqyn/synthesize.py"
click node_evaluation "https://github.com/manifestro/aqyn/blob/main/src/aqyn/evaluate.py"
click node_benchmark "https://github.com/manifestro/aqyn/blob/main/src/aqyn/bench.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_prepare,node_text,node_align,node_codec,node_tokens toneBlue
class node_tts,node_blocks,node_cfc toneAmber
class node_config,node_trainer,node_checkpoint toneMint
class node_synthesis,node_evaluation,node_asr,node_benchmark toneRose
class node_user toneIndigo
class node_cli toneTeal
```

## Components

### Data preparation

- [Corpus preparation](https://github.com/manifestro/aqyn/blob/main/src/aqyn/prepare.py): `src/aqyn/prepare.py`
- [Text normalization](https://github.com/manifestro/aqyn/blob/main/src/aqyn/text.py): `src/aqyn/text.py`
- [Word alignment](https://github.com/manifestro/aqyn/blob/main/src/aqyn/align.py): `src/aqyn/align.py`
- [Mimi codec](https://github.com/manifestro/aqyn/blob/main/src/aqyn/codec.py): `src/aqyn/codec.py`
- [Token datasets](https://github.com/manifestro/aqyn/blob/main/src/aqyn/data.py): `src/aqyn/data.py`

### Speech model

- [Frame-rate TTS](https://github.com/manifestro/aqyn/blob/main/src/aqyn/models/tts.py): `src/aqyn/models/tts.py`
- [Backbone blocks](https://github.com/manifestro/aqyn/blob/main/src/aqyn/models/blocks.py): `src/aqyn/models/blocks.py`
- [CfC recurrence](https://github.com/manifestro/aqyn/blob/main/src/aqyn/models/cfc.py): `src/aqyn/models/cfc.py`

### Training

- [Experiment config](https://github.com/manifestro/aqyn/blob/main/src/aqyn/config.py): `src/aqyn/config.py`
- [Training loop](https://github.com/manifestro/aqyn/blob/main/src/aqyn/train.py): `src/aqyn/train.py`
- [Model checkpoints](https://github.com/manifestro/aqyn/blob/main/src/aqyn/checkpoint.py): `src/aqyn/checkpoint.py`

### Inference and evaluation

- [Audio synthesis](https://github.com/manifestro/aqyn/blob/main/src/aqyn/synthesize.py): `src/aqyn/synthesize.py`
- [Speech evaluation](https://github.com/manifestro/aqyn/blob/main/src/aqyn/evaluate.py): `src/aqyn/evaluate.py`
- **ASR service**
- [Model benchmark](https://github.com/manifestro/aqyn/blob/main/src/aqyn/bench.py): `src/aqyn/bench.py`

### Other components

- **Researcher**
- [Aqyn CLI](https://github.com/manifestro/aqyn/blob/main/src/aqyn/cli.py): `src/aqyn/cli.py`

## Connections

- Researcher → Aqyn CLI: runs commands (evidence: `README.md`)
- Aqyn CLI → Corpus preparation: dispatches prepare (evidence: `README.md`)
- Aqyn CLI → Training loop: dispatches train (evidence: `README.md`)
- Aqyn CLI → Audio synthesis: dispatches synth (evidence: `README.md`)
- Aqyn CLI → Speech evaluation: dispatches eval (evidence: `README.md`)
- Aqyn CLI → Model benchmark: dispatches bench (evidence: `README.md`)
- Corpus preparation → Text normalization: builds vocabulary (evidence: `src/aqyn/prepare.py`)
- Corpus preparation → Word alignment: aligns transcripts (evidence: `src/aqyn/prepare.py`)
- Corpus preparation → Mimi codec: encodes audio (evidence: `src/aqyn/prepare.py`)
- Corpus preparation → Token datasets: writes token data (evidence: `README.md`)
- Training loop → Experiment config: loads settings (evidence: `src/aqyn/train.py`)
- Training loop → Token datasets: loads batches (evidence: `src/aqyn/train.py`)
- Training loop → Frame-rate TTS: trains model (evidence: `src/aqyn/train.py`)
- Training loop → Model checkpoints: saves state (evidence: `src/aqyn/train.py`)
- Training loop → Mimi codec: decodes samples (evidence: `src/aqyn/train.py`)
- Frame-rate TTS → Backbone blocks: uses blocks (evidence: `src/aqyn/models/tts.py`)
- Backbone blocks → CfC recurrence: uses CfC mixer (evidence: `src/aqyn/models/blocks.py`)
- Audio synthesis → Model checkpoints: loads model (evidence: `src/aqyn/synthesize.py`)
- Audio synthesis → Mimi codec: decodes tokens (evidence: `src/aqyn/synthesize.py`)
- Speech evaluation → Model checkpoints: loads model (evidence: `src/aqyn/evaluate.py`)
- Speech evaluation → Token datasets: reads held-out data (evidence: `src/aqyn/evaluate.py`)
- Speech evaluation → Mimi codec: decodes audio (evidence: `src/aqyn/evaluate.py`)
- Speech evaluation → ASR service: transcribes audio (evidence: `src/aqyn/evaluate.py`)
