initial commit

2026-06-08 22:49:50 -07:00
commit f6a6681e16
40 changed files with 3026 additions and 0 deletions
@@ -0,0 +1,90 @@
+# sfxkeeb
+
+Annotate keyboard key presses on a video timeline and preview/export mechanical switch sounds mixed with the video audio.
+
+## 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)
+
+```bash
+# macOS
+brew install ffmpeg
+```
+
+## Setup
+
+```bash
+# Python dependencies
+uv sync
+
+# Frontend dependencies
+cd frontend && npm install
+```
+
+## Development
+
+Run both servers in separate terminals:
+
+```bash
+# Terminal 1 — FastAPI backend (audio export API)
+uv run uvicorn backend.main:app --reload
+
+# Terminal 2 — Vite dev server (proxies /api to :8000)
+cd frontend && npm run dev
+```
+
+Open http://localhost:5173
+
+## Production-like run
+
+```bash
+cd frontend && npm run build
+uv run uvicorn backend.main:app --host 127.0.0.1 --port 8000
+```
+
+Open http://127.0.0.1:8000
+
+## Usage
+
+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)
+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
+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
+
+### 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": 1,
+  "switch": "cherry-mx-blue",
+  "markers": [
+    { "id": "m1", "time": 1.234, "key": "a" }
+  ]
+}
+```
+
+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.
+
+## 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 via pydub in-memory overlay