vocal_helper.types module

vocal_helper.types

Typed dicts and dataclasses passed between pipeline stages.

The shapes are deliberately small and JSON-friendly so the same events can be (a) consumed by an in-process subscriber, (b) shipped over a WebSocket / SSE feed, (c) stored as JSONL for replay.

PCM convention — the same one used across the AI Helpers suite (capture_helper.MicFrame, podcast_helper.PcmFrame) :

mono np.float32
16 kHz (resampling is the source’s responsibility ; the pipeline assumes the configured sample_rate).

Time convention :

t0 / t1 are seconds since pipeline start_at (the monotonic time the pipeline began consuming frames). All stages use the same clock so events can be aligned downstream.

Author

Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui

class vocal_helper.types.DiarizedSegment[source]

Bases: TypedDict

Voiced segment with a global speaker id attached.

Emitted by vocal_helper.diar.OnlineDiarStage after each voiced segment has been embedded and matched against the running speaker centroids. speaker is a stable string id of the form "S0", "S1" — same speaker across the whole session.

pcm: ndarray[tuple[Any, ...], dtype[float32]]

sample_rate: int

speaker: str

t0: float

t1: float

class vocal_helper.types.PcmFrame[source]

Bases: TypedDict

One PCM frame at the configured sample rate.

Mirrors capture_helper.MicFrame and podcast_helper.PcmFrame so a producer from either library can feed this pipeline directly.

pcm: ndarray[tuple[Any, ...], dtype[float32]]

sample_rate: int

t0: float

class vocal_helper.types.SummarySnapshot[source]

Bases: TypedDict

One running summary as produced by the optional LLM analyst.

recent is the verbatim transcript of the last recent_window_s seconds ; summary is the LLM’s running digest of everything older than that.

model: str

recent: str

summary: str

t0: float

class vocal_helper.types.Utterance[source]

Bases: TypedDict

Transcribed diarized segment.

Emitted by vocal_helper.asr.WhisperStage. words is a list of (t0, t1, text) triplets when the underlying backend supports word-level timestamps, else a single triplet spanning the whole utterance.

language: str | None

speaker: str

t0: float

t1: float

text: str

words: list[tuple[float, float, str]]

class vocal_helper.types.VoicedSegment[source]

Bases: TypedDict

A contiguous run of voiced speech as detected by VAD.

Emitted by vocal_helper.vad.SileroVADStage when speech ends (i.e. after min_silence_ms of trailing silence) — the PCM buffer holds the full voiced span minus the trailing silence.

pcm: ndarray[tuple[Any, ...], dtype[float32]]

sample_rate: int

t0: float

t1: float