### Setup Development Environment

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/contributing.md

Clone the repository and install development dependencies using pip.

```bash
git clone https://github.com/YOUR_USERNAME/VideoCaptioner.git
cd VideoCaptioner
pip install -r requirements.txt
```

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

### Install VideoCaptioner CLI

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Install the lightweight CLI version or the full version with GUI dependencies. Development setup involves cloning the repository and installing dependencies.

```bash
pip install videocaptioner
```

```bash
pip install videocaptioner[gui]
```

```bash
git clone https://github.com/WEIFENG2333/VideoCaptioner.git
cd VideoCaptioner
uv sync
uv run videocaptioner --help
```

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

### Clone and Setup Project on MacOS

Source: https://github.com/weifeng2333/videocaptioner/wiki/Home

Clone the VideoCaptioner repository and set up a Python virtual environment to install project dependencies. Activate the environment before proceeding.

```bash
git clone https://github.com/WEIFENG2333/VideoCaptioner.git
cd VideoCaptioner
python3.** -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

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

### Start Development Server

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Use this command to start the local development server for viewing the documentation. Access it at http://localhost:5173.

```bash
npm run docs:dev
```

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

### Install Dependencies

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Run this command to install project dependencies.

```bash
npm install
```

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

### Configuration File Example

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Example TOML configuration file for VideoCaptioner. Settings are applied with priority: command-line > environment variables > config file > defaults.

```toml
[llm]
api_key = "sk-xxx"
api_base = "https://api.openai.com/v1"
model = "gpt-4o-mini"

[transcribe]
asr = "bijian"
language = "auto"

[subtitle]
optimize = true
translate = false

[translate]
service = "llm"
target_language = "zh-Hans"
```

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

### Install VideoCaptioner CLI

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Install the VideoCaptioner CLI tool. Use the `[gui]` extra for desktop GUI dependencies.

```bash
pip install videocaptioner          # CLI（轻量，无 GUI 依赖）
```

```bash
pip install videocaptioner[gui]     # CLI + GUI 桌面版
```

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

### Install VideoCaptioner CLI

Source: https://github.com/weifeng2333/videocaptioner/blob/master/README.md

Installs the command-line interface for VideoCaptioner. Use the `[gui]` extra to include GUI dependencies.

```bash
pip install videocaptioner          # 仅安装 CLI（轻量，无 GUI 依赖）
```

```bash
pip install videocaptioner[gui]     # 安装 CLI + GUI 桌面版
```

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

### Run VideoCaptioner from Source on MacOS

Source: https://github.com/weifeng2333/videocaptioner/wiki/Home

After cloning the repository and installing dependencies, run the main Python script to start the VideoCaptioner application.

```bash
python main.py
```

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

### VideoCaptioner Development Setup

Source: https://github.com/weifeng2333/videocaptioner/blob/master/README.md

Clones the repository and sets up the development environment using `uv`. Includes commands to run the GUI, CLI, type checking, and tests.

```bash
git clone https://github.com/WEIFENG2333/VideoCaptioner.git
```

```bash
cd VideoCaptioner
```

```bash
uv sync && uv run videocaptioner     # 运行 GUI
```

```bash
uv run videocaptioner --help          # 运行 CLI
```

```bash
uv run pyright                        # 类型检查
```

```bash
uv run pytest tests/test_cli/ -q      # 运行测试
```

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

### Initialize Configuration Interactively

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Start an interactive process to set up the videocaptioner configuration. This is helpful for new users or when setting up for the first time.

```bash
videocaptioner config init
```

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

### Install and Launch VideoCaptioner GUI

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Install the GUI version of VideoCaptioner using pip and launch it by running the command without any arguments. This provides a desktop interface for video processing.

```bash
# 安装并启动 GUI
pip install videocaptioner[gui]
videocaptioner

# macOS 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/WEIFENG2333/VideoCaptioner/master/scripts/run.sh | bash

# Windows：从 Release 下载安装包
# https://github.com/WEIFENG2333/VideoCaptioner/releases
```

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

### Launch VideoCaptioner GUI

Source: https://github.com/weifeng2333/videocaptioner/blob/master/README.md

Installs the GUI components and launches the desktop application. If no arguments are provided, it automatically opens the GUI.

```bash
pip install videocaptioner[gui]
```

```bash
videocaptioner                      # 无参数时自动打开桌面版
```

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

### TOML Configuration File Example

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

An example of the TOML configuration file (`~/.config/videocaptioner/config.toml`) showing various settings for LLM, Whisper API, transcription, subtitles, translation, and synthesis.

```toml
[llm]
api_key = "sk-xxx"
api_base = "https://api.openai.com/v1"
model = "gpt-4o-mini"

[whisper_api]
api_key = "sk-xxx"
api_base = "https://api.openai.com/v1"
model = "whisper-1"

[transcribe]
asr = "bijian"
language = "auto"

[subtitle]
optimize = true
translate = false
split = true
max_word_count_cjk = 18
max_word_count_english = 12
thread_num = 4
batch_size = 20

[translate]
service = "llm"
target_language = "zh-Hans"
reflect = false

[synthesize]
subtitle_mode = "soft"
quality = "medium"
layout = "target-above"
render_mode = "ass"
style = "default"

```

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

### macOS Installation Script

Source: https://github.com/weifeng2333/videocaptioner/blob/master/README.md

Installs VideoCaptioner on macOS using a curl script. This is an alternative installation method.

```bash
curl -fsSL https://raw.githubusercontent.com/WEIFENG2333/VideoCaptioner/master/scripts/run.sh | bash
```

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

### Quick Start: Transcribe and Translate

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Perform basic transcription and translation tasks using the CLI. Free features do not require configuration.

```bash
# 语音转字幕（免费）
videocaptioner transcribe video.mp4 --asr bijian
```

```bash
# 翻译字幕（免费必应翻译）
videocaptioner subtitle input.srt --translator bing --target-language en
```

```bash
# 全流程：转录 → 优化 → 翻译 → 合成
videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja
```

```bash
# 给视频加字幕
videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard
```

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

### Custom Container Examples

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Demonstrates the usage of custom container blocks for tips, warnings, and dangers within Markdown.

```markdown
::: tip 提示
这是一个提示框
:::

::: warning 注意
这是一个警告框
:::

::: danger 危险
这是一个危险警告框
:::
```

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

### Manage VideoCaptioner Configuration

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Manage CLI configuration settings, including viewing, setting, getting values, and initializing interactively.

```bash
videocaptioner config show              # 查看配置
```

```bash
videocaptioner config set <key> <value> # 设置配置项
```

```bash
videocaptioner config get <key>         # 获取配置项
```

```bash
videocaptioner config path              # 配置文件路径
```

```bash
videocaptioner config init              # 交互式初始化
```

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

### Custom Theme Configuration

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Example of configuring a custom theme by importing a CSS file in `docs/.vitepress/theme/index.ts`.

```typescript
// docs/.vitepress/theme/index.ts
import DefaultTheme from "vitepress/theme";
import "./custom.css";

export default DefaultTheme;
```

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

### Troubleshoot ImportError

Source: https://github.com/weifeng2333/videocaptioner/blob/master/tests/README.md

Resolve ImportError by installing all extra dependencies using the uv sync command with the --all-extras flag.

```bash
uv sync --all-extras
```

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

### Install Dependencies for MacOS

Source: https://github.com/weifeng2333/videocaptioner/wiki/Home

For MacOS users, install necessary tools like ffmpeg, aria2, and Python before running the project from source. Ensure you are using a compatible Python version.

```bash
brew install ffmpeg
brew install aria2
brew install python@3.**
```

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

### Get Single Configuration Item

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Retrieve the value of a specific configuration parameter using the 'config get' command. This is useful for verifying settings.

```bash
videocaptioner config get llm.model
```

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

### Install Claude Code Skill

Source: https://github.com/weifeng2333/videocaptioner/blob/master/README.md

Installs the VideoCaptioner skill for Claude Code. This allows AI programming assistants to directly use VideoCaptioner functionalities.

```bash
mkdir -p ~/.claude/skills/videocaptioner
```

```bash
cp skills/SKILL.md ~/.claude/skills/videocaptioner/SKILL.md
```

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

### Apply ASS Style to Video Subtitles

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Use the ASS rendering mode for traditional subtitle styling with custom fonts, colors, and outlines. This example applies an anime style preset and overrides outline color and font size.

```bash
# 使用动漫风格预设
videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard --style anime
```

```bash
# 自定义红色描边
videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard \
  --style-override '{"outline_color": "#ff0000", "font_size": 48}'
```

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

### Build Configuration with build_config()

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

The build_config function merges configurations from multiple sources: defaults, config files, environment variables, and CLI arguments, producing a final configuration dictionary. Configuration values can be retrieved using get() and persisted using save_config_value().

```python
from videocaptioner.cli.config import build_config, get, save_config_value
from pathlib import Path

# 使用默认配置
config = build_config()
print(get(config, "llm.model"))          # gpt-4o-mini
print(get(config, "transcribe.asr"))     # bijian
print(get(config, "translate.target_language"))  # zh-Hans

# 使用自定义配置文件
config = build_config(config_path=Path("./my_config.toml"))

# 命令行参数覆盖
config = build_config(cli_overrides={
    "llm": {"model": "deepseek-chat", "api_base": "https://api.deepseek.com/v1"},
    "translate": {"target_language": "en"},
})

# 持久化保存配置项
save_config_value("llm.api_key", "sk-new-key")
save_config_value("translate.reflect", "true")
save_config_value("subtitle.thread_num", "8")
```

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

### Recommended Configuration for New Users

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/config/llm.md

This configuration is recommended for users new to the system, balancing ease of use with good performance.

```yaml
服务商: 本项目中转站
模型: gpt-4o-mini
线程数: 20
温度: 0.3
```

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

### Exact Text Matching Example

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/asr-chunk-merger.md

Provides a conceptual example of how exact text matching works for identifying overlapping segments. It shows two sequences of words and highlights the longest common subsequence found, which is used to align the chunks.

```text
Chunk1 end: ["and", "we", "need", "to", "find", "the", "best"]
Chunk2 start: ["need", "to", "find", "the", "best", "solution"]

Best match: ["need", "to", "find", "the", "best"] (5 words)
```

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

### Run Quick Tests (Free APIs)

Source: https://github.com/weifeng2333/videocaptioner/blob/master/tests/README.md

Execute tests for Google and Bing translators which do not require any configuration.

```bash
# Google + Bing 翻译器（无需配置）
uv run pytest tests/test_translate/test_google_translator.py tests/test_translate/test_bing_translator.py -v
```

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

### Run Full Tests (Requires API Keys)

Source: https://github.com/weifeng2333/videocaptioner/blob/master/tests/README.md

Configure necessary environment variables for LLM translators and then run all integration tests.

```bash
# 1. 配置环境变量
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_API_KEY=sk-your-key

# 2. 运行所有测试
uv run pytest tests/test_translate/ -v
```

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

### Preview Build Results

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Command to preview the built documentation before deployment.

```bash
npm run docs:preview
```

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

### Build Documentation

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Command to build the documentation for deployment. The output will be in the `docs/.vitepress/dist/` directory.

```bash
npm run docs:build
```

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

### 下载 Ollama 模型

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/config/llm.md

使用 Ollama CLI 下载推荐的 Llama3.1 或更大的 Qwen2.5 模型。确保 Ollama 已安装。

```bash
ollama pull llama3.1:8b
```

```bash
ollama pull qwen2.5:14b
```

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

### Configuration for Privacy-Focused Users

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/config/llm.md

This setup prioritizes privacy by utilizing a local Ollama instance, suitable for sensitive data processing.

```yaml
服务商: Ollama（本地）
模型: qwen2.5:14b
线程数: 4
温度: 0.5
```

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

### Build Docker Image for VideoCaptioner

Source: https://github.com/weifeng2333/videocaptioner/wiki/Home

Build the Docker image for VideoCaptioner by navigating to the project directory and running the docker build command. This prepares the application for containerized deployment.

```bash
git clone https://github.com/WEIFENG2333/VideoCaptioner.git
cd VideoCaptioner
docker build -t video-captioner .
```

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

### Extend with New Translator

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/translate-module.md

Example of extending the translate module by creating a new translator class that inherits from BaseTranslator and implements the `_translate_chunk` method.

```python
from app.core.translate.base import BaseTranslator

class MyTranslator(BaseTranslator):
    def _translate_chunk(self, subtitle_chunk: Dict[str, str]) -> Dict[str, str]:
        # 实现翻译逻辑
        result = {}
        for idx, text in subtitle_chunk.items():
            result[idx] = my_translate_function(text)
        return result
```

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

### AppData Directory Structure

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/guide/cookies-config.md

Illustrates the expected directory structure for VideoCaptioner, highlighting where the cookies.txt file should be placed.

```text
VideoCaptioner/
├─ app/
├─ resource/
├─ AppData/          # Cookie 文件放这里
│  ├─ cache/
│  ├─ logs/
│  ├─ models/
│  ├─ cookies.txt    # ← 将文件放在这里
│  └─ settings.json
└─ work-dir/
```

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

### Configuration for Budget-Conscious Users

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/config/llm.md

This configuration is optimized for cost-effectiveness, making it ideal for users with limited budgets.

```yaml
服务商: SiliconCloud
模型: Qwen/Qwen2.5-72B-Instruct
线程数: 5
温度: 0.3
```

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

### Merge Subtitle Segments (Python)

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

The `merge_segments` method allows combining multiple consecutive subtitle segments into a single one. Specify the start and end indices (inclusive) of the segments to merge.

```python
# 合并段落
asr_data.merge_segments(0, 2)  # 合并 index 0~2 的段落

```

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

### Optimize Subtitle Timing (Python)

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Use `optimize_timing` to adjust the start and end times of adjacent subtitle segments to reduce flickering. A `threshold_ms` can be set to define the minimum gap for optimization.

```python
# 优化相邻字幕时间边界（减少闪烁）
asr_data.optimize_timing(threshold_ms=1000)

```

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

### Iterate and Access Subtitle Segments (Python)

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

You can iterate directly over an `ASRData` object to access individual subtitle segments (`ASRDataSeg`). Each segment contains start time, end time, and the text content.

```python
# 遍历字幕段
for seg in asr_data:
    print(f"[{seg.start_time}ms - {seg.end_time}ms] {seg.text}")
    # 输出: [1200ms - 3400ms] Hello, welcome to this lecture.

```

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

### Submit Sitemap to Google Search Console

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Instructions for submitting the sitemap to Google Search Console for indexing.

```bash
https://weifeng2333.github.io/VideoCaptioner/sitemap.xml
```

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

### Add New Translator Test

Source: https://github.com/weifeng2333/videocaptioner/blob/master/tests/README.md

Example of how to add a new translator test case using pytest. This includes setting up a translator fixture and defining a test method to verify translation functionality.

```python
# tests/test_translate/test_my_translator.py
import pytest
from app.core.translate.my_translator import MyTranslator

@pytest.mark.integration
class TestMyTranslator:
    @pytest.fixture
    def translator(self, target_language):
        return MyTranslator(
            thread_num=2,
            batch_num=5,
            target_language=target_language,
            update_callback=None,
        )

    def test_translate(self, translator, sample_asr_data):
        result = translator.translate_subtitle(sample_asr_data)
        assert len(result.segments) == len(sample_asr_data.segments)
        for seg in result.segments:
            assert seg.translated_text  # 确保有翻译结果
```

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

### Docker 部署 VideoCaptioner

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/guide/getting-started.md

使用 Docker 构建 VideoCaptioner 镜像并运行容器。需要配置环境变量以使用外部 LLM API。

```bash
# 1. 构建镜像
docker build -t video-captioner .

# 2. 运行容器
docker run -d \
  -p 8501:8501 \
  -v $(pwd)/temp:/app/temp \
  -e OPENAI_BASE_URL="Your API address" \
  -e OPENAI_API_KEY="Your API key" \
  --name video-captioner \
  video-captioner

# 3. 访问应用
# 打开浏览器访问 http://localhost:8501
```

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

### Save Transcription Results to SRT (Python)

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

After obtaining `ASRData`, you can save the transcription results to an SRT file using the `save` method. The `to_srt` method can also be used to get the SRT content as a string.

```python
# 保存为 SRT 文件
asr_data.save("output.srt")
print(asr_data.to_srt())

```

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

### Submit Sitemap to Baidu Webmaster Platform

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/README.md

Instructions for submitting the sitemap to Baidu Webmaster Platform for indexing.

```bash
https://ziyuan.baidu.com/
```

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

### merge_chunks Method Parameters

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/asr-chunk-merger.md

Details the parameters for the `merge_chunks` method, including `chunks` (list of ASRData objects), `chunk_offsets` (optional list of start times in milliseconds, defaults to automatic inference), and `overlap_duration` (in milliseconds, defaults to 10000).

```python
merge_chunks(
    chunks: List[ASRData],
    chunk_offsets: Optional[List[int]] = None,
    overlap_duration: int = 10000
) -> ASRData
```

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

### Ubuntu/Debian 手动安装系统依赖

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/guide/getting-started.md

在 Ubuntu/Debian 系统上手动安装 VideoCaptioner 所需的系统依赖，包括 ffmpeg、aria2 和 Python。

```bash
sudo apt update
sudo apt install ffmpeg aria2 python3.11 python3.11-venv python3-pip
```

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

### Manage Configuration Settings

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

The 'config' command manages persistent settings in `~/.config/videocaptioner/config.toml`. Command-line arguments override environment variables, which override config files. Use 'show', 'set', and 'unset' subcommands.

```bash
videocaptioner config show
```

```bash
videocaptioner config set llm.api_key sk-your-openai-key
videocaptioner config set llm.api_base https://api.openai.com/v1
videocaptioner config set llm.model gpt-4o-mini
```

```bash
videocaptioner config set whisper_api.api_key sk-whisper-key
videocaptioner config set whisper_api.api_base https://api.openai.com/v1
```

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

### Automatic Time Offset Inference for Chunk Merging

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/asr-chunk-merger.md

Demonstrates merging chunks without explicitly providing `chunk_offsets`. The `ChunkMerger` will automatically infer the start times of subsequent chunks based on the end time of the previous chunk and the specified `overlap_duration`.

```python
# If chunk_offsets are not provided, they will be inferred automatically
merged = merger.merge_chunks(
    chunks=[chunk1, chunk2, chunk3],
    overlap_duration=10000  # Only overlap duration needs to be specified
)
```

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

### Verify Timestamp Continuity After Merging

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/asr-chunk-merger.md

Provides a code snippet to check for gaps or overlaps in the timestamps of the merged ASR segments. It iterates through the segments and flags any intervals between the end of one segment and the start of the next that exceed a specified threshold (e.g., 2000ms).

```python
# Verify timestamps
for i in range(len(merged.segments) - 1):
    seg1 = merged.segments[i]
    seg2 = merged.segments[i + 1]
    gap = seg2.start_time - seg1.end_time
    if gap > 2000:  # Interval exceeds 2s
        print(f"Warning: Gap of {gap}ms between segments {i} and {i+1}")
```

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

### View Available Subtitle Styles

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

List all available subtitle style presets and their configuration parameters for both ASS and rounded background modes.

```bash
videocaptioner style
```

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

### Apply Rounded Background Style to Video Subtitles

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Utilize the rounded background rendering mode for modern subtitle appearance. Customize background color, corner radius, and text color. This example sets a white text on a semi-transparent red background.

```bash
# 使用圆角背景
videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard --render-mode rounded
```

```bash
# 自定义白字红底
videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard \
  --style-override '{"text_color": "#ffffff", "bg_color": "#ff000099", "corner_radius": 12}'
```

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

### Download Online Videos

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Use the 'download' command with yt-dlp to fetch videos from platforms like YouTube and Bilibili. Downloaded files can be directly processed by the 'process' command. Use '-o' to specify output directory and '-q' for quiet mode.

```bash
videocaptioner download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

```bash
videocaptioner download "https://www.bilibili.com/video/BVxxx" -o ./downloads/
```

```bash
URL="https://www.youtube.com/watch?v=xxx"
videocaptioner download "$URL" -o ./tmp/ -q
FILE=$(ls ./tmp/*.mp4 | head -1)
videocaptioner process "$FILE" --asr bijian --translator bing --target-language zh-Hans
```

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

### Full Process: Transcribe, Optimize, Translate, Synthesize

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Execute the complete video captioning pipeline with a single command. This command supports parameters from transcribe, subtitle, and synthesize.

```bash
videocaptioner process <音视频文件> [选项]
```

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

### Run Type Checking and Formatting

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/contributing.md

Use pyright for type checking and ruff for code formatting and linting. These commands ensure code quality and consistency.

```bash
# Type checking
uv run pyright
```

```bash
# Code formatting
uv run ruff check --select I --fix .
```

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

### View Configuration File Path

Source: https://context7.com/weifeng2333/videocaptioner/llms.txt

Display the location of the current configuration file using the 'config path' command. This helps in locating and editing the configuration.

```bash
videocaptioner config path
```

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

### Fedora 手动安装系统依赖

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/guide/getting-started.md

在 Fedora 系统上手动安装 VideoCaptioner 所需的系统依赖，包括 ffmpeg、aria2 和 Python。

```bash
sudo dnf install ffmpeg aria2 python3.11
```

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

### macOS/Linux 自动安装脚本

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/guide/getting-started.md

推荐使用此脚本在 macOS 或 Linux 上安装 VideoCaptioner。它会自动处理环境检测、依赖安装和工具检测。

```bash
# 1. 克隆项目
git clone https://github.com/WEIFENG2333/VideoCaptioner.git
cd VideoCaptioner

# 2. 运行安装脚本
chmod +x run.sh
./run.sh
```

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

### Initialize ChunkMerger and Merge Two Overlapping Chunks

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/asr-chunk-merger.md

Demonstrates creating a ChunkMerger instance and merging two ASRData objects representing audio chunks with a specified overlap duration and offset. The `min_match_count` parameter controls the minimum number of matching words required for a successful overlap match.

```python
from app.core.asr.chunk_merger import ChunkMerger
from app.core.asr.asr_data import ASRData, ASRDataSeg

# Create merger
merger = ChunkMerger(min_match_count=2)

# Chunk 1: 0-30s recognition results
chunk1_segments = [
    ASRDataSeg("Hello", 0, 1000),
    ASRDataSeg("world", 1000, 2000),
    ASRDataSeg("this", 2000, 3000),
    # ... more segments
]
chunk1 = ASRData(chunk1_segments)

# Chunk 2: 20-50s recognition results (10s overlap)
chunk2_segments = [
    ASRDataSeg("this", 0, 1000),      # Actual time 20-21s
    ASRDataSeg("is", 1000, 2000),     # Actual time 21-22s
    ASRDataSeg("test", 2000, 3000),   # Actual time 22-23s
    # ... more segments
]
chunk2 = ASRData(chunk2_segments)

# Merge
merged = merger.merge_chunks(
    chunks=[chunk1, chunk2],
    chunk_offsets=[0, 20000],      # chunk2 starts at 20s
    overlap_duration=10000         # 10s overlap
)

print(f"Number of segments after merge: {len(merged.segments)}")
```

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

### General CLI Options

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/cli.md

Common options applicable to most VideoCaptioner commands for controlling output verbosity and configuration file usage.

```bash
-v / --verbose       # 详细输出
```

```bash
-q / --quiet         # 静默模式，仅输出结果路径（适合管道使用）
```

```bash
--config FILE       # 指定配置文件
```

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

### 全流程处理视频字幕

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/guide/getting-started.md

最简单的一键式处理流程，包括语音识别、断句、优化、翻译和视频合成。

```bash
# 1. 在主界面点击 "任务创建" 标签
# 2. 拖拽视频文件到窗口，或点击选择文件
#    - 也可以输入 YouTube、B站等视频链接
# 3. 点击 "开始全流程处理" 按钮
# 4. 等待处理完成，输出文件保存在 `work-dir/` 目录
```

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

### Progress Callback Configuration

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/translate-module.md

Implement and configure a progress callback function to monitor translation progress.

```python
def on_progress(result):
    print(f"翻译进度: {result}")

translator = TranslatorFactory.create_translator(
    translator_type=TranslatorType.OPENAI,
    update_callback=on_progress,
)
```

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

### Create LLM Translator

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/dev/translate-module.md

Instantiate an LLM translator using the factory. Requires specifying the model and target language. Adjust temperature for creativity.

```python
from app.core.translate import TranslatorFactory, TranslatorType

# 创建 LLM 翻译器
translator = TranslatorFactory.create_translator(
    translator_type=TranslatorType.OPENAI,
    model="gpt-4o-mini",
    target_language="Chinese",
    temperature=0.7,
)

# 翻译字幕
result = translator.translate_subtitle("subtitle.srt")
```

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

### Configuration for High-Quality Output

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/config/llm.md

Prioritize output quality with this configuration, suitable for tasks requiring the best possible results.

```yaml
服务商: 本项目中转站
模型: claude-sonnet-4.5
线程数: 15
温度: 0.3
反思翻译: 开启
```

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

### 启动 Ollama 服务

Source: https://github.com/weifeng2333/videocaptioner/blob/master/docs/config/llm.md

在本地启动 Ollama 服务，以便 VideoCaptioner 可以连接到它。默认端口为 11434。

```bash
ollama serve
```