# globluez/bluez-dubbing architecture

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

- Interactive diagram: https://gitdiagram.com/globluez/bluez-dubbing
- Repository: https://github.com/globluez/bluez-dubbing

## Overview

Bluez-Dubbing accepts media through its web UI or API, then coordinates separation, speech recognition, translation, speech synthesis, audio synchronization, and subtitle rendering into downloadable results. The README documents multiple modes, translation strategies, subtitle styles, model selection, progress reporting, and optional intermediate artifacts. Sampled source confirms orchestration calls to ASR and TTS and audio-separation behavior; translation and some final-render wiring are documented but their implementation is not present in the supplied tree.

Main entry points: [`apps/backend/services/orchestrator/app/main.py`](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/app/main.py) (REST API), [`apps/frontend/scripts/app.js`](https://github.com/globluez/bluez-dubbing/blob/main/apps/frontend/scripts/app.js) (Web UI), [`apps/backend/services/tts/app/main.py`](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/app/main.py) (Speech synthesis), [`apps/backend/services/asr/app/main.py`](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/asr/app/main.py) (Speech recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_frontend["Web UI<br/>[app.js]"]
  node_progress["Live progress<br/>[results.js]"]
end

subgraph group_orchestration["Pipeline orchestration"]
  node_api["REST API<br/>[main.py]"]
  node_shared["Shared schemas<br/>[models.py]"]
end

subgraph group_models["Model services"]
  node_asr["Speech recognition<br/>[main.py]"]
  node_asr_runner["WhisperX runner<br/>[runner_0.py]"]
  node_translation["Translation"]
  node_tts["Speech synthesis<br/>[main.py]"]
  node_chatterbox["Chatterbox model<br/>[runner.py]"]
  node_edge_tts["Edge TTS model<br/>[runner.py]"]
end

subgraph group_media["Media processing"]
  node_separation["Audio separation"]
  node_audio["Audio alignment"]
  node_final_pass["Final rendering<br/>[final_pass.py]"]
  node_subtitles["Subtitle output"]
end

node_user(("User"))
node_workspace[("Job outputs")]

node_user -->|"submits media"| node_frontend
node_frontend -->|"sends requests"| node_api
node_api -->|"stores job files"| node_workspace
node_api -->|"validates payloads"| node_shared
node_api -->|"separates audio"| node_separation
node_api -->|"requests transcription"| node_asr
node_asr -->|"dispatches work"| node_asr_runner
node_api -.->|"requests translation"| node_translation
node_api -->|"requests synthesis"| node_tts
node_tts -.->|"dispatches work"| node_chatterbox
node_tts -.->|"dispatches work"| node_edge_tts
node_api -->|"aligns audio"| node_audio
node_api -.->|"generates subtitles"| node_subtitles
node_api -.->|"renders output"| node_final_pass
node_api -->|"reports progress"| node_frontend
node_frontend -->|"displays updates"| node_progress

click node_frontend "https://github.com/globluez/bluez-dubbing/blob/main/apps/frontend/scripts/app.js"
click node_api "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/app/main.py"
click node_shared "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/libs/common-schemas/common_schemas/models.py"
click node_separation "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/preprocessing/media_separation.py"
click node_asr "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/asr/app/main.py"
click node_asr_runner "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/asr/models/whisperxModel/runner_0.py"
click node_tts "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/app/main.py"
click node_chatterbox "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/models/chatterboxModel/runner.py"
click node_edge_tts "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/models/edgeTTsModel/runner.py"
click node_audio "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/media_processing/audio_processing.py"
click node_final_pass "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/media_processing/final_pass.py"
click node_subtitles "https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/media_processing/subtitles_handling.py"
click node_progress "https://github.com/globluez/bluez-dubbing/blob/main/apps/frontend/scripts/modules/results.js"

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_frontend,node_progress,node_user toneBlue
class node_api,node_shared,node_workspace toneAmber
class node_asr,node_asr_runner,node_translation,node_tts,node_chatterbox,node_edge_tts toneMint
class node_separation,node_audio,node_final_pass,node_subtitles toneRose
```

## Components

### User interface

- [Web UI](https://github.com/globluez/bluez-dubbing/blob/main/apps/frontend/scripts/app.js): `apps/frontend/scripts/app.js`
- [Live progress](https://github.com/globluez/bluez-dubbing/blob/main/apps/frontend/scripts/modules/results.js): `apps/frontend/scripts/modules/results.js`

### Pipeline orchestration

- [REST API](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/app/main.py): `apps/backend/services/orchestrator/app/main.py`
- [Shared schemas](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/libs/common-schemas/common_schemas/models.py): `apps/backend/libs/common-schemas/common_schemas/models.py`

### Model services

- [Speech recognition](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/asr/app/main.py): `apps/backend/services/asr/app/main.py`
- [WhisperX runner](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/asr/models/whisperxModel/runner_0.py): `apps/backend/services/asr/models/whisperxModel/runner_0.py`
- **Translation**
- [Speech synthesis](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/app/main.py): `apps/backend/services/tts/app/main.py`
- [Chatterbox model](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/models/chatterboxModel/runner.py): `apps/backend/services/tts/models/chatterboxModel/runner.py`
- [Edge TTS model](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/tts/models/edgeTTsModel/runner.py): `apps/backend/services/tts/models/edgeTTsModel/runner.py`

### Media processing

- [Audio separation](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/preprocessing/media_separation.py): `apps/backend/services/orchestrator/preprocessing/media_separation.py`
- [Audio alignment](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/media_processing/audio_processing.py): `apps/backend/services/orchestrator/media_processing/audio_processing.py`
- [Final rendering](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/media_processing/final_pass.py): `apps/backend/services/orchestrator/media_processing/final_pass.py`
- [Subtitle output](https://github.com/globluez/bluez-dubbing/blob/main/apps/backend/services/orchestrator/media_processing/subtitles_handling.py): `apps/backend/services/orchestrator/media_processing/subtitles_handling.py`

### Other components

- **User**
- **Job outputs**

## Connections

- User → Web UI: submits media
- Web UI → REST API: sends requests
- REST API → Job outputs: stores job files
- REST API → Shared schemas: validates payloads
- REST API → Audio separation: separates audio
- REST API → Speech recognition: requests transcription
- Speech recognition → WhisperX runner: dispatches work
- REST API → Translation: requests translation
- REST API → Speech synthesis: requests synthesis
- Speech synthesis → Chatterbox model: dispatches work
- Speech synthesis → Edge TTS model: dispatches work
- REST API → Audio alignment: aligns audio
- REST API → Subtitle output: generates subtitles
- REST API → Final rendering: renders output
- REST API → Web UI: reports progress
- Web UI → Live progress: displays updates