use real sounds from kbsim

README.md

@@ -2,11 +2,14 @@
 
 Annotate keyboard key presses on a video timeline and preview/export mechanical switch sounds mixed with the video audio.
 
+Keyboard sounds are sourced from [kbsim](https://github.com/tplai/kbsim) (MIT license) — recorded press and release samples with per-key variation.
+
 ## Requirements
 
 - [uv](https://docs.astral.sh/uv/) (Python package manager)
 - Node.js 18+ and npm
 - **ffmpeg** on your PATH (required by pydub for audio export)
+- **git** (to fetch kbsim sample assets)
 
 ```bash
 # macOS
@@ -21,6 +24,9 @@ uv sync
 
 # Frontend dependencies
 cd frontend && npm install
+
+# Download kbsim switch samples (~151 MP3 files)
+./scripts/fetch_kbsim_samples.sh
 ```
 
 ## Development
@@ -50,8 +56,10 @@ Open http://127.0.0.1:8000
 
 1. **Open Video** — load an MP4 file
 2. Press keys while the playhead is at the desired time to add markers (works while playing or paused)
+   - Press sound plays on keydown; release sound plays on keyup
+   - Each physical key maps to a stable press variant (same key always sounds the same)
 3. Select markers to override keys, nudge with arrow keys, or multi-select with marquee drag
-4. Choose a mechanical switch sound from the dropdown
+4. Choose a mechanical switch sound from the dropdown (13 kbsim profiles)
 5. **Save Project** / **Open Project** — JSON with version, markers, and switch setting (no video path)
 6. **Export Audio** — download a WAV file of keyboard sounds only, full video length
 
@@ -69,19 +77,31 @@ Open http://127.0.0.1:8000
 
 ```json
 {
-  "version": 1,
-  "switch": "cherry-mx-blue",
+  "version": 2,
+  "switch": "mxbrown",
   "markers": [
-    { "id": "m1", "time": 1.234, "key": "a" }
+    { "id": "m1", "time": 1.234, "key": "a", "code": "KeyA", "releaseTime": 1.312 }
   ]
 }
 ```
 
+- `time` — press timestamp (seconds)
+- `releaseTime` — keyup timestamp; omitted in v1 projects default to press + 80ms at playback/export
+- `code` — `event.code` for stable per-key sound mapping (e.g. `KeyA`, `Digit1`)
+
+v1 projects with `cherry-mx-blue` / `cherry-mx-red` / `cherry-mx-brown` switches are migrated automatically.
+
 Re-open the video manually after loading a project file.
 
 ## Switch samples
 
-Bundled samples are short synthetic click sounds representing Cherry MX Blue (clicky), Red (linear), and Brown (tactile) switches.
+Samples live in `assets/samples/kbsim/` and are fetched via `scripts/fetch_kbsim_samples.sh`. Available profiles:
+
+NovelKeys Creams, Holy Pandas, Alpacas, Turquoise Tealios, Gateron Black Inks, Gateron Red Inks, Cherry MX Blacks, Cherry MX Browns, Cherry MX Blues, Kailh Box Navies, Buckling Spring, SKCM Blue Alps, Topre.
+
+## Attribution
+
+Keyboard sound samples from [tplai/kbsim](https://github.com/tplai/kbsim) by Thomas Lai (MIT license).
 
 ## Known limitations