xuezh Chinese Learning

Chinese learning engine with pronunciation feedback and study flows via OpenClaw.

xuezh (学中文, 'learn Chinese') by @joshp123 is a sophisticated Mandarin learning engine designed as a CLI tool that integrates with OpenClaw for conversational language study. It provides pronunciation assessment via Azure Speech Services, text-to-speech for listening practice, spaced-repetition review queues, and HSK-level progress tracking — all accessible through natural chat interaction. The tool handles three core learning flows: pronunciation feedback (send a voice note, get detailed assessment of tones, accuracy, and fluency), listen-and-repeat (ask how to say something, get a native-quality audio response), and progress review (SRS-based flashcard reviews with separate recall and pronunciation scoring). It uses Azure Speech for STT and pronunciation assessment, edge-tts for text-to-speech generation, and SQLite for local persistence of study progress. What makes xuezh architecturally interesting is its strict separation of 'engine' (mechanical operations, data persistence, audio processing) and 'model' (lesson planning, pedagogy, choosing what to study next). The engine follows a 'Zero Framework Cognition' principle — it only returns raw data and performs transforms, leaving all pedagogical decisions to the LLM layer. This means OpenClaw's language model handles the teaching strategy while xuezh provides the tools. The primary author is Codex (gpt-5.2-codex), with xuezh being one of the most code-heavy community projects.

Tags: learning, voice, skill, language

Category: knowledge

Tips

  • Get a free Azure Speech key (free tier provides 500K characters/month) — this powers the pronunciation assessment and is the most critical dependency
  • Install via Nix (`nix run github:joshp123/xuezh`) for the cleanest setup with all dependencies managed automatically
  • Use the pronunciation feedback flow regularly — send voice notes of Chinese phrases and get per-syllable tone accuracy scores
  • Configure HSK level tracking to match your study goals — xuezh supports HSK 1-9 with vocabulary and character coverage reports
  • Combine with OpenClaw's cron for daily study reminders and spaced-repetition review sessions delivered to Telegram

Community Feedback

@joshp123 created 'xuezh,' a Chinese learning engine with pronunciation feedback. A language tutor that lives in their messaging app.

— Generative AI Publication

xuezh is a local learning engine for Mandarin study. It is designed to be used as a tool/skill behind a bot runtime + SOTA LLM. Recommended integration: Clawdbot.

— GitHub

Chinese learning engine with pronunciation feedback and study flows via OpenClaw. Send a voice note, get detailed assessment of tones and accuracy.

— OpenClaw Showcase

Frequently Asked Questions

Do I need to know any Chinese to start using xuezh?

No. xuezh supports all HSK levels starting from beginner (HSK 1). The LLM handles lesson planning and adapts to your level. Start with basic phrases and the tool tracks your progress.

What's the Zero Framework Cognition (ZFC) principle?

ZFC means the xuezh engine never makes pedagogical decisions — it only provides data and mechanical transforms. All decisions about what to study, lesson order, and difficulty progression are handled by the LLM (OpenClaw's model). This keeps the engine simple and the teaching strategy flexible.

Can I use this for languages other than Chinese?

xuezh is specifically designed for Mandarin Chinese, with tone-specific pronunciation assessment that's tailored to Chinese phonology. The architecture could theoretically be adapted for other languages, but you'd need a different pronunciation assessment backend.

Does it work offline?

The engine itself runs locally, but pronunciation assessment requires Azure Speech Services (cloud API). TTS can use edge-tts which is free but also cloud-based. A Whisper-based local fallback exists for STT, but Azure provides better Chinese pronunciation assessment.