# sayan4496/transcadence architecture

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

- Interactive diagram: https://gitdiagram.com/sayan4496/transcadence
- Repository: https://github.com/sayan4496/transcadence

## Overview

TransCadence turns an uploaded English video into a Hindi-dubbed MP4 with synchronized SRT subtitles. The frontend uploads and then exposes translation, processing, status polling, and download; the backend handles upload-time validation, audio extraction, and word-timed transcription, followed by Hindi translation and the dubbing pipeline. The main pipeline orchestrates speech generation, timing adjustment, audio composition, subtitles, video rendering, and synchronization checks. The README documents those capabilities; some service-to-service calls are supported only by its workflow description or the source index, so those edges are marked as documented rather than inferred from filenames.

Main entry points: [`backend/app/services/job_processing_service.py`](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/job_processing_service.py) (Dubbing orchestrator), [`backend/app/api/upload.py`](https://github.com/sayan4496/transcadence/blob/main/backend/app/api/upload.py) (Video upload), [`backend/app/main.py`](https://github.com/sayan4496/transcadence/blob/main/backend/app/main.py) (API application), [`frontend/src/api.ts`](https://github.com/sayan4496/transcadence/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["Dubbing workspace<br/>[App.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_jobstate["Local job history<br/>[jobs.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["API application<br/>[main.py]"]
  node_upload["Video upload<br/>[upload.py]"]
  node_transcribe_api["Transcription route<br/>[transcribe.py]"]
  node_translate_api["Translation route<br/>[translate.py]"]
  node_jobs_api["Job routes<br/>[jobs.py]"]
end

subgraph group_speech["Speech and translation"]
  node_asr["Word-timed ASR<br/>[asr_service.py]"]
  node_translation["Hindi translation"]
  node_sync["Cadence alignment<br/>[sync_service.py]"]
  node_tts["Hindi speech TTS<br/>[tts_service.py]"]
end

subgraph group_media["Media composition"]
  node_video_validate["Video validation<br/>[video_service.py]"]
  node_audio_extract["Audio extraction<br/>[audio_service.py]"]
  node_pipeline["Dubbing orchestrator"]
  node_adjust["Audio adjustment"]
  node_mix["Timeline audio mix"]
  node_srt["SRT subtitles<br/>[srt_service.py]"]
  node_render["Dubbed video render"]
  node_validation["Sync validation"]
end

subgraph group_state["Job and files"]
  node_files[("Local media files")]
end

node_user(("Video user"))
node_gemini{{"Google Gemini"}}
node_piper{{"Piper voice model"}}
node_ffmpeg{{"FFmpeg"}}

node_user -->|"uploads video"| node_app
node_app -->|"requests API"| node_client
node_app -->|"updates history"| node_jobstate
node_client -->|"POST upload"| node_upload
node_client -->|"POST translate"| node_translate_api
node_client -->|"process, poll, download"| node_jobs_api
node_fastapi -->|"registers route"| node_upload
node_fastapi -->|"registers route"| node_transcribe_api
node_fastapi -->|"registers route"| node_translate_api
node_fastapi -->|"registers route"| node_jobs_api
node_upload -->|"validates video"| node_video_validate
node_upload -->|"extracts audio"| node_audio_extract
node_upload -->|"transcribes audio"| node_asr
node_upload -->|"stores upload and transcript"| node_files
node_transcribe_api -->|"transcribes job"| node_asr
node_translate_api -->|"translates segments"| node_translation
node_translation -->|"generates translation"| node_gemini
node_jobs_api -->|"processes job"| node_pipeline
node_pipeline -->|"aligns speech windows"| node_sync
node_pipeline -->|"synthesizes Hindi"| node_tts
node_tts -->|"synthesizes voice"| node_piper
node_pipeline -->|"fits clip duration"| node_adjust
node_adjust -->|"applies atempo"| node_ffmpeg
node_pipeline -->|"composes timeline audio"| node_mix
node_pipeline -->|"writes subtitles"| node_srt
node_pipeline -->|"renders final video"| node_render
node_render -->|"encodes video"| node_ffmpeg
node_render -->|"reads video metadata"| node_video_validate
node_pipeline -->|"checks synchronization"| node_validation
node_pipeline -->|"reads and writes job artifacts"| node_files
node_jobs_api -->|"returns status and download"| node_files

click node_app "https://github.com/sayan4496/transcadence/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/sayan4496/transcadence/blob/main/frontend/src/api.ts"
click node_jobstate "https://github.com/sayan4496/transcadence/blob/main/frontend/src/jobs.ts"
click node_fastapi "https://github.com/sayan4496/transcadence/blob/main/backend/app/main.py"
click node_upload "https://github.com/sayan4496/transcadence/blob/main/backend/app/api/upload.py"
click node_transcribe_api "https://github.com/sayan4496/transcadence/blob/main/backend/app/api/transcribe.py"
click node_translate_api "https://github.com/sayan4496/transcadence/blob/main/backend/app/api/translate.py"
click node_jobs_api "https://github.com/sayan4496/transcadence/blob/main/backend/app/api/jobs.py"
click node_video_validate "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/video_service.py"
click node_audio_extract "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/audio_service.py"
click node_asr "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/asr_service.py"
click node_translation "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/translation_service.py"
click node_pipeline "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/job_processing_service.py"
click node_sync "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/sync_service.py"
click node_tts "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/tts_service.py"
click node_adjust "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/audio_adjustment_service.py"
click node_mix "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/audio_mix_service.py"
click node_srt "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/srt_service.py"
click node_render "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/video_generation_service.py"
click node_validation "https://github.com/sayan4496/transcadence/blob/main/backend/app/services/sync_validation_service.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_app,node_client,node_jobstate,node_user toneBlue
class node_fastapi,node_upload,node_transcribe_api,node_translate_api,node_jobs_api toneAmber
class node_asr,node_translation,node_sync,node_tts toneMint
class node_video_validate,node_audio_extract,node_pipeline,node_adjust,node_mix,node_srt,node_render,node_validation toneRose
class node_files,node_gemini,node_piper,node_ffmpeg toneIndigo
```

## Components

### Web interface

- [Dubbing workspace](https://github.com/sayan4496/transcadence/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/sayan4496/transcadence/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Local job history](https://github.com/sayan4496/transcadence/blob/main/frontend/src/jobs.ts): `frontend/src/jobs.ts`

### Backend API

- [API application](https://github.com/sayan4496/transcadence/blob/main/backend/app/main.py): `backend/app/main.py`
- [Video upload](https://github.com/sayan4496/transcadence/blob/main/backend/app/api/upload.py): `backend/app/api/upload.py`
- [Transcription route](https://github.com/sayan4496/transcadence/blob/main/backend/app/api/transcribe.py): `backend/app/api/transcribe.py`
- [Translation route](https://github.com/sayan4496/transcadence/blob/main/backend/app/api/translate.py): `backend/app/api/translate.py`
- [Job routes](https://github.com/sayan4496/transcadence/blob/main/backend/app/api/jobs.py): `backend/app/api/jobs.py`

### Speech and translation

- [Word-timed ASR](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/asr_service.py): `backend/app/services/asr_service.py`
- [Hindi translation](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/translation_service.py): `backend/app/services/translation_service.py`
- [Cadence alignment](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/sync_service.py): `backend/app/services/sync_service.py`
- [Hindi speech TTS](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/tts_service.py): `backend/app/services/tts_service.py`

### Media composition

- [Video validation](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/video_service.py): `backend/app/services/video_service.py`
- [Audio extraction](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/audio_service.py): `backend/app/services/audio_service.py`
- [Dubbing orchestrator](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/job_processing_service.py): `backend/app/services/job_processing_service.py`
- [Audio adjustment](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/audio_adjustment_service.py): `backend/app/services/audio_adjustment_service.py`
- [Timeline audio mix](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/audio_mix_service.py): `backend/app/services/audio_mix_service.py`
- [SRT subtitles](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/srt_service.py): `backend/app/services/srt_service.py`
- [Dubbed video render](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/video_generation_service.py): `backend/app/services/video_generation_service.py`
- [Sync validation](https://github.com/sayan4496/transcadence/blob/main/backend/app/services/sync_validation_service.py): `backend/app/services/sync_validation_service.py`

### Job and files

- **Local media files**

### Other components

- **Video user**
- **Google Gemini**
- **Piper voice model**
- **FFmpeg**

## Connections

- Video user → Dubbing workspace: uploads video (evidence: `Readme.MD`)
- Dubbing workspace → API client: requests API (evidence: `frontend/src/App.tsx`)
- Dubbing workspace → Local job history: updates history (evidence: `frontend/src/App.tsx`)
- API client → Video upload: POST upload (evidence: `Readme.MD`)
- API client → Translation route: POST translate (evidence: `Readme.MD`)
- API client → Job routes: process, poll, download (evidence: `Readme.MD`)
- API application → Video upload: registers route (evidence: `backend/app/main.py`)
- API application → Transcription route: registers route (evidence: `backend/app/main.py`)
- API application → Translation route: registers route (evidence: `backend/app/main.py`)
- API application → Job routes: registers route (evidence: `backend/app/main.py`)
- Video upload → Video validation: validates video (evidence: `backend/app/api/upload.py`)
- Video upload → Audio extraction: extracts audio (evidence: `backend/app/api/upload.py`)
- Video upload → Word-timed ASR: transcribes audio (evidence: `backend/app/api/upload.py`)
- Video upload → Local media files: stores upload and transcript (evidence: `backend/app/api/upload.py`)
- Transcription route → Word-timed ASR: transcribes job (evidence: `backend/app/api/transcribe.py`)
- Translation route → Hindi translation: translates segments (evidence: `backend/app/api/translate.py`)
- Hindi translation → Google Gemini: generates translation (evidence: `backend/app/services/translation_service.py`)
- Job routes → Dubbing orchestrator: processes job (evidence: `backend/app/api/jobs.py`)
- Dubbing orchestrator → Cadence alignment: aligns speech windows (evidence: `Readme.MD`)
- Dubbing orchestrator → Hindi speech TTS: synthesizes Hindi (evidence: `Readme.MD`)
- Hindi speech TTS → Piper voice model: synthesizes voice (evidence: `backend/app/services/tts_service.py`)
- Dubbing orchestrator → Audio adjustment: fits clip duration (evidence: `backend/app/services/job_processing_service.py`)
- Audio adjustment → FFmpeg: applies atempo (evidence: `backend/app/services/audio_adjustment_service.py`)
- Dubbing orchestrator → Timeline audio mix: composes timeline audio (evidence: `backend/app/services/job_processing_service.py`)
- Dubbing orchestrator → SRT subtitles: writes subtitles (evidence: `backend/app/services/job_processing_service.py`)
- Dubbing orchestrator → Dubbed video render: renders final video (evidence: `backend/app/services/job_processing_service.py`)
- Dubbed video render → FFmpeg: encodes video (evidence: `backend/app/services/video_generation_service.py`)
- Dubbed video render → Video validation: reads video metadata (evidence: `backend/app/services/video_generation_service.py`)
- Dubbing orchestrator → Sync validation: checks synchronization (evidence: `Readme.MD`)
- Dubbing orchestrator → Local media files: reads and writes job artifacts (evidence: `backend/app/services/job_processing_service.py`)
- Job routes → Local media files: returns status and download (evidence: `Readme.MD`)
