Process video subtitles — transcribe speech, optimize/translate text, burn styled subtitles into video. Use when you need to add subtitles to a video, transcribe audio, translate subtitles, or customize subtitle styles.
AI-powered video captioning: transcribe speech → optimize subtitles → translate → burn into video with beautiful styles.
Always run videocaptioner <command> --help first to check the latest options and defaults before executing a command. The examples below are common patterns, but --help is the source of truth.
pip install videocaptionerbrew install ffmpeg on macOS)OPENAI_API_KEY env var or --api-key flagvideocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
--subtitle-mode hard --quality high -o output.mp4
videocaptioner transcribe video.mp4 --asr bijian -o output.srt
# Output as JSON format to a directory
videocaptioner transcribe video.mp4 --asr bijian --format json -o ./subtitles/
# Free Bing → English, bilingual output with translation above original
videocaptioner subtitle input.srt --translator bing --target-language en --layout target-above -o translated.srt
# Free Google → Japanese, translation only (discard original text)
videocaptioner subtitle input.srt --translator google --target-language ja --no-optimize --layout target-only -o output_ja.srt
# High quality LLM translation with reflective mode
videocaptioner subtitle input.srt --translator llm --target-language en --reflect \
--api-key $OPENAI_API_KEY -o output_en.srt
# Anime-style subtitles (warm color + orange outline), high quality video
videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja \
--subtitle-mode hard --style anime --quality high -o output_ja.mp4
# Modern rounded background subtitles
videocaptioner process video.mp4 --asr bijian --translator google --target-language ko \
--subtitle-mode hard --render-mode rounded -o output_ko.mp4
# Custom colors: white text with red outline, ultra quality
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
--subtitle-mode hard --quality ultra \
--style-override '{"outline_color": "#ff0000", "primary_color": "#ffffff"}' -o output_en.mp4
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
--format ass --no-synthesize -o ./output/
# Step 1: Transcribe
videocaptioner transcribe video.mp4 --asr bijian -o video.srt
# Step 2: Translate (bilingual, original text above translation)
videocaptioner subtitle video.srt --translator bing --target-language en --layout source-above -o video_en.srt
# Step 3: Burn into video with rounded background, high quality
videocaptioner synthesize video.mp4 -s video_en.srt --subtitle-mode hard \
--render-mode rounded --quality high -o video_with_subs.mp4
videocaptioner process podcast.mp3 --asr bijian --translator bing --target-language en -o ./output/
videocaptioner transcribe french_video.mp4 --asr whisper-api \
--whisper-api-key $OPENAI_API_KEY --language fr -o french.srt
videocaptioner subtitle raw_subtitle.srt --no-translate --api-key $OPENAI_API_KEY -o optimized.srt
videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard \
--style-override '{"text_color": "#ffffff", "bg_color": "#000000cc", "corner_radius": 10, "font_size": 36}' \
--font-file ./NotoSansSC.ttf --quality high -o styled_video.mp4
| Command | Purpose |
|---|---|
transcribe | Speech → subtitles. Engines: bijian(free) jianying(free) whisper-api whisper-cpp |
subtitle | Optimize (LLM) and/or translate (LLM/Bing/Google) subtitle files |
synthesize | Burn subtitles into video with customizable styles |
process | Full pipeline: transcribe → optimize → translate → synthesize |
download | Download video from YouTube, Bilibili, etc. |
config | Manage settings (show set get path init) |
style | List all subtitle style presets with parameters |
Run videocaptioner <command> --help for full options.
Two rendering modes for beautiful subtitles:
ASS mode (default) — outline/shadow style:
default (white+black outline), anime (warm+orange outline), vertical (portrait videos)font_name, font_size, primary_color, outline_color, outline_width, bold, spacing, margin_bottomRounded mode — modern rounded background boxes:
rounded (dark text on semi-transparent background)font_name, font_size, text_color, bg_color (#rrggbbaa), corner_radius, padding_h, padding_v, margin_bottomStyle options only work with --subtitle-mode hard.
BCP 47 codes: zh-Hans zh-Hant en ja ko fr de es ru pt it ar th vi id and 23 more.
| Variable | Purpose |
|---|---|
OPENAI_API_KEY | LLM API key |
OPENAI_BASE_URL | LLM API base URL |
0 success · 2 bad arguments · 3 file not found · 4 missing dependency · 5 runtime error
-q for scripting (stdout = result path only)bijian/jianying ASR is free but only supports Chinese & Englishvideocaptioner style to see all style presets