### Clone Repository and Install Dependencies

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Clones the pyVideoTrans repository and installs its dependencies using uv. Ensure the path for cloning does not contain spaces or Chinese characters.

```bash
# 1. Clone the repository (Ensure path has no spaces/Chinese characters)
git clone https://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans

# 2. Install dependencies (uv automatically syncs environment)
uv sync

# If you need local channels for qwen-tts and qwen-asr, please execute `uv sync --extra qwen-tts --extra qwen-asr`

```

--------------------------------

### Install Google Cloud Text-to-Speech Package

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/googlecloud_tts.md

Install the required Python package for Google Cloud Text-to-Speech integration. Ensure you are using version 2.14.0 or higher.

```bash
pip install google-cloud-texttospeech>=2.14.0
```

--------------------------------

### Install uv Package Manager (macOS/Linux)

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Installs the uv package manager using a curl script. This is recommended for faster package management and better environment isolation.

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install uv Package Manager (Windows)

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Installs the uv package manager on Windows using PowerShell. This tool helps manage Python dependencies efficiently.

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Configure GPU Acceleration with PyTorch

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Install the CUDA-supported PyTorch version by first uninstalling the CPU version and then adding the appropriate PyTorch, torchaudio, and CUDA libraries.

```bash
# Uninstall CPU version
uv remove torch torchaudio

# Install CUDA version (Example for CUDA 12.x)
uv add torch==2.7 torchaudio==2.7 --index-url https://download.pytorch.org/whl/cu128
uv add nvidia-cublas-cu12 nvidia-cudnn-cu12
```

--------------------------------

### Launch pyVideoTrans GUI

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Starts the graphical user interface for pyVideoTrans using the uv run command. This is the primary way to interact with the tool for most users.

```bash
uv run sp.py
```

--------------------------------

### Translation Cache Implementation

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Shows the structure for translation cache keys and mentions the methods for setting and getting cache entries.

```python
# BaseTrans (videotrans/translator/_base.py) implements MD5-based translation cache:
# Cache key = md5(channel_name + api_url + model + source_lang + target_lang + text)
# Cache files stored in {TEMP_ROOT}/translate_cache/
# Write interface _set_cache(), read interface _get_cache()
```

--------------------------------

### UI Language Example

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/language.md

Modify the 'ui_lang' field by changing the field values to the desired language text, keeping the field names unchanged.

```json
"ui_lang": {
    "SP-video Translate Dubbing": "SP-video Translate Dubbing",
    "Multiple MP4 videos can be selected and automatically queued for processing": "Multiple MP4 videos can be selected and automatically queued for processing",
    "Select video..": "Select video..",
}
```

--------------------------------

### Toolbox Language Example

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/language.md

Modify the 'toolbox_lang' field by changing the field values to the desired language text, keeping the field names unchanged.

```json
"toolbox_lang": {
    "No voice video":"无声视频",
    "Open dir":"打开目录",
    "Audio Wav":"音频文件",
}
```

--------------------------------

### Get System Default Locale

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/language.md

Execute this code in the console to determine the system's current language code, which is used to name the language JSON file.

```python
import locale
locale.getdefaultlocale()[0]
```

--------------------------------

### Language Code List Example

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/language.md

Modify the 'language_code_list' field by changing the field values to the desired display names for each language code, keeping the field names unchanged.

```json
"language_code_list": {
    "zh-cn":"Simplified Chinese",
    "zh-tw":"Traditional Chinese",
    "en":"English",
    "fr":"French",
    "de":"German",
    "ja":"Japanese",
    "ko":"Korean",
    "ru":"Russian",
    "es":"Spanish",
    "th":"Thai",
    "it":"Italian",
    "pt":"Portuguese",
    "vi":"Vietnamese",
    "ar":"Arabic",
    "tr":"Turkish",
    "hi":"Hindi"
  }
```

--------------------------------

### Application Startup Flow

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

The sp.py script serves as the entry point for the application. It initializes the QApplication, sets up logging and error handling, displays a splash screen, and then loads the main window and its associated components.

```python
sp.py (if __name__ == "__main__")
  │
  ├── 1. multiprocessing.freeze_support() / set_start_method('spawn')
  ├── 2. qInstallMessageHandler() 抑制 Qt 警告
  ├── 3. atexit.register(cleanup) 注册退出清理
  ├── 4. QApplication.setHighDpiScaleFactorRoundingPolicy(PassThrough)
  ├── 5. 创建 QApplication
  ├── 6. 检测是否在压缩包内运行（PyInstaller 打包版）
  ├── 7. 创建 StartWindow (splash screen, 无边框半透明)
  │       └── QTimer.singleShot(100ms) → initialize_full_app()
  │           ├── 重定向 sys.stdout/stderr 到日志文件
  │           ├── 设置全局异常钩子 show_global_error_dialog
  │           ├── 解析 --lang CLI 参数
  │           ├── 导入 darkstyle_rc（编译后的 QRC 资源）
  │           ├── 加载 QSS 样式表 (videotrans/styles/style.qss)
  │           ├── 恢复上次窗口大小 (QSettings)
  │           └── 实例化 MainWindow → uito 连接 splash.update_lable
  │               └── MainWindow.__init__()
  │                   ├── setupUi() → 填充下拉列表（翻译/识别/TTS 渠道、语言列表）
  │                   ├── AiLoaderThread 启动 → 检测 GPU → 回调 _start_workers()
  │                   ├── _start_workers() → start_thread() 启动 9 种 Worker 线程
  │                   ├── _set_default() → 恢复上次用户选择
  │                   ├── _bind_signal() → 绑定 ~60 个控件事件
  │                   ├── SignalHub.new_message.connect(win_action.update_data)
  │                   └── uito.emit('end') → splash 关闭
  └── 8. app.exec() → Qt 事件循环
```

--------------------------------

### Unified Entry Function for Modules

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Demonstrates the unified 'run' entry point functions for recognition, translator, and tts modules, which use 'get_class' to instantiate and call the appropriate channel class.

```python
# recognition/__init__.py
def run(*, recogn_type, detect_language, audio_file, ...) -> List[SrtItem]:
    _cls = get_class(recogn_type, "recognition", _ID_NAME_DICT)
    return _cls(**kwargs).run()

# translator/__init__.py
def run(*, translate_type, text_list, source_code, target_code, ...) -> List[SrtItem]:
    _cls = get_class(translate_type, "translator", _ID_NAME_DICT)
    return _cls(**kwargs).run()

# tts/__init__.py
def run(*, queue_tts, language, tts_type, ...) -> None:
    _cls = get_class(tts_type, "tts", _ID_NAME_DICT)
    return _cls(**kwargs).run()
```

--------------------------------

### Use pyVideoTrans CLI

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Indicates how to use the command-line interface for pyVideoTrans. Detailed parameters can be found in the official documentation.

```bash
# Use CLI:
# [View documentation for detailed parameters](https://pyvideotrans.com/cli)

```

--------------------------------

### AppSettings Features

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Demonstrates dictionary-like access and type coercion features of the AppSettings configuration class.

```python
settings['key']
settings.get('key', default)
```

--------------------------------

### Translate Language Example

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/language.md

Modify the 'translate_language' field by changing the field values to the desired language text, keeping the field names unchanged.

```json
"translate_language": {
    "qianyiwenjian": "The video path or name contains non ASCII spaces. To avoid errors, it has been migrated to ",
    "mansuchucuo": "Video automatic slow error, please try to cancel the 'Video auto down' option",
}
```

--------------------------------

### Environment Variable Initialization

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Code snippet showing environment variables being set during module loading for model caching, Qt API, PATH, and parallelism control.

```python
MODELSCOPE_CACHE / HF_HOME / HF_HUB_CACHE -> ROOT_DIR/models
QT_API = 'pyside6'
PATH append ffmpeg/sox dir
OMP_NUM_THREADS = 1
TOKENIZERS_PARALLELISM = false
```

--------------------------------

### SignalHub Implementation

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

A singleton class implementing a message center using Qt signals for inter-thread communication, emitting new messages with a UUID and data payload.

```python
class SignalHub(QObject):
    _instance = None
    new_message = Signal(str, object)  # (uuid, SignMsg)

    @classmethod
    def instance(cls):
        if cls._instance is None:
            cls._instance = cls()
        return cls._instance

    def post(self, uuid, data):
        self.new_message.emit(uuid, data)  # uses QueuedConnection automatically
```

--------------------------------

### Run Video Translation Task

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Execute the video translation task using the CLI. Specify the video file, source, and target language codes.

```bash
uv run cli.py --task vtv --name "./video.mp4" --source_language_code zh --target_language_code en
```

--------------------------------

### Configuration Classes

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Dataclass definitions for application configuration, including runtime state (AppCfg), global settings (AppSettings), and user preferences (AppParams).

```python
app_cfg: AppCfg = AppCfg()
settings: AppSettings = AppSettings()
params: AppParams = AppParams()
```

--------------------------------

### GPU Process Pool Sizing Logic

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Explains the logic for determining the number of GPU workers, prioritizing manual settings and then falling back to auto-detection based on available GPUs.

```python
prioritize settings.process_max_gpu
fallback to auto-detection based on multi_gpus and NVIDIA_GPU_NUMS
(no GPU = 1, single GPU = 1, multi-GPU = min(GPU count, 8, cpu_count))
```

--------------------------------

### AppCfg Runtime State

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Details the components of AppCfg, including its 9 queues, tracking dictionaries for video separation and line roles, and a cache for child window instances.

```python
prepare_queue
taskdone_queue
queue_novice: Dict
line_roles: Dict
child_forms: Dict
```

--------------------------------

### Verify Vulkan Support

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/whisper_net_setup.md

Run this command in your terminal to check if your graphics card supports Vulkan. If it displays graphics card information, Vulkan is supported.

```bash
vulkaninfo
```

--------------------------------

### Run Audio to Subtitle Task

Source: https://github.com/jianchang512/pyvideotrans/blob/main/README.md

Execute the audio to subtitle task using the CLI. Specify the audio file and the transcription model.

```bash
uv run cli.py --task stt --name "./audio.wav" --model_name large-v3
```

--------------------------------

### TransCreate Core Internal Methods

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Key internal methods of the TransCreate class responsible for the 9-stage video translation process, including initialization, audio/video splitting, and subtitle handling.

```python
__post_init__()
_split_novoice_byraw()
_split_audio_byraw()
_tts()
_create_ref_from_vocal()
_recogn_succeed()
_back_music()
_separate()
_process_subtitles()
```

--------------------------------

### UI Architecture Layers

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

The UI is structured in layers: UI Definition (PySide6 layouts), UI Logic (reusable components), Window Management (settings/feature windows), Main Window (initialization, logic, lifecycle), and Task Layer (processing engines).

```python
UI 定义层         videotrans/ui/         ← PySide6 UI 布局文件（~74 个），dark/ 资源文件
    ↓
UI 逻辑层         videotrans/component/   ← 通用组件：进度条、设置表单、字幕编辑器、实时语音识别、视频裁剪、文本比对
    ↓
窗口管理层        videotrans/winform/     ← 懒加载的 ~64 个设置/功能窗口模块
    ↓
主窗口层          videotrans/mainwin/
    ├── main_win.py                      ← MainWindow(QMainWindow): UI 初始化、信号绑定、Worker 启动、窗口生命周期
    ├── _actions.py                       ← WinAction: 核心业务逻辑 → 参数收集 → 任务启动 → 状态分发
    └── _actions_base.py                 ← WinActionBase: 代理管理、模式切换、文件选择、CUDA 检测、试听
    ↓
任务层            videotrans/task/        ← TransCreate、SpeechToText、DubbingSrt、TranslateSrt、Worker 线程、SpeedRate
```

--------------------------------

### Dynamic Channel Loading Mechanism

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Provides the Python code for a generic channel provider class and a function to dynamically import and load classes from modules.

```python
@dataclass
class ChannelProvider:
    name: str           # 界面显示名称
    imp: str            # 模块导入后缀（如 "._whisper" → "videotrans.recognition._whisper"）
    key_name: str|None  # 对应 params.json 中的 API key 字段（用于 is_input_api 校验）
    win: str|None       # 对应 winform 中的设置窗口名称

def get_class(channel_id, provider_type, _ID_NAME_DICT):
    key = f'{provider_type}-{channel_id}'
    if key in _loaded_modules:
        return _loaded_modules[key]
    module = importlib.import_module(f'videotrans.{provider_type}{module_map.imp}')
    for _, obj in inspect.getmembers(module, inspect.isclass):
        if obj.__module__ == module.__name__:
            _loaded_modules[key] = obj
            return obj
```

--------------------------------

### Message Handling Flow

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Illustrates the flow of signals and messages within the application, from initial signal emission to specific UI updates based on message types.

```python
BaseCon.signal(**kwargs)
    → push_queue(uuid, SignMsg(**kwargs))     [configure/config.py]
        → SignalHub.instance().post(uuid, data)
            → new_message Signal (QueuedConnection)
                → WinAction.update_data(uuid, data)   [mainwin/_actions.py]
                    → 按 type 分发:
                        'logs'|'error'|'succeed'|'set_precent' → set_process_btn_text()
                        'edit_subtitle_source' → 弹出 EditRecognResultDialog
                        'edit_subtitle_target' → 弹出 SpeakerAssignmentDialog
                        'edit_dubbing' → 弹出 EditDubbingResultDialog
                        'replace_subtitle' → 更新字幕编辑区
                        'end' → update_status('end')
```

--------------------------------

### AppParams Features

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Illustrates batch parameter updates and API key management within the AppParams configuration class.

```python
getset_params(update_data)
```

--------------------------------

### BaseTask Stage Methods

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

These are placeholder methods in the BaseTask class that are intended to be overridden by subclasses to implement specific stages of the video processing pipeline.

```python
prepare()
recogn()
diariz()
trans()
dubbing()
align()
assembling()
task_done()
```

--------------------------------

### CJK Language Special Handling

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Details the post-initialization logic in BaseRecogn for CJK languages, including word joining, line length limits, and character set conversion.

```python
# BaseRecogn (videotrans/recognition/_base.py:60-80) performs special handling for CJK languages in __post_init__:
# - join_word_flag: No space between words for CJK languages (zh, ja, ko, yu, th, km, yue); spaces for others.
# - maxlen: Max characters per line for CJK is settings.cjk_len (default 20), others are settings.other_len (default 46).
# - jianfan: Enables Traditional/Simplified Chinese conversion if language is Chinese and settings.zh_hant_s is True.
```

--------------------------------

### GlobalProcessManager Structure

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Outlines the class-level singleton structure of GlobalProcessManager, detailing its CPU and GPU process pools with worker counts and task management strategies.

```python
GlobalProcessManager (class-level singleton)
    ├── _executor_cpu: multiprocessing.Pool
    │       workers = max(min(available_ram/4GB, 8, cpu_count), 2)  ← based on remaining memory
    │       maxtasksperchild = 1  ← restart after each task to prevent memory leaks
    │
    └── _executor_gpu: multiprocessing.Pool
            workers = GPU count (prioritize settings.process_max_gpu)
            maxtasksperchild = 1
```

--------------------------------

### CPU Process Pool Sizing Logic

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Describes the dynamic calculation of CPU process pool workers based on available system memory, with a configurable override.

```python
psutil.virtual_memory().available
calculated per 4GB RAM, limited to 2-8 workers, not exceeding os.cpu_count()
configurable via settings.process_max
```

--------------------------------

### Task Configuration Data Class Hierarchy

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

The v4.00 release refactored task configurations into a hierarchical `@dataclass` system in `videotrans/task/taskcfg.py`. This structure organizes common and specific fields for different task types.

```python
@dataclass TaskCfgBase              ← Common fields (paths, language codes, cache directory, etc.)
    ├── @dataclass TaskCfgSTT       ← Speech recognition related fields (recogn_type, model_name, rephrase, etc.)
    ├── @dataclass TaskCfgTTS       ← Dubbing related fields (tts_type, voice_role, voice_autorate, etc.)
    ├── @dataclass TaskCfgSTS       ← Translation related fields (translate_type)
    └── @dataclass TaskCfgVTT       ← Full video translation fields (inherits STT + TTS + STS, adds video-specific fields)
```

--------------------------------

### Single Video Processing Workflow

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

The Worker class in videotrans/task/only_one.py executes all 9 stages serially within a single QThread. It communicates with the main thread via uito signals. Key pause points allow for user editing of subtitles and dubbing results.

```python
Worker.run()
    ├── trk = TransCreate(cfg=TaskCfgVTT(**self.cfg | obj))
    ├── trk.prepare()
    ├── trk.recogn()
    ├── trk.diariz()
    ├── [暂停点 ①] → _post(type='edit_subtitle_source')
    │    用户校对原始字幕 → 点击"确定"或等待倒计时
    ├── trk.trans() (if shoud_trans)
    ├── [暂停点 ②] → _post(type='edit_subtitle_target')
    │    用户校对翻译字幕 + 分配说话人角色 → 点击"确定"
    ├── trk.dubbing() (if shoud_dubbing)
    ├── [暂停点 ③] → _post(type='edit_dubbing')
    │    用户修改配音结果 → 点击"确定"
    ├── trk.align()
    ├── trk.recogn2pass()
    ├── trk.assembling()
    └── trk.task_done()
```

--------------------------------

### Multi-threaded Asynchronous Task Processing Architecture

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

pyVideoTrans employs a multi-threaded, multi-queue architecture based on the 'producer-consumer' pattern. The `MultVideo` thread acts as the producer, feeding tasks into the pipeline's queues, which are then processed by specialized `BaseWorker` subclasses.

```python
                     MultVideo (Producer)
                           │
                    app_cfg.prepare_queue
                           ▼
                   WorkerPrepare (×N)
                    ┌────────┼────────┐
                    │ should_recogn ?  │
                    ▼        ▼        ▼
           regcon_queue  trans_queue  dubb_queue / assemb_queue / taskdone_queue
                │
                ▼
          WorkerRegcon (×N)
                │
         diariz_queue
                │
                ▼
          WorkerDiariz (×N)
           ┌────┼────┐
           ▼    ▼    ▼
      trans_queue  dubb_queue  assemb_queue / taskdone_queue
           │
           ▼
     WorkerTrans (×1)
      ┌────┼────┐
      ▼    ▼    ▼
 dubb_queue  assemb_queue  taskdone_queue
      │
      ▼
WorkerDubb (×1)
      │
 align_queue
      │
      ▼
WorkerAlign (×1)
 ┌────┼────┐
 ▼    ▼    ▼
regcon2_queue  assemb_queue  taskdone_queue
 │
 ▼
WorkerRegcon2Pass (×1)
 ┌────┼────┐
 ▼    ▼
assemb_queue  taskdone_queue
 │
 ▼
WorkerAssemb (×N)
 │
taskdone_queue
 │
 ▼
WorkerTaskDone (×1)
 │
(end)
```

--------------------------------

### GlobalProcessManager Task Submission

Source: https://github.com/jianchang512/pyvideotrans/blob/main/docs/architecture.md

Shows the interface for submitting tasks to the CPU or GPU process pools, returning a wrapper around the asynchronous result.

```python
GlobalProcessManager.submit_task_cpu(func, **kwargs)   → AsyncResultFutureWrapper
GlobalProcessManager.submit_task_gpu(func, **kwargs)   → AsyncResultFutureWrapper
```