edit_captions
The default path for caption/subtitle tweaks: read_captions, then edit wording/spelling, grouping, emphasis, presets, style, layout or translation here. Use set_card_text for what viewers read; source transcription and audible speech stay unchanged. Caption polish needs no source-transcript repair or raw transcript-file edits. For a new look, discover published ordinary/animated presets with template and use their returned previewOptions/applyActions.
Shared appearance, templates and position belong on the caption track: use style/template/layout with trackId (renderer uses sourceId). A selected Card identifies its track; it does not imply a one-Card change. Reserve set_card_style/set_card_layout and cardId renderer writes for intentional local exceptions. Never copy resolved track appearance into every item's appearanceOverride: those values override later track edits. Preserve unrelated authored exceptions.
All caption tooling requires topology v2: real caption tracks/items, never legacy Program/Cue operations. On v1, ONLY action="refresh" is allowed. It converts saved captions to v2 without regenerating them; then read_captions and continue. Reads and other actions never implicitly migrate, reconcile or edit v1.
Start with read_captions (or track_items {"operation":"read"}). It returns caption track ids, compact projections, a revision, and availableSources with separate media track ids/labels. Caption C1/C2 and media V1/A1 are different identities. Never invent ids, captionConfig fields, or a languageCode at the top of a stored track.
Style example: action="style", json {"trackId":"","fontFamily":"Montserrat","captionStyle":{"version":1,"container":{"fontSize":"54px","fontWeight":800,"lineHeight":1.1,"letterSpacing":"-0.02em","textTransform":"uppercase"},"token":{"color":"#FCFCF6"},"activeToken":{"color":"#F8F622"}}}. Font weights accept numbers or strings; lineHeight accepts a positive ratio (number or numeric string) or px/em. CSS lengths, including signed letterSpacing, preserve their units. Flat captionStyle typography/paint aliases normalize into slots; do not specify the same property twice. Desktop uses its own native style model, not this CSS sheet.
Successful writes return a compact receipt with status, revision and bounded changed/created/deleted IDs, not a caption page. Use its revision for the next edit and read_captions with limit/cardId/frame filters for content. A host output-size error after a write is not proof the edit failed: read the current state before retrying.
Native actions:
template: discover published templates (optional offset/query/languageCode). Recommend only available publishedTemplates, including motion-graphic entries for animated or distinctive captions. Use returned previewOptions.presetId for embedded widget cards or previewOptions.captionPreview for external visual cards; preserve the returned language and revision. Apply with {catalogTemplateId,languageCode,trackId}. This copies appearance only, preserving destination caption text and timing. Legacy templatePreset remains accepted for existing selections. Pass the actual caption language: all non-CJK languages share the general preset family; CJK uses its own family with preferred authored typography. Never substitute between the two families or claim an unavailable preview works.
enable / disable: change global CC only; never erase or regenerate captions.
source_list: read caption tracks and available media sources, including hidden tracks.
translate: {"languageCode":"zh","mode":"bilingual"}, then {"languageCode":"ja","mode":"bilingual"} adds both requested languages as separate sourced caption tracks, preserving the original and existing translations. Translation uses saved original caption text, not manage_transcript. Omit force to reuse existing translations. Optional trackId selects an ORIGINAL caption track (or its media source); do not select a translated track as the original. mode:"translation" hides only the selected original. primary:"translation" places the new language above its original; otherwise it is placed below. Read back and inspect actual frames.
refresh: update sourced unlocked tracks, retaining authored pages and cached translations when transcript translations are absent.
style / template / layout: edit native caption track appearance and geometry. Optional json trackId (or sourceId) selects a caption track; omit to affect all visible unlocked tracks. style uses captionStyle CSS slots with fontFamily/fontFallbacks, presentation and pagination; familiar color/sizePx aliases normalize to the same native appearance. template with no selector discovers published templates; use its returned applyActions for the chosen template. layout accepts left/top/width/height or preset bottom/top/center (and title-safe top-left etc.). These never change source selection.
set_card_text / set_card_style / set_card_layout / set_card_tokens / set_card_span_style / split_card / merge_cards: native item edits, using cardId and current revision from read_captions. Keep revision inside json. Span style uses exact text, optional occurrence/languageCode, and sibling style/activeStyle. Token edits use tokenId with optional text/fromFrame/endFrame. Split beforeWordKey or beforeWordKeys uses real token ids; merge cardIds must be adjacent items on one track. New item ids and revision are returned; reread after structural edits.
set_card_emphasis: semantic selection only, with {cardId,revision,spans:[{text,emphasis:true|false|"auto",occurrence?,languageCode?}]}. Exact-text matching follows set_card_span_style. true selects explicitly; false suppresses without selecting a replacement; "auto" removes that exact semantic override. Any explicit semantic annotation switches the Card to manual selection. Text, timing, token ids and CSS remain unchanged. set_card_span_style also accepts emphasis with optional style; style:null clears CSS while preserving emphasis. read_captions with words:true returns projected words and resolvedEmphasis.
renderer: read/set native track or item code using inline code and optional properties. sourceId selects a caption track; cardId plus revision selects an item. Omit code to read, code:null to clear. The shared Web caption-renderer validator still applies. Caption code reads useSpecialEffects().caption_v1; do not create MG assets.
batch: top-level revision plus 1–100 synchronous edits {action,...json fields}. Applies atomically to native rows; any failure writes nothing. Allowed edits: set_card_text, set_card_style, set_card_layout, set_card_span_style, set_card_emphasis, set_card_tokens, split_card, merge_cards. Translation/generation/render requests are not batch edits.
track_items: JSON operations below. Omitted trackId on generate means all sourced unlocked caption tracks, not a media track. To generate a new original track, create it first and use the returned caption track id.
If an original track already has one requested language (e.g. Chinese speech), keep it and translate only missing languages; do not duplicate Chinese as a translation of Chinese. Word edits fromFrame/endFrame are absolute timeline frames; saved token.from is relative to its Card and may be negative.
track_items examples (json is a JSON string in the tool arguments): {"operation":"create-track","name":"Original","source":{"trackId":""}} {"operation":"create-track","name":"Notes","source":null} {"operation":"generate","trackId":""} {"operation":"update-track","trackId":"","hidden":false,"appearance":{"captionStyle":{"version":1,"token":{"color":"#ffffff"}}}} {"operation":"create-item","trackId":"","from":30,"durationInFrames":60,"text":"Manual subtitle"} {"operation":"update-item","itemId":"","text":"Corrected display wording"} {"operation":"update-item","itemId":"","appearance":{"top":700,"width":1200}} {"operation":"move","itemIds":[""],"trackId":""} {"operation":"delete-items","itemIds":[""]} {"operation":"delete-track","trackId":""} {"operation":"settings","enabled":true} {"operation":"settings"} reads settings without changing them.
Chinese script is a reversible content-display setting, independent of language/translation. Use {"operation":"update-track","trackId":"...","appearance":{"presentationOverride":{"chineseScript":"simplified"}}} or the same appearance patch in update-item. Values are original (no conversion), simplified and traditional. OpenCC converts display text in preview/export and read_captions; authored text, source transcript, IDs and timings are preserved. Visual preset/template changes preserve this setting. Do not rewrite every item's text to convert Chinese.
create-track supplies UUID, timelineId, trackType, order, visibility, locking, appearance and suppressedBindings defaults. update-track/update-item patch only supplied fields. Appearance uses captionStyle CSS slots, captionTemplateKey, fontFamily/fontFallbacks, presentationOverride, paginationOverride and geometry left/top/width/height; use canonical native field names, not legacy style aliases. read_captions omits renderer source and reconciliation internals: its compact projections are not complete upsert-track/upsert-item rows. Use incremental operations instead. New manual items use binding:null. A move preserves identity and appearance, suppresses old automatic generation and detaches incompatible source bindings atomically. New text/timing edits are marked authored. Optional revision on any operation rejects stale reads; every write is additionally input-revision fenced. Send edits sequentially.
No legacy fallback exists. source_add/source_update/set_sources/source_layout/positions/layout_policy/cue_* and legacy preset/reset actions are not part of this contract. Use native track creation/patches, item edits and explicit generation instead. Track-wide appearance changes preserve content/timing. Shared source-transcript repair is a separate explicitly requested task, not a first step for caption edits.
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": {
"action": "<action>"
},
"name": "edit_captions"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | For renderer: inline caption JSX using implicit caption_v1. Omit to read; null clears code. Not a file or MG asset. If this host has the active MG Skill's caption_v1 and Web renderer safety references, read them in full before renderer source changes. | |
| json | No | The default path for caption/subtitle tweaks: read_captions, then edit wording/spelling, grouping, emphasis, presets, style, layout or translation here. Use set_card_text for what viewers read; source transcription and audible speech stay unchanged. Caption polish needs no source-transcript repair or raw transcript-file edits. For a new look, discover published ordinary/animated presets with template and use their returned previewOptions/applyActions. Shared appearance, templates and position belong on the caption track: use style/template/layout with trackId (renderer uses sourceId). A selected Card identifies its track; it does not imply a one-Card change. Reserve set_card_style/set_card_layout and cardId renderer writes for intentional local exceptions. Never copy resolved track appearance into every item's appearanceOverride: those values override later track edits. Preserve unrelated authored exceptions. All caption tooling requires topology v2: real caption tracks/items, never legacy Program/Cue operations. On v1, ONLY action="refresh" is allowed. It converts saved captions to v2 without regenerating them; then read_captions and continue. Reads and other actions never implicitly migrate, reconcile or edit v1. Start with read_captions (or track_items {"operation":"read"}). It returns caption track ids, compact projections, a revision, and availableSources with separate media track ids/labels. Caption C1/C2 and media V1/A1 are different identities. Never invent ids, captionConfig fields, or a languageCode at the top of a stored track. Style example: action="style", json {"trackId":"<caption track id>","fontFamily":"Montserrat","captionStyle":{"version":1,"container":{"fontSize":"54px","fontWeight":800,"lineHeight":1.1,"letterSpacing":"-0.02em","textTransform":"uppercase"},"token":{"color":"#FCFCF6"},"activeToken":{"color":"#F8F622"}}}. Font weights accept numbers or strings; lineHeight accepts a positive ratio (number or numeric string) or px/em. CSS lengths, including signed letterSpacing, preserve their units. Flat captionStyle typography/paint aliases normalize into slots; do not specify the same property twice. Desktop uses its own native style model, not this CSS sheet. Successful writes return a compact receipt with status, revision and bounded changed/created/deleted IDs, not a caption page. Use its revision for the next edit and read_captions with limit/cardId/frame filters for content. A host output-size error after a write is not proof the edit failed: read the current state before retrying. Native actions: - template: discover published templates (optional offset/query/languageCode). Recommend only available publishedTemplates, including motion-graphic entries for animated or distinctive captions. Use returned previewOptions.presetId for embedded widget cards or previewOptions.captionPreview for external visual cards; preserve the returned language and revision. Apply with {catalogTemplateId,languageCode,trackId}. This copies appearance only, preserving destination caption text and timing. Legacy templatePreset remains accepted for existing selections. Pass the actual caption language: all non-CJK languages share the general preset family; CJK uses its own family with preferred authored typography. Never substitute between the two families or claim an unavailable preview works. - enable / disable: change global CC only; never erase or regenerate captions. - source_list: read caption tracks and available media sources, including hidden tracks. - translate: {"languageCode":"zh","mode":"bilingual"}, then {"languageCode":"ja","mode":"bilingual"} adds both requested languages as separate sourced caption tracks, preserving the original and existing translations. Translation uses saved original caption text, not manage_transcript. Omit force to reuse existing translations. Optional trackId selects an ORIGINAL caption track (or its media source); do not select a translated track as the original. mode:"translation" hides only the selected original. primary:"translation" places the new language above its original; otherwise it is placed below. Read back and inspect actual frames. - refresh: update sourced unlocked tracks, retaining authored pages and cached translations when transcript translations are absent. - style / template / layout: edit native caption track appearance and geometry. Optional json trackId (or sourceId) selects a caption track; omit to affect all visible unlocked tracks. style uses captionStyle CSS slots with fontFamily/fontFallbacks, presentation and pagination; familiar color/sizePx aliases normalize to the same native appearance. template with no selector discovers published templates; use its returned applyActions for the chosen template. layout accepts left/top/width/height or preset bottom/top/center (and title-safe top-left etc.). These never change source selection. - set_card_text / set_card_style / set_card_layout / set_card_tokens / set_card_span_style / split_card / merge_cards: native item edits, using cardId and current revision from read_captions. Keep revision inside json. Span style uses exact text, optional occurrence/languageCode, and sibling style/activeStyle. Token edits use tokenId with optional text/fromFrame/endFrame. Split beforeWordKey or beforeWordKeys uses real token ids; merge cardIds must be adjacent items on one track. New item ids and revision are returned; reread after structural edits. - set_card_emphasis: semantic selection only, with {cardId,revision,spans:[{text,emphasis:true|false|"auto",occurrence?,languageCode?}]}. Exact-text matching follows set_card_span_style. true selects explicitly; false suppresses without selecting a replacement; "auto" removes that exact semantic override. Any explicit semantic annotation switches the Card to manual selection. Text, timing, token ids and CSS remain unchanged. set_card_span_style also accepts emphasis with optional style; style:null clears CSS while preserving emphasis. read_captions with words:true returns projected words and resolvedEmphasis. - renderer: read/set native track or item code using inline code and optional properties. sourceId selects a caption track; cardId plus revision selects an item. Omit code to read, code:null to clear. The shared Web caption-renderer validator still applies. Caption code reads useSpecialEffects().caption_v1; do not create MG assets. - batch: top-level revision plus 1–100 synchronous edits {action,...json fields}. Applies atomically to native rows; any failure writes nothing. Allowed edits: set_card_text, set_card_style, set_card_layout, set_card_span_style, set_card_emphasis, set_card_tokens, split_card, merge_cards. Translation/generation/render requests are not batch edits. - track_items: JSON operations below. Omitted trackId on generate means all sourced unlocked caption tracks, not a media track. To generate a new original track, create it first and use the returned caption track id. If an original track already has one requested language (e.g. Chinese speech), keep it and translate only missing languages; do not duplicate Chinese as a translation of Chinese. Word edits fromFrame/endFrame are absolute timeline frames; saved token.from is relative to its Card and may be negative. track_items examples (json is a JSON string in the tool arguments): {"operation":"create-track","name":"Original","source":{"trackId":"<media track id from availableSources>"}} {"operation":"create-track","name":"Notes","source":null} {"operation":"generate","trackId":"<returned caption track id>"} {"operation":"update-track","trackId":"<caption track id>","hidden":false,"appearance":{"captionStyle":{"version":1,"token":{"color":"#ffffff"}}}} {"operation":"create-item","trackId":"<caption track id>","from":30,"durationInFrames":60,"text":"Manual subtitle"} {"operation":"update-item","itemId":"<caption item id>","text":"Corrected display wording"} {"operation":"update-item","itemId":"<caption item id>","appearance":{"top":700,"width":1200}} {"operation":"move","itemIds":["<caption item id>"],"trackId":"<destination caption track id>"} {"operation":"delete-items","itemIds":["<caption item id>"]} {"operation":"delete-track","trackId":"<caption track id>"} {"operation":"settings","enabled":true} {"operation":"settings"} reads settings without changing them. Chinese script is a reversible content-display setting, independent of language/translation. Use {"operation":"update-track","trackId":"...","appearance":{"presentationOverride":{"chineseScript":"simplified"}}} or the same appearance patch in update-item. Values are original (no conversion), simplified and traditional. OpenCC converts display text in preview/export and read_captions; authored text, source transcript, IDs and timings are preserved. Visual preset/template changes preserve this setting. Do not rewrite every item's text to convert Chinese. create-track supplies UUID, timelineId, trackType, order, visibility, locking, appearance and suppressedBindings defaults. update-track/update-item patch only supplied fields. Appearance uses captionStyle CSS slots, captionTemplateKey, fontFamily/fontFallbacks, presentationOverride, paginationOverride and geometry left/top/width/height; use canonical native field names, not legacy style aliases. read_captions omits renderer source and reconciliation internals: its compact projections are not complete upsert-track/upsert-item rows. Use incremental operations instead. New manual items use binding:null. A move preserves identity and appearance, suppresses old automatic generation and detaches incompatible source bindings atomically. New text/timing edits are marked authored. Optional revision on any operation rejects stale reads; every write is additionally input-revision fenced. Send edits sequentially. No legacy fallback exists. source_add/source_update/set_sources/source_layout/positions/layout_policy/cue_* and legacy preset/reset actions are not part of this contract. Use native track creation/patches, item edits and explicit generation instead. Track-wide appearance changes preserve content/timing. Shared source-transcript repair is a separate explicitly requested task, not a first step for caption edits. | |
| list | No | For action="track", list:true is a read-only alias of source_list. | |
| edits | No | Native synchronous Card edits applied atomically; a failure writes nothing. Top-level revision required, no json. | |
| action | Yes | Native caption operation. V1 permits ONLY refresh to convert saved captions to v2; all other reads/edits require v2. | |
| cardId | No | Native caption item id for renderer; other Card actions keep cardId inside json. | |
| preset | No | Built-in preset alias for templatePreset with action=template. | |
| trackId | No | Native caption track id; alternatively put trackId in json for style/layout. Media V1/A1 labels are availableSources, not caption tracks. | |
| revision | No | Current read_captions revision for batch and renderer item writes. Other item actions keep revision inside json. | |
| sourceId | No | Native caption track id, not a media source id. Used by renderer/style/layout. | |
| projectId | No | Project for this call (full ID or unambiguous prefix). Explicit-timeline calls never change the target of later calls; legacy project selection applies otherwise. | |
| properties | No | For renderer: editable property definitions. Omit to retain existing definitions; null clears. | |
| timelineId | No | Optional target timeline UUID; must match this invocation's working timeline. | |
| templatePreset | No | Built-in preset id from action=template. Omit to list the catalog. Applying preserves timing, geometry and pagination. | |
| chatcutSpecialEffectUsed | No | For renderer with code: request Web tracking/raw-transcription protocols in addition to implicit caption_v1. Requests follow the caption source and are stored with the scoped renderer. Omit to retain scoped requests unless code includes its own header; null or [] clears. Optional Web-only media-analysis declarations. Omit for ordinary Motion Graphics, effects and caption edits; preserve existing declarations on unrelated revisions. Transitions and Desktop do not support these readers. caption_v1 is supplied only to caption-owned code. |