https://github.com/oduerr/hsk
HSK Flashcard Game
https://github.com/oduerr/hsk
Last synced: 2 days ago
JSON representation
HSK Flashcard Game
- Host: GitHub
- URL: https://github.com/oduerr/hsk
- Owner: oduerr
- Created: 2025-08-13T06:27:15.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-20T09:56:31.000Z (10 months ago)
- Last Synced: 2025-08-20T11:45:33.808Z (10 months ago)
- Language: JavaScript
- Size: 29.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# HSK Flashcards (Offline HTML/JS)
## Disclaimer
This is a work in progress! Probably too much have been done with AI coding Agents.
The Data Model is quite patchy, it (kind of) works but before adding new features to the Data Model a thorough review is needed
_This is an experimental learning project; it stores all data locally in your browser and uses some third-party APIs (see [Privacy](#privacy))._
## Quick start
- Open `index.html` in a modern browser.
- If your browser blocks `file://` fetch for CSV, run a tiny server from the `hsk/` folder:
- macOS/Linux: `python3 -m http.server`
## Data & levels
- CSV format: `hanzi,pinyin,english,locale` (UTF‑8, quoted fields supported; pinyin spacing normalized; locale defaults to zh-CN if missing).
- Vocabulary files live in `data/` directory.
- The app automatically discovers available vocabulary files using a smart discovery system.
## File Loading
### Primary Method: `vocab.csv` Index
The app primarily discovers vocabulary files by reading `data/vocab.csv`, which serves as a central index:
```csv
filename,display_name,description
hsk1.csv,HSK 1,Basic Chinese vocabulary (150 words)
hsk2.csv,HSK 2,Elementary Chinese vocabulary (300 words)
eng_oliver.csv,Oliver's English,Personal English vocabulary collection
```
**To add new vocabulary files:**
1. Place your CSV file in the `data/` folder
2. Add a row to `data/vocab.csv` with:
- `filename`: The actual CSV filename
- `display_name`: User-friendly name shown in the interface
- `description`: Optional description of the content
3. Reload the page - the file will automatically appear in the vocabulary manager
### Fallback Discovery
If `vocab.csv` is not available, the app falls back to pattern-based discovery, automatically detecting common filename patterns like `hsk*.csv`, `vocabulary.csv`, etc.
### Benefits of `vocab.csv` Approach
- **User control**: You decide what files are available
- **Rich metadata**: Display names and descriptions for better UX
- **Easy maintenance**: No code changes needed for new files
- **Flexible naming**: Use any filename you want
- **Future-proof**: Works with any vocabulary format
## Features (v4.50)
- Core flashcard flow: Reveal / Next / Mistake, progress indicator, live mistake count
- Sessions: full event log; save checkpoints; export/import to JSON; replay only mistaken cards
- Vocabulary management: 📚 button for importing HSK files and custom vocabulary sets
- Mobile‑friendly layout; single‑tap mistake toggle on mobile; swipe left/right for next/back
- Settings (gear):
- Auto‑reveal + seconds and countdown
- Minimal UI
- Outdoor mode (high contrast) and Light/Dark theme
- Audio feedback beeps on mark/unmark
- Voice section: Browser TTS or OpenAI TTS (model, voice, cache, API key test), Voice speed slider
- Info panel (version/build/checkpoint/session)
- Mic (🎙️) Tone visualizer: live pitch trace, final contour, recorded spectrogram, re‑record/stop/replay controls
- Speaker (🔊) for pronunciation
## UI and controls
- Top bar: 📚 Vocabulary Manager, New Run, Replay…, Save Progress, Mistake, Gear
- Above card (right): 🎙️ Tone visualizer, 🔊 Speak
- Bottom bar: Back, Reveal, Mistake, Next, Save Progress
- Keyboard:
- Space / ↑ / ↓: Reveal / Unreveal
- Enter / →: Next
- ←: Back
- M: Mistake toggle
- R: Open Replay dialog
## Export / Import
- Found in the Gear menu and also the Replay dialog; drag‑and‑drop supported.
- Exports `flash_sessions_YYYYMMDD.json` of all sessions; includes the current in‑progress run snapshot so mid‑run mistakes are preserved.
- Import merges sessions by `id`; supports multiple JSON shapes.
- **Format documentation**: See [`data/JSON_FORMAT.md`](data/JSON_FORMAT.md) for complete JSON structure specifications.
## File structure
```text
index.html
css/
style.css
js/
main.js // boot, wiring, flow
data.js // CSV fetch/parse/normalize, level discovery
state.js // run state, session logging, finalize
ui.js // render, counters, progress/mistake views
util.js // hash, helpers
storage.js // LocalStorage, export/import, settings
speech.js // TTS (browser/OpenAI)
toneVisualizer.js // mic + pitch visualization
data/
vocab.csv # Vocabulary file index
hsk*.csv # HSK vocabulary files
*.csv # Other vocabulary files
```
## Privacy
All learning data (sessions, progress, vocabulary) is stored locally in your browser.
The app has no backend server and does not transmit your personal data.
Some optional features (e.g. speech recognition) use third-party browser APIs such as the Google Web Speech API.
In those cases, audio may be processed by the browser provider’s servers. The app itself never stores or sends speech data externally.
## Troubleshooting
- Browser blocks CSV on `file://`: run `python3 -m http.server` and open the local URL.
- No vocabulary files showing: ensure `data/vocab.csv` exists and contains valid entries, or check that CSV files exist in `data/` directory; the vocabulary manager will populate automatically on reload.
- Exported file seems empty: finish a run or mark some mistakes; in‑progress runs are also exported.