end
f2e5c09172
Replace the NPM-first workflow with Wails v3 dev and build instructions, including platform prerequisites for macOS and Windows. Co-authored-by: Cursor <cursoragent@cursor.com>
124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# sfxkeeb
|
||
|
||
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.
|
||
|
||
sfxkeeb is a **Wails v3 desktop app** (Go shell + Svelte frontend). Native file dialogs are used for opening videos/projects and saving exports.
|
||
|
||
## Requirements
|
||
|
||
- **Go** 1.22+
|
||
- **Wails v3 CLI**: `go install github.com/wailsapp/wails/v3/cmd/wails3@latest`
|
||
- **Node.js** 18+ and npm
|
||
- **git** (to fetch kbsim sample assets)
|
||
|
||
### Platform tooling
|
||
|
||
| Platform | Additional requirements |
|
||
| -------- | ----------------------- |
|
||
| macOS | Xcode Command Line Tools |
|
||
| Windows | [WebView2 runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) (usually pre-installed on Windows 11); build tools for `wails3 task build` |
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
# Frontend dependencies
|
||
cd frontend && npm install
|
||
|
||
# Download kbsim switch samples (~151 MP3 files)
|
||
cd .. && ./scripts/fetch_kbsim_samples.sh
|
||
```
|
||
|
||
## Development
|
||
|
||
From the repository root:
|
||
|
||
```bash
|
||
wails3 dev
|
||
```
|
||
|
||
This builds the Go backend, starts the Vite dev server, and opens the desktop window. File I/O uses native dialogs via Wails bindings.
|
||
|
||
For frontend-only work (no Wails bindings), you can still run `cd frontend && npm run dev`, but open/save dialogs will not function outside the Wails shell.
|
||
|
||
## Production build
|
||
|
||
From the repository root:
|
||
|
||
```bash
|
||
wails3 task build
|
||
```
|
||
|
||
The compiled binary is written to `bin/sfxkeeb`. On macOS, package a `.app` bundle with:
|
||
|
||
```bash
|
||
wails3 task package
|
||
```
|
||
|
||
Build on each target platform (macOS for `.app`, Windows for `.exe`). Windows users need the WebView2 runtime installed.
|
||
|
||
## Usage
|
||
|
||
1. **Open Video** — pick an MP4 (or other supported video) via native file dialog
|
||
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 (13 kbsim profiles)
|
||
5. Adjust preview speed (25–200%) for fast-paced content — preview only; export is always at 1×
|
||
6. **Save Project** / **Open Project** — JSON with version, markers, and switch setting (no video path)
|
||
7. **Export Audio** — save a WAV file of keyboard sounds only, full video length (rendered client-side)
|
||
|
||
### Keyboard shortcuts
|
||
|
||
| Shortcut | Action |
|
||
| ------------------ | ----------------------------------- |
|
||
| Ctrl+Space | Play / pause |
|
||
| Arrow keys | Nudge selected marker(s) one frame |
|
||
| Alt+Scroll | Zoom timeline (centers on playhead) |
|
||
| Backspace / Delete | Delete selected marker(s) |
|
||
| Ctrl+A | Select all markers |
|
||
|
||
## Project file format
|
||
|
||
```json
|
||
{
|
||
"version": 2,
|
||
"switch": "mxbrown",
|
||
"markers": [
|
||
{
|
||
"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
|
||
|
||
Available profiles from [kbsim](https://github.com/tplai/kbsim):
|
||
|
||
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
|
||
|
||
- Frame stepping uses `video.currentTime` and may land on nearest keyframes for some MP4 encodings
|
||
- Project files do not reference the video file path
|
||
- Very long videos may take longer to export client-side via OfflineAudioContext
|