VideoCaptioner

https://github.com/weifeng2333/videocaptioner
Admin
An AI-powered video captioning tool that provides end-to-end processing including speech...
Tokens:34,804
Snippets:395
Trust Score:9.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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)
```

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

### 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}'
```

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

### 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
```

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

### 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)

```

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

### 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")
```

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

### 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
```

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

### 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}'
```

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

### 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
```

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

### 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
```

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

### 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 .
```

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

### 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 的段落

```

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

### 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
```

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

### 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
```

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

### VideoCaptioner CLI: Configure LLM API Key

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

Sets the API key, base URL, and model for Large Language Model (LLM) functionalities. These configurations are used for subtitle optimization and advanced translation.

```bash
videocaptioner config set llm.api_key <your-key>
```

```bash
videocaptioner config set llm.api_base https://api.openai.com/v1
```

```bash
videocaptioner config set llm.model gpt-4o-mini
```

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

### VideoCaptioner CLI: Download Online Video

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

Downloads video content from online platforms like YouTube.

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

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

### 分步处理视频字幕 - 字幕优化与翻译

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

第二步：对转录生成的字幕进行优化和翻译。支持智能断句、字幕校正和多语言翻译。

```bash
# 1. 切换到 "字幕优化与翻译" 标签
# 2. 加载字幕文件（自动加载或手动选择）
# 3. 配置处理选项：
#    - 智能断句：重新分段，阅读更流畅
#    - 字幕校正：修正错别字、优化格式
#    - 字幕翻译：翻译为目标语言
# 4. （可选）填写文稿提示，提升准确度
# 5. 点击 "开始处理"
```

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

### VideoCaptioner CLI: Full Processing Pipeline

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

Executes the complete video captioning process: transcription, optimization, translation, and synthesis. Specify the target language for translation.

```bash
videocaptioner process video.mp4 --target-language ja
```

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

### Local Development Environment Variables

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

Set up environment variables in a .env file for testing LLM and DeepLX translators locally. This file is ignored by git.

```bash
# LLM 翻译器测试（必需）
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-your-api-key

# DeepLX 翻译器测试（可选）
DEEPLX_ENDPOINT=https://api.deeplx.org/translate
```

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

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

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

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

```bash
brew install ffmpeg aria2 python@3.11
```

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

### ChunkMerger Constructor Parameters

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

Illustrates the initialization of the ChunkMerger class, highlighting the `min_match_count` parameter. This parameter sets the minimum number of consecutive words that must match between overlapping segments to be considered a valid overlap.

```python
ChunkMerger(min_match_count: int = 2)
```

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

### Environment Variable Configuration

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

Configure videocaptioner settings using environment variables. These settings take precedence over the configuration file. Variables can be prefixed with OPENAI_ or VIDEOCAPTIONER_ for specific overrides.

```bash
export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="gpt-4o-mini"

# 或使用 VIDEOCAPTIONER_ 前缀（优先级更高）
export VIDEOCAPTIONER_LLM_API_KEY="sk-xxx"
export VIDEOCAPTIONER_LLM_API_BASE="https://api.openai.com/v1"
export VIDEOCAPTIONER_TARGET_LANG="zh-Hans"

```

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

### Run ChunkMerger Tests with Pytest

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

Instructions on how to execute the test suite for the ChunkMerger module using `pytest`. It shows commands for running all tests or specific test classes within the test file.

```bash
# Run all tests
uv run pytest tests/test_asr/test_chunk_merger.py -v

# Run a specific test
uv run pytest tests/test_asr/test_chunk_merger.py::TestChunkMergerBasic -v
```

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

### build_config()

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

Merges configuration from multiple layers (defaults, config file, environment variables, CLI arguments) into a final configuration dictionary.

```APIDOC
## Function: build_config

### Description
Merges configuration from multiple layers (defaults, config file, environment variables, CLI arguments) into a final configuration dictionary, usable in custom scripts.

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

# Using default configuration
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

# Using a custom configuration file
config = build_config(config_path=Path("./my_config.toml"))

# Command-line argument overrides
config = build_config(cli_overrides={
    "llm": {"model": "deepseek-chat", "api_base": "https://api.deepseek.com/v1"},
    "translate": {"target_language": "en"},
})

# Persistently save configuration items
save_config_value("llm.api_key", "sk-new-key")
save_config_value("translate.reflect", "true")
save_config_value("subtitle.thread_num", "8")
```

### Parameters
- **config_path** (Path, optional): Path to a custom TOML configuration file.
- **cli_overrides** (dict, optional): Dictionary of configuration values to override from the command line.

### Helper Functions
- **get(config, key)**: Retrieves a configuration value by key.
- **save_config_value(key, value)**: Persistently saves a configuration item.
```

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

### Troubleshoot Skipped Tests

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

If tests are skipped due to missing environment variables, set the required variables like OPENAI_BASE_URL and OPENAI_API_KEY.

```bash
export OPENAI_BASE_URL=...
export OPENAI_API_KEY=...
```

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

### Directory Structure for Cookie File

Source: https://github.com/weifeng2333/videocaptioner/wiki/Cookie-配置说明

Ensure your 'cookies.txt' file is placed in the 'AppData' directory alongside other configuration files.

```text
├─AppData
│  ├─cache
│  ├─logs
│  ├─models
│  ├─cookies.txt  # Cookie文件
│  └─settings.json
```

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

### transcribe()

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

Transcribes audio from a given file path using specified configuration.

```APIDOC
## transcribe()

### Description
Transcribes audio from a given file path using specified configuration.

### Method
Python Function Call

### Parameters
#### Path Parameters
- **audio_path** (string) - Required - The path to the audio file to transcribe.
- **config** (TranscribeConfig) - Required - Configuration object for transcription.

### Request Example
```python
from app.core.asr import transcribe

result = transcribe(
    audio_path="video.mp4",
    config=TranscribeConfig(...)
)
```

### Response
#### Success Response
- **result** (object) - The transcription result.
```

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

### Load Subtitle Data from File (Python)

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

The `ASRData` class provides a static method `from_subtitle_file` to load subtitle data from various formats including SRT, VTT, ASS, and JSON. It returns an `ASRData` object.

```python
from videocaptioner.core.asr.asr_data import ASRData, ASRDataSeg
from videocaptioner.core.entities import SubtitleLayoutEnum

# 从字幕文件加载（支持 .srt / .vtt / .ass / .json）
asr_data = ASRData.from_subtitle_file("input.srt")
print(f"段落数: {len(asr_data)}, 有数据: {asr_data.has_data()}")

```

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

### Full Pipeline Video Processing

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

The 'process' command automates the entire workflow: transcription, optimization, translation, and synthesis. It accepts parameters from all other commands. Use '--no-synthesize' to output only subtitle files.

```bash
videocaptioner process video.mp4 \
  --asr bijian \
  --translator bing \
  --target-language zh-Hans
```

```bash
videocaptioner process lecture.mp4 \
  --asr whisper-api \
  --whisper-api-key sk-whisper-xxx \
  --language en \
  --translator llm \
  --target-language zh-Hans \
  --reflect \
  --api-key sk-llm-xxx \
  --api-base https://api.openai.com/v1 \
  --model gpt-4o-mini \
  --subtitle-mode hard \
  --quality high \
  --layout target-above \
  -o ./output/
```

```bash
videocaptioner process video.mp4 \
  --asr bijian \
  --no-synthesize \
  --translator bing \
  --target-language ja
```

```bash
for f in videos/*.mp4; do
  videocaptioner process "$f" --asr bijian -q
done
```

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

### Download Online Videos

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

Download videos from supported platforms like YouTube and Bilibili using the yt-dlp backend.

```bash
videocaptioner download <URL> [-o 目录]
```

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

### Optimize Subtitles with SubtitleOptimizer

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

Use SubtitleOptimizer to batch optimize ASRData with LLMs. It includes an agent loop for automatic validation and correction, with up to 3 retries. Original text is retained on failure. Requires ASRData input.

```python
from videocaptioner.core.optimize.optimize import SubtitleOptimizer
from videocaptioner.core.asr.asr_data import ASRData

asr_data = ASRData.from_subtitle_file("raw_asr.srt")

optimizer = SubtitleOptimizer(
    thread_num=4,          # 并发线程数
    batch_num=20,          # 每批字幕条数
    model="gpt-4o-mini",   # LLM 模型名
    custom_prompt="这是一段机器学习课程字幕，请保留英文专业术语",
    update_callback=lambda data: print(f"已优化 {len(data)} 条"),
)

try:
    optimized_data = optimizer.optimize_subtitle(asr_data)
    optimized_data.save("optimized.srt")
    print(f"优化完成，共 {len(optimized_data)} 段")
finally:
    optimizer.stop()  # 释放线程池资源
```

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

### Create Google Translator

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

Instantiate a Google translator using the factory. Specify the target language for translation.

```python
translator = TranslatorFactory.create_translator(
    translator_type=TranslatorType.GOOGLE,
    target_language="简体中文",
)

result = translator.translate_subtitle("subtitle.srt")
```

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

### Custom Prompt Configuration

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

Customize the translation behavior by providing a custom prompt during translator creation.

```python
translator = TranslatorFactory.create_translator(
    translator_type=TranslatorType.OPENAI,
    custom_prompt="请保持原文的语气和风格",
)
```

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

### Submit Sitemap to Bing Webmaster Tools

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

Instructions for submitting the sitemap to Bing Webmaster Tools for indexing.

```bash
https://www.bing.com/webmasters
```

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

### SubtitleOptimizer

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

Uses LLM for batch concurrent optimization of ASRData with built-in agent loop for validation and correction.

```APIDOC
## Class: SubtitleOptimizer

### Description
Uses LLM for batch concurrent optimization of ASRData with built-in agent loop for validation and correction (up to 3 attempts). Retains original text on failure.

### Usage
```python
from videocaptioner.core.optimize.optimize import SubtitleOptimizer
from videocaptioner.core.asr.asr_data import ASRData

asr_data = ASRData.from_subtitle_file("raw_asr.srt")

optimizer = SubtitleOptimizer(
    thread_num=4,          # Number of concurrent threads
    batch_num=20,          # Number of subtitle items per batch
    model="gpt-4o-mini",   # LLM model name
    custom_prompt="这是一段机器学习课程字幕，请保留英文专业术语",
    update_callback=lambda data: print(f"已优化 {len(data)} 条"),
)

try:
    optimized_data = optimizer.optimize_subtitle(asr_data)
    optimized_data.save("optimized.srt")
    print(f"优化完成，共 {len(optimized_data)} 段")
finally:
    optimizer.stop()  # Release thread pool resources
```

### Parameters
- **thread_num** (int): Number of concurrent threads.
- **batch_num** (int): Number of subtitle items per batch.
- **model** (str): LLM model name.
- **custom_prompt** (str): Custom prompt for the LLM.
- **update_callback** (function): Callback function to report optimization progress.
```

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

### 手动安装 Python 依赖并运行

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

克隆项目后，手动创建虚拟环境、激活并安装 Python 依赖，然后运行主程序。

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

# 创建虚拟环境
python3.11 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或
# .\venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt

# 运行程序
python main.py
```

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

### Parse ASS File and Auto Wrap

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

Parses an ASS file into a type-safe dataclass and performs intelligent line wrapping based on actual rendered width. Ensure the input ASS file exists and the video width is specified for accurate wrapping.

```python
from app.core.subtitle import parse_ass_info, auto_wrap_ass_file

# 解析 ASS 文件（返回类型安全的 dataclass）
ass_info = parse_ass_info(ass_content)
print(f"分辨率: {ass_info.video_width}x{ass_info.video_height}")
for style in ass_info.styles.values():
    print(f"{style.name}: {style.font_name} {style.font_size}px")

# 智能换行（基于实际字体渲染宽度）
auto_wrap_ass_file("input.ass", video_width=1920)
```

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

### Real-time Streaming ASR with Chunk Merging

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

Demonstrates how ChunkMerger can be integrated into a real-time streaming ASR system. The `on_chunk_received` method processes incoming audio chunks, transcribes them, and merges them incrementally to provide continuous ASR output.

```python
class StreamingASR:
    def __init__(self):
        self.merger = ChunkMerger()
        self.chunks = []
        self.offsets = []

    def on_chunk_received(self, chunk_audio, timestamp):
        # Transcribe current chunk
        asr_result = transcribe(chunk_audio)
        self.chunks.append(asr_result)
        self.offsets.append(timestamp)

        # Real-time merge
        if len(self.chunks) >= 2:
            merged = self.merger.merge_chunks(
                chunks=self.chunks,
                chunk_offsets=self.offsets,
                overlap_duration=5000  # 5s overlap
            )
            return merged
```

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

### Run Specific Tests

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

Execute specific test cases, such as only the Google translator, or skip tests requiring API keys using markers.

```bash
# 只运行 Google 翻译器
uv run pytest tests/test_translate/test_google_translator.py::TestGoogleTranslator::test_translate_simple_text -v
```

```bash
# 跳过需要 API 的测试
uv run pytest tests/test_translate/ -m "not integration" -v
```

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

### Generate Subtitles for Long Video

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

Illustrates a practical application of ChunkMerger for generating subtitles for a long video. It outlines a process of segmenting the video, transcribing each segment, and then merging the ASR results using ChunkMerger.

```python
# 60 minute video, 30s segments, 10s overlap
chunks = []
offsets = []

for i in range(0, 3600, 20):  # Start every 20s (30s segment - 10s overlap)
    audio_chunk = extract_audio(video_path, start=i, duration=30)
    asr_result = transcribe(audio_chunk)
    chunks.append(asr_result)
    offsets.append(i * 1000)  # Convert to milliseconds

# Merge all segments
final_result = merger.merge_chunks(
    chunks=chunks,
    chunk_offsets=offsets,
    overlap_duration=10000
)

# Save subtitles
final_result.save("output.srt")
```

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

### Create Bing Translator

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

Instantiate a Bing translator using the factory. Specify the target language for translation.

```python
translator = TranslatorFactory.create_translator(
    translator_type=TranslatorType.BING,
    target_language="Chinese",
)

result = translator.translate_subtitle("subtitle.srt")
```

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

### Google PageSpeed Insights Tool

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

Link to Google PageSpeed Insights for performance analysis.

```bash
https://pagespeed.web.dev/
```
Tokens:
Raw