Chinese Dictation

Chinese Dictation Generator

Given a list of Chinese words (with pinyin), produce a self-contained HTML page that:

1. Lists every word + pinyin (hidden by default, click to reveal — encourages real practice).
2. Generates one tiny ogg per word, and embeds a JavaScript scheduler that plays them sequentially with a client-side adjustable interval. User can change the gap (e.g. 5s → 10s), pause/resume, skip to next word, or stop entirely — all live in the browser, no need to regenerate.

Designed for elementary-school 中文/語文 homework. Defaults to 繁體中文 reading voice; works for simplified too.

When to invoke

User (Chris) typically shares a screenshot of a textbook 生字 page or 聽寫表. The expected workflow is fully autonomous: read the image → extract 字+拼音 → generate the dictation page → send the URL. Don't ask back about voice/pause/etc — defaults are already production-tested. If the page is part of a series (e.g. user already did page 24, now sends page 25), use a slug like pageNN for clean URL grouping.

Workflow (Claude side)

Step 1 — Extract words from the image

You (Claude) read the user's screenshot directly. For each entry on the page, extract:

• hanzi — the character(s) to dictate (preserve traditional form if the source is traditional)
• pinyin — full pinyin with tone marks (e.g. qiū qiān, not qiu1 qian1)

If pinyin is missing from the image but you're confident, fill it in. If a word is ambiguous, ask the user before generating.

Step 2 — Run the generator

Write the words to /tmp/dictation-input.json:

{
  "title": "第一週聽寫",
  "slug": "week1",
  "words": [
    {"hanzi": "鞦韆", "pinyin": "qiū qiān"},
    {"hanzi": "翱翔", "pinyin": "áo xiáng"},
    {"hanzi": "璀璨", "pinyin": "cuǐ càn"}
  ],
  "pause_seconds": 20,
  "repeat": 2,
  "voice": "vindemiatrix"
}

Then run:

python3 ~/.claude/skills/chinese-dictation/scripts/generate.py /tmp/dictation-input.json

Output (one line, the public URL):

https://www.closecrab.com/pages/dictation-week1-20260523-145912.html

Send that URL to the user.

Important: title is the Chinese display name shown in the page; slug is the ASCII-only filename component for clean URLs. If you omit slug, the URL falls back to dictation-{timestamp}.html (still clean, just less descriptive). Never put Chinese in the URL — picks like week1, unit3-lesson5, 2025-spring work well.

Defaults / tuning

What the generated HTML contains

• Header — title, date, word count, estimated duration.
• Audio player — single <audio> element, the user clicks play and writes along.
• Word grid — every word shown as a card with hanzi + pinyin blurred by default. Click a card to reveal (for self-check after listening). A "全部顯示 / 全部隱藏" toggle button up top.
• Print-friendly — @media print reveals all answers for the teacher's answer key.

Pause tuning

The first time you generate dictation for a particular student, suggest the user try pause_seconds: 20, then offer to regenerate with adjusted timing based on feedback ("太快了" → 25, "太慢了" → 15).

Tips

• Traditional vs simplified: pass hanzi exactly as the user wants to practice. The script doesn't auto-convert.
• Multi-character words (詞組): treat as a single dictation unit, e.g. {"hanzi": "鞦韆"} not two entries.
• Phrases with same word reading multiple times: repeat: 3 if they need more practice.

Files

• scripts/generate.py — main entry, JSON → HTML+audio → CC Pages upload.
• Dependencies: ffmpeg, tts-generator skill (Gemini 3.1 Flash TTS).