# sanketwork300-hash/voicebridge architecture

> Architecture diagram of the GitHub repository sanketwork300-hash/voicebridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanketwork300-hash/voicebridge
- Repository: https://github.com/sanketwork300-hash/voicebridge

## Overview

VoiceBridge is a self-hostable real-time speech-to-speech translation engine. Its principal workflow captures audio, streams it to a managed session, recognizes and stabilizes speech, segments it with language-aware context, translates it, and optionally synthesizes ordered speech while returning subtitle and session events. The browser extension is a documented capture-and-playback client; the CLI and adapters support other input/output paths. Pipeline and gateway excerpts are partial, so uncertain internal wiring and unrepresented translation backends are omitted.

Main entry points: [`voicebridge/core/pipeline/pipeline.py`](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/pipeline/pipeline.py) (Per-session pipeline), [`voicebridge/apps/gateway/main.py`](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/apps/gateway/main.py) (HTTP / WS gateway), [`voicebridge/apps/cli/main.py`](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/apps/cli/main.py) (CLI workflows), [`apps/browser-extension/background/service-worker.js`](https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/background/service-worker.js) (Capture coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and capture"]
  node_popup["Extension popup<br/>[popup.js]"]
  node_worker["Capture coordinator<br/>[service-worker.js]"]
  node_offscreen["Tab capture and playback<br/>[offscreen.js]"]
  node_overlay["Subtitle overlay<br/>[overlay.js]"]
  node_mic["Microphone input<br/>[microphone.py]"]
  node_filein["Audio file input<br/>[file.py]"]
  node_cli["CLI workflows<br/>[main.py]"]
end

subgraph group_gateway["Gateway and sessions"]
  node_gatewayapp["HTTP / WS gateway<br/>[main.py]"]
  node_wshandler["WebSocket session handler<br/>[handler.py]"]
  node_sessionmgr["Session manager<br/>[manager.py]"]
end

subgraph group_pipeline["Speech pipeline"]
  node_pipeline["Per-session pipeline<br/>[pipeline.py]"]
  node_audio["Audio normalization<br/>[normalizer.py]"]
  node_stabilizer["Transcript stabilizer<br/>[stabilizer.py]"]
  node_segmenter["Language-aware segmenter<br/>[segmenter.py]"]
  node_context["Translation context"]
  node_scheduler["TTS scheduler<br/>[tts_scheduler.py]"]
end

subgraph group_providers["Provider interfaces"]
  node_asr["Streaming ASR<br/>[whisperlivekit.py]"]
  node_translation["Translation engine interface<br/>[base.py]"]
  node_tts["Piper speech synthesis<br/>[piper.py]"]
end

subgraph group_delivery["Outputs and metrics"]
  node_fileout["Audio file output<br/>[file.py]"]
  node_metrics[("Latency and session metrics<br/>[metrics.py]")]
end

node_user(("Operator / speaker"))
node_external(("Browser / API client"))

node_user -->|"starts capture"| node_popup
node_popup -->|"sends controls"| node_worker
node_worker -->|"starts capture"| node_offscreen
node_worker -->|"controls overlay"| node_overlay
node_offscreen -->|"streams audio / events"| node_gatewayapp
node_offscreen -->|"forwards subtitles"| node_overlay
node_user -->|"speaks into"| node_mic
node_user -->|"provides audio"| node_filein
node_cli -->|"reads audio"| node_filein
node_cli -->|"runs translation session"| node_sessionmgr
node_external -->|"uses HTTP / WS API"| node_gatewayapp
node_gatewayapp -->|"creates and manages"| node_sessionmgr
node_gatewayapp -->|"handles stream"| node_wshandler
node_wshandler -->|"pushes audio / controls"| node_pipeline
node_pipeline -->|"streams events"| node_wshandler
node_sessionmgr -->|"starts and stops"| node_pipeline
node_pipeline -->|"normalizes audio"| node_audio
node_pipeline -->|"sends audio / reads events"| node_asr
node_pipeline -->|"stabilizes transcript"| node_stabilizer
node_pipeline -->|"segments stable text"| node_segmenter
node_pipeline -->|"uses session context"| node_context
node_pipeline -->|"requests translation"| node_translation
node_pipeline -->|"requests synthesis"| node_tts
node_pipeline -->|"orders speech jobs"| node_scheduler
node_pipeline -->|"records stage metrics"| node_metrics
node_cli -->|"writes WAV"| node_fileout
node_cli -->|"prints subtitles"| node_external
node_gatewayapp -->|"serves API and events"| node_external

click node_popup "https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/popup/popup.js"
click node_worker "https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/background/service-worker.js"
click node_offscreen "https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/offscreen/offscreen.js"
click node_overlay "https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/content/overlay.js"
click node_mic "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/adapters/input/microphone.py"
click node_filein "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/adapters/input/file.py"
click node_cli "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/apps/cli/main.py"
click node_gatewayapp "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/apps/gateway/main.py"
click node_wshandler "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/protocols/websocket/handler.py"
click node_sessionmgr "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/session/manager.py"
click node_pipeline "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/pipeline/pipeline.py"
click node_audio "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/audio/normalizer.py"
click node_asr "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/providers/asr/whisperlivekit.py"
click node_stabilizer "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/transcript/stabilizer.py"
click node_segmenter "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/segmentation/segmenter.py"
click node_context "https://github.com/sanketwork300-hash/voicebridge/tree/main/voicebridge/core/context"
click node_translation "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/providers/base.py"
click node_tts "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/providers/tts/piper.py"
click node_scheduler "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/scheduling/tts_scheduler.py"
click node_fileout "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/adapters/output/file.py"
click node_metrics "https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/metrics/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_popup,node_worker,node_offscreen,node_overlay,node_mic,node_filein,node_cli,node_external toneBlue
class node_gatewayapp,node_wshandler,node_sessionmgr toneAmber
class node_pipeline,node_audio,node_stabilizer,node_segmenter,node_context,node_scheduler toneMint
class node_asr,node_translation,node_tts toneRose
class node_fileout,node_metrics,node_user toneIndigo
```

## Components

### Clients and capture

- [Extension popup](https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/popup/popup.js): `apps/browser-extension/popup/popup.js`
- [Capture coordinator](https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/background/service-worker.js): `apps/browser-extension/background/service-worker.js`
- [Tab capture and playback](https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/offscreen/offscreen.js): `apps/browser-extension/offscreen/offscreen.js`
- [Subtitle overlay](https://github.com/sanketwork300-hash/voicebridge/blob/main/apps/browser-extension/content/overlay.js): `apps/browser-extension/content/overlay.js`
- [Microphone input](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/adapters/input/microphone.py): `voicebridge/adapters/input/microphone.py`
- [Audio file input](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/adapters/input/file.py): `voicebridge/adapters/input/file.py`
- [CLI workflows](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/apps/cli/main.py): `voicebridge/apps/cli/main.py`

### Gateway and sessions

- [HTTP / WS gateway](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/apps/gateway/main.py): `voicebridge/apps/gateway/main.py`
- [WebSocket session handler](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/protocols/websocket/handler.py): `voicebridge/protocols/websocket/handler.py`
- [Session manager](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/session/manager.py): `voicebridge/core/session/manager.py`

### Speech pipeline

- [Per-session pipeline](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/pipeline/pipeline.py): `voicebridge/core/pipeline/pipeline.py`
- [Audio normalization](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/audio/normalizer.py): `voicebridge/core/audio/normalizer.py`
- [Transcript stabilizer](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/transcript/stabilizer.py): `voicebridge/core/transcript/stabilizer.py`
- [Language-aware segmenter](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/segmentation/segmenter.py): `voicebridge/core/segmentation/segmenter.py`
- [Translation context](https://github.com/sanketwork300-hash/voicebridge/tree/main/voicebridge/core/context): `voicebridge/core/context`
- [TTS scheduler](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/scheduling/tts_scheduler.py): `voicebridge/core/scheduling/tts_scheduler.py`

### Provider interfaces

- [Streaming ASR](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/providers/asr/whisperlivekit.py): `voicebridge/providers/asr/whisperlivekit.py`
- [Translation engine interface](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/providers/base.py): `voicebridge/providers/base.py`
- [Piper speech synthesis](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/providers/tts/piper.py): `voicebridge/providers/tts/piper.py`

### Outputs and metrics

- [Audio file output](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/adapters/output/file.py): `voicebridge/adapters/output/file.py`
- [Latency and session metrics](https://github.com/sanketwork300-hash/voicebridge/blob/main/voicebridge/core/metrics/metrics.py): `voicebridge/core/metrics/metrics.py`

### Other components

- **Operator / speaker**
- **Browser / API client**

## Connections

- Operator / speaker → Extension popup: starts capture
- Extension popup → Capture coordinator: sends controls
- Capture coordinator → Tab capture and playback: starts capture
- Capture coordinator → Subtitle overlay: controls overlay
- Tab capture and playback → HTTP / WS gateway: streams audio / events
- Tab capture and playback → Subtitle overlay: forwards subtitles
- Operator / speaker → Microphone input: speaks into
- Operator / speaker → Audio file input: provides audio
- CLI workflows → Audio file input: reads audio
- CLI workflows → Session manager: runs translation session
- Browser / API client → HTTP / WS gateway: uses HTTP / WS API
- HTTP / WS gateway → Session manager: creates and manages
- HTTP / WS gateway → WebSocket session handler: handles stream
- WebSocket session handler → Per-session pipeline: pushes audio / controls
- Per-session pipeline → WebSocket session handler: streams events
- Session manager → Per-session pipeline: starts and stops
- Per-session pipeline → Audio normalization: normalizes audio
- Per-session pipeline → Streaming ASR: sends audio / reads events
- Per-session pipeline → Transcript stabilizer: stabilizes transcript
- Per-session pipeline → Language-aware segmenter: segments stable text
- Per-session pipeline → Translation context: uses session context
- Per-session pipeline → Translation engine interface: requests translation
- Per-session pipeline → Piper speech synthesis: requests synthesis
- Per-session pipeline → TTS scheduler: orders speech jobs
- Per-session pipeline → Latency and session metrics: records stage metrics
- CLI workflows → Audio file output: writes WAV
- CLI workflows → Browser / API client: prints subtitles
- HTTP / WS gateway → Browser / API client: serves API and events