# MiniMax Voice — Code Map

## Folder structure

```
minimax_voice_tts_stt/
├── AGENTS.md              Project brief and full history.
├── README.md             Technical README.
├── docs/
│   ├── minimax-voice-flow.mmd          Mermaid source.
│   ├── diagrams/                       Rendered PNG.
│   ├── archify/                        Archify JSON specification.
│   ├── minimax-voice-map.html          Interactive Archify map.
│   └── outline/                        These AI-context documents.
├── notes/                 Per-phase engineering notes.
├── benchmark/             STT benchmark harness and corpus.
│   ├── bench.py                        Endpoint benchmark.
│   ├── corpus/                         Real 22-command human corpus.
│   ├── proxy-corpus-piper/             Synthetic piper clips.
│   └── results/                        Raw JSON and text results.
├── voice_stt_shim/        Cloud STT shim (port 5001).
├── voice_whisper_fallback/ Local STT fallback (port 5002).
└── tts_router/            TTS router and speech plan.
```

## Entry points

| Entry point | Language | Role |
| :--- | :--- | :--- |
| `voice_stt_shim/shim.py` | Python 3 | `POST /transcribe` service. |
| `voice_whisper_fallback/app.py` | Python 3 | Local fallback service. |
| `tts_router/tts_router.py` | Python 3 | TTS CLI called by `speak_direct.sh`. |
| `benchmark/bench.py` | Python 3 | Corpus benchmark. |

## Key modules

| Module | Role |
| :--- | :--- |
| `voice_stt_shim/shim.py` | WAV decode, cloud call, fallback chain, secret precedence. |
| `tts_router/tts_core.py` | MiniMax T2A client, hex decode, peak ceiling, sound tags. |
| `tts_router/speech_plan.py` | Speech-plan schema, mood policy, clamping. |
| `tts_router/snapcast_send.py` | Resampler and Snapcast sender. |
| `benchmark/bench.py` | Latency, word error rate, and memory measurement. |

## Tests

| Test file | Tests | Scope |
| :--- | :--- | :--- |
| `tts_router/test_tts_router.py` | 74 | Routing, decode, resample, fallbacks, speech plan. |
| `voice_stt_shim/test_contract.py` | 7 | Secret precedence and the STT contract. |
| `voice_bridge/test_transcribe_and_send.py` + `test_corpus_capture.py` | 13 | Bridge caller and corpus capture. |
| `benchmark/test_bench_normalise.py` | 7 | Scoring normalisation. |

All suites pass on 2026-10-08 (AUD-34). Raw logs: `benchmark/results/aud32/`.

## Dependencies

The shim and router use the Python standard library only. There are no pip
packages. Both images use `python:3.9-slim`. The fallback image adds `flask`
and `faster-whisper`, and bakes the `base.en` model at build time.

System tools: Docker, Docker Compose, `mmdc` (Mermaid), Node.js (Archify).

## Data flow

1. `voice_bridge/mqtt_audio_bridge.py` sends a WAV to `voice_stt_shim`.
2. `shim.py` decodes the WAV to mono 16 kHz int16.
3. `shim.py` calls the cloud, or the fallback on failure.
4. The transcript goes to `homeassistant/voice/text` on the `.30` broker.
5. `voice-agent/app.py` runs the LLM and calls tools.
6. `voice-agent` calls `speak_direct.sh` with the reply text.
7. `speak_direct.sh` runs `tts_router.py`.
8. `tts_router.py` calls MiniMax T2A, or piper on failure.
9. `snapcast_send.py` resamples to 48 kHz stereo and sends to Snapcast.