Skip to content
Get packs

Guide · Agent skill

How to use the VideoCaptioner Subtitles agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The VideoCaptioner Subtitles skill lets an AI agent caption a video for you: it transcribes speech, cleans up and translates the subtitles, and either attaches them to the video or burns them into the picture. It works by driving the cli-anything-videocaptioner command-line tool, which wraps the VideoCaptioner backend. This guide covers what the skill does, how to install it, how to phrase requests, and what to check before you rely on the output.

VideoCaptioner SubtitlesHKUDS/CLI-Anything · Apache-2.0

Quick start

  1. 1Check Python and FFmpeg. Confirm you have Python between 3.10 and 3.12 and FFmpeg installed, since setup fails without them.
  2. 2Install the CLI and backend. Run pip install cli-anything-videocaptioner and pip install videocaptioner in your environment.
  3. 3Place the skill. Unzip the downloaded ZIP and put the folder in ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills.
  4. 4Confirm the CLI runs. Run cli-anything-videocaptioner --help to check the tool is available.
  5. 5Ask for a transcript. Request a transcription of a short test video, which uses the free bijian engine.
  6. 6Translate and review. Ask for a translation with the free Bing translator, then review subtitles before any hard burn.

What the skill lets the agent do

Once the skill is installed, the agent can turn a video's speech into subtitle files in SRT, ASS, TXT or JSON format. It can also clean up those subtitles, translate them into one of 38 target languages, and then either attach them to the video as a soft subtitle track or permanently burn them into the picture (hard subtitles).

Before a final hard burn, the skill can render a single preview frame so you can check how the subtitles look.

  • Transcribe: speech to subtitle file (bijian, jianying, whisper-api or whisper-cpp engines)
  • Subtitle: optimize and translate an existing SRT or ASS file
  • Synthesize: burn subtitles into a video, soft or hard
  • Review: check subtitle/script drift and render a preview frame
  • Process: run the whole pipeline in one command

Install the skill from the ZIP

Download the skill ZIP from this page and unzip it. The package contains a single file, SKILL.md. Then choose one of the two install locations below.

For a personal skill available across your projects, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Single project: .claude/skills/ inside the project folder
  • Claude apps: Settings → Capabilities → Skills (upload)

Install the required tools

The skill needs the command-line tool and its backend. The SKILL.md installs the CLI with pip, and the backend must also be installed. You need Python 3.10 to 3.12, because the backend version 1.4.1 requires Python '>=3.10,<3.13'. The source suggests Python 3.12 for the most reliable runs.

FFmpeg is also required for producing video output such as burned-in subtitles.

  • Python 3.10-3.12 (3.12 preferred per the source)
  • FFmpeg installed and available for video synthesis
  • Optional: whisper-api key, passed with --whisper-api-key, for the whisper-api transcription engine
  • Optional: LLM credentials, needed for the llm translator
pip install cli-anything-videocaptioner pip install videocaptioner

Ask the agent in plain language

You do not need to memorise commands. Describe the result you want, naming the video or subtitle file and the target language. The agent maps your request to the right command. To check that the CLI works, you can run the help command yourself first.

If you want the agent to read results directly, the source notes that every command supports a JSON output mode for machine-readable output.

  • "Transcribe video.mp4 and give me an SRT file."
  • "Translate subtitles.srt into English using the free Bing translator."
  • "Make a full captioned version of video.mp4 with hard subtitles in English."
  • "Render a preview frame from review_5s.png before you burn the final video."
cli-anything-videocaptioner --help

Examples of the underlying commands

The agent runs commands like these. You can run them yourself to understand what it is doing. The bijian engine is free and works for Chinese and English with no setup. The Bing translator is also free.

The process command runs transcribe, translate and burn in one step. Use --subtitle-mode hard to burn the subtitles into the picture.

cli-anything-videocaptioner transcribe video.mp4 --asr bijian cli-anything-videocaptioner subtitle input.srt --translator bing --target-language en cli-anything-videocaptioner process video.mp4 --asr bijian --translator bing --target-language en --subtitle-mode hard cli-anything-videocaptioner --json transcribe video.mp4 --asr bijian

Check subtitles before a final hard burn

Burning subtitles is hard to undo, so the skill includes a review step. The review command detects drift between your subtitle file and an approved script, and can render one preview frame at a chosen timecode. The synthesize command can also run this check with --review-script.

Lower --max-script-diff-ratio when exact wording matters more than tolerance for small differences.

  • review: checks subtitles against a script and can output a preview image
  • synthesize --review-script: checks drift before the final export
cli-anything-videocaptioner review subtitles.srt --script approved_script.txt --preview-video video.mp4 --preview-output review_5s.png

Safety notes: scripts and network

This skill runs scripts on your machine through the command-line tool, and it uses the network. The bijian and Bing/Google options are free, but the whisper-api and LLM options send data to external services. If your recording is sensitive, avoid those options or check that you are comfortable with the data leaving your computer.

Subtitle appearance is controlled by the backend version, not by extra harness flags. Flags such as layout, style and font_file should be treated as non-stable unless the styles command confirms the installed backend supports them. Run styles to see what your install exposes.

  • Runs scripts: yes, via the cli-anything-videocaptioner command
  • Uses network: yes; whisper-api and LLM options send content to third parties
  • Check styles output before relying on custom styling flags
cli-anything-videocaptioner styles

Tips for better results

Start with a short clip to confirm the install works before captioning long videos. Review the transcript yourself, because automatic speech recognition and translation can make errors. Use the review step before any hard burn.

Check that your target language code is correct. The source uses BCP 47 codes such as zh-Hans, zh-Hant, en, ja, ko, fr and de.

  • Test on a short clip first
  • Use the review command before hard-burning
  • Use BCP 47 codes such as en, fr, zh-Hans
  • Use config show and config set to manage settings

What people use it for

  • Adding English subtitles to a short social video with a hard burn
  • Translating an existing SRT file into another language with a free translator
  • Producing a scripted captioning pipeline that runs in one process command
  • Checking a preview frame of subtitles at a chosen timecode before the final export

Frequently asked questions

Is the VideoCaptioner Subtitles skill free?

The source describes the bijian transcription engine and the Bing and Google translators as free, with no setup needed for bijian. Options such as whisper-api and the LLM translator need a key or credentials, which may carry their own costs. Check the licence of the repository, which is Apache-2.0.

What do I need to install before using this skill?

You need Python 3.10 to 3.12, the cli-anything-videocaptioner and videocaptioner Python packages, and FFmpeg for video output. The source recommends Python 3.12 for the most reliable runs.

Where do I put the skill folder?

Unzip the ZIP and place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Why does the agent fail with a Python version error?

The backend requires Python '>=3.10,<3.13' for version 1.4.1, so Python 3.13 or newer will not work. Install Python 3.10, 3.11 or 3.12 and install the packages again in that environment.

Can it burn subtitles into a video?

Yes. The synthesize and process commands can burn subtitles with --subtitle-mode hard, and the soft mode attaches them instead. Burning requires FFmpeg.

Is the transcription accurate enough for legal or medical captions?

The source warns that automatic speech recognition and translation can make errors that need human review, so it is not suited to guaranteed-accuracy legal, medical or broadcast captions without checking.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits creators and teams who want quick subtitles and free translations for short videos, and who can install Python and FFmpeg. Pick another tool if you need guaranteed accuracy for legal, medical or broadcast captions, or if you cannot send audio to network services for sensitive recordings.

Download the skill