# meizhong986/whisperjav architecture

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

- Interactive diagram: https://gitdiagram.com/meizhong986/whisperjav
- Repository: https://github.com/meizhong986/whisperjav

## Overview

WhisperJAV is a local Japanese-video subtitle generator, exposed through a command-line interface and a webview GUI. Its main workflow configures a transcription mode, discovers media, prepares and segments audio, runs speech recognition, then assembles and writes subtitles with per-file outcomes. The README also documents ensemble runs, multiple output formats, and a separate translation capability. Sampled source confirms pipeline, enhancement, and configuration responsibilities; several connections and product branches below follow documented behavior because their implementation was not sampled.

Main entry points: [`whisperjav/main.py`](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/main.py) (Run coordinator), [`whisperjav/pipelines/balanced_pipeline.py`](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/balanced_pipeline.py) (Balanced pipeline), [`whisperjav/pipelines/qwen_pipeline.py`](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/qwen_pipeline.py) (Qwen pipeline), [`whisperjav/ensemble/orchestrator.py`](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/ensemble/orchestrator.py) (Ensemble runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_gui["Webview GUI<br/>[main.py]"]
  node_gui_api["GUI API<br/>[api.py]"]
  node_main["Run coordinator<br/>[main.py]"]
end

subgraph group_audio["Audio preparation"]
  node_media["Media discovery<br/>[media_discovery.py]"]
  node_extraction["Audio extraction"]
  node_scene["Scene detection<br/>[scene_detection.py]"]
  node_enhancement["Speech enhancement<br/>[pipeline_helper.py]"]
  node_segmentation["Speech segmentation<br/>[factory.py]"]
end

subgraph group_transcription["Transcription"]
  node_balanced["Balanced pipeline"]
  node_qwen["Qwen pipeline<br/>[qwen_pipeline.py]"]
  node_hf_pipeline["Transformers pipeline"]
  node_ensemble["Ensemble runner<br/>[orchestrator.py]"]
  node_asr["ASR engines"]
end

subgraph group_subtitle["Subtitle and translation"]
  node_subtitle_pipeline["Subtitle pipeline<br/>[orchestrator.py]"]
  node_postprocess["Subtitle post-processing"]
  node_output["Subtitle output<br/>[main.py]"]
  node_outcomes["Run outcomes<br/>[run_outcome.py]"]
  node_translation["Translation service<br/>[service.py]"]
  node_providers["Translation providers<br/>[providers.py]"]
  node_ollama["Ollama service<br/>[ollama_manager.py]"]
end

subgraph group_configuration["Configuration"]
  node_config_manager["Config manager<br/>[manager.py]"]
  node_config_resolver["Config resolver<br/>[resolver_v3.py]"]
end

node_user(("User"))

node_user -->|"invokes"| node_cli
node_user -->|"uses"| node_gui
node_gui -->|"calls"| node_gui_api
node_cli -->|"starts run"| node_main
node_gui_api -->|"starts run"| node_main
node_main -->|"loads settings"| node_config_manager
node_main -->|"resolves options"| node_config_resolver
node_main -->|"discovers files"| node_media
node_main -->|"dispatches mode"| node_balanced
node_main -->|"dispatches mode"| node_qwen
node_main -->|"dispatches mode"| node_hf_pipeline
node_main -->|"dispatches ensemble"| node_ensemble
node_balanced -->|"extracts audio"| node_extraction
node_balanced -->|"detects scenes"| node_scene
node_balanced -->|"prepares audio"| node_enhancement
node_balanced -->|"segments speech"| node_segmentation
node_balanced -->|"transcribes scenes"| node_asr
node_qwen -->|"orchestrates subtitles"| node_subtitle_pipeline
node_qwen -->|"generates text"| node_asr
node_hf_pipeline -->|"transcribes audio"| node_asr
node_ensemble -->|"runs pass"| node_balanced
node_ensemble -->|"runs pass"| node_qwen
node_subtitle_pipeline -->|"cleans subtitles"| node_postprocess
node_main -->|"post-processes output"| node_postprocess
node_main -->|"writes subtitles"| node_output
node_main -->|"records results"| node_outcomes
node_user -.->|"requests translation"| node_translation
node_translation -->|"uses provider"| node_providers
node_translation -.->|"manages local models"| node_ollama

click node_cli "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/cli.py"
click node_gui "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/webview_gui/main.py"
click node_gui_api "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/webview_gui/api.py"
click node_main "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/main.py"
click node_config_manager "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/config/manager.py"
click node_config_resolver "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/config/resolver_v3.py"
click node_media "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/media_discovery.py"
click node_extraction "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/audio_extraction.py"
click node_scene "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/scene_detection.py"
click node_enhancement "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/speech_enhancement/pipeline_helper.py"
click node_segmentation "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/speech_segmentation/factory.py"
click node_balanced "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/balanced_pipeline.py"
click node_qwen "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/qwen_pipeline.py"
click node_hf_pipeline "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/transformers_pipeline.py"
click node_ensemble "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/ensemble/orchestrator.py"
click node_asr "https://github.com/meizhong986/whisperjav/tree/main/whisperjav/modules"
click node_subtitle_pipeline "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/subtitle_pipeline/orchestrator.py"
click node_postprocess "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/srt_postprocessing.py"
click node_output "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/main.py"
click node_outcomes "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/utils/run_outcome.py"
click node_translation "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/translate/service.py"
click node_providers "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/translate/providers.py"
click node_ollama "https://github.com/meizhong986/whisperjav/blob/main/whisperjav/translate/ollama_manager.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_cli,node_gui,node_gui_api,node_main,node_user toneBlue
class node_media,node_extraction,node_scene,node_enhancement,node_segmentation toneAmber
class node_balanced,node_qwen,node_hf_pipeline,node_ensemble,node_asr toneMint
class node_subtitle_pipeline,node_postprocess,node_output,node_outcomes,node_translation,node_providers,node_ollama toneRose
class node_config_manager,node_config_resolver toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/cli.py): `whisperjav/cli.py`
- [Webview GUI](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/webview_gui/main.py): `whisperjav/webview_gui/main.py`
- [GUI API](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/webview_gui/api.py): `whisperjav/webview_gui/api.py`
- [Run coordinator](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/main.py): `whisperjav/main.py`

### Audio preparation

- [Media discovery](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/media_discovery.py): `whisperjav/modules/media_discovery.py`
- [Audio extraction](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/audio_extraction.py): `whisperjav/modules/audio_extraction.py`
- [Scene detection](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/scene_detection.py): `whisperjav/modules/scene_detection.py`
- [Speech enhancement](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/speech_enhancement/pipeline_helper.py): `whisperjav/modules/speech_enhancement/pipeline_helper.py`
- [Speech segmentation](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/speech_segmentation/factory.py): `whisperjav/modules/speech_segmentation/factory.py`

### Transcription

- [Balanced pipeline](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/balanced_pipeline.py): `whisperjav/pipelines/balanced_pipeline.py`
- [Qwen pipeline](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/qwen_pipeline.py): `whisperjav/pipelines/qwen_pipeline.py`
- [Transformers pipeline](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/pipelines/transformers_pipeline.py): `whisperjav/pipelines/transformers_pipeline.py`
- [Ensemble runner](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/ensemble/orchestrator.py): `whisperjav/ensemble/orchestrator.py`
- [ASR engines](https://github.com/meizhong986/whisperjav/tree/main/whisperjav/modules): `whisperjav/modules`

### Subtitle and translation

- [Subtitle pipeline](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/subtitle_pipeline/orchestrator.py): `whisperjav/modules/subtitle_pipeline/orchestrator.py`
- [Subtitle post-processing](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/modules/srt_postprocessing.py): `whisperjav/modules/srt_postprocessing.py`
- [Subtitle output](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/main.py): `whisperjav/main.py`
- [Run outcomes](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/utils/run_outcome.py): `whisperjav/utils/run_outcome.py`
- [Translation service](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/translate/service.py): `whisperjav/translate/service.py`
- [Translation providers](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/translate/providers.py): `whisperjav/translate/providers.py`
- [Ollama service](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/translate/ollama_manager.py): `whisperjav/translate/ollama_manager.py`

### Configuration

- [Config manager](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/config/manager.py): `whisperjav/config/manager.py`
- [Config resolver](https://github.com/meizhong986/whisperjav/blob/main/whisperjav/config/resolver_v3.py): `whisperjav/config/resolver_v3.py`

### Other components

- **User**

## Connections

- User → CLI: invokes
- User → Webview GUI: uses
- Webview GUI → GUI API: calls
- CLI → Run coordinator: starts run
- GUI API → Run coordinator: starts run
- Run coordinator → Config manager: loads settings
- Run coordinator → Config resolver: resolves options
- Run coordinator → Media discovery: discovers files
- Run coordinator → Balanced pipeline: dispatches mode
- Run coordinator → Qwen pipeline: dispatches mode
- Run coordinator → Transformers pipeline: dispatches mode
- Run coordinator → Ensemble runner: dispatches ensemble
- Balanced pipeline → Audio extraction: extracts audio
- Balanced pipeline → Scene detection: detects scenes
- Balanced pipeline → Speech enhancement: prepares audio
- Balanced pipeline → Speech segmentation: segments speech
- Balanced pipeline → ASR engines: transcribes scenes
- Qwen pipeline → Subtitle pipeline: orchestrates subtitles
- Qwen pipeline → ASR engines: generates text
- Transformers pipeline → ASR engines: transcribes audio
- Ensemble runner → Balanced pipeline: runs pass
- Ensemble runner → Qwen pipeline: runs pass
- Subtitle pipeline → Subtitle post-processing: cleans subtitles
- Run coordinator → Subtitle post-processing: post-processes output
- Run coordinator → Subtitle output: writes subtitles
- Run coordinator → Run outcomes: records results
- User → Translation service: requests translation
- Translation service → Translation providers: uses provider
- Translation service → Ollama service: manages local models