videocaptioner
- Repo stars 14,857
- Author updated Live
- Author repo VideoCaptioner
- Domain
- Engineering
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @WEIFENG2333 · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Required · OpenAI
- Operating systems
- macOS
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: videocaptioner
description: Process video subtitles — transcribe speech, optimize/translate text, burn styled subtitles into…
category: engineering
runtime: no special runtime
---
# videocaptioner output preview
## PART A: Task fit
- Use case: 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..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When to use / Before you start / Common scenarios” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “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.”.
- **02** When the source has headings, the agent prioritizes “When to use / Before you start / Common scenarios” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands, read environment variables; may access external network resources; requires OpenAI API keys.
## Running Rules
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; requires OpenAI API keys.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands, read environment variables.
Start with a small task and check whether the result follows “When to use / Before you start / Common scenarios”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: videocaptioner
description: Process video subtitles — transcribe speech, optimize/translate text, burn styled subtitles into…
category: engineering
source: WEIFENG2333/VideoCaptioner
---
# videocaptioner
## When to use
- Process video subtitles — transcribe speech, optimize/translate text, burn styled subtitles into video. Use when you n…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “When to use / Before you start / Common scenarios” and keep inference separate from source facts.
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; requires OpenAI API keys.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "videocaptioner" {
input -> user goal + target files + boundaries + acceptance criteria
context -> When to use / Before you start / Common scenarios
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands, read environment variables | may access external network resources
guardrails -> requires OpenAI API keys + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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 ffmpegon 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_KEYenv var or--api-keyflag
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
-qfor scripting (stdout = result path only) - Bing/Google translation is free, no API key needed
bijian/jianyingASR is free but only supports Chinese & English- Run
videocaptioner styleto see all style presets
Decide Fit First
Design Intent
How To Use It
Boundaries And Review