feat: VoiceFrame SSE wire format — shared type definition for cf-voice consumers #40

New issue

Closed

opened 2026-04-06 15:49:27 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-04-06 15:49:27 -07:00

Owner

Context

Linnet consumes VoiceFrame from cf-voice and re-emits ToneEvent over SSE to the frontend. Osprey will consume VoiceFrame for its own telephony annotation path.

The SSE wire format (JSON serialisation of ToneEvent) should be documented as part of cf-voice so Osprey and future consumers know what to expect from a Linnet-compatible annotation stream.

Deliverable

Document ToneEvent JSON shape in cf-voice README alongside VoiceFrame
Confirm field names are stable before Linnet v0.1.x ships
Fields: label, confidence, speaker_id, shift_magnitude, timestamp, session_id

Rationale

When <LinnetWidget /> is embedded in Osprey or Falcon, the host app subscribes to tone-event emissions. Locking the wire format early prevents a breaking change when the widget ships in v1.0.

Circuit-Forge/circuitforge-core#39 (cf-voice stub repo)
Circuit-Forge/linnet#14 (LinnetWidget isolation)

## Context Linnet consumes `VoiceFrame` from `cf-voice` and re-emits `ToneEvent` over SSE to the frontend. Osprey will consume `VoiceFrame` for its own telephony annotation path. The SSE wire format (JSON serialisation of `ToneEvent`) should be documented as part of cf-voice so Osprey and future consumers know what to expect from a Linnet-compatible annotation stream. ## Deliverable - Document `ToneEvent` JSON shape in `cf-voice` README alongside `VoiceFrame` - Confirm field names are stable before Linnet v0.1.x ships - Fields: `label`, `confidence`, `speaker_id`, `shift_magnitude`, `timestamp`, `session_id` ## Rationale When `<LinnetWidget />` is embedded in Osprey or Falcon, the host app subscribes to `tone-event` emissions. Locking the wire format early prevents a breaking change when the widget ships in v1.0. ## Related - `Circuit-Forge/circuitforge-core#39` (cf-voice stub repo) - `Circuit-Forge/linnet#14` (LinnetWidget isolation)