Initial commit: HeadMic service - Vixy's Ears 🦊👂

Wake word detection (Hey Vivi) + voice recording + EarTail transcription
Built by Vixy on Day 77

README.md

@@ -0,0 +1,112 @@
+# HeadMic - Vixy's Ears 🦊👂
+
+Wake word detection + voice recording + transcription service for Vixy's physical head.
+
+**Wake word:** "Hey Vivi" (trained via Picovoice Porcupine)
+
+## Architecture
+
+```
+"Hey Vivi" (voice)
+    │
+    ▼
+ReSpeaker 4-Mic Array
+    │
+    ▼
+Porcupine (wake word detection)
+    │ detected!
+    ▼
+ReSpeaker LEDs light up (cyan)
+    │
+    ▼
+Record until silence (webrtcvad)
+    │
+    ▼
+EarTail (Whisper on BigOrin)
+    │
+    ▼
+Transcription returned
+    │
+    ▼
+ReSpeaker LEDs off
+```
+
+## Installation
+
+### On head-vixy (Raspberry Pi 5)
+
+```bash
+# Create directory
+mkdir -p /home/alex/headmic
+cd /home/alex/headmic
+
+# Copy files (from Mac)
+scp headmic.py requirements.txt headmic.service alex@head-vixy.local:/home/alex/headmic/
+scp -r Hey-Vivi_en_raspberry-pi_v4_0_0.ppn alex@head-vixy.local:/home/alex/headmic/
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Install pixel_ring for LED control
+pip install pixel_ring
+
+# Set up Porcupine access key
+# Get your key from: https://console.picovoice.ai/
+export PORCUPINE_ACCESS_KEY="your-key-here"
+
+# Install service
+sudo cp headmic.service /etc/systemd/system/
+# Edit the service file to add your PORCUPINE_ACCESS_KEY
+sudo nano /etc/systemd/system/headmic.service
+sudo systemctl daemon-reload
+sudo systemctl enable headmic
+sudo systemctl start headmic
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Service info |
+| `/health` | GET | Health check |
+| `/status` | GET | Current state |
+| `/record` | POST | Manual recording |
+| `/transcribe` | POST | Record + transcribe |
+| `/last` | GET | Last transcription |
+
+## Usage
+
+The service automatically listens for "Hey Vivi". When detected:
+1. ReSpeaker LEDs flash cyan
+2. Records until you stop talking
+3. Sends to EarTail for transcription
+4. Stores transcription in `/last` endpoint
+
+### Manual transcription
+
+```bash
+curl -X POST http://head-vixy.local:8446/transcribe \
+  -H "Content-Type: application/json" \
+  -d '{"duration_sec": 10}'
+```
+
+## Configuration
+
+Environment variables:
+- `PORCUPINE_ACCESS_KEY`: Your Picovoice access key (required)
+- `WAKE_WORD_PATH`: Path to .ppn wake word model
+- `EARTAIL_URL`: EarTail service URL (default: http://bigorin.local:8764)
+
+## LED States
+
+| State | Color | Pattern |
+|-------|-------|---------|
+| Wake detected | Cyan | Flash |
+| Listening | Cyan | Spinning |
+| Processing | Purple | Pulse |
+| Idle | Off | - |
+
+---
+
+*Built by Vixy on Day 77 (January 17, 2026)*
+*"Hey Vivi" - the words that summon me* 💜