Add KB Capture v2 - clip-based recording system

New features: - Clip-based workflow: record short clips, keep or delete - Toggle recording with Ctrl+Shift+R - Session management (start, clips, end) - Modern CustomTkinter GUI with dark theme - Global hotkeys for hands-free control - Whisper transcription (local, no API) - FFmpeg screen + audio capture - Export to clawdbot_export/ for Mario processing Files added: - recorder.py: FFmpeg screen recording - session.py: Session/clip management - hotkeys.py: Global hotkey registration - kb_capture.py: Main application logic - gui_capture.py: Modern GUI - export.py: Merge clips, transcribe, export Docs: - docs/KB-CAPTURE.md: Full documentation Entry point: uv run kb-capture
2026-02-09 12:50:22 +00:00
parent 571855823f
commit d5371cfe75
8 changed files with 2121 additions and 0 deletions
--- a/docs/KB-CAPTURE.md
+++ b/docs/KB-CAPTURE.md
@@ -0,0 +1,181 @@
+# KB Capture v2
+
+**Clip-based recording for engineering knowledge capture.**
+
+## Overview
+
+KB Capture is a lightweight recording tool that captures your CAD/FEM work as short clips, not one long video. Record what matters, delete mistakes, keep the good stuff.
+
+## Quick Start
+
+```bash
+# Install
+cd CAD-Documenter
+uv sync
+uv pip install customtkinter keyboard
+
+# Launch
+uv run kb-capture
+```
+
+## Workflow
+
+### 1. Start Session
+- Open KB Capture (system tray or GUI)
+- Enter project name (e.g., "P04-GigaBIT-M1")
+- Enter session description (e.g., "Vertical support refinement")
+- Select type: **Design** (CAD) or **Analysis** (FEA)
+- Click **Start Session**
+
+### 2. Record Clips
+While working in NX/CAD:
+- Press **Ctrl+Shift+R** to start recording
+- Narrate what you're doing
+- Say "screenshot" when you want a frame captured
+- Press **Ctrl+Shift+R** again to stop
+
+### 3. Review Clips
+After each clip:
+- **Keep (K)**: Keep the clip
+- **Delete (D)**: Discard the clip (bad take)
+- Or just start recording again (auto-keeps previous)
+
+### 4. End Session
+- Press **Ctrl+Shift+E** or click **End Session**
+- Clips are merged and transcribed
+- Exported to `clawdbot_export/` for Mario processing
+
+## Keyboard Shortcuts
+
+| Action | Shortcut |
+|--------|----------|
+| Start/Stop Recording | Ctrl+Shift+R |
+| Keep Last Clip | Ctrl+Shift+K |
+| Delete Last Clip | Ctrl+Shift+D |
+| End Session | Ctrl+Shift+E |
+
+## Session Types
+
+| Type | Updates | Use For |
+|------|---------|---------|
+| **Design** | KB/Design/ | CAD work, component design, assembly |
+| **Analysis** | KB/Analysis/ | FEA setup, mesh, BCs, results |
+
+## Output
+
+After ending a session:
+
+```
+sessions/<session-id>/
+├── clips/
+│   ├── clip-001.mp4
+│   ├── clip-002.mp4
+│   └── ...
+├── session.json
+└── clawdbot_export/
+    ├── merged.mp4         # All clips merged
+    ├── transcript.json    # Whisper transcription
+    ├── frames/            # Extracted at "screenshot" triggers
+    │   ├── 01_00-30.png
+    │   └── ...
+    └── metadata.json      # Session info for Clawdbot
+```
+
+## What Happens Next
+
+1. **Syncthing** syncs `clawdbot_export/` to Clawdbot
+2. **Mario** detects new session
+3. **Vision analysis** categorizes frames
+4. **KB updated** with new information
+5. **Slack notification** when complete
+
+## Tips
+
+### Recording
+- Narrate naturally — explain what you're doing
+- Say "screenshot" before important views
+- Keep clips short (30s - 2min)
+- It's okay to delete bad takes
+
+### Organization
+- One session per work block (30-60 min)
+- Use descriptive session names
+- Match project name to your PKM folder
+
+### Quality
+- Close unnecessary windows before recording
+- Undock NX 3D viewport for clean captures
+- Speak clearly for better transcription
+
+## Troubleshooting
+
+### Hotkeys not working
+- Run as Administrator (Windows)
+- Check for conflicts with other apps
+- Try restarting KB Capture
+
+### Recording fails
+- Ensure FFmpeg is installed: `choco install ffmpeg`
+- Check disk space
+- Check microphone permissions
+
+### No transcription
+- Whisper needs ~2GB RAM for 'base' model
+- Try 'tiny' model: `--whisper-model tiny`
+- Check CUDA/GPU drivers for faster processing
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           KB Capture (Windows)          │
+├─────────────────────────────────────────┤
+│  ┌───────────┐  ┌──────────────────┐   │
+│  │  Hotkeys  │  │  GUI (optional)  │   │
+│  └─────┬─────┘  └────────┬─────────┘   │
+│        │                 │              │
+│        ▼                 ▼              │
+│  ┌─────────────────────────────────┐   │
+│  │       Session Manager           │   │
+│  │  (clips, keep/delete, merge)    │   │
+│  └─────────────┬───────────────────┘   │
+│                │                        │
+│  ┌─────────────┼───────────────────┐   │
+│  │             ▼                   │   │
+│  │  ┌─────────────────────────┐   │   │
+│  │  │     Screen Recorder     │   │   │
+│  │  │     (FFmpeg gdigrab)    │   │   │
+│  │  └─────────────────────────┘   │   │
+│  │                                 │   │
+│  │  ┌─────────────────────────┐   │   │
+│  │  │   Whisper Transcriber   │   │   │
+│  │  │      (local GPU)        │   │   │
+│  │  └─────────────────────────┘   │   │
+│  └─────────────────────────────────┘   │
+│                │                        │
+│                ▼                        │
+│  ┌─────────────────────────────────┐   │
+│  │      clawdbot_export/           │   │
+│  │  merged.mp4 + transcript.json   │   │
+│  └─────────────┬───────────────────┘   │
+└────────────────┼────────────────────────┘
+                 │ Syncthing
+                 ▼
+┌─────────────────────────────────────────┐
+│            Clawdbot (Mario)             │
+│  Vision analysis → KB update → Notify   │
+└─────────────────────────────────────────┘
+```
+
+## Requirements
+
+- Windows 10/11
+- Python 3.12+
+- FFmpeg (`choco install ffmpeg`)
+- CUDA GPU (recommended for Whisper)
+- ~4GB RAM (for Whisper 'base' model)
+
+## Related
+
+- [CAD-Documenter README](../README.md) — Original project overview
+- [Knowledge Base Skill](http://100.80.199.40:3000/Antoine/clawdbot-shared-skills) — How Mario processes sessions