Skip to main content
Glama

Captions burned into a video

caption_video
Destructive

Burns captions or subtitles into a video from word-timed JSON, SRT or WebVTT files, in karaoke, line or word style, kept clear of app buttons.

Instructions

Use it when the user wants captions or subtitles burned into a video, to read with the sound off, karaoke style or in the brand's fonts, clear of an app's buttons. Burns captions into a video from words with times the user already has: a speech-to-text JSON with word or line times, from OpenAI, whisper.cpp, Deepgram and others, an SRT or WebVTT file, or a demo's steps file, whose step notes become the captions. It does not listen, and no tool here makes such a file. karaoke shows each caption whole and lights the word being spoken, line shows whole captions, word one word at a time. The captions sit inside the space every place in for leaves free of its buttons, drawn by Chrome on this machine in the fonts and color given and laid over the video in one ffmpeg encode, its sound copied. Writes captioned.mp4, captions.srt, captions.vtt, captions.ass, words.json, sheet.png (captions on their frames, the picture to look at first), safe-zones.png (a frame under each app's buttons) and CAPTIONS.md, which the result shows. For the subtitle files alone, use make_subtitles instead. The captions playbook (makersmcp_playbook) has the whole job. (easycaptionkit 0.1.4, on this machine.)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "video": "<video>",
      "words": "<words>"
    },
    "name": "caption_video"
  }
}

Input Schema

NameRequiredDescriptionDefault
boxNoA dark box behind the words instead of an outline.
forNoThe places the video goes to: the captions keep clear of the buttons of every one of them at once (default: the places of the video's shape).
fontNoA font family to draw with, from fonts.css or this machine, like Inter.
sizeNoThe letters' size in percent of a phone's width, or of the frame's short side, 2 to 20 (default 6.5, or 9.5 for the word style). A line too wide for the free space is drawn smaller.
brandNoA brand kit, its folder or brand.json: its button, link or logo color lights the spoken word, and without fonts or font its heading font is asked for by name, which this machine may not have. make_brand_kit makes one.
fontsNoA font kit, its folder or fonts.css: the captions are drawn with the site's own font files, its heading font first. make_font_kit makes one.
linesNoLines a caption may take, 1 to 3 (default 2); the word style shows one.
styleNokaraoke lights the word being spoken in each whole caption (default karaoke), line shows whole captions in one color, word one word at a time, bigger.
videoYesThe video to caption, any file ffmpeg reads. A launch film's film.timeline.json beside it is copied as captioned.timeline.json, so check_video finds its cuts.
wordsYesThe words and their times: a speech-to-text JSON, an SRT or WebVTT file, a demo's steps.json, or the words.json of an earlier run with a misheard word fixed by hand. Not an ASS file.
libassNoDraw the captions with ffmpeg's libass instead of Chrome, for a machine where Chrome cannot start; it needs an ffmpeg built with libass and draws no color emoji.
out_dirNoFolder to save into, absolute or relative to /app. Default: <video-folder>/easycaptionkit-<video-name>, where <video-name> is the name of video without its extension and <video-folder> is the folder video is in. A run replaces the files an earlier run of this kit left there, so give each version its own out_dir.
positionNoWhere in the free space the captions sit (default bottom): middle or top when the picture has text or a face at the bottom of it.
highlightNoThe spoken word's color, like #ffd23f, in the karaoke and word styles; a dark one lights the word on a patch of it.
max_charsNoCharacters a line may take, 8 to 80 (default: what fits the safe width, at most 42).
wait_secondsNoHow long to wait for the result, counted from the start of the call, before returning a job_id to wait on. Some clients end a call after 60 or 240 seconds; 45 is safe in all of them.

Output Schema

NameRequiredDescriptionDefault
kitYes
docsNoThe notes the text shows, and where each one is.
nextNoWhat to do next, as the Next line says.
toolYes
filesNo
folderNoWhere the kit saved its files.
job_idYes
passedNoFor checks: whether the check passed.
statusYes
continuedNoTrue when this call continued the job of an identical call whose answer did not reach the client, instead of starting another.
exit_codeNo
last_lineNoWhat the kit was doing last.
expires_atNoWhen the download links stop working.
next_actionNo
elapsed_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.2.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare a destructive, non-idempotent write, and the description explains exactly why: a run replaces the files an earlier run left in out_dir, so each version needs its own folder. It further discloses the rendering path (Chrome on this machine, or libass as a fallback), a single ffmpeg encode with audio copied, and that a job_id may come back after wait_seconds — all context the annotations do not carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and the alternative, then layers detail; almost every clause carries real information. Some sentences are dense to the point of awkwardness ("the space every place in for leaves free of its buttons") and the output-file inventory duplicates the output schema, costing a little tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter tool, the description covers inputs, prerequisites (words with times must already exist), rendering backend choice, output artifacts, and the sibling alternative. The output schema carries the return shape, so the file list in prose is extra rather than load-bearing, but nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 16 parameters thoroughly, including enum values and defaults. The description reinforces the style modes (karaoke lights the spoken word, line shows whole captions, word is one at a time) in prose, but adds no format or constraint detail beyond what the schema states, so it sits at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Burns captions into a video from words with times the user already has") and immediately scopes what it is not: "It does not listen, and no tool here makes such a file." It also names the sibling boundary — "For the subtitle files alone, use make_subtitles instead" — so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use trigger (captions read with the sound off, karaoke style, brand fonts, clear of an app's buttons) and explicit exclusions (it does not transcribe; use make_subtitles for files alone). It also points to the playbook for the full workflow, covering the case where the agent needs more context than the description carries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.