Add Title
add_titleAdds on-screen titles from plain text using stock Premiere Essential Graphics templates, with multi-line fields and verified text baking for reliable import.
Instructions
Add an on-screen title from plain text using a stock Essential Graphics template that ships with Premiere (default: Basic Title). Pass text for one line, or lines to fill the template's text fields in order (for example a lower third's name and role). Premiere-built templates (kind 'premiere') get the text baked into a verified copy before import, because Premiere exposes no writable text for them (textVerification 'template_verified'; confirm the render with export_frame). The baked copy path is returned as templateFile and saved under the application support premiere-pro-mcp/titles folder (macOS: ~/Library/Application Support/premiere-pro-mcp/titles). The cache keeps the newest 50 baked copies by modification time; export or copy templates elsewhere if a project needs older copies retained. After Effects-built templates (kind 'after_effects') are imported and their text fields written by position and read back from Premiere (textVerification 'verified', 'mismatch', 'missing_property', or 'committed_unverified'). The graphic is trimmed to duration_seconds and its length read back. Optional styling: font_family (PostScript name) and font_size write every text run of each AE text control when the template allows font editing (Premiere 26 fontEditValue/fontSizeEditValue runs, or legacy fontName/fontSize keys); fill_color requires one exposed Fill Color control; position moves the whole graphic through intrinsic normalized Motion Position. Each requested field has styleChecks readback. Premiere-authored font/fill styling and align are refused before import: no reliable writable/readable CEP 26.5.2 contract is established. Tracking is unsupported. Font readback confirms the stored name, not installation or rendered glyphs. Use list_stock_titles to see templates, their kind, and how many lines each takes.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "add_title"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Title text for the first text field. Specify exactly one of text or lines. | |
| align | No | Alignment request. Currently refused before import because a reliable CEP text-alignment setter/readback contract is unavailable. | |
| lines | No | Text for each of the template's text fields in order (see list_stock_titles). Specify exactly one of text or lines. | |
| position | No | Optional normalized intrinsic Motion Position of the whole graphic, not its internal text-layer anchor. | |
| template | No | Stock template name such as "Basic Title", "Bold Title", or "Basic Lower Third", or category/name such as "Titles/Bold Title" (default: Basic Title). | |
| font_size | No | Optional text size in points for every requested AE text field and every text run in it. Requires a template that allows size editing (Premiere 26 fontSizeEditValue runs, or a legacy fontSize key). | |
| fill_color | No | Optional opaque #RRGGBB fill through exactly one exposed MGT Fill Color control; does not guess private JSON color encodings. | |
| font_family | No | Optional PostScript font name (for example Metropolis-Regular) for every requested AE text field and every text run in it. Requires a template that allows font editing (Premiere 26 fontEditValue runs, or a legacy fontName key). Stored-name readback does not prove the font is installed or rendered. | |
| track_index | No | Zero-based video track for the graphic (default: 1, the track above the main footage). | |
| start_seconds | No | Timeline start in seconds (default: 0). | |
| 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 the HTTP server process when Streamable HTTP is stateless per request) and held in memory only (200 keys, 1 hour); it does not survive a restart or reconnect. Read-only invocations are never deduplicated. | |
| duration_seconds | No | How long the title stays on screen in seconds (default: 5). | |
| 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. |
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. |