# 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* 💜