PhonemPanda

A web-based German pronunciation trainer designed for Chinese-L1 learners. Record yourself saying a German word and get instant feedback powered by Whisper speech recognition running locally on your machine. No cloud API keys required.

Words are grouped by phonetic challenge areas that are typically difficult for Chinese speakers: umlauts, the uvular R, CH sounds, consonant clusters, vowel length contrasts, diphthongs, and W/V distinctions.

System Requirements

• Python 3.12+
• ffmpeg (converts browser WebM/Opus audio to PCM WAV)
• A modern browser with microphone access
• ~460 MB disk space for the Whisper model (downloaded automatically on first use)

Installation

# Install ffmpeg (macOS)
brew install ffmpeg

# Create a virtual environment and install dependencies
uv venv
uv pip install -e .

Prefetch the Whisper Model

The model downloads automatically on the first assessment request. To download it ahead of time (e.g. before going offline):

python -c "from faster_whisper import WhisperModel; WhisperModel('small', compute_type='int8')"

Running

uvicorn app.main:app --host 127.0.0.1 --port 8000

Then open http://127.0.0.1:8000 in your browser.

Docker

docker build -t phonem-panda .
docker run -p 8000:8000 phonem-panda

The Docker image includes the Whisper model — no additional downloads needed at runtime.

Usage

1. Pick a category from the top bar (or "Alle" for all words)
2. Hold the spacebar to record yourself saying the displayed word, release to submit
3. You can also click the microphone button to start/stop recording
4. Review your scores:
   • Gesamtbewertung — overall pronunciation score
   • Genauigkeit — accuracy (how confident Whisper is in what you said)
   • Vollständigkeit — whether Whisper recognized the correct word
5. Use the arrow buttons or navigate through categories to practise more words

Updating the Word List

Words live in app/words.py in the WORD_LIST list. Each entry is a dictionary with three fields:

{"word": "Müde", "hint": "Lippen runden wie bei 'u', aber 'i' sagen", "category": "Umlaute"}

Field	Description
word	The German word to practise
hint	A short pronunciation tip shown to the learner (in German)
category	Groups the word in the UI; pick an existing category or add a new one

To add words, append entries to WORD_LIST. New categories appear in the UI automatically. Restart the server after editing.

Running Tests

uv pip install -e ".[dev]"
pytest tests/ -v

Project Structure

app/
  main.py            FastAPI application and API routes
  assessment.py      Audio conversion (ffmpeg) + Whisper pronunciation assessment
  words.py           Word list and category helpers
static/
  index.html         Single-page frontend
tests/
  test_assessment.py Unit tests for assessment logic
Dockerfile           Container build (includes Whisper model)
pyproject.toml       Python dependencies