VoiceFi Ambient Voice Protocol & IPC Bus

An open standard and architectural specification for bidirectional, hands-free acoustic loops connecting physical audio hardware to autonomous agent runtimes on macOS.

1. Abstract & IPC Topology

Modern autonomous AI coding agents execute multi-step tool calls, test suites, and refactors in the background. Traditional interactive paradigms require constant terminal split-pane babysitting and manual keyboard focus switching.

VoiceFi defines a lightweight local loopback protocol operating over a WebSocket server and Unix Domain Socket at localhost:8765. Runtimes communicate using standardized JSON-RPC 2.0 frames.

[Agent Runtime (Antigravity/Claude)]
            │  (JSON-RPC 2.0 over WebSocket)
            ▼
   [VoiceFi Daemon (Port 8765)]
       ├── Acoustic Clean Engine
       ├── Microsoft Edge / Neural TTS Audio Pipeline
       ├── Local Faster-Whisper (Metal CoreML)
       └── macOS Native Audio Session (CoreAudio)

2. Message Framing & JSON-RPC 2.0 Schemas

2.1. agent.turn_completed

Emitted by the agent hook when execution finishes:

{
  "jsonrpc": "2.0",
  "method": "agent.turn_completed",
  "params": {
    "session_id": "conv-6f6b2d64",
    "agent_name": "Antigravity",
    "persona": "Christopher",
    "summary": "Completed unit tests for authentication module. 12 passing.",
    "auto_listen": true,
    "vad_silence_timeout_ms": 1200
  }
}

2.2. voice.transcription_completed

Emitted by VoiceFi when user speech has been transcribed and is ready for runtime injection:

{
  "jsonrpc": "2.0",
  "method": "voice.transcription_completed",
  "params": {
    "text": "Looks great, create the pull request now.",
    "duration_ms": 1420,
    "confidence": 0.984,
    "engine": "faster-whisper-metal"
  }
}

3. REST Endpoint Contracts

POST /v1/speak

Synthesize and speak acoustic payload using assigned persona.

POST /v1/listen

Open ambient microphone with energy-based VAD.

GET /v1/status

Return daemon health, active audio devices, and latency metrics.

4. Security & Localhost Invariant

VoiceFi servers MUST bind strictly to 127.0.0.1 loopback interface. External network exposure is prohibited. Microphone buffers are processed in transient memory pools and zero audio frames are written to persistent storage without explicit user invocation of vifi memo record.