d8devs/mathassist-audio repository overview

⁠MathAssist Audio Service (Docker)

Self‑hosted audio microservice providing:

• STT: Speech‑to‑Text via faster‑whisper (CPU)
• TTS: Text‑to‑Speech via Piper + ONNX voices

This service is called by the web app for microphone transcription and answer playback.

⁠Quick Start

• Build and run with Compose (from repo root):

docker compose -f docker/docker-compose.yml build
docker compose -f docker/docker-compose.yml up -d

• API: http://localhost:8001⁠

• Add at least one Piper voice (see Voices below), then verify:

curl -s http://localhost:8001/tts/voices | jq

⁠Endpoints

• GET / → { service, stt_model, voices }
• POST /stt (multipart)
  • fields:
    • audio: audio file (webm/ogg/wav)
    • language: optional (auto, en, de, tr, …)
  • returns: { text, language, language_probability }
• GET /tts/voices → { voices: ["de_DE-thorsten-low.onnx", ...] }
• POST /tts (form)
  • fields: text, voice (filename from /voices)
  • returns: audio/wav stream
• POST /tts/voice_from_url (form)
  • fields: url (direct .onnx), config_url (matching .onnx.json, optional)
  • downloads files into /voices
• POST /tts/voice_upload (multipart)
  • fields: onnx (file), config (file) → saves both into /voices

⁠Voices

Piper requires a voice pair: voice.onnx and voice.onnx.json.

Options to install voices on the host:

• Manual: download from Hugging Face (use resolve/main, not blob):

https://huggingface.co/datasets/rhasspy/piper-voices/resolve/main/de/de_DE/thorsten-low/de_DE-thorsten-low.onnx
https://huggingface.co/datasets/rhasspy/piper-voices/resolve/main/de/de_DE/thorsten-low/de_DE-thorsten-low.onnx.json

⁠Mounting the voices directory

Compose mounts ./voices:/voices by default. Make sure your files are under ./voices.

If you downloaded to docker/voices, either:

• Move them: mkdir -p voices && mv docker/voices/* voices/ && docker compose -f docker/docker-compose.yml restart
• Or change the mount in docker/docker-compose.yml to ./docker/voices:/voices and restart.

⁠Configuration

Environment variables (see docker/docker-compose.yml):

• STT_MODEL (default small) – faster‑whisper model id
• STT_COMPUTE_TYPE (default int8) – e.g. int8, int8_float16, int16, float16
• STT_LANGUAGE (default auto) – language hint for STT

The image enables CORS for browser access.

⁠Examples

• STT:

curl -s -X POST http://localhost:8001/stt \
  -F language=de \
  -F audio=@/path/to/sample.wav

• TTS:

curl -s -X POST http://localhost:8001/tts \
  -F text='Hallo! Ich helfe dir bei Mathe.' \
  -F voice=de_DE-thorsten-low.onnx \
  -o out.wav && \
  ffplay -nodisp -autoexit out.wav

⁠Build & Push (Docker Hub)

• One‑off:

docker build -t YOUR_DH_USER/mathassist-audio:latest -f docker/Dockerfile .
docker login
docker push YOUR_DH_USER/mathassist-audio:latest

• Multi‑arch:

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t YOUR_DH_USER/mathassist-audio:latest \
  -f docker/Dockerfile --push .

For README sync and automated pushes, consider a GitHub Actions workflow using docker/build-push-action and peter-evans/dockerhub-description.

⁠Licensing

• Engine: Piper (MIT), faster‑whisper (MIT)
• Models/voices: check each voice’s license (many are CC‑BY‑4.0 or CC0; commercial use allowed with attribution; verify before distribution).

⁠Troubleshooting

• /tts/voices is empty
  • Ensure voices are under the mounted path (./voices by default). Restart the container after adding files.
• STT works but TTS fails
  • Check selected voice exists in /voices and the .onnx.json is present.
• CORS errors in browser
  • This image enables permissive CORS. If accessing from a different host, ensure network/firewall allows it.