Skip to main content
Glama
Hermoso

Hermoso

Official

Add subtitles to a video

add_subtitles

Burn subtitles into video without cutting or re-rendering; optionally get an .srt file, with word- or sentence-timed captions, custom cues, or highlighted spoken words.

Instructions

Burn subtitles into ANY video and get the .srt too; nothing is cut or re-rendered. Set textStyle only when the user describes a look (default: white sentence case, thin outline, bottom). Timed by the spoken words (up to 5 words a line); auto:'sentences' times per sentence. Only when asked, textStyle 'highlight' (or a highlightColor) lights the word being said, timed word by word. Or pass cues to burn your own lines exactly, untranscribed (reel-style phrases, stage directions). burn:false returns only the .srt. Takes a video file or URL, a Vimeo-style page, or a TikTok / Reel / X post link (not YouTube: YouTube does not let us download videos, so upload the file). No speech is refused and refunded. Runs in the background and lands in the Library.

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>"
    },
    "name": "add_subtitles"
  }
}

Input Schema

NameRequiredDescriptionDefault
autoNowords (default) or sentences: timing unit for transcribed subtitles
burnNofalse = only the .srt
cuesNoyour own lines in seconds, no overlap, max 90 chars, no emoji
videoYesthe video to subtitle; a URL, not a local file path; use upload_file for local files
scriptNothe words actually spoken, when you have them: the subtitles then use these words and take only the timing from the audio (a video we rendered already knows its script)
get_costNotrue: return the price only; nothing runs or bills
textStyleNothe look: words, a preset or fields; omit for the default
wordsPerCueNowords per subtitle line when timed by words
idempotency_keyNochosen once, resent unchanged on retries: the same key never buys twice
expected_creditsNothe get_cost price; refused unbilled if the live price differs

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.539
    • addedInput schema / properties / script
      Added value: +{
      +  "description": "the words actually spoken, when you have them: the subtitles then use these words and take only the timing from the audio (a video we rendered already knows its script)",
      +  "maxLength": 8000,
      +  "type": "string"
      +}
  2. Changed5 schema fields changedv0.1.532
    • changedInput schema / properties / auto / description
      Previous value: -"sentences (default) or words: timing unit for transcribed subtitles"New value: +"words (default) or sentences: timing unit for transcribed subtitles"
    • addedInput schema / properties / expected_credits
      Added value: +{
      +  "description": "the get_cost price; refused unbilled if the live price differs",
      +  "type": "number"
      +}
    • addedInput schema / properties / get_cost
      Added value: +{
      +  "description": "true: return the price only; nothing runs or bills",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "chosen once, resent unchanged on retries: the same key never buys twice",
      +  "type": "string"
      +}
    • changedInput schema / properties / wordsPerCue / description
      Previous value: -"words per subtitle line when auto is words"New value: +"words per subtitle line when timed by words"
  3. Changed2 schema fields changedv0.1.525
    • changedInput schema / properties / textStyle / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "properties": {
      -      "background": {
      -        "description": "none|pill|a colour",
      -        "type": "string"
      -      },
      -      "cardColor": {
      -        "type": "string"
      -      },
      -      "color": {
      -        "description": "any CSS colour",
      -        "type": "string"
      -      },
      -      "describe": {
      -        "description": "the look in words",
      -        "type": "string"
      -      },
      -      "font": {
      -        "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
      -        "type": "string"
      -      },
      -      "italic": {
      -        "type": "boolean"
      -      },
      -      "outline": {
      -        "type": "boolean"
      -      },
      -      "outlineColor": {
      -        "type": "string"
      -      },
      -      "position": {
      -        "description": "top|center|lower|bottom or 0.05-0.95 from the top",
      -        "type": [
      -          "string",
      -          "number"
      -        ]
      -      },
      -      "preset": {
      -        "type": "string"
      -      },
      -      "shadow": {
      -        "type": "boolean"
      -      },
      -      "size": {
      -        "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction",
      -        "type": [
      -          "string",
      -          "number"
      -        ]
      -      },
      -      "subFont": {
      -        "type": "string"
      -      },
      -      "subItalic": {
      -        "type": "boolean"
      -      },
      -      "textCase": {
      -        "enum": [
      -          "as-is",
      -          "upper",
      -          "lower",
      -          "title"
      -        ],
      -        "type": "string"
      -      },
      -      "tilt": {
      -        "description": "degrees, ±45",
      -        "type": "number"
      -      },
      -      "weight": {
      -        "type": "number"
      -      }
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "properties": {
      +      "background": {
      +        "description": "none|pill|a colour",
      +        "type": "string"
      +      },
      +      "cardColor": {
      +        "type": "string"
      +      },
      +      "color": {
      +        "description": "any CSS colour",
      +        "type": "string"
      +      },
      +      "describe": {
      +        "description": "the look in words",
      +        "type": "string"
      +      },
      +      "font": {
      +        "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
      +        "type": "string"
      +      },
      +      "highlightColor": {
      +        "description": "word-timed subtitles only: the word being said is lit in this colour (preset highlight sets it)",
      +        "type": "string"
      +      },
      +      "italic": {
      +        "type": "boolean"
      +      },
      +      "outline": {
      +        "type": "boolean"
      +      },
      +      "outlineColor": {
      +        "type": "string"
      +      },
      +      "position": {
      +        "description": "top|center|lower|bottom or 0.05-0.95 from the top",
      +        "type": [
      +          "string",
      +          "number"
      +        ]
      +      },
      +      "preset": {
      +        "type": "string"
      +      },
      +      "shadow": {
      +        "type": "boolean"
      +      },
      +      "size": {
      +        "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction",
      +        "type": [
      +          "string",
      +          "number"
      +        ]
      +      },
      +      "subFont": {
      +        "type": "string"
      +      },
      +      "subItalic": {
      +        "type": "boolean"
      +      },
      +      "textCase": {
      +        "enum": [
      +          "as-is",
      +          "upper",
      +          "lower",
      +          "title"
      +        ],
      +        "type": "string"
      +      },
      +      "tilt": {
      +        "description": "degrees, ±45",
      +        "type": "number"
      +      },
      +      "weight": {
      +        "type": "number"
      +      }
      +    },
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / video / description
      Previous value: -"the video to subtitle"New value: +"the video to subtitle; a URL, not a local file path; use upload_file for local files"
  4. Changed5 schema fields changedv0.1.465
    • addedInput schema / properties / auto / description
      Added value: +"sentences (default) or words: timing unit for transcribed subtitles"
    • addedInput schema / properties / cues / items / properties / end / description
      Added value: +"second the line disappears"
    • addedInput schema / properties / cues / items / properties / start / description
      Added value: +"second the line appears"
    • addedInput schema / properties / cues / items / properties / text / description
      Added value: +"subtitle line text, max 90 characters, no emoji"
    • addedInput schema / properties / wordsPerCue / description
      Added value: +"words per subtitle line when auto is words"
  5. Changed1 schema field changedv0.1.454
    • changedInput schema / properties / textStyle / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "properties": {
      -      "background": {
      -        "description": "none|pill|a colour",
      -        "type": "string"
      -      },
      -      "cardColor": {
      -        "type": "string"
      -      },
      -      "color": {
      -        "description": "any CSS colour",
      -        "type": "string"
      -      },
      -      "describe": {
      -        "description": "the look in words",
      -        "type": "string"
      -      },
      -      "font": {
      -        "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
      -        "type": "string"
      -      },
      -      "italic": {
      -        "type": "boolean"
      -      },
      -      "outline": {
      -        "type": "boolean"
      -      },
      -      "outlineColor": {
      -        "type": "string"
      -      },
      -      "position": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "number"
      -          }
      -        ],
      -        "description": "top|center|lower|bottom or 0.05-0.95 from the top"
      -      },
      -      "preset": {
      -        "type": "string"
      -      },
      -      "shadow": {
      -        "type": "boolean"
      -      },
      -      "size": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "number"
      -          }
      -        ],
      -        "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction"
      -      },
      -      "subFont": {
      -        "type": "string"
      -      },
      -      "subItalic": {
      -        "type": "boolean"
      -      },
      -      "textCase": {
      -        "enum": [
      -          "as-is",
      -          "upper",
      -          "lower",
      -          "title"
      -        ],
      -        "type": "string"
      -      },
      -      "tilt": {
      -        "description": "degrees, ±45",
      -        "type": "number"
      -      },
      -      "weight": {
      -        "type": "number"
      -      }
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "properties": {
      +      "background": {
      +        "description": "none|pill|a colour",
      +        "type": "string"
      +      },
      +      "cardColor": {
      +        "type": "string"
      +      },
      +      "color": {
      +        "description": "any CSS colour",
      +        "type": "string"
      +      },
      +      "describe": {
      +        "description": "the look in words",
      +        "type": "string"
      +      },
      +      "font": {
      +        "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
      +        "type": "string"
      +      },
      +      "italic": {
      +        "type": "boolean"
      +      },
      +      "outline": {
      +        "type": "boolean"
      +      },
      +      "outlineColor": {
      +        "type": "string"
      +      },
      +      "position": {
      +        "description": "top|center|lower|bottom or 0.05-0.95 from the top",
      +        "type": [
      +          "string",
      +          "number"
      +        ]
      +      },
      +      "preset": {
      +        "type": "string"
      +      },
      +      "shadow": {
      +        "type": "boolean"
      +      },
      +      "size": {
      +        "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction",
      +        "type": [
      +          "string",
      +          "number"
      +        ]
      +      },
      +      "subFont": {
      +        "type": "string"
      +      },
      +      "subItalic": {
      +        "type": "boolean"
      +      },
      +      "textCase": {
      +        "enum": [
      +          "as-is",
      +          "upper",
      +          "lower",
      +          "title"
      +        ],
      +        "type": "string"
      +      },
      +      "tilt": {
      +        "description": "degrees, ±45",
      +        "type": "number"
      +      },
      +      "weight": {
      +        "type": "number"
      +      }
      +    },
      +    "type": "object"
      +  }
      +]
  6. Changed5 schema fields changedv0.1.285
    • addedInput schema / properties / auto
      Added value: +{
      +  "enum": [
      +    "sentences",
      +    "words"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / cues
      Added value: +{
      +  "description": "your own lines in seconds, no overlap, max 90 chars, no emoji",
      +  "items": {
      +    "properties": {
      +      "end": {
      +        "type": "number"
      +      },
      +      "start": {
      +        "type": "number"
      +      },
      +      "text": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "text",
      +      "start",
      +      "end"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 400,
      +  "type": "array"
      +}
    • changedInput schema / properties / textStyle / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "pill",
      -      "editorial",
      -      "bold",
      -      "minimal",
      -      "handwritten",
      -      "boxed"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "properties": {
      -      "background": {
      -        "description": "none | pill | #hex box",
      -        "type": "string"
      -      },
      -      "color": {
      -        "description": "#hex",
      -        "type": "string"
      -      },
      -      "font": {
      -        "enum": [
      -          "sans",
      -          "serif",
      -          "elegant",
      -          "condensed",
      -          "hand"
      -        ],
      -        "type": "string"
      -      },
      -      "italic": {
      -        "type": "boolean"
      -      },
      -      "outline": {
      -        "type": "boolean"
      -      },
      -      "position": {
      -        "enum": [
      -          "top",
      -          "center",
      -          "lower",
      -          "bottom"
      -        ],
      -        "type": "string"
      -      },
      -      "preset": {
      -        "enum": [
      -          "pill",
      -          "editorial",
      -          "bold",
      -          "minimal",
      -          "handwritten",
      -          "boxed"
      -        ],
      -        "type": "string"
      -      },
      -      "shadow": {
      -        "type": "boolean"
      -      },
      -      "size": {
      -        "anyOf": [
      -          {
      -            "enum": [
      -              "s",
      -              "m",
      -              "l",
      -              "xl"
      -            ],
      -            "type": "string"
      -          },
      -          {
      -            "type": "number"
      -          }
      -        ]
      -      },
      -      "textCase": {
      -        "enum": [
      -          "as-is",
      -          "upper",
      -          "lower",
      -          "title"
      -        ],
      -        "type": "string"
      -      },
      -      "tilt": {
      -        "description": "degrees, ±12",
      -        "type": "number"
      -      },
      -      "weight": {
      -        "type": "number"
      -      }
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "properties": {
      +      "background": {
      +        "description": "none|pill|a colour",
      +        "type": "string"
      +      },
      +      "cardColor": {
      +        "type": "string"
      +      },
      +      "color": {
      +        "description": "any CSS colour",
      +        "type": "string"
      +      },
      +      "describe": {
      +        "description": "the look in words",
      +        "type": "string"
      +      },
      +      "font": {
      +        "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
      +        "type": "string"
      +      },
      +      "italic": {
      +        "type": "boolean"
      +      },
      +      "outline": {
      +        "type": "boolean"
      +      },
      +      "outlineColor": {
      +        "type": "string"
      +      },
      +      "position": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "description": "top|center|lower|bottom or 0.05-0.95 from the top"
      +      },
      +      "preset": {
      +        "type": "string"
      +      },
      +      "shadow": {
      +        "type": "boolean"
      +      },
      +      "size": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "number"
      +          }
      +        ],
      +        "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction"
      +      },
      +      "subFont": {
      +        "type": "string"
      +      },
      +      "subItalic": {
      +        "type": "boolean"
      +      },
      +      "textCase": {
      +        "enum": [
      +          "as-is",
      +          "upper",
      +          "lower",
      +          "title"
      +        ],
      +        "type": "string"
      +      },
      +      "tilt": {
      +        "description": "degrees, ±45",
      +        "type": "number"
      +      },
      +      "weight": {
      +        "type": "number"
      +      }
      +    },
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / textStyle / description
      Previous value: -"the look: a preset or overrides; omit for the default"New value: +"the look: words, a preset or fields; omit for the default"
    • addedInput schema / properties / wordsPerCue
      Added value: +{
      +  "type": "number"
      +}
  7. Addedv0.1.227

TDQS

A4.5/5.0
Behavior4/5

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

Goes well beyond the annotations: narration is not cut or re-rendered, no-speech jobs are refused and refunded, work runs in the background and lands in the Library, and the idempotency/expected_credits billing safeguards are explained. The one gap is the returned job/handle shape, since there is no output schema — the description says where output lands but not what the call immediately returns.

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-loaded with the core promise and dense with signal, no filler sentences. Some clauses are tightly compressed (the parenthetical "reel-style phrases, *stage directions*") and the style rules run together, which costs a little parseability for a 10-parameter tool.

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

Completeness4/5

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

For a 10-parameter, no-output-schema tool it covers the essentials: input sources, style defaults, cue mode, srt-only mode, billing safeguards, and async/Library delivery. Remaining ambiguity is minor — what the immediate response contains and how to retrieve the artifact afterward.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretation: the default textStyle (white sentence case, thin outline, bottom), the meaning of auto:'sentences' versus word timing, the 5-word line default, and that cues are burned verbatim without transcription. That framing helps an agent choose values rather than just read field docs.

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?

"Burn subtitles into ANY video and get the .srt too" states a specific verb and resource, plus the dual output, and immediately distinguishes it from editing/restyling siblings. The following sentences pin down the two modes (transcribed vs. supplied cues) so an agent can tell exactly which capability this tool carries.

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?

Explicit when-to guidance throughout: set textStyle only when a look is described, use highlight only when asked, pass cues for untranscribed lines, burn:false for srt-only. It also states a hard exclusion (YouTube links refused, upload instead) and the accepted source types, which is exactly the routing information an agent needs.

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

Deploy Server

Other Tools