Learn a Language With Voice Flashcards on Telnyx — TTS Speaks, You Repeat, AI Scores

Language learning apps work fine on a screen, but the hardest part of picking up a new language is the thing screens avoid: actually speaking out loud, in real time, and getting immediate feedback on whether you said it right.

Most voice-based language tools either play a recording or transcribe your speech — they don't do both in an interactive loop. This example does. Telnyx TTS speaks a flashcard phrase, you repeat it back, Telnyx STT transcribes your speech, and Telnyx Inference scores your pronunciation as correct, close, or wrong. All three AI primitives in one loop, one platform, one API key.

The canonical code example is in the Telnyx code examples repo:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/language-learning-flashcards-python

The Use Case: Interactive Pronunciation Practice

Flashcard apps show you a word and ask you to type it. Voice flashcards play a word and ask you to say it. The difference is the feedback loop: you hear the correct pronunciation, you attempt it, and the app tells you whether you got it right.

This example solves that. The app plays a phrase in Spanish (or French) using a native-sounding Ultra voice. You record yourself repeating it. The app sends your recording to Telnyx STT for transcription, then asks Telnyx Inference to compare your transcription against the target phrase. The result is a score — correct, close, or wrong — plus a one-sentence tip.

The default decks are Spanish greetings, numbers, common phrases, and French greetings. Each deck has 6-8 cards. You can add more by editing one Python dict.

How It Uses All Three Telnyx AI Primitives

Most Telnyx examples use one or two AI primitives. This one uses all three in a single interactive loop:

One platform, one API key, no external services. The browser captures audio; the server does the rest.

The Voices

The app uses native Ultra voices per language — not one English voice with language_boost:

To add more languages, enumerate voices via GET /v2/text-to-speech/voices and add them to LANGUAGE_VOICE_MAP in app.py.

How the Scoring Works

The Inference call uses a system prompt that tells the model to compare the target phrase against the user's spoken text and return JSON:

You are a language pronunciation checker.
Compare the target phrase with what the user said.
Return ONLY valid JSON: {"score": "correct"|"close"|"wrong", "feedback": "one short sentence tip"}

The model evaluates whether the spoken text matches the target phrase, accounting for minor accent differences (correct), noticeable errors (close), or completely wrong speech (wrong). Kimi-K2.6 is a reasoning model — it takes ~10 seconds to think before scoring, but the result is more nuanced than a simple string comparison.

Architecture

  Telnyx TTS plays flashcard phrase
              ↓
      You listen and repeat
              ↓
  Browser records your voice
              ↓
     POST /check (audio + target phrase)
              ↓
  Telnyx STT transcribes your speech
              ↓
  Telnyx Inference compares + scores
              ↓
   Score: correct / close / wrong
   + feedback + target vs spoken
              ↓
       Next card or try again

The Flask app is the orchestrator. TTS, STT, and Inference all run on Telnyx infrastructure. The browser captures audio and displays results. The server does the rest.

Run It

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/language-learning-flashcards-python
cp .env.example .env    # fill in TELNYX_API_KEY
pip install -r requirements.txt
python app.py           # starts on http://127.0.0.1:5050

Open the browser, pick a deck, listen, repeat, get scored.

Where This Goes Next

• Add more languages and decks (German, Italian, Portuguese, Japanese, Hindi).
• Add a streak counter or score tracking across a deck.
• Add difficulty levels (speed challenge, no-translation hint).
• Replace in-memory store with persistent storage for progress tracking.
• Add a "free practice" mode where the user says any phrase and gets a pronunciation score.

The point is the interactive loop: TTS speaks, you repeat, STT transcribes, Inference scores. Everything else follows from that.

Related Examples

• ai-language-learning-phone-tutor-python — phone-based language tutor (Call Control, not AI Assistant)
• ai-content-translator-python — STT + translate + TTS pipeline (one-directional)
• multi-character-narrator-python — multi-voice TTS with SSML emotions