videocaptioner

name	videocaptioner
description	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.
allowed-tools	Bash(videocaptioner *, ffprobe *, ffmpeg -ss *)

VideoCaptioner CLI

AI-powered video captioning: transcribe speech → optimize subtitles → translate → burn into video with beautiful styles.

When to use

• User wants to add subtitles to a video
• User wants to transcribe audio/video to text
• User wants to translate subtitles to another language
• User wants to customize subtitle appearance (colors, fonts, rounded backgrounds)
• User wants to download and subtitle online videos

Before you start

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.

• Install: pip install videocaptioner
• FFmpeg required for video synthesis (brew install ffmpeg on macOS)
• Free (no API key): transcription (bijian/jianying), translation (Bing/Google)
• Requires LLM API key: subtitle optimization, subtitle re-segmentation, LLM translation. Set via OPENAI_API_KEY env var or --api-key flag

Common scenarios

1. Give a Chinese video English subtitles (one command, all free)

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality high -o output.mp4

2. Transcribe a video to SRT (free)

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/

3. Translate existing 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

4. Full pipeline with beautiful styled subtitles

# 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

5. Subtitle only, output as ASS format (no video synthesis)

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --format ass --no-synthesize -o ./output/

6. Step-by-step control (transcribe → translate → synthesize separately)

# 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

7. Process audio file (auto-skips video synthesis)

videocaptioner process podcast.mp3 --asr bijian --translator bing --target-language en -o ./output/

8. Transcribe other languages (whisper-api)

videocaptioner transcribe french_video.mp4 --asr whisper-api \
  --whisper-api-key $OPENAI_API_KEY --language fr -o french.srt

9. Only optimize subtitles with LLM (fix ASR errors, no translation)

videocaptioner subtitle raw_subtitle.srt --no-translate --api-key $OPENAI_API_KEY -o optimized.srt

10. Custom rounded background style with custom font

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 reference

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.

Subtitle styles

Two rendering modes for beautiful subtitles:

ASS mode (default) — outline/shadow style:

• Presets: default (white+black outline), anime (warm+orange outline), vertical (portrait videos)
• Customizable fields: font_name, font_size, primary_color, outline_color, outline_width, bold, spacing, margin_bottom

Rounded mode — modern rounded background boxes:

• Preset: rounded (dark text on semi-transparent background)
• Customizable fields: font_name, font_size, text_color, bg_color (#rrggbbaa), corner_radius, padding_h, padding_v, margin_bottom

Style options only work with --subtitle-mode hard.

Target languages

BCP 47 codes: zh-Hans zh-Hant en ja ko fr de es ru pt it ar th vi id and 23 more.

Environment variables

Variable	Purpose
OPENAI_API_KEY	LLM API key
OPENAI_BASE_URL	LLM API base URL

Exit codes

0 success · 2 bad arguments · 3 file not found · 4 missing dependency · 5 runtime error

Tips

• Use -q for scripting (stdout = result path only)
• Bing/Google translation is free, no API key needed
• bijian/jianying ASR is free but only supports Chinese & English
• Run videocaptioner style to see all style presets