Japanese N5 Tutor

Overview

The Japanese N5 Tutor covers the full JLPT N5 curriculum — 572 vocabulary words, 100 kanji, hiragana, katakana, grammar patterns, reading passages, and 15 AI tutor conversation lessons. The target is conversational confidence in VRChat-style Japanese, not exam preparation.

At the core is FSRS-6, a state-of-the-art spaced repetition algorithm. Every word, kana, and kanji you study gets its own memory model tracking personal stability and difficulty. The app tells you exactly when to review each item and gates new content behind mastery thresholds so you're never overwhelmed.

The AI tutor is Yuki — a conversation-first teacher powered by a local LLM. She remembers your name, hobbies, and background across sessions. Every Japanese line she speaks plays automatically via VOICEVOX, a local text-to-speech engine. All speaking practice runs through Whisper for offline transcription and pronunciation scoring.

572 Vocabulary Words

100 N5 Kanji

15 Tutor Lessons

84 Source Files

Spaced Repetition — FSRS-6

How Memory Works

Every item you study — each word, kana character, and kanji — gets its own memory model with two personal parameters: Stability (how long you'll remember it) and Difficulty (how hard this specific item is for you). After each answer, FSRS-6 updates both and schedules exactly when you should see it next.

Correct answers push the next review further out. Wrong answers reset it to tomorrow. Items climb a five-step status ladder, with streak requirements at each gate to prove genuine retention.

Unseen

Not yet introduced

Introduced

2 correct in a row to leave

Learning

4 correct in a row to leave

Known

8 correct in a row to leave

Mastered

Long-term retention proven

CURRICULUM GATES

Hiragana 80% known ↓ Unlocks Katakana Katakana 80% known ↓ Unlocks Vocabulary Unlocks Grammar Unlocks Kanji Vocabulary 40% known ↓ Unlocks Reading Thresholds are in config.py and can be adjusted.

Study Modes — 13 Ways to Learn

🔥

Daily Review

The main 15-minute loop: 5 min SRS flashcards (due items + weak items + new introductions) → 5 min VRChat conversation with AI → 5 min reading passage + comprehension question.

📚

Vocabulary Hub

5 ways to study the same 572 words: Flashcards with audio, Multiple Choice (4-option), Typing Drill with fuzzy matching, Fill in the Blank, Word Match (6 pairs, 5 rounds). Overview grid shows every word colour-coded by SRS status.

🎓

AI Tutor Lessons

15 conversation-first lessons with Yuki. She shows Japanese examples before grammar explanations, gives 3-step corrections (acknowledge → problem → retry), and remembers your name and background. All her Japanese auto-plays via VOICEVOX.

漢

Kanji Hub

All 100 N5 kanji with meanings, stroke counts, on-yomi, kun-yomi, mnemonics, and 10–15 example words each. Includes Kanji Match game (20 questions).

ひ

Kana

Drill hiragana and katakana individually. Kana Rain game: falling kana blocks you type before they hit the bottom.

🗣️

Speaking Practice

Pick a category → see Japanese text → VOICEVOX plays reference audio → record yourself → Whisper transcribes → pronunciation scored 0–100 via character-level comparison.

🎧

Listening Practice

Japanese text is hidden — only the audio plays. Type the English meaning to answer. Tests comprehension without visual support.

🔄

Shadowing

Hear the Japanese, record yourself repeating it from memory, get scored. Target text is revealed after scoring. Builds muscle memory for pronunciation patterns.

📖

Reading

Short Japanese passages with comprehension questions in English. Progress-gated — requires 40% vocabulary known before unlocking.

🎮

VRChat Conversation

Chat in Japanese with an AI playing a VRChat character. The AI's vocabulary is constrained to words you actually know. Wrong Japanese gets gentle corrections in context.

📝

Grammar Q&A

Ask any grammar question in English. If a textbook PDF has been imported, answers are grounded in that book via RAG (semantic search). Falls back to LM Studio knowledge without one.

🔊

Speak & Translate

Guided speaking with translation assistance — speak Japanese, get translation help and pronunciation feedback.

🕹️

Games

Kana Rain (falling kana typing game) and Kanji Match (20-question recognition game). Low-stakes reinforcement of core characters.

AI Tutor — Yuki's 15 Lessons

Conversation-first, grammar-second. Yuki shows Japanese examples before she explains them, and never leads with a grammar table.

#	Lesson
01	Greetings & Goodbye
02	Self Introduction
03	Asking About Things
04	Likes & Dislikes
05	Numbers in Real Context — age, how long
06	Location & Places
07	Basic Verbs
08	Keeping Conversations Going
09	Ability & Possibility
10	Requests & Permissions
11	Natural Reactions & Social Glue
12	Past & Future Tense
13	Katakana Loanwords
14	Casual vs Polite Speech
15	Full VRChat Role-Play

Voice Pipeline — 100% Offline

No Cloud. No Mic Data Leaving Your PC.

Text-to-speech runs through VOICEVOX, a local Japanese TTS engine using Kasukabe Tsumugi — a clear, gentle voice designed for natural pacing. Every synthesised phrase is cached by MD5 hash so the same sentence is never generated twice.

Speech-to-text uses faster-whisper, running in-process on CPU with no server required. Three model sizes are available (tiny / base / small) with "small" as the default for accuracy. Recordings are captured with sounddevice and fed directly to Whisper as numpy arrays.

Pronunciation scoring works by character-level comparison between what Whisper heard and the target text, giving a 0–100 score with no dependency on any external API.

TEXT → SPEECH

Japanese text ↓ MD5 cache check ↓ (miss) VOICEVOX :50021 Speaker: Tsumugi (8) ↓ WAV cached + played via PowerShell

MIC → TEXT → SCORE

sounddevice records ↓ numpy array ↓ faster-whisper model: small (CPU) ↓ transcript ↓ char-level diff ↓ 0–100 score

Database — SQLite, 20+ Tables

Content

kanaAll hiragana + katakana characters

vocabulary572 words — tags, readings, meanings

grammarGrammar patterns with example sentences

kanji100 N5 kanji — on/kun readings, mnemonics

lessons15 lesson structures with prerequisites

reading_passagesShort reading exercises

Learner Tracking

learnersProfile — name, streak, totals

learner_itemsSRS state per item — stability, difficulty, next review

reviewsEvery answer ever given

mistakesEvery wrong answer logged

sessionsEach study session with stats

voice_attemptsSpeaking/shadowing attempts with scores

session_analysesYuki's written feedback per session

learner_profileRolling computed stats — accuracy, velocity, weaknesses

tutor_lesson_progressWhich of the 15 lessons are completed

tutor_student_factsThings you've told Yuki — name, hobbies, origin

Book Ingestion (PDF import)

source_booksImported PDF textbooks

chunksSemantic chunks for RAG retrieval

dialoguesExtracted dialogue segments

conversation_sessionsConversation history from book-grounded sessions

Learner Analytics

Computed and stored after every session. Feed into Yuki's post-session written report and next lesson plan.

30-day accuracyRolling average across all review attempts

Sessions per weekConsistency tracking — how often you actually study

Vocab velocityNew words reaching "known" per week

Chronic weaknessesItems with >40% error rate across 3+ attempts

N5 readiness% of 700 target vocab items at "known" or better

StreakConsecutive study days — current + longest ever

Tech Stack

PythonCore language — launch via gui.py or main.py

PySide6 (Qt 6)All GUI — desktop app with 22 UI screens

SQLite 3Single database file, 20+ tables

FSRS-6Spaced repetition algorithm — custom implementation in fsrs.py

LM StudioLocal LLM — AI tutor, conversation, session analysis

VOICEVOXOffline Japanese TTS — Kasukabe Tsumugi voice

faster-whisperOffline speech-to-text — in-process, CPU, no server

sounddeviceMicrophone recording

difflibFuzzy answer matching — dyslexia-friendly throughout

ChromaDB + nomicVector search for PDF textbook RAG (optional)

How Memory Works

No Cloud. No Mic Data Leaving Your PC.