Retime Caption File
retime_caption_fileRetimes local SRT/VTT caption files after ripple edits to keep captions aligned when Premiere captions do not follow ripple removals or inserts.
Instructions
Retime a local SRT/VTT file after ripple edits; Premiere captions do not follow ripple_remove_timeline_ranges or insert_from_source. Operations: shift, ripple_remove_ranges, ripple_insert, edit_cue. Keeps VTT header/NOTE/STYLE, cue settings, karaoke stamps; renumbers SRT. Local-only, never changes Premiere: re-import via create_caption_track, then reapply styling (get_caption_style_guidance).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | Optional sequence frame rate (e.g. 23.976, 25, 29.97). When set, every output time and every removal range snaps to the nearest frame, matching ripple_remove_timeline_ranges; otherwise times round to milliseconds. Required for offset_frames and duration_frames. | |
| text | No | edit_cue: replacement cue text; separate lines with a newline. Blank lines and "-->" are rejected. | |
| ranges | No | ripple_remove_ranges: removed timeline ranges in seconds, sorted and non-overlapping (the same ranges passed to ripple_remove_timeline_ranges; overlapping ranges are rejected, not merged). | |
| content | No | Inline SRT or VTT text. Provide exactly one of input_path or content. A UTF-8 BOM and CRLF line endings are accepted. | |
| cue_index | No | edit_cue: 1-based cue position in file order (SRT numbers are ignored). | |
| operation | Yes | shift, ripple_remove_ranges, ripple_insert, or edit_cue. | |
| at_seconds | No | ripple_insert: timeline time of the insert; cues starting at or after it move right. | |
| input_path | No | Absolute path of an existing .srt or .vtt file inside approved_workspace_path (realpath-checked, at most 2097152 bytes). Provide exactly one of input_path or content. | |
| end_seconds | No | edit_cue: new cue end in seconds; must be after the start. | |
| output_path | No | Optional absolute .srt/.vtt path to write the result to. Requires approved_workspace_path; the parent must exist inside it and the file must not already exist (never overwritten). | |
| from_seconds | No | shift: only shift cues whose start is at or after this time; earlier cues stay put. | |
| input_format | No | Syntax of the input. Defaults to the input_path extension, else VTT when content starts with WEBVTT, else SRT. | |
| offset_frames | No | shift: whole frames to add at fps (negative moves earlier). | |
| output_format | No | Format of the result (default: the output_path extension, else the input format). SRT output drops VTT header/NOTE/STYLE/REGION blocks, cue settings, identifiers, and karaoke timestamps, with warnings. | |
| start_seconds | No | edit_cue: new cue start in seconds. | |
| offset_seconds | No | shift: seconds to add (negative moves earlier). Cues ending at or before 0 are removed; cues crossing 0 are trimmed. Use exactly one of offset_seconds or offset_frames. | |
| return_content | No | Also return the retimed text inline when output_path is set (default false). Inline text is always returned without output_path, up to 512 KiB. | |
| duration_frames | No | ripple_insert: inserted duration in whole frames at fps. | |
| idempotency_key | No | Optional client-chosen key (1-128 chars of A-Z a-z 0-9 . _ : -) for this intended edit. Pass a fresh key per edit and reuse it only when retrying that same edit, for example after a client-side timeout. A repeat with the same tool, key and arguments is not run again: while the first call is running it fails with IDEMPOTENCY_IN_PROGRESS (poll get_last_operations); after it finished it returns the original outcome marked replayed. A definite failure with nothing applied (receipt outcome not_applied) may be retried with the same key. Reusing a key with different arguments fails with IDEMPOTENCY_KEY_REUSED. Scoped to this MCP session (the stdio server process or one HTTP session) and held in memory only (200 keys, 1 hour); it does not survive a restart or reconnect. Read-only invocations are never deduplicated. | |
| straddle_policy | No | ripple_insert: a cue spanning at_seconds is split into two cues around the gap (split, default) or stretched across it (extend). | |
| duration_seconds | No | ripple_insert: inserted duration in seconds. Use exactly one of duration_seconds or duration_frames. | |
| expected_cep_target | No | Optional reviewed CEP sequence/clip identity and exact tick ranges. Checked before every generated command; UXP refuses this CEP-only guard. | |
| expected_project_path | No | Optional absolute saved-project path. Every generated CEP command refuses before its body when the active project differs or is unsaved. UXP commands refuse this CEP-only guard; local-only tools do not inspect Premiere. Omit to keep existing behavior. | |
| approved_workspace_path | No | Absolute existing directory that must contain input_path and output_path. Required when either path is given. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | Whether the tool completed successfully. | |
| data | No | Tool-specific result data when ok is true; on failure, diagnostic detail when the tool provides it. | |
| tool | Yes | The registered MCP tool name. | |
| error | No | Failure detail when ok is false. | |
| receipt | No | Versioned common mutation receipt; success never implies rendered verification. | |
| idempotency | No | Present when idempotency_key deduplicated this call: replayed is true when the original outcome was returned instead of running again. |