AI字幕工作流

Requirements

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal # Linux / macOS

Windows PowerShell:

$env:RUSTUP_DIST_SERVER="https://rsproxy.cn"
$env:RUSTUP_UPDATE_ROOT="https://rsproxy.cn/rustup"

winget install --id Rustlang.Rustup --exact --force

rustup set profile minimal
rustup toolchain install stable
rustup default stable
cargo --version

mkdir $env:USERPROFILE\.cargo -Force
@"
[source.crates-io]
replace-with = "rsproxy"

[source.rsproxy]
registry = "sparse+https://rsproxy.cn/index/"
"@ | Set-Content -Encoding UTF8 $env:USERPROFILE\.cargo\config.toml

Install ffmpeg:

sudo apt install ffmpeg            # Debian / Ubuntu
sudo dnf install ffmpeg            # Fedora
sudo pacman -S ffmpeg              # Arch
brew install ffmpeg                # macOS
winget install Gyan.FFmpeg         # Windows

Install SubForge:

git clone https://github.com/deusjin/subforge.git
cd subforge
cargo install --path .
subforge --version

Install Python-side dependencies:

subforge setup                         # CPU PyTorch
subforge setup --compute cu124         # CUDA 12.x
subforge setup --compute cu128-nightly # RTX 50 / Blackwell sm_120
subforge setup --force                 # rebuild the local venv

Create local config:

cp config.toml.example config.toml      # Linux / macOS
copy config.toml.example config.toml    # Windows cmd

Then verify the environment:

subforge doctor

config.toml is ignored by Git because it may contain API keys.

Installation

SubForge currently builds from source. Prebuilt binaries are not published yet.

Quick Start

Process a video end to end:

subforge process video.mp4

Generate translated subtitles without burning them into the video:

subforge translate video.mp4

Batch translate a folder of videos into an output directory:

subforge batch translate videos/ -o out

Use soft subtitle muxing instead of re-encoding the video:

subforge process video.mp4 --synth-mode soft

Generate both a hard-burned video and a soft-subtitle output:

subforge process video.mp4 --synth-mode both

Run each stage manually:

subforge transcribe video.mp4 --asr faster-whisper
subforge subtitle video.srt --translator google
subforge synthesize video.mp4 --subtitle video_translated.srt

Configuration

Config lookup order:

1. --config <path>
2. $SUBFORGE_CONFIG
3. ./config.toml
4. $XDG_CONFIG_HOME/subforge/config.toml
5. $HOME/.config/subforge/config.toml

Common options:

Use:

subforge config show
subforge config get api_key
subforge config set whisper_model medium
subforge config path

subforge config get api_key only prints a redacted prefix.

CLI Overview

Research References

SubForge is engineering-oriented, but several stages are inspired by published subtitle and translation quality work:

• Segment Any Text, EMNLP 2024 - neural segmentation
• Long-Form Speech Translation, Findings of EMNLP 2023 - context-aware subtitle work
• GEMBA-MQM, WMT 2023 - LLM-based quality estimation
• MAPS, WMT 2024 - terminology extraction and consistency
• SubER, IWSLT 2022 - subtitle evaluation

LLM Quality Pipeline

The LLM backend uses a staged pipeline:

source SRT
  |
  +-- terminology extraction
  |     -> glossary.jsonl
  |
  +-- batched translation
  |     -> chained mode or concurrent wave mode
  |
  +-- GEMBA-MQM quality estimation
  |
  +-- targeted refinement for low-score cues
  |
  +-- translation memory
        -> memory.jsonl

chained_translation = true gives the best continuity because every batch sees the previous translations before it runs. It is effectively sequential for the main LLM translation stage.

chained_translation = false warms up with three sequential batches and then runs later batches in concurrent waves. It is faster on long videos, while preserving cross-wave context.

chained_translation = true   # best continuity
thread_num          = 3
batch_size          = 7

For faster long-video runs:

chained_translation = false
thread_num          = 5
batch_size          = 10

batch_size controls how many subtitle cues go into one LLM request. thread_num controls how many requests can run at the same time.

Troubleshooting

For a full local check:

subforge doctor