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)

# 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

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 💜