# MiniMax Voice — Configuration and Environment

## Secrets

All secrets live in `~/.config/environment.d/10-secrets.conf` on `.13`
(mode 600). The file is never committed.

| Key | Purpose |
| :--- | :--- |
| `MINIMAX_SUBSCRIPTION_KEY` | Funded M-Plan/Credits key. Preferred for STT and TTS. |
| `MINIMAX_API_KEY` | Pay-as-you-go key. Returns error 1008 (no balance). Fallback only. |
| `MINIMAX_GROUP_ID` | Group identifier. Not needed by `api.minimax.io`. |
| `OPENROUTER_API_KEY` | Rollback STT primary. |
| `MQTT_USER`, `MQTT_PASS` | MQTT credentials for both brokers. |
| `VIKUNJA_TOKEN`, `OL_API_KEY`, `GITEA_TOKEN` | Project tracking and documentation. |

`environment.d` reaches the systemd user manager. It does not reach a fresh SSH
shell. Pass variables explicitly, or read them from the secrets file.

## STT shim (`voice_stt_shim`)

| Variable | Default | Meaning |
| :--- | :--- | :--- |
| `SHIM_PORT` | `5001` | Bind port. |
| `SHIM_STUB` | `0` | `1` never calls the cloud. |
| `SHIM_REQUIRE_KEY` | `1` | `1` returns 503 when the key is missing. |
| `STT_PROVIDER` | `minimax` | `minimax` or `openai`. |
| `STT_PRIMARY` | provider URL | Explicit primary URL override. |
| `STT_PRIMARY_TIMEOUT` | `3` | Cloud timeout in seconds. |
| `STT_FALLBACK` | `http://127.0.0.1:5002/transcribe` | Local fallback URL. |
| `STT_FALLBACK_TIMEOUT` | `30` | Fallback timeout in seconds. |
| `MINIMAX_STT_URL` | `https://api.minimax.io/v1/speech_to_text` | Endpoint. |
| `MINIMAX_STT_MODEL` | `asr-1.0` | Model. |

The live container uses `STT_PROVIDER=minimax` with MiniMax `asr-1.0`
(AUD-31). To roll back, set `STT_PROVIDER=openai` and rebuild.

## Local fallback (`voice_whisper_fallback`)

| Variable | Default | Meaning |
| :--- | :--- | :--- |
| `WHISPER_MODEL` | `base.en` | Model build argument. |
| Port | `5002` | Fixed contract port. |

The model is built into the image. The container works offline.

## TTS router (`tts_router`)

| Variable | Default | Meaning |
| :--- | :--- | :--- |
| `MINIMAX_SUBSCRIPTION_KEY` | — | Preferred secret. |
| `MINIMAX_TTS_URL` | `https://api.minimax.io/v1/t2a_v2` | Endpoint. |
| `MINIMAX_TTS_MODEL` | `speech-2.8-turbo` | Model. HD for short replies. |
| `MINIMAX_TTS_SAMPLE_RATE` | `32000` | Requested PCM rate. |
| `MINIMAX_TTS_FORMAT` | `pcm` | Keep PCM to avoid a decoder. |
| `MINIMAX_TTS_TIMEOUT` | `8` | Cloud timeout in seconds. |
| `TTS_FALLBACK_VOICE` | `en_US-hal_6409-medium.onnx` | Piper voice on failure. |
| `TTS_SINK` | `snapcast` | `snapcast`, `file:<path>`, or `null`. |
| `TTS_OUT_RATE` | `48000` | Snapcast output rate. |
| `TTS_PAD_LEAD` / `TTS_PAD_TAIL` | `1.0` / `1.2` | Silence padding in seconds. |
| `TTS_EMOTION` / `TTS_PITCH` / `TTS_VOL` | — / `0` / `1.0` | Delivery defaults. |

The router prints one machine-readable line per call:
`[tts] path=minimax voice=... usage_characters=<n>`.

## Voice agent (`voice-agent`)

Agent settings live in `/home/sam/voice-agent/.env`. The important keys are
`SPEAK_CMD` and `DEFAULT_VOICE`. `VOICE_PERSONALITY=0` disables the Phase 4
speech plan without a code change.

## Config paths

| Path | Role |
| :--- | :--- |
| `/home/sam/paseo/projects/minimax_voice_tts_stt/` | Project source and notes. |
| `/home/sam/speech_piper/speak_direct.sh` | Live TTS wrapper. |
| `/home/sam/voice-agent/` | Live agent brain. |
| `/home/sam/voice-agent/voices.json` | Voice registry. |
| `/home/sam/voice_bridge/mqtt_audio_bridge.py` | Wake word and STT caller. |