BitterClip tool reference
These are the 63 tools in the deployed Rails mcp_model_visible catalog. Names, titles, descriptions, and schemas below come directly from that catalog. A host may show fewer tools or adapt their presentation according to its capabilities and your permissions. The model-only result profile omits output schemas; Live Workspace may rename its workspace-opening tool. Errors and examples below are catalog guidance, not extra fields in MCP tools/list.
Product release 71f75c2f964c6c44bd89d0aac8b5bb1541591546
Catalog SHA-256 bb76e7b0de0fae72b2d1783602703dc048e04cb8a72d6700a68d6d83e55576ba
Captured 2026-09-23T16:00:39.482Z from the deployed catalog.
recordings_list
List recordings
List standalone recordings (raw source media) — the drawer, not the editorial unit. Use for source/ingest/readiness asks ("latest searchable session", "what uploads are ready?") or to inspect and select recordings inside a project (project_id). For one Project reel whose useful footage spans separate recordings rather than one parent Episode, inspect selected recording pixels directly with recording_sample_frames when needed, then pass recording_id ranges directly to one episode_create without derived_from_id. Never create a throwaway Episode merely to inspect a Recording. `query` matches title, project, or who is in it ("the latest with Andrew" matches Andrew as a speaker). PAGINATED, newest first: one call returns up to 20 rows and says when more exist; continue with the returned next_cursor (same query/project_id) as `cursor`. One listing walk reaches at most the newest 50 recordings — anything older is reachable only by narrowing with query or project_id, and the result states which case you are in. Model rows carry both the exact tool-only recording_id and the episode-of-one episode_id, plus captured_at, searchability status/notes, and a compact indexed description. Prefer the newest `searchability_status:"searchable"` row for latest-session asks; episode_pending means the Recording may not have an Episode-of-one, not that direct source-time frame inspection must wait. Not for ordinary composition browsing (episodes_list) and not for searching what was SAID (transcript_search). Read-only.
Input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Optional case-insensitive filter — returns only recordings whose TITLE, a composited SOURCE TITLE, or a diarized SPEAKER NAME contains this text (substring). The filter scans the FULL catalog before the newest-50 listing window applies, so it also reaches recordings a bare walk cannot. Each kept recording carries a `match_reason` (\"title\" / \"source: …\" / \"speaker: …\") explaining why. Composes with project_id, limit, and cursor. Use it to find a recording by who is in it or what it's called, e.g. query: \"Andrew\"."
},
"project_id": {
"type": "string",
"description": "Optional project public ID — scope the list to a single project's recordings."
},
"limit": {
"type": "integer",
"description": "Rows per page. Default 20, which is also the model-context page ceiling (a larger value still pages at 20 with a next_cursor to continue; app hydration callers may receive up to 50 in one call)."
},
"cursor": {
"type": "string",
"description": "Opaque continuation returned as next_cursor by the previous page of this listing. Keep query and project_id identical when continuing; omit cursor to restart from the newest recordings. Never invent or edit a cursor."
},
"result_profile": {
"type": "string",
"enum": [
"app",
"model"
],
"description": "Caller profile. \"app\" (widgets/apps) keeps full structured rows for hydration; \"model\" returns the complete row story as prose only. Omit to use the server default."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Examples
[
{
"label": "List recent recordings",
"input": {
"limit": 10
}
},
{
"label": "Find a recording by speaker or title",
"input": {
"query": "Andrew"
}
},
{
"label": "List the recordings in a project",
"input": {
"project_id": "proj_..."
}
}
]projects_list
List projects
List or find BitterClip projects/shows visible to this person, including projects shared with them. Use this before recordings_list or episodes_list when the user names a show/project, says a project was shared by another account, or needs the project_id for a shared shell. Pass query to filter by project title, description, or owning studio; multi-word queries tolerate punctuation differences (for example, "andrew adrian" can match "andrew & adrian"). Returned project_id values can be passed directly to recordings_list, episodes_list, and upload tools. To open a Project with workspace_open, pass target_type:"project" and that project_id as target_id.
Input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Optional case-insensitive filter across project title, description, owning studio name, and relationship (owned/shared)."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"invalid_input"
]Examples
[
{
"label": "Find a shared show by name",
"input": {
"query": "Science Based AI"
}
},
{
"label": "List accessible projects",
"input": {}
}
]account_context_get
Read the studio working context
Read the OWNER's optional studio-wide working context — one bounded paragraph of standing context that spans Projects (who the studio is, recurring audience, standing constraints). OWNER-ONLY: it fails closed as not-found for guests and non-owner members, and it must NEVER be quoted or summarized into a conversation with anyone but the owner. Precedence is fixed: the person's explicit request wins over a confirmed Project working brief, which ALWAYS wins over this context, which sits above the general constitution. When a Project has no confirmed brief, this context may inform a brief you PROPOSE — draft it, show it, and confirm it only through project_brief_set with the owner's agreement; never treat the context itself as Project direction, and never write it anywhere silently. Read-only; no media effect.
Input schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"account_id": {
"type": "string"
},
"brief": {
"type": "string",
"description": "The exact current confirmed context text; empty when none is confirmed."
},
"revision": {
"type": "integer",
"description": "The current monotonic context revision (0 when none exists)."
},
"confirmed_by_public_id": {
"type": [
"string",
"null"
]
},
"confirmed_at": {
"type": [
"string",
"null"
]
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"account_not_found"
]account_context_set
Confirm the studio working context
Confirm the OWNER's optional studio-wide working context — one bounded paragraph of standing context that spans Projects. OWNER-ONLY: it fails closed as not-found for guests and non-owner members. It is WEAKER than Project direction: a confirmed Project working brief always wins, and the person's explicit request wins over both. Use it only when the owner explicitly states or corrects studio-level standing context — NEVER infer it from conversation history; it replaces the whole context, so carry forward anything still current. Read the current context first (account_context_get) and pass that exact revision as expected_revision (0 when none exists); a stale revision fails without overwriting. Retrying the exact same confirmation with the same idempotency_key replays as a no-op, even after a later confirmation; the same key with different text fails closed. Pass an empty context to clear it. Confirming never touches sibling account settings, never changes any Project's working brief or direction, and causes no Program edit, Clip, Render, media, publication, or public-link effect.
Input schema
{
"type": "object",
"properties": {
"brief": {
"type": "string",
"maxLength": 1000,
"description": "The complete working context text to confirm — it replaces the current context. An empty string clears it. Limited to 1000 characters."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "The current working-context revision from a fresh account_context_get. Pass 0 when no context has been confirmed yet."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for an exact safe retry of this one confirmation."
}
},
"required": [
"brief",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"account_id": {
"type": "string"
},
"brief": {
"type": "string",
"description": "The exact current confirmed context text after this call."
},
"revision": {
"type": "integer",
"description": "The current monotonic context revision."
},
"confirmed_by_public_id": {
"type": [
"string",
"null"
]
},
"confirmed_at": {
"type": [
"string",
"null"
]
},
"already_applied": {
"type": "boolean",
"description": "true when this exact confirmation had already been applied and nothing changed."
},
"applied_revision": {
"type": "integer",
"description": "The revision this confirmation originally produced; equals revision unless a later confirmation superseded it."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"account_not_found",
"stale_context_revision",
"idempotency_conflict",
"invalid_input"
]Examples
[
{
"label": "Set optional studio-wide standing context",
"input": {
"brief": "Two-person dev studio. Audience: technical founders. Keep cuts dense and unhyped.",
"expected_revision": 0,
"idempotency_key": "context-2026-08-14-a"
}
}
]project_brief_set
Confirm the Project working brief
Confirm the Project's working brief — the durable steering text every host and ingest synthesis reads for this Project (what to make, tone, audience, what to avoid). It is STANDING direction: follow it for Project work, and when the person's explicit current request conflicts with it, their request wins. Use it when the person states or corrects standing direction for the Project as a whole; it replaces the whole brief, so carry forward anything still current. Read the current brief first — episode_read on an Episode in the Project renders the exact current PROJECT WORKING BRIEF block with its revision — and pass that exact revision as expected_revision (0 when no brief exists yet); a stale revision fails without overwriting a newer confirmation. Retrying the exact same confirmation with the same idempotency_key replays as a no-op, even after a later confirmation; the same key with different text fails closed. Pass an empty brief to clear steering. Confirming never touches sibling direction settings such as canonical vocabulary or copy preferences, and causes no Program edit, Clip, Render, publication, or public-link effect. Not for Episode metadata (episode_update) or channel/package copy (publish_prepare / publish_update).
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID (show_...) or UUID from projects_list / episode_read."
},
"brief": {
"type": "string",
"maxLength": 2000,
"description": "The complete working brief text to confirm — it replaces the current brief. An empty string clears steering. Limited to 2000 characters."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "The current working-brief revision from a fresh episode_read (its PROJECT WORKING BRIEF block states the revision). Pass 0 for a Project with no confirmed brief yet."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for an exact safe retry of this one confirmation."
}
},
"required": [
"project_id",
"brief",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"project_id": {
"type": "string"
},
"brief": {
"type": "string",
"description": "The exact current confirmed brief after this call."
},
"revision": {
"type": "integer",
"description": "The current monotonic brief revision."
},
"confirmed_by_public_id": {
"type": [
"string",
"null"
]
},
"confirmed_at": {
"type": [
"string",
"null"
]
},
"already_applied": {
"type": "boolean",
"description": "true when this exact confirmation had already been applied and nothing changed."
},
"applied_revision": {
"type": "integer",
"description": "The revision this confirmation originally produced; equals revision unless a later confirmation superseded it."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"stale_brief_revision",
"idempotency_conflict",
"invalid_input"
]Examples
[
{
"label": "Set standing direction for a Project",
"input": {
"project_id": "show_...",
"brief": "Audience: prospective customers. Tone: direct, no hype. Prefer moments showing the product working.",
"expected_revision": 0,
"idempotency_key": "brief-2026-08-13-a"
}
}
]project_participants_read
Read participant groups
Read a Project's opt-in visible-person recognition, exact representative images, saved reviews and background match status. Empty-gallery groups can be named before any people are saved. A host's confirmed faces are theirs wherever they were confirmed and match here whenever this Project's recognition is on; Project-scoped people match only in their Project. Automatic face matches do not identify voices. Inspect the actual images before reviewing; ambiguous people remain unresolved. Poll this read after Save and update matches until computation settles. No extraction or inference is started by this read. episode_id limits the view to its distinct underlying Recordings. recording_query and recording_cursor search/page the complete Project library; group_offset reaches remaining groups. context_observation_id returns the exact original playback context for one displayed appearance. update_scopes separates cached matching from new analysis, including counts and an honest unavailable estimate.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string"
},
"recording_id": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"recording_query": {
"type": "string",
"maxLength": 120
},
"recording_cursor": {
"type": "string"
},
"group_offset": {
"type": "integer",
"minimum": 0,
"maximum": 4096
},
"context_observation_id": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 24
}
},
"required": [
"project_id"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"not_found",
"invalid_input"
]project_participants_mutate
Save participant recognition and reviews
Studio-owner operation for Project-scoped face recognition. enable requires explicit participant permission and expected_consent_revision from a fresh read; recording_ids selects up to eight historical Recordings, while enabled future intake is automatic. process selects further existing Recordings. review names/confirms only explicitly included displayed observation IDs and excludes the displayed examples that are not that person; pass the exact review_context, choose speaker_profile_id OR new_person_name, and then poll project_participants_read for real cached-descriptor regrouping. Agents acting under delegated review authority must set reviewer_kind:delegated_agent_review; never claim the owner personally inspected images. undo requires the current review_id and refuses to overwrite newer answers. disable stops use/work while retaining saved data. forget disables and removes this feature's Project descriptors, previews and associations; Recordings, voices, approved portraits and a host's confirmed face references remain. retry names a failed recording_id or job_id. review, undo, and update_matches accept match_scope with type episode plus episode_id, type recordings plus up to eight recording_ids, or type project. Omission retains the Project-wide default for existing clients. update_matches only uses cached descriptors and never analyzes original video; unavailable evidence is reported separately. Deferred Recordings retain reviewed facts while older automatic names are withheld. cancel_update with job_id stops a cached update and retains the saved answer; retry reuses that job scope. Every action requires a stable idempotency_key. Never infer participant permission or enable other Projects from this one; consent here gates only this Project's matching, and a host's confirmed faces stay theirs whether it is on or off.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"action": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"enable",
"process",
"review",
"undo",
"disable",
"forget",
"retry",
"update_matches",
"cancel_update"
]
},
"expected_consent_revision": {
"type": "integer",
"minimum": 0
},
"participant_permission": {
"type": "boolean"
},
"recording_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 8,
"uniqueItems": true
},
"review_context": {
"type": "string"
},
"included_observation_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"uniqueItems": true
},
"excluded_observation_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 6,
"uniqueItems": true
},
"speaker_profile_id": {
"type": "string"
},
"new_person_name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"reviewer_kind": {
"type": "string",
"enum": [
"owner_review",
"delegated_agent_review"
]
},
"match_scope": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode",
"project",
"recordings"
]
},
"episode_id": {
"type": "string"
},
"recording_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 8,
"uniqueItems": true
}
},
"required": [
"type"
],
"additionalProperties": false
},
"review_id": {
"type": "string"
},
"job_id": {
"type": "string"
},
"recording_id": {
"type": "string"
}
},
"required": [
"type"
],
"additionalProperties": false
}
},
"required": [
"project_id",
"idempotency_key",
"action"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"not_found",
"invalid_input",
"recognition_owner_required",
"recognition_review_stale",
"recognition_undo_stale",
"recognition_consent_changed",
"recognition_retry_changed"
]transcript_search
Search library content
Search what was SAID across the library using approximate time-anchored transcript units, saved moments, and Episode descriptions/chapters; visual annotations are searchable where analysis exists. Hits locate semantic neighborhoods; text/times never authorize a structural boundary. Keyword hits are exact unstemmed tokens; issue morphological variants; quoted phrases are exact and exhaustive. Semantic hits are labeled retrieval_mode:semantic — read before quoting. Every response carries coverage, interpretation, and freshness. Person grains: person_speaking vs person_present; combinable; facets_only:true gives the bare map. Narrow wide results via facets, not pagination. Escalate through episode_read on the returned window; source media only for an edit/review boundary, never as physical-progress proof. A FIND tool, not a judge. Use returned handles exactly (projects_list/episodes_list for title discovery). Read bitterclip://docs/tool-workflows. Read-only.
Input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Keyword or phrase to find. Exact-token, unstemmed; \"quoted phrases\" match exactly. Required unless facets_only is true with a project, person, or date filter."
},
"project_id": {
"type": "string",
"description": "Optional project public ID returned by projects_list/episodes_list (show_... or UUID) — scope the search to one readable project. Do not pass a project title/name here; use projects_list(query:) or episodes_list(query:) first."
},
"person_speaking": {
"type": "string",
"description": "Optional person (profile public ID or name). Returns only transcript hits where THIS PERSON IS TALKING — 'what did X say about Y'. Resolves real people across renames and generic diarization labels; resolution (and any ambiguity) is reported in interpretation. May be combined with person_present to find one person speaking while another appears in the same episode."
},
"person_present": {
"type": "string",
"description": "Optional person (profile public ID or name). Returns hits from episodes where this person APPEARS AT ALL, whoever is speaking — silent-participant safe ('sessions with Adrian'). May be combined with person_speaking. Presence is speech-derived for now; interpretation says so."
},
"speaker": {
"type": "string",
"description": "LEGACY raw diarization-label filter, kept for compatibility. Matches transcript_units.speaker_label verbatim and does NOT resolve people — prefer person_speaking."
},
"date_from": {
"type": "string",
"description": "Optional ISO date; include episodes with episode_date on or after this date."
},
"date_to": {
"type": "string",
"description": "Optional ISO date; include episodes with episode_date on or before this date."
},
"scope": {
"type": "string",
"enum": [
"recordings",
"all"
],
"description": "Optional. Slice 1 supports recording-backed library search. `all` is accepted as an alias for recordings; true episode-projection search is a fast-follow."
},
"detail": {
"type": "string",
"enum": [
"concise",
"detailed"
],
"description": "Optional response detail level. concise is default; detailed may return more hit text within budget."
},
"facets_only": {
"type": "boolean",
"description": "Optional. Return the exhaustive episode/project/person/month facet map with no hits."
},
"limit": {
"type": "integer",
"description": "Maximum hits to return. Default 8, maximum 10."
},
"page": {
"type": "integer",
"description": "1-indexed page of compact search hits. Default 1. Use next_page from the response to continue."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"invalid_input",
"project_not_found"
]Examples
[
{
"label": "Find recordings where Andrew was present in June",
"input": {
"query": "pricing",
"person_present": "Andrew",
"date_from": "2026-06-01",
"date_to": "2026-06-30",
"limit": 8
}
},
{
"label": "Exhaustive map of every episode mentioning the sponsor (for set algebra / complements)",
"input": {
"query": "\"sponsor read\"",
"facets_only": true
}
}
]upload_link_create
Create an upload link
Create a hosted BitterClip upload link for local audio or video files. Prefer this when the user wants a link or another camera operator will contribute later. Pass capture_session_id to add multiple files or a whole device folder to one footage-session chronology. A link cannot add files directly to an existing episode: create a footage session for that episode and pass its capture_session_id.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Optional project public ID, slug, or name to attach uploads to. Omit for the default uploads project."
},
"project": {
"type": "string",
"description": "Backward-compatible project name/slug/public ID alias."
},
"capture_session_id": {
"type": "string",
"description": "Optional footage-session public ID. Every uploaded file joins that session and triggers incremental chronology analysis."
}
},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"description": "\"upload_link\" when a shareable upload link is returned."
},
"upload_url": {
"type": "string",
"description": "The token-gated drop-zone page URL to give the user."
},
"project": {
"type": "object",
"description": "The resolved project the uploads land in, or null for the default project."
},
"capture_session": {
"type": "object",
"description": "Present for footage-session links: {id, title}."
},
"expires_at": {
"type": "string",
"description": "ISO8601 link expiry."
},
"accepted_content_types": {
"type": "array",
"items": {
"type": "string"
}
},
"max_bytes": {
"type": "integer"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"invalid_input"
]recordings_visual_identity_read
Read image identifications and application status
Read saved exact-image answers, current native background work, capability limits and guarded recovery actions. Optional contextual image questions include source time, marked box, media evidence and a signed question_context. Inspect the actual evidence before answering; raw examples are not a recognition-training checklist. Poll pending application with include_questions false. A completed update does not establish identity throughout a Recording.
Input schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"source_seconds": {
"type": "number",
"minimum": 0,
"description": "Deliberately inspect retained marked images nearest this Recording time. Returned times are exact; do not assume the requested time was sampled."
},
"include_questions": {
"type": "boolean",
"default": true
},
"visual_identity_decision_id": {
"type": "string"
}
},
"required": [
"recording_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"visual_identity_questions": {
"type": "object"
},
"decision": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"recording_not_found",
"visual_identity_decision_not_found",
"invalid_input"
]recordings_visual_identity_undo
Undo an image identification
Append a guarded withdrawal of the current exact-image answer, or restore the answer it corrected. Preserves newer and unrelated answers. The durable Undo is separate from its native background picture update; read status until settled.
Input schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"visual_identity_decision_id": {
"type": "string"
},
"idempotency_key": {
"type": "string"
}
},
"required": [
"recording_id",
"visual_identity_decision_id",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"decision": {
"type": "object"
},
"speaker_evidence": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"recording_not_found",
"visual_identity_actor_required",
"visual_identity_supersession_stale",
"visual_identity_question_stale",
"idempotency_conflict",
"invalid_input"
]recordings_visual_identity_retry
Retry a saved image answer’s picture update
Retry only native application of the current saved image answer. Preserves the answer and starts no recognition, transcription or render provider work. Existing pending work is reused; use the returned status and recovery action.
Input schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"visual_identity_decision_id": {
"type": "string"
}
},
"required": [
"recording_id",
"visual_identity_decision_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"decision": {
"type": "object"
},
"speaker_evidence": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"recording_not_found",
"visual_identity_actor_required",
"visual_identity_supersession_stale",
"visual_identity_question_stale",
"invalid_input"
]recordings_visual_identity_decide
Answer a visible-person identity check
Record one source-current human answer about the exact visible person marked in one Recording frame. Yes confirms only the displayed face-to-person proposal; Someone else records the rejected proposed person and one separately selected displayed candidate atomically; Not sure is neutral; Not a person rejects only that exact detection. This never confirms or renames an audio speaker track, changes captions, chooses a Thumbnail, approves a Speaker photo, trusts a face reference, stores a reusable face template, or changes recognition consent. A non-neutral answer queues a bounded person-evidence generation so affected automatic Thumbnail evidence can be reconsidered without overwriting a manual Thumbnail.
Input schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string",
"description": "Recording public ID that owns the exact current visual question."
},
"visual_identity_question_id": {
"type": "string",
"description": "Opaque source-current question ID returned inside recording speaker evidence."
},
"decision": {
"type": "string",
"enum": [
"confirmed",
"identified",
"someone_else",
"not_sure",
"not_a_person"
],
"description": "Exact visual answer. The UI presents these as Yes, Use the selected person, Someone else, Not sure, and Not a person."
},
"selected_speaker_profile_id": {
"type": "string",
"description": "Required for identified or someone_else; must be one of the canonical scoped candidates displayed with this exact question."
},
"new_person_name": {
"type": "string",
"maxLength": 120,
"description": "A new visible person’s name, instead of a selected profile. Creates a project-local person without assigning a voice or approving memory."
},
"question_context": {
"type": "string",
"description": "Copy the opaque displayed question_context unchanged. It preserves exact-image and proposal meaning across background publication."
},
"reason": {
"type": "string",
"description": "Optional short human context retained with the decision receipt."
},
"supersedes_decision_id": {
"type": "string",
"description": "Optional current decision ID when deliberately appending a correction to the same exact question."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable retry key for this exact answer."
}
},
"required": [
"recording_id",
"visual_identity_question_id",
"decision",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"recording_id": {
"type": "string"
},
"already_applied": {
"type": "boolean"
},
"decision": {
"type": "object"
},
"speaker_evidence": {
"type": "object",
"description": "Refreshed bounded speaker evidence and remaining visual identity questions."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"recording_not_found",
"invalid_input",
"visual_identity_actor_required",
"visual_identity_question_stale",
"visual_identity_question_already_answered",
"visual_identity_supersession_stale",
"visual_identity_candidate_not_shown",
"idempotency_conflict"
]speaker_rename
Rename a speaker on a recording
Relabel one diarized speaker track inside a recording or that recording's episode-of-one, without confirming identity, creating a SpeakerProfile, or enrolling/saving a voiceprint. Use this when the user asks to fix captions such as "Speaker 2 is Adrian" and wants future captioned exports from this recording to use the corrected name. This is rename-only: biometric voice memory and identity confirmation require a human web action in speaker review.
Input schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string",
"description": "Recording public ID (`src_...`) or an episode/composition public ID (`comp_...`) that resolves to one recording."
},
"speaker": {
"type": "string",
"description": "Current speaker display label, speaker_key, or SpeakerMap public ID for the diarized track to rename."
},
"new_name": {
"type": "string",
"description": "New recording-local display name for this speaker track."
},
"confirm": {
"type": "boolean",
"description": "Optional; must be false or omitted. This tool does not confirm identity or save a voiceprint."
}
},
"required": [
"recording_id",
"speaker",
"new_name"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string"
},
"speaker_map_id": {
"type": "string"
},
"from_label": {
"type": "string"
},
"to_label": {
"type": "string"
},
"confirmed": {
"type": "boolean"
},
"teaches_voice": {
"type": "boolean"
},
"speaker_map_summary": {
"type": "object",
"description": "Updated speaker map summary with display_name, needs_confirmation, confirmed, and appearances_count."
},
"speaker_evidence": {
"type": "object"
},
"speaker_model_context": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"recording_not_found",
"speaker_not_found",
"invalid_input"
]capture_session_create
Create a footage session
Create a project-scoped Footage session for a bucket of recordings captured across one real-world period. The session starts without a master recording, reserves one stable editable episode handle, and can receive more files or device folders later. Follow with upload_link_create(capture_session_id: ...) for local or contributor uploads, then capture_session_read while chronology analysis settles.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID that owns the Footage session."
},
"title": {
"type": "string",
"description": "Short human title, such as Park coaching · Jul 15."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry of this exact creation request."
}
},
"required": [
"project_id",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"capture_session_id": {
"type": "string"
},
"episode_id": {
"type": "string",
"description": "Stable episode handle reserved for the eventual editable projection."
},
"project_id": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"revision": {
"type": "integer"
},
"already_applied": {
"type": "boolean"
},
"next_action": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"idempotency_conflict",
"invalid_input"
]capture_session_read
Read a footage session
Read the evidence-backed Footage-session manifest. Returns source facts, typed observations, solve receipts, exact capture-time gaps and overlaps, source/capture/episode mappings, corrections, revision, uncertainty, and the next safe action. Capture time preserves real gaps; episode time collapses idle gaps after an explicit build.
Input schema
{
"type": "object",
"properties": {
"capture_session_id": {
"type": "string",
"description": "Footage-session public ID."
}
},
"required": [
"capture_session_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"capture_session_id": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"project_id": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"revision": {
"type": "integer"
},
"zoom_import": {
"type": [
"object",
"null"
],
"description": "Safe lifecycle projection for an autonomous Zoom recording import, when this Footage session came from Zoom."
},
"coordinate_origin_recording_id": {
"type": [
"string",
"null"
],
"description": "Recording that defines capture-time zero for the accepted chronology."
},
"capture_origin_at": {
"type": [
"string",
"null"
],
"description": "ISO 8601 wall-clock instant corresponding to capture-time zero when trusted clock evidence exists."
},
"facts": {
"type": "object"
},
"inferences": {
"type": "object"
},
"episode_projection": {
"type": "object"
},
"listening_reference": {
"type": "object",
"description": "Automatic or user-selected speech-rich listening reference. This preference does not replace per-recording transcription or Precision-2 speaker identity."
},
"corrections": {
"type": "array"
},
"next_action": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"capture_session_not_found",
"invalid_input"
]capture_session_mutate
Change a footage session
One footage-session change per call: add_recordings, camera_group_set, listening_reference_set, remove_recording, set_recording_start, or retry_analysis. add_recordings attaches existing project recordings (top-level recording_ids) and schedules incremental chronology analysis — use upload_link_create with capture_session_id instead when bytes are still local or another camera operator uploads later; membership is retry-safe and never creates unrelated top-level episodes. camera_group_set assigns the top-level recording_ids to one stable camera group without changing chronology, source identity, or coverage: it never advances the chronology revision, never returns the session to analysis, and never queues another solve (omit camera_group_key to mint a new group; camera_label renames without becoming identity; camera identity carries its own generation, and expected_camera_generation is REQUIRED so a concurrent camera edit cannot be silently overwritten; the receipt retains prior keys and labels so grouping reverses through the same action). listening_reference_set chooses the default speech-rich listening reference camera via top-level recording_id, or omits it to restore automatic selection; it never selects Program camera or audio, discards transcripts, or overrides speaker identity. remove_recording is a revision-guarded, audited exclusion of one recording (top-level recording_id) that preserves the original recording, membership history, observations, and solve receipts. set_recording_start is an audited placement correction setting one unresolved recording's start on the stable capture clock; read the manifest first, cite the evidence or human instruction in reason, and never guess a gap. retry_analysis retries the same evidence revision after bounded automatic chronology attempts have failed — call it only when next_action.kind is retry_analysis, keeping one idempotency key per exact terminal failure generation. Subject references ride top-level: capture_session_id always; recording_id / recording_ids per action.
Input schema
{
"type": "object",
"properties": {
"capture_session_id": {
"type": "string",
"description": "Footage-session public ID."
},
"recording_id": {
"type": "string",
"description": "Recording public ID for listening_reference_set (optional; omit for automatic), remove_recording, and set_recording_start."
},
"recording_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"description": "Recording public IDs for add_recordings and camera_group_set."
},
"expected_revision": {
"type": "integer",
"description": "Current footage-session revision. Required for every action except add_recordings; a stale revision is rejected."
},
"expected_camera_generation": {
"type": "integer",
"description": "REQUIRED for camera_group_set: the camera-identity generation this decision was made against, from manifest.camera_grouping.camera_generation. Camera identity has its own generation because grouping never advances the footage-session revision, so expected_revision cannot detect a concurrent camera decision. Omitting it is rejected; a stale one is rejected."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry of this exact change."
},
"action": {
"type": "object",
"description": "One footage-session action. Subject references (capture_session_id, recording_id, recording_ids) ride top-level.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"add_recordings"
]
},
"relative_paths": {
"type": "object",
"description": "Optional map from recording ID to a safe device/folder-relative path retained as ingest context."
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"camera_group_set"
]
},
"camera_group_key": {
"type": "string",
"description": "Optional existing group key from this session. Omit to create a new group."
},
"camera_label": {
"type": "string",
"description": "Optional human label. Renaming never changes group identity."
},
"reason": {
"type": "string",
"description": "Required evidence or explicit human instruction supporting the grouping."
}
},
"required": [
"type",
"reason"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"listening_reference_set"
]
},
"reason": {
"type": "string",
"description": "Optional concise reason retained with the preference receipt."
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"remove_recording"
]
},
"reason": {
"type": "string",
"description": "Optional concise reason retained in the audit receipt."
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"set_recording_start"
]
},
"capture_start_seconds": {
"type": "number",
"description": "Recording start on the session's stable capture clock. May be negative when footage predates the coordinate origin."
},
"reason": {
"type": "string",
"description": "Required concise rationale citing the capture evidence or explicit human instruction that establishes this placement. Never guess a gap."
}
},
"required": [
"type",
"capture_start_seconds",
"reason"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"retry_analysis"
]
}
},
"required": [
"type"
],
"additionalProperties": false
}
]
}
},
"required": [
"capture_session_id",
"idempotency_key",
"action"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"capture_session_id": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"status": {
"type": "string"
},
"already_applied": {
"type": "boolean"
},
"analysis_enqueued": {
"type": "boolean"
},
"dispatch_status": {
"type": "string",
"enum": [
"dispatching",
"queued",
"observed",
"enqueue_failed"
],
"description": "retry_analysis only: durable queue-delivery state for this retry receipt."
},
"recording_id": {
"type": [
"string",
"null"
]
},
"recording_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"added_recording_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"camera_group_key": {
"type": [
"string",
"null"
]
},
"camera_label": {
"type": [
"string",
"null"
]
},
"camera_generation": {
"type": "integer",
"description": "camera_group_set only: the footage session's camera-identity generation after this call. Send it back as expected_camera_generation on the next camera edit."
},
"prior_memberships": {
"type": "array",
"items": {
"type": "object"
}
},
"removed_membership_id": {
"type": "string"
},
"source_preserved": {
"type": "boolean"
},
"correction_id": {
"type": "string"
},
"capture_start_seconds": {
"type": "number"
},
"selection_basis": {
"type": "string",
"enum": [
"automatic",
"user_selected"
]
},
"audit_receipt_id": {
"type": "string"
},
"manifest": {
"type": "object"
},
"next_action": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"capture_session_not_found",
"capture_session_not_failed",
"recording_not_found",
"stale_capture_session_revision",
"idempotency_conflict",
"invalid_input"
]capture_session_build_episode
Build editable episode from footage
Revision-guarded projection of a settled footage-session chronology into its ordinary editable episode. Collapses real idle gaps, chooses a deterministic continuity-first program source, retains capture/source/episode mapping receipts, then enqueues one bounded whole-session speaker-reconciliation and semantic-synthesis pass. Chronology is always derived from the best available evidence — build immediately when next_action is build_episode or update_episode; the returned chronology_evidence and the manifest's inferences.chronology record how each recording was placed. It refuses unresolved footage, any covered interval with only audio and no renderable video, unsupported clock drift, and any automatic rewrite after the episode has been edited. Episode structure may finish before every Program or alternate-angle preview is playable or before whole-session understanding is complete: workspace_url is omitted until the complete media graph plus title, description, chapters, and visual understanding are ready for the working editor.
Input schema
{
"type": "object",
"properties": {
"capture_session_id": {
"type": "string",
"description": "Footage-session public ID."
},
"expected_revision": {
"type": "integer",
"description": "Current session revision from its manifest. A stale revision is rejected."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry of this exact projection request."
},
"acknowledge_chronology_review": {
"type": "boolean",
"description": "Deprecated; accepted and ignored. Chronology review is no longer a gate — placement provenance is always recorded in chronology_evidence."
}
},
"required": [
"capture_session_id",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"capture_session_id": {
"type": "string"
},
"session_revision": {
"type": "integer"
},
"episode_id": {
"type": "string"
},
"episode_revision": {
"type": "integer"
},
"segment_count": {
"type": "integer"
},
"angle_count": {
"type": "integer"
},
"duration_seconds": {
"type": "number"
},
"collapsed_gap_seconds": {
"type": "number"
},
"chronology_evidence": {
"type": "object",
"description": "How the accepted chronology placed each recording: placement-basis histogram, audio-linked recording count, and the accepted-run review receipt when one exists."
},
"already_applied": {
"type": "boolean"
},
"understanding_enqueued": {
"type": "boolean",
"description": "true when this projection queued a new bounded whole-session reconciliation/synthesis generation; false when the same generation was already underway or complete."
},
"workspace_url": {
"type": "string",
"description": "Present only when every Program and alternate-angle recording has playable preview media and whole-session understanding is terminal, so the working editor is ready to open."
},
"manifest": {
"type": "object"
},
"next_action": {
"type": "object",
"description": "edit_episode only when the working editor is ready; wait_for_episode_media while previews are pending; wait_for_understanding while title, description, chapters, and visual understanding finish; retry_understanding after a terminal preparation failure; repair_episode_media with recording_ids when preview repair is required."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"capture_session_not_found",
"stale_capture_session_revision",
"capture_session_not_ready",
"capture_session_audio_only_gap",
"capture_session_rate_mismatch",
"capture_episode_has_edits",
"idempotency_conflict",
"invalid_input"
]episode_camera_group_set
Group episode cameras
Explicitly assign synchronized camera angles in one editable Episode to a stable camera group. Omit camera_group_key to create a new opaque group, pass an existing Episode group, or backfill the exact key already carried by every selected angle's active Footage-session membership. This changes only camera identity/label projection: synchronization, angle IDs, Program ranges, preview, and render resolution remain unchanged. The revision-guarded receipt retains every prior key and label for reversal.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Editable Episode public ID."
},
"angle_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200,
"description": "Angles that should share the group."
},
"camera_group_key": {
"type": "string",
"description": "Optional existing group key from this Episode. Omit to create one."
},
"camera_label": {
"type": "string",
"description": "Optional human-facing group label; never used as identity."
},
"expected_revision": {
"type": "integer",
"description": "Current Episode structural revision."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable retry key for this exact regrouping."
},
"reason": {
"type": "string",
"description": "Required evidence or explicit human instruction supporting the grouping."
}
},
"required": [
"episode_id",
"angle_ids",
"expected_revision",
"idempotency_key",
"reason"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"camera_group_key": {
"type": "string"
},
"camera_label": {
"type": [
"string",
"null"
]
},
"angles": {
"type": "array",
"items": {
"type": "object"
}
},
"prior_anchors": {
"type": "array",
"items": {
"type": "object"
}
},
"audit_receipt_id": {
"type": "string"
},
"already_applied": {
"type": "boolean"
},
"render_stale": {
"type": "boolean"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"angle_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input"
]camera_program_set
Direct or restore the Picture Program for an Episode
Perform exactly one Picture Program command without changing Program Audio, transcript timing, Episode chronology, or duration. Read episode_read first and use its current revision, exact scene summaries, placed ang_... handles (including handles labeled hidden when the request explicitly chooses them), and Episode-scoped piev_... evidence handles. For a simultaneous layout, pass scenes:[{episode_range:[start,end],layout:{key:"custom.v1"},slots:[...]}]. Use exactly one role:"primary" slot; name the other role:"secondary" for a two-person stack. Every custom slot needs role, box:{x,y,width,height}, and a distinct z_index integer. Use binding:{kind:"original.v1"} for the base Recording in any slot; use framing:{mode:"fill",focal_point:{x:0.5,y:0.5}} or framing:{mode:"fit"}, never a slot-level fit field. One to 64 disjoint scenes are accepted. A complete same-recording stack example is in bitterclip://docs/source-crops. The primary may omit binding to use program.v1. The ID-less original.v1 binding may fill any role with the underlying base Program Recording; it refuses unless one base Recording truthfully covers the complete scene, and callers never supply its source ID. Every additional slot otherwise needs original.v1, angle.v1, or evidence_range.v1. When the simultaneous layout belongs on a new derived Clip, prove complete coverage for every distinct secondary camera before clip_create. Create the Clip once, then author its scene; never create a throwaway Clip to test camera coverage. If truthful coverage begins after the user's requested point, explain the shift before writing. Side-by-side, PiP, five-picture speaker rail, grid, and custom geometry are presets or direct arrangements over the same slots primitive; custom.v1 accepts normalized boxes with x, y, width, and height in 0..1 plus local z_index. Optional source_crop:{x,y,w,h} selects a static normalized Recording display-frame region before Fit/Fill; focal points are relative to that region. Inspect the Recording frame to crop each participant tightly enough to exclude baked-in gallery padding and labels, then inspect the composed canvas before rendering. Layout boxes do not reposition captions: when reserving a caption gap, inspect any visible captions and use episode_edit occurrence.caption to place them in that gap if needed. Omit source_crop to remove it; never send null. Two slots may crop the same admitted camera and source range independently. Every slot is silent: the existing Program Audio remains the one audible authority. This release is configured to preview and render at most five enabled slots. The saved/read schema remains compatible with sixteen-slot scenes, but new work above the five-slot runtime maximum refuses before persistence, debit, queue state, media acquisition, or provider work. Evidence ranges must exactly match scene duration; v1 does not retime, hold, loop, phase-warp, or run a slot-local continuous clock. For a local camera correction, change the inspected interval and preserve other camera choices unless inspected evidence supports a broader change. Fit bars alone do not establish that a useful alternate should be discarded; judge subject visibility and the requested coverage. Pass episode_range plus camera, with optional picture_time. For a coherent legacy directing pass, pass 1–64 disjoint decisions under one revision and receipt; each decision is {episode_range,camera} with optional picture_time. Camera is an ang_... synchronized alternate exposed by episode_read, original to lock the base Program picture, or auto to remove explicit intent for that range. To Undo an exact receipt-backed camera or scene command, pass only revert_receipt_id; recovery fails closed if Program, camera, or Picture Program state has moved since that receipt. Direct recording or Episode ranges already chosen by episode_create determine the base picture, so do not restate them mechanically, and never pass a src_... Recording ID as camera or slot binding. When choosing autonomously, use episode_sample_frames to inspect the base picture and each candidate at the same evidence-backed Episode times before deciding; skip that comparison only when the human explicitly instructs which camera to use. For a compressed internal dialogue splice, inspect a truthful same-exchange listener angle on both sides of the removed source interval; enter that listener before the audio seam, hold through it, and return after retained speech is established. A placed-angle decision may set picture_time:'continuous' to keep that listener's source footage advancing continuously across compressed Program chronology; the default synchronized mode follows Program source time. Continuous placed-angle time is for truthful listener coverage and never the speaking camera. Original may use continuous picture time only as a split-edit bridge of at most 0.5 seconds: it carries one unchanged base Recording across the audio splice and returns to synchronized Original at the explicit, quieter resynchronization point. When inspected frames prove that hard resynchronization still exposes a pose jump, that same Original decision may add resync_blend_seconds up to 0.2; this is a duration-neutral picture-only fade into synchronized Original at the decision end and never changes or overlaps Program Audio. Do not add it to clean hard landings or to placed angles. Because Original may keep a speaking face visible, use it only when dense frame inspection shows the temporary lip-sync offset and landing are less distracting than the synchronized jump. Original continuity fails closed across Recordings, when accumulated desync exceeds 1.0 seconds, or when the occurrence has a rendered Crossfade. Continuous Auto and explicit scene slots remain unsupported. Every continuous decision fails closed when its persisted source anchor cannot survive a later structural edit. Never borrow a reaction from unrelated source time. At a speaker handoff, a motivated J- or L-cut may lead or lag the picture instead of switching on the first phoneme. Every selected angle must cover its complete requested range. One atomic program is preferred over many tiny mutation turns. The idempotency key makes an exact retry safe.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Episode public ID whose picture program is being edited."
},
"episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number"
},
"description": "Half-open [start_seconds, end_seconds) range on the stitched episode clock."
},
"camera": {
"type": "string",
"description": "Camera choice: original, auto, or a synchronized camera angle ID such as ang_...."
},
"picture_time": {
"type": "string",
"enum": [
"synchronized",
"continuous"
],
"description": "Optional legacy single-choice picture clock. synchronized follows Program source time; continuous advances one placed ang_... camera or one-Recording Original picture across compressed chronology until the explicit decision end. Never put this field inside scenes or slots."
},
"revert_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$",
"description": "Exact v2 camera operation receipt to Undo. Do not also pass episode_range or camera."
},
"decisions": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"description": "Bounded atomic camera program. Ranges must be disjoint; adjacent equal choices are consolidated automatically.",
"items": {
"type": "object",
"properties": {
"episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number"
},
"description": "Half-open [start_seconds,end_seconds) range on the Episode clock."
},
"camera": {
"type": "string",
"description": "original, auto, or an ang_... ID exposed by episode_read."
},
"picture_time": {
"type": "string",
"enum": [
"synchronized",
"continuous"
],
"description": "Optional picture clock. synchronized (default) follows compressed Program source time. continuous advances adjacent source footage for a placed ang_... listener or one-Recording Original base picture through a bounded internal dialogue splice; synchronized picture resumes at the explicit decision end."
},
"resync_blend_seconds": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 0.2,
"description": "Optional only for original + continuous. Duration-neutral picture-only fade from the carried clock into synchronized Original at this decision's end; Program Audio is untouched. Use only after frame evidence rejects the hard landing."
}
},
"required": [
"episode_range",
"camera"
],
"additionalProperties": false
}
},
"scenes": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"description": "Bounded atomic Picture Scene program. Ranges must be disjoint. Presets and custom geometry use the same slot primitive; all slot media are silent.",
"items": {
"type": "object",
"properties": {
"episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
},
"description": "Half-open [start_seconds,end_seconds) range on source-backed Episode content."
},
"layout": {
"type": "object",
"properties": {
"key": {
"type": "string",
"enum": [
"solo.v1",
"two_up.v1",
"pip_top_right.v1",
"pip_bottom_right.v1",
"speaker_rail_right.v1",
"grid.v1",
"custom.v1"
],
"description": "Familiar preset or custom geometry. Presets resolve server-owned boxes; custom.v1 requires every slot box."
}
},
"required": [
"key"
],
"additionalProperties": false
},
"background": {
"description": "Optional scene base. Omit on new coverage for black or on one complete existing Scene to preserve it; ambiguous replacements require an explicit value.",
"oneOf": [
{
"type": "object",
"properties": {
"policy": {
"type": "string",
"enum": [
"black.v1"
]
}
},
"required": [
"policy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"policy": {
"type": "string",
"enum": [
"still.source.v1"
]
},
"source_id": {
"type": "string",
"pattern": "^src_[a-z0-9]{20}$"
},
"source_seconds": {
"type": "number",
"minimum": 0
}
},
"required": [
"policy",
"source_id",
"source_seconds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"policy": {
"type": "string",
"enum": [
"html.graphic.v1"
]
},
"scene_id": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]*$"
},
"at_ms": {
"type": "integer",
"minimum": 0,
"maximum": 59999
}
},
"required": [
"policy",
"scene_id",
"at_ms"
],
"additionalProperties": false
}
]
},
"slots": {
"type": "array",
"minItems": 1,
"maxItems": 16,
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^[a-z][a-z0-9_]{0,39}$",
"description": "Scene-local semantic role such as primary, secondary, or inset. Roles must be unique inside the scene."
},
"binding": {
"description": "Omit only on the primary to use Program picture. Prefer a typed object. The schema also publishes the unambiguous host shorthands program/program.v1, original/original.v1, and an exact ang_... handle; the shared operation normalizes them to the same typed contract and never accepts a raw Recording ID or URL.",
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"program.v1"
]
}
},
"required": [
"kind"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"original.v1"
],
"description": "Underlying base Program Recording and occurrence source clock. Allowed in any role; no caller-supplied source ID."
}
},
"required": [
"kind"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"angle.v1"
]
},
"angle_id": {
"type": "string",
"pattern": "^ang_[a-z0-9]{20}$"
}
},
"required": [
"kind",
"angle_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"evidence_range.v1"
]
},
"evidence_id": {
"type": "string",
"pattern": "^piev_[a-z0-9]{20}$"
},
"source_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
},
"description": "Exact independent-source range; its duration must equal the complete scene duration in v1."
}
},
"required": [
"kind",
"evidence_id",
"source_range"
],
"additionalProperties": false
},
{
"type": "string",
"enum": [
"program",
"program.v1",
"original",
"original.v1"
],
"description": "Unambiguous compact binding normalized to program.v1 or original.v1."
},
{
"type": "string",
"pattern": "^ang_[a-z0-9]{20}$",
"description": "Exact Episode camera handle normalized to an angle.v1 binding."
}
]
},
"box": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false,
"description": "Normalized canvas box. x+width and y+height must each be at most 1."
},
"z_index": {
"type": "integer",
"minimum": -16,
"maximum": 16,
"description": "Scene-local stacking order from -16 through 16; values must be unique. Required with custom.v1."
},
"framing": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.picture_framing.v1"
]
},
"mode": {
"type": "string",
"enum": [
"fill",
"fit"
]
},
"focal_point": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"mode"
],
"additionalProperties": false
},
"source_crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"w": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
},
"h": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"w",
"h"
],
"additionalProperties": false,
"description": "Optional static source region in the Recording display frame, normalized to 0..1. x+w and y+h must be at most 1. Inward-rounded decoded edges must retain at least 32 pixels on each axis for every resolved source interval. Fit/Fill and framing.focal_point operate inside this cropped region. Omit the key for the full source frame or to remove a saved crop; never send null. Choose from inspected source pixels; person boxes are evidence, never an automatic crop."
},
"mask": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"rectangle.v1"
]
}
},
"required": [
"kind"
],
"additionalProperties": false
},
"enabled": {
"type": "boolean",
"description": "Defaults true. Disabled slots remain saved but do not consume live/render capacity."
}
},
"required": [
"role"
],
"additionalProperties": false
},
"description": "One local camera position per role. Exactly one enabled slot must have role primary; every slot is silent."
}
},
"required": [
"episode_range",
"layout",
"slots"
],
"additionalProperties": false
}
},
"expected_revision": {
"type": "integer",
"description": "Current structural revision returned by episode_read or the editor document."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for a safe retry of this exact camera decision."
}
},
"required": [
"episode_id",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"episode_range",
"camera"
],
"not": {
"anyOf": [
{
"required": [
"decisions"
]
},
{
"required": [
"scenes"
]
},
{
"required": [
"revert_receipt_id"
]
}
]
}
},
{
"required": [
"decisions"
],
"not": {
"anyOf": [
{
"required": [
"episode_range"
]
},
{
"required": [
"camera"
]
},
{
"required": [
"picture_time"
]
},
{
"required": [
"scenes"
]
},
{
"required": [
"revert_receipt_id"
]
}
]
}
},
{
"required": [
"scenes"
],
"not": {
"anyOf": [
{
"required": [
"episode_range"
]
},
{
"required": [
"camera"
]
},
{
"required": [
"picture_time"
]
},
{
"required": [
"decisions"
]
},
{
"required": [
"revert_receipt_id"
]
}
]
}
},
{
"required": [
"revert_receipt_id"
],
"not": {
"anyOf": [
{
"required": [
"episode_range"
]
},
{
"required": [
"camera"
]
},
{
"required": [
"picture_time"
]
},
{
"required": [
"decisions"
]
},
{
"required": [
"scenes"
]
}
]
}
}
]
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"command_type": {
"type": "string",
"enum": [
"camera.set",
"camera.clear",
"camera.program_set",
"camera.revert",
"picture_program.scene.set",
"picture_program.revert"
]
},
"affected_episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number"
}
},
"base_revision": {
"type": "integer"
},
"revision": {
"type": "integer",
"description": "Revision committed by this receipt."
},
"current_revision": {
"type": "integer",
"description": "Current Episode revision, which may be later on exact replay."
},
"changed": {
"type": "boolean"
},
"already_applied": {
"type": "boolean"
},
"render_stale": {
"type": "boolean"
},
"operation_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
},
"reverts_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
},
"before_camera_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"camera_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current_camera_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"before_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"before_picture_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"picture_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current_picture_program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"inverse": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"camera_program_set"
]
},
"revert_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
}
},
"required": [
"op",
"revert_receipt_id"
],
"additionalProperties": false
},
"tool_outcome": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.tool_outcome.v1"
]
},
"tool": {
"type": "string",
"enum": [
"camera_program_set"
]
},
"status": {
"type": "string",
"enum": [
"applied",
"replayed"
]
},
"target": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode"
]
},
"id": {
"type": "string",
"pattern": "^comp_[a-z0-9]+$"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
"command_type": {
"type": "string",
"enum": [
"camera.set",
"camera.clear",
"camera.program_set",
"camera.revert",
"picture_program.scene.set",
"picture_program.revert"
]
},
"affected_episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
}
},
"applied_decision_count": {
"type": "integer",
"minimum": 1,
"maximum": 64
},
"applied_scene_count": {
"type": "integer",
"minimum": 0,
"maximum": 64
},
"picture_scene_target": {
"type": "object",
"properties": {
"scene_id": {
"type": "string",
"pattern": "^pscn_[a-z0-9]+$"
},
"layout_key": {
"type": "string",
"enum": [
"solo.v1",
"two_up.v1",
"pip_top_right.v1",
"pip_bottom_right.v1",
"speaker_rail_right.v1",
"grid.v1",
"custom.v1"
]
},
"episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
}
}
},
"required": [
"scene_id",
"layout_key",
"episode_range"
],
"additionalProperties": false
},
"revisions": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": 0
},
"committed": {
"type": "integer",
"minimum": 1
},
"current": {
"type": "integer",
"minimum": 1
}
},
"required": [
"base",
"committed",
"current"
],
"additionalProperties": false
},
"receipt": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
},
"inverse": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"camera_program_set"
]
},
"revert_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
}
},
"required": [
"op",
"revert_receipt_id"
],
"additionalProperties": false
},
"reverts_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
}
},
"required": [
"id",
"inverse"
],
"additionalProperties": false
},
"digests": {
"type": "object",
"properties": {
"camera_program": {
"type": "object",
"properties": {
"before": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"result": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"required": [
"before",
"result",
"current"
],
"additionalProperties": false
},
"program": {
"type": "object",
"properties": {
"before": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"result": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"required": [
"before",
"result",
"current"
],
"additionalProperties": false
},
"picture_program": {
"type": "object",
"properties": {
"before": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"result": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"required": [
"before",
"result",
"current"
],
"additionalProperties": false
}
},
"required": [
"camera_program",
"program"
],
"additionalProperties": false
}
},
"required": [
"schema",
"tool",
"status",
"target",
"command_type",
"affected_episode_range",
"revisions",
"receipt",
"digests"
],
"additionalProperties": false
},
"program": {
"type": "array",
"items": {
"type": "object"
},
"description": "Resolved picture intervals used identically by immediate preview and render, including automatic fallback."
},
"decisions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Sparse persisted explicit angle or Original decisions after this edit."
},
"applied_decision_count": {
"type": "integer",
"description": "Present for an atomic multi-range directing pass."
},
"picture_program": {
"type": "object",
"description": "Current canonical Picture Program resolver document used by browser/editor preview and render. Model-context MCP replaces this field with picture_program_summary and keeps full app hydration private."
},
"picture_program_summary": {
"type": "object",
"description": "Bounded current consequence summary with affected counts and a revision-pinned episode_read next step."
},
"picture_program_availability": {
"type": "object",
"description": "Current bounded ready/degraded counts for committed Picture Slot sources."
},
"applied_scene_count": {
"type": "integer",
"minimum": 0,
"maximum": 64
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"angle_not_found",
"camera_not_available",
"stale_composition_revision",
"idempotency_conflict",
"invalid_time_range",
"invalid_input",
"camera_operation_receipt_not_found",
"camera_operation_receipt_invalid",
"camera_operation_not_revertible",
"camera_program_projection_conflict",
"camera_program_revert_conflict",
"camera_program_recovery_unavailable",
"camera_program_recovery_failed",
"picture_layout_capacity_exceeded",
"picture_program_authoring_disabled",
"picture_program_conflict",
"picture_program_integrity_failed",
"picture_program_recovery_failed",
"picture_program_recovery_unavailable",
"picture_program_revert_conflict",
"picture_program_transition_conflict",
"picture_program_write_failed",
"picture_scene_invalid",
"picture_source_not_available",
"picture_source_evidence_stale",
"source_crop_raster_too_small",
"source_media_unavailable"
]Examples
[
{
"label": "Put the Program and one synchronized camera side by side",
"input": {
"episode_id": "comp_...",
"scenes": [
{
"episode_range": [
12,
18
],
"layout": {
"key": "two_up.v1"
},
"slots": [
{
"role": "primary"
},
{
"role": "secondary",
"binding": {
"kind": "angle.v1",
"angle_id": "ang_..."
}
}
]
}
],
"expected_revision": 8,
"idempotency_key": "two-up-12-18-v8"
}
},
{
"label": "Show admitted comparison footage as a bottom-right inset",
"input": {
"episode_id": "comp_...",
"scenes": [
{
"episode_range": [
20,
25
],
"layout": {
"key": "pip_bottom_right.v1"
},
"slots": [
{
"role": "primary"
},
{
"role": "inset",
"binding": {
"kind": "evidence_range.v1",
"evidence_id": "piev_...",
"source_range": [
42,
47
]
},
"framing": {
"mode": "fill",
"focal_point": {
"x": 0.5,
"y": 0.45
}
}
}
]
}
],
"expected_revision": 9,
"idempotency_key": "comparison-pip-v9"
}
},
{
"label": "Crop a solo subject into an existing portrait canvas",
"input": {
"episode_id": "comp_...",
"scenes": [
{
"episode_range": [
12,
18
],
"layout": {
"key": "solo.v1"
},
"slots": [
{
"role": "primary",
"source_crop": {
"x": 0.02,
"y": 0.09,
"w": 0.46,
"h": 0.82
},
"framing": {
"mode": "fill",
"focal_point": {
"x": 0.5,
"y": 0.5
}
}
}
]
}
],
"expected_revision": 8,
"idempotency_key": "solo-source-crop-v8"
}
},
{
"label": "Crop one admitted camera twice into a portrait stack with a clear caption band",
"input": {
"episode_id": "comp_...",
"scenes": [
{
"episode_range": [
12,
18
],
"layout": {
"key": "custom.v1"
},
"slots": [
{
"role": "primary",
"binding": {
"kind": "evidence_range.v1",
"evidence_id": "piev_...",
"source_range": [
42,
48
]
},
"box": {
"x": 0,
"y": 0,
"width": 1,
"height": 0.42
},
"z_index": 0,
"source_crop": {
"x": 0.05,
"y": 0.15,
"w": 0.4,
"h": 0.7
},
"framing": {
"mode": "fill",
"focal_point": {
"x": 0.5,
"y": 0.5
}
}
},
{
"role": "secondary",
"binding": {
"kind": "evidence_range.v1",
"evidence_id": "piev_...",
"source_range": [
42,
48
]
},
"box": {
"x": 0,
"y": 0.58,
"width": 1,
"height": 0.42
},
"z_index": 1,
"source_crop": {
"x": 0.55,
"y": 0.15,
"w": 0.4,
"h": 0.7
},
"framing": {
"mode": "fill",
"focal_point": {
"x": 0.5,
"y": 0.5
}
}
}
]
}
],
"expected_revision": 8,
"idempotency_key": "stack-source-crops-v8"
}
},
{
"label": "Undo the exact Picture Program receipt",
"input": {
"episode_id": "comp_...",
"revert_receipt_id": "rcpt_...",
"expected_revision": 10,
"idempotency_key": "undo-picture-receipt-v10"
}
}
]music_cue_mutate
Change music in an Episode
Add, move, trim, replace, mute, remove, or restore one music cue in an Episode. Read the Episode first and pass its current revision. Each cue uses one ready song from the project's music library, an Episode range, volume, fades, a song start offset, and trim or loop-to-fill behavior. Music cues cannot overlap. The idempotency key makes an exact retry safe. Music authoring remains available only where the project has enabled it.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Editable Episode public ID."
},
"expected_revision": {
"type": "integer",
"description": "Current Episode revision from the editor document."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable retry key for this exact change."
},
"action": {
"type": "object",
"description": "One music action. Use the canonical field names in the matching action shape.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"add"
]
},
"episode_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
},
"bed_id": {
"type": "string",
"description": "Ready song ID returned by identity_assets_list under assets.music_beds."
},
"parameters": {
"type": "object",
"description": "Optional music settings. Omitted fields keep their current values; a new cue uses the documented defaults.",
"properties": {
"label": {
"type": "string",
"description": "Optional plain-language label for this cue."
},
"asset_offset_seconds": {
"type": "number",
"minimum": 0,
"description": "Where to begin inside the selected song."
},
"gain_db": {
"type": "number",
"description": "Music volume in decibels."
},
"fade_in_seconds": {
"type": "number",
"minimum": 0
},
"fade_out_seconds": {
"type": "number",
"minimum": 0
},
"ducking_db": {
"type": "number",
"enum": [
0
],
"description": "Reserved music-side speech ducking amount. Use 0 until speech-aware ducking is available."
},
"fit_mode": {
"type": "string",
"enum": [
"trim_to_range",
"loop_crossfade"
],
"description": "Trim the song to the cue or loop it to fill the cue range."
},
"enabled": {
"type": "boolean",
"description": "Whether this cue plays."
}
},
"additionalProperties": false
}
},
"required": [
"type",
"episode_range",
"bed_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"update"
]
},
"music_id": {
"type": "string",
"description": "Music cue ID returned by the Episode music projection or an earlier music change."
},
"episode_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
},
"parameters": {
"type": "object",
"description": "Optional music settings. Omitted fields keep their current values; a new cue uses the documented defaults.",
"properties": {
"label": {
"type": "string",
"description": "Optional plain-language label for this cue."
},
"asset_offset_seconds": {
"type": "number",
"minimum": 0,
"description": "Where to begin inside the selected song."
},
"gain_db": {
"type": "number",
"description": "Music volume in decibels."
},
"fade_in_seconds": {
"type": "number",
"minimum": 0
},
"fade_out_seconds": {
"type": "number",
"minimum": 0
},
"ducking_db": {
"type": "number",
"enum": [
0
],
"description": "Reserved music-side speech ducking amount. Use 0 until speech-aware ducking is available."
},
"fit_mode": {
"type": "string",
"enum": [
"trim_to_range",
"loop_crossfade"
],
"description": "Trim the song to the cue or loop it to fill the cue range."
},
"enabled": {
"type": "boolean",
"description": "Whether this cue plays."
}
},
"additionalProperties": false
}
},
"required": [
"type",
"music_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"replace"
]
},
"music_id": {
"type": "string",
"description": "Music cue ID returned by the Episode music projection or an earlier music change."
},
"bed_id": {
"type": "string",
"description": "Ready song ID returned by identity_assets_list under assets.music_beds."
},
"episode_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
},
"parameters": {
"type": "object",
"description": "Optional music settings. Omitted fields keep their current values; a new cue uses the documented defaults.",
"properties": {
"label": {
"type": "string",
"description": "Optional plain-language label for this cue."
},
"asset_offset_seconds": {
"type": "number",
"minimum": 0,
"description": "Where to begin inside the selected song."
},
"gain_db": {
"type": "number",
"description": "Music volume in decibels."
},
"fade_in_seconds": {
"type": "number",
"minimum": 0
},
"fade_out_seconds": {
"type": "number",
"minimum": 0
},
"ducking_db": {
"type": "number",
"enum": [
0
],
"description": "Reserved music-side speech ducking amount. Use 0 until speech-aware ducking is available."
},
"fit_mode": {
"type": "string",
"enum": [
"trim_to_range",
"loop_crossfade"
],
"description": "Trim the song to the cue or loop it to fill the cue range."
},
"enabled": {
"type": "boolean",
"description": "Whether this cue plays."
}
},
"additionalProperties": false
}
},
"required": [
"type",
"music_id",
"bed_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"set_enabled"
]
},
"music_id": {
"type": "string",
"description": "Music cue ID returned by the Episode music projection or an earlier music change."
},
"enabled": {
"type": "boolean"
}
},
"required": [
"type",
"music_id",
"enabled"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"remove"
]
},
"music_id": {
"type": "string",
"description": "Music cue ID returned by the Episode music projection or an earlier music change."
}
},
"required": [
"type",
"music_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"revert"
]
},
"receipt_id": {
"type": "string",
"description": "Receipt ID returned by the music change to restore."
}
},
"required": [
"type",
"receipt_id"
],
"additionalProperties": false
}
]
}
},
"required": [
"episode_id",
"expected_revision",
"idempotency_key",
"action"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"changed": {
"type": "boolean"
},
"already_applied": {
"type": "boolean"
},
"render_stale": {
"type": "boolean"
},
"music_digest": {
"type": "string"
},
"music": {
"type": "array",
"items": {
"type": "object"
}
},
"cue": {
"type": [
"object",
"null"
]
},
"receipt": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"music_export_in_progress",
"music_not_found",
"music_cue_not_found",
"music_cue_limit",
"music_receipt_not_found",
"music_revert_conflict",
"music_unavailable",
"invalid_music_cue",
"invalid_music_range",
"music_anchor_unavailable",
"music_anchor_transform_unsupported",
"music_range_inverted",
"music_ranges_overlap",
"music_asset_too_short",
"music_trim_out_of_range",
"music_fades_too_long",
"identity_music_bed_not_ready",
"identity_music_bed_audio_missing",
"identity_music_bed_content_type_invalid",
"identity_music_bed_too_large",
"identity_music_bed_duration_invalid",
"identity_music_bed_codec_invalid",
"identity_music_bed_channels_invalid",
"identity_music_bed_sample_rate_invalid",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input"
]speaker_title_mutate
Change a stable speaker title
Add, revise, hide, remove, or restore one sparse professional speaker label in an Episode. Read the Episode first and pass its current revision. A title lasts 0.8–12 seconds inside one source-backed occurrence and stays completely fixed in a semantic left/right + upper/lower slot; offsets are small canvas-relative nudges, never pixels, face boxes, or a tracking path. Frontier Clean uses crisp black type on a quiet white field with a restrained rail/lock reveal; give the entrance roughly 0.3–0.5 seconds when the title should feel authored rather than abrupt. Place titles only where identification earns the interruption—typically once during a cold open and once near a speaker's first sustained appearance in the body, not on every camera cut. Choose a slot that does not collide with the active caption lane or the speaker's face. For top-aligned 4:5 picture on a 9:16 canvas with a dedicated lower matte caption panel, lower places the title just inside the picture edge; the matte remains exclusively for centered subtitles. Use an upper slot only when the actual composition makes it the calmer negative-space choice. A title has one restrained entrance and fade-out, then remains fixed. Small feedback such as ‘move Jay left,’ ‘move it down,’ or ‘leave it up longer’ updates the same title without rerunning visual analysis. For an enabled title, the successful MCP response attempts to attach exactly one receipt-bound settled positioning JPEG using Export geometry, including any committed caption visible at that instant so title/subtitle collisions are observable. Inspect that image before deciding whether to nudge the same title. positioning_sample is always present: ready, not_applicable, unavailable, or superseded; unavailable never means the committed mutation failed. Re-read before another change. The idempotency key makes an exact retry safe.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Editable Episode public ID."
},
"expected_revision": {
"type": "integer",
"description": "Current Episode revision returned by episode_read or the editor document."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable retry key for this exact speaker-title change."
},
"action": {
"type": "object",
"description": "One speaker-title action. Use the canonical fields in the matching action shape.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"add"
]
},
"episode_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock. Must remain inside one source-backed occurrence and last 0.8–12 seconds."
},
"content": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 80,
"description": "Speaker name shown in the strong first line."
},
"subtitle": {
"type": "string",
"maxLength": 120,
"description": "Optional role, company, or other concise second line."
}
},
"required": [
"name"
],
"additionalProperties": false
},
"presentation": {
"type": "object",
"description": "Stable picture-aware treatment. Omitted add fields use Frontier Clean, left/lower, a restrained 320 ms rail/field/type reveal, and a 220 ms fade-out; omitted update fields keep their current values.",
"properties": {
"preset": {
"type": "string",
"enum": [
"frontier_clean"
]
},
"side": {
"type": "string",
"enum": [
"left",
"right"
],
"description": "Stable horizontal anchor for the whole title appearance."
},
"lane": {
"type": "string",
"enum": [
"upper",
"lower"
],
"description": "Stable vertical lane for the whole title appearance. In a portrait canvas with top-aligned 4:5 picture and a lower matte caption panel, lower sits inside the picture just above its edge; the caption panel remains solely for subtitles. Otherwise choose against occupied face space and the active caption lane."
},
"horizontal_offset": {
"type": "number",
"minimum": -0.12,
"maximum": 0.12,
"description": "Small normalized nudge; positive moves right and negative moves left."
},
"vertical_offset": {
"type": "number",
"minimum": -0.15,
"maximum": 0.15,
"description": "Small normalized nudge; positive moves down and negative moves up."
},
"fade_in_seconds": {
"type": "number",
"minimum": 0,
"maximum": 1.5
},
"fade_out_seconds": {
"type": "number",
"minimum": 0,
"maximum": 1.5
}
},
"additionalProperties": false
}
},
"required": [
"type",
"episode_range",
"content"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"update"
]
},
"speaker_title_id": {
"type": "string",
"description": "Speaker-title ID returned by episode_read or an earlier speaker-title change."
},
"episode_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock. Must remain inside one source-backed occurrence and last 0.8–12 seconds."
},
"content": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 80
},
"subtitle": {
"type": "string",
"maxLength": 120,
"description": "Set to an empty string to remove the second line."
}
},
"required": [],
"additionalProperties": false
},
"presentation": {
"type": "object",
"description": "Stable picture-aware treatment. Omitted add fields use Frontier Clean, left/lower, a restrained 320 ms rail/field/type reveal, and a 220 ms fade-out; omitted update fields keep their current values.",
"properties": {
"preset": {
"type": "string",
"enum": [
"frontier_clean"
]
},
"side": {
"type": "string",
"enum": [
"left",
"right"
],
"description": "Stable horizontal anchor for the whole title appearance."
},
"lane": {
"type": "string",
"enum": [
"upper",
"lower"
],
"description": "Stable vertical lane for the whole title appearance. In a portrait canvas with top-aligned 4:5 picture and a lower matte caption panel, lower sits inside the picture just above its edge; the caption panel remains solely for subtitles. Otherwise choose against occupied face space and the active caption lane."
},
"horizontal_offset": {
"type": "number",
"minimum": -0.12,
"maximum": 0.12,
"description": "Small normalized nudge; positive moves right and negative moves left."
},
"vertical_offset": {
"type": "number",
"minimum": -0.15,
"maximum": 0.15,
"description": "Small normalized nudge; positive moves down and negative moves up."
},
"fade_in_seconds": {
"type": "number",
"minimum": 0,
"maximum": 1.5
},
"fade_out_seconds": {
"type": "number",
"minimum": 0,
"maximum": 1.5
}
},
"additionalProperties": false
}
},
"required": [
"type",
"speaker_title_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"set_enabled"
]
},
"speaker_title_id": {
"type": "string",
"description": "Speaker-title ID returned by episode_read or an earlier speaker-title change."
},
"enabled": {
"type": "boolean"
}
},
"required": [
"type",
"speaker_title_id",
"enabled"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"remove"
]
},
"speaker_title_id": {
"type": "string",
"description": "Speaker-title ID returned by episode_read or an earlier speaker-title change."
}
},
"required": [
"type",
"speaker_title_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"revert"
]
},
"receipt_id": {
"type": "string",
"description": "Receipt ID returned by the speaker-title change to restore."
}
},
"required": [
"type",
"receipt_id"
],
"additionalProperties": false
}
]
}
},
"required": [
"episode_id",
"expected_revision",
"idempotency_key",
"action"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"changed": {
"type": "boolean"
},
"already_applied": {
"type": "boolean"
},
"render_stale": {
"type": "boolean"
},
"speaker_titles_digest": {
"type": "string"
},
"speaker_titles": {
"type": "array",
"items": {
"type": "object"
}
},
"speaker_title": {
"type": [
"object",
"null"
]
},
"speaker_title_digest": {
"type": [
"string",
"null"
]
},
"positioning_sample": {
"type": "object",
"description": "Post-commit positioning feedback. ready means exactly one inline JPEG plus durable sample/frame references; other statuses carry a reason and safe retry guidance without changing mutation success."
},
"receipt": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"speaker_title_export_in_progress",
"speaker_title_not_found",
"speaker_title_limit",
"speaker_title_receipt_not_found",
"speaker_title_revert_conflict",
"invalid_speaker_title",
"invalid_speaker_title_range",
"speaker_title_occurrence_unsupported",
"speaker_title_anchor_unavailable",
"speaker_title_overlap",
"speaker_title_anchor_transform_unsupported",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input"
]audio_program_mutate
Change Program audio
One Program-audio change per call: set, pin_set, treatment_set, or revert. This controls source audio only; it never adds, mixes, lowers, or ducks background music — use music_cue_mutate for music. set chooses occurrence-relative Program audio without changing picture — mode accepts replace, silence, clear, or reset; Replace requires an Episode camera_group_key plus the exact footage-session revision you inspected, and BitterClip derives every recording/source slice from synchronized evidence (the caller never supplies source coordinates; read the Episode first and address stable occurrence IDs and source-time ranges, never transcript word times); reset atomically clears the Program pin and every explicit interval policy, omitting occurrence_id and occurrence_source_range. pin_set chooses one stable synchronized camera group as the preferred Program-audio source wherever it has usable coverage, without changing picture, chronology, or the listening reference; pass auto to clear. The settled fallback is explicit interval Replace or silence, then the pin where covered, then the Program occurrence's own recording, then true silence. treatment_set chooses Speech (a versioned, bounded gain/ramp plan tied to the exact raw audio-authority digest; when audio authority later changes the saved plan reads stale and playback falls back truthfully to Raw) or Raw for an explicit bypass. Speech requires measured short-term loudness from ordinary ingest of a supported new recording. If processing is pending, follow the returned recording-status continuation before retrying; terminal unavailable, silence, or insufficient-measurement results retain Raw and must not be retried to regenerate missing measurements. Existing recordings are not backfilled. Speech leveling is separate from final Export mastering. revert applies the server-owned inverse recorded by one Program-audio receipt as a new revision-checked forward edit, failing closed if the prior audio state can no longer be restored exactly.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Editable Episode public ID that scopes this change."
},
"expected_revision": {
"type": "integer",
"description": "Current Episode revision returned by episode_read."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for an exact retry."
},
"action": {
"type": "object",
"description": "One Program-audio action. Use the canonical field names in the matching action shape.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"set"
]
},
"occurrence_id": {
"type": "string",
"description": "Stable occ_... Program occurrence identity. Omit only for reset."
},
"occurrence_source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open source-time range inside the occurrence. Omit only for reset."
},
"mode": {
"type": "string",
"enum": [
"replace",
"silence",
"clear",
"reset"
],
"description": "Replace with synchronized camera-group audio, choose deliberate silence, clear policy in one occurrence range, or reset the whole Program audio graph."
},
"camera_group_key": {
"type": "string",
"description": "Required for Replace: stable camgrp_... identity from the Episode camera roster."
},
"expected_capture_session_revision": {
"type": "integer",
"description": "Required for Replace: exact footage-session evidence revision returned by episode_read."
}
},
"required": [
"type",
"mode"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"pin_set"
]
},
"camera_group_key": {
"type": "string",
"description": "Stable camgrp_... identity from the Episode camera roster, or auto to clear the explicit pin."
},
"expected_capture_session_revision": {
"type": "integer",
"description": "Required when pinning: exact footage-session evidence revision returned by episode_read. Omit only when clearing with auto."
}
},
"required": [
"type",
"camera_group_key"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"treatment_set"
]
},
"mode": {
"type": "string",
"enum": [
"speech",
"raw"
],
"description": "Speech applies the saved speech-leveling plan; Raw bypasses it."
}
},
"required": [
"type",
"mode"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"revert"
]
},
"receipt_id": {
"type": "string",
"description": "Program-audio operation receipt returned by a prior audio_program_mutate action."
}
},
"required": [
"type",
"receipt_id"
],
"additionalProperties": false
}
]
}
},
"required": [
"episode_id",
"expected_revision",
"idempotency_key",
"action"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"base_revision": {
"type": "integer"
},
"revision": {
"type": "integer",
"description": "Revision committed by this audio operation."
},
"current_revision": {
"type": "integer",
"description": "Current durable Episode head, which may be newer on an exact retry."
},
"changed": {
"type": "boolean"
},
"already_applied": {
"type": "boolean"
},
"operation_receipt_id": {
"type": "string"
},
"audio_program_digest": {
"type": "string",
"description": "Resolved Program-audio digest committed by this operation."
},
"current_audio_program_digest": {
"type": [
"string",
"null"
]
},
"audio_program": {
"type": [
"object",
"null"
],
"description": "Canonical Program-audio intervals shared by immediate playback and render. Null only when changed footage evidence makes the current audio policy fail closed."
},
"audio_program_error": {
"type": [
"object",
"null"
],
"description": "Typed fail-closed projection when the current audio policy needs review."
},
"render_stale": {
"type": "boolean"
},
"inverse": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"audio_program_mutate"
],
"description": "Revert by calling this op with action { type: revert, receipt_id }."
},
"receipt_id": {
"type": "string"
}
},
"required": [
"op",
"receipt_id"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"recording_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_time_range",
"invalid_audio_treatment",
"audio_evidence_unavailable",
"transcript_timing_unavailable",
"speech_evidence_unavailable",
"speech_source_unavailable",
"invalid_input",
"program_audio_conflict"
]help
BitterClip help
Discover BitterClip help with no input, ask a natural-language question for short sourced passages, or pass an exact bitterclip://docs URI to read a page. Covers live public creator docs and private agent operating guidance. Read-only; no customer media.
Input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Question or exact bitterclip://docs URI. Omit to discover help."
},
"limit": {
"type": "integer",
"description": "Maximum search matches (1-5, default 3)."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"invalid_input"
]speakers_list
List remembered people
List the people BitterClip remembers for this account, with per-person recording/word/voiceprint counts, first/last-seen dates, and review flags. For a whole-account or current-account speaker-exception ask, start with one speakers_list call using filter=assignment_exceptions and no project_id. When that complete queue succeeds, do not reconstruct it with projects_list, project-title search, enumeration, or project-scoped fan-out; title filtering can omit in-scope projects whose names do not match the user's shorthand. For a deliberately named subset of projects, keep that narrower scope and use project-scoped reads only for the named subset. The account queue begins with a complete contiguous short-answer block: preserve its project, recording-group, and open-track header, include every numbered project group regardless of title, and treat the later recording rows as an evidence appendix rather than a new scope. It returns exact row-derived account and per-project totals, every open project and recording group, and no hidden tail; shared projects from other studios are excluded. With project_id, needs_review or assignment_exceptions reports recording-assignment exceptions separately from person-profile confirmation, including current owner-reviewed wrong/unsure tracks and other tracks still needing review. The exception queue is grouped by recording, deliberately omits per-track size because size alone cannot resolve identity or dismiss an exception, and marks every open row non-dismissible until an explicit review or verified correction resolves it. A known-wrong current label does not identify the replacement speaker; that track stays open. Treat the result as one project-level exception queue: recording groups are evidence organization, not separate tasks, and every listed row remains in the queue. Generic provider labels are recording-local, so matching Speaker 1/2 text across recordings never proves one voice or merges track decisions. Absence from the queue never proves a label, person, recording, or project is settled. The readable result includes every open recording group; there is no hidden compact-list tail. Never infer noise, crosstalk, non-person status, optionality, or safe-to-ignore state from track size alone. Use the appropriate whole-account or project-scoped mode FIRST when the user asks who appears across recordings, who spoke how much, or which identities need review; do not reconstruct the answer from transcripts. Ordinary people-list modes return stable spkr_... IDs for speakers_get/speakers_get_appearances follow-ups; the account assignment_exceptions mode instead returns complete ID-free queue prose. Read-only.
Input schema
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"enum": [
"assignment_exceptions",
"needs_review",
"needs_photo_review",
"possible_duplicates",
"no_voice",
"recent",
"merged"
],
"description": "Optional people filter. Defaults to recent. assignment_exceptions without project_id returns the complete current-account recording-assignment queue and ignores the people limit; with project_id, assignment_exceptions and needs_review select people attached to track exceptions while also reporting unbound exceptions."
},
"project_id": {
"type": "string",
"description": "Optional project public ID to limit results to people seen or configured in one project."
},
"limit": {
"type": "integer",
"description": "Maximum people to return. Default 20, maximum 50. The complete assignment_exceptions account queue is never truncated by this people limit."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]speakers_get
Get remembered person
Read one remembered person, including names, saved voice examples, project names, merge history, and appearance counts. With project_id, it also reports that person's current recording-assignment exceptions; a confirmed person profile does not imply every track assignment is correct. This does not change identity.
Input schema
{
"type": "object",
"properties": {
"speaker_profile_id": {
"type": "string",
"description": "Person public ID, slug, or UUID."
},
"project_id": {
"type": "string",
"description": "Optional project public ID to scope project-limited access."
}
},
"required": [
"speaker_profile_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"speaker": {
"type": "object"
},
"aliases": {
"type": "array",
"items": {
"type": "object"
}
},
"voiceprints": {
"type": "array",
"items": {
"type": "object"
}
},
"project_presentations": {
"type": "array",
"items": {
"type": "object"
}
},
"merge_history": {
"type": "array",
"items": {
"type": "object"
}
},
"appearance_counts": {
"type": "object"
},
"assignment_review": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"speaker_not_found",
"invalid_input"
]speakers_get_appearances
Get where a person appears
Read a person's current Recording voices, saved answers with lost placement, and editorial Moments. Each voice carries its current identity state, source timing when available, and the recording_id/speaker_map_id selector for recordings_get_speaker_evidence. Unplaced answers retain their recording_id/decision_id selector when available; no current occurrence or timing is inferred. Each recent group reports truncation separately. A suggestion is not an attached person. With project_id, all rows are project-scoped and assignment exceptions are reported separately. Moment rows keep the transcript speaker_label and use current project presentation for display_label. Legacy clips and exports groups are empty; exact finished Export labels are not recalculated.
Input schema
{
"type": "object",
"properties": {
"speaker_profile_id": {
"type": "string",
"description": "Person public ID, slug, or UUID."
},
"status": {
"type": "string",
"enum": [
"all",
"current",
"stale"
],
"description": "Optional Moment status filter. Defaults to all. Voices always describe current placements; their standing reports any stale review separately."
},
"project_id": {
"type": "string",
"description": "Optional project public ID to limit results."
},
"limit": {
"type": "integer",
"description": "Maximum rows per group. Default 20, maximum 50."
}
},
"required": [
"speaker_profile_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"speaker": {
"type": "object"
},
"status": {
"type": "string"
},
"counts": {
"type": "object"
},
"assignment_review": {
"type": "object"
},
"moments": {
"type": "array",
"items": {
"type": "object"
}
},
"voices": {
"type": "array",
"items": {
"type": "object"
}
},
"voices_has_more": {
"type": "boolean"
},
"unplaced_answers": {
"type": "array",
"items": {
"type": "object"
}
},
"unplaced_answers_has_more": {
"type": "boolean"
},
"clips": {
"type": "array",
"items": {
"type": "object"
}
},
"exports": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"speaker_not_found",
"project_not_found",
"invalid_input"
]workspace_open
Open BitterClip workspace
Read-only. Requires exact target_type + target_id. Never use it for discovery or open a Project en route to a named Episode/Clip; discover first, then call once and last. Prepare BitterClip's review, edit, or publish workspace for a recording, Episode, Clip, or publish package. This tool never creates or changes an Episode, review point, or other saved state. To prepare one named read-only moment, pass target_type episode or clip, mode review, the exact expected_revision from episode_read, and focus_range:[start,end] in playable Episode time; the range is transient and never saved. A matching returned workspace_navigation proves BitterClip prepared the target, not that the host visibly mounted, played, or navigated it. Omit focus_range to open the whole target. Use review_points_place only when the user explicitly asks to save or mark reviewable Moments. In Embedded mode the host can mount the returned workspace resource. Every lane's result carries `open_status`. "already_open" means a live editor session for this exact target is beside the user and updates itself: direct attention to the exact place instead of presenting a link or claiming navigation. In Live Workspace mode without presence the result is "link_ready" plus an exact `workspace_url`; that does not prove a browser opened, so present the exact Open workspace link unless visible navigation is independently verified. In Embedded mode without presence it is "prepared": the host may mount the returned workspace resource, but nothing was navigated, so never claim you opened it unless your host visibly shows it. A just-created montage gives the user a playable stitched preview of the draft. A project target returns a concise handoff with bounded recent editable Episodes/Clips for rediscovery rather than an embedded library; use projects_list, recordings_list, and episodes_list for source discovery. On informational asks ("do I have X?", "did we discuss X?"), answer with receipts and OFFER to open related findings — prepare the handoff only when the user asked to open/show/review something.
Input schema
{
"type": "object",
"properties": {
"target_type": {
"type": "string",
"enum": [
"project",
"recording",
"episode",
"clip",
"publish_package"
],
"description": "Object to hand off. Project targets produce a concise summary; exact media targets prepare the visual workspace."
},
"target_id": {
"type": "string",
"description": "Public ID for the target object."
},
"mode": {
"type": "string",
"enum": [
"review",
"edit",
"publish"
],
"description": "Requested workspace mode."
},
"project_id": {
"type": "string",
"description": "Optional Project context for the exact target. To open a Project, pass target_type:\"project\" and its ID as target_id. For episode/clip targets OMIT this unless you hold the project id from a listing — it is never required, an episode id here is invalid_input, and a just-created clip's project may differ from what you assume."
},
"focus_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Optional transient half-open [start_seconds, end_seconds) Episode-time focus. Valid only for episode/clip review with expected_revision; must be finite, nonempty, and fully in bounds. Never clamped or saved."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "Exact structural revision from episode_read. Required with focus_range and rejected without it."
}
},
"required": [
"target_type",
"target_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"tool_outcome": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.tool_outcome.v1"
]
},
"tool": {
"type": "string",
"enum": [
"workspace_open"
]
},
"kind": {
"type": "string",
"enum": [
"workspace-prepared"
]
},
"status": {
"type": "string",
"enum": [
"prepared"
]
},
"target": {
"type": "object"
},
"revision": {
"type": "integer"
},
"next_action": {
"type": "object"
}
},
"required": [
"schema",
"tool",
"kind",
"status",
"target",
"revision",
"next_action"
],
"additionalProperties": false
},
"opened": {
"type": "boolean",
"description": "Embedded-mode resource acceptance only. This never proves a host browser visibly opened."
},
"open_status": {
"type": "string",
"enum": [
"link_ready",
"already_open",
"prepared"
],
"description": "Handoff state. already_open (any lane): a live editor session for this exact target was seen within its presence window — the workspace beside the user updates itself, so direct attention to the exact place instead of presenting a link or claiming navigation. link_ready (Live Workspace, no presence): present workspace_url as the exact Open workspace link; visible navigation is not verified. prepared (Embedded, no presence): the workspace was prepared for the host to display; nothing was navigated, so do not claim you opened it unless your host visibly shows it."
},
"workspace_url": {
"type": "string",
"description": "Exact authorized BitterClip workspace URL."
},
"project_id": {
"type": "string"
},
"project": {
"type": "object"
},
"recent_outputs": {
"type": "object",
"description": "Bounded newest-first editable Episode/Clip work for a project handoff, with exact reopen actions and no media URLs."
},
"recording": {
"type": "object"
},
"media": {
"type": "object"
},
"composition": {
"type": "object"
},
"focus_range": {
"type": "array",
"items": {
"type": "number"
},
"description": "Accepted transient Episode-time review range, when requested."
},
"focus_revision": {
"type": "integer",
"description": "Structural revision against which focus_range was validated."
},
"workspace_navigation": {
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"target",
"route"
],
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.workspace-nav.v1"
]
},
"target": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"id"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string",
"pattern": "^comp_[A-Za-z0-9_-]{1,120}$"
}
}
},
"route": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"mode"
],
"properties": {
"name": {
"type": "string",
"enum": [
"composition"
]
},
"mode": {
"type": "string",
"enum": [
"review"
]
}
}
}
}
},
"editor_document": {
"type": "object",
"description": "Versioned application document consumed by the shared editor."
},
"moments": {
"type": "array"
},
"speaker_legend": {
"type": "array"
},
"speaker_model_context": {
"type": "object"
},
"publish_package_id": {
"type": [
"string",
"null"
],
"description": "Present when opening a publish package or approval for review."
},
"publish_package": {
"type": "object"
},
"publish_state": {
"type": "object",
"description": "Canonical BitterClip publish-state envelope for web, mobile, MCP/App widgets, and AI cockpit tools. Use stage first for the current product state and next action.",
"properties": {
"schema_version": {
"type": "string"
},
"object": {
"type": "object",
"description": "Current publish object identity, using public IDs only.",
"properties": {
"kind": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"recording_id": {
"type": [
"string",
"null"
]
},
"clip_id": {
"type": [
"string",
"null"
]
},
"composition_id": {
"type": [
"string",
"null"
]
},
"export_id": {
"type": [
"string",
"null"
]
},
"approval_id": {
"type": "string"
},
"platform": {
"type": "string"
}
}
},
"media": {
"type": "object",
"description": "Whether the media asset can be published.",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"rendering",
"failed",
"missing",
"render_required",
"stale"
]
},
"ready": {
"type": "boolean"
},
"source": {
"type": "string"
},
"message": {
"type": "string"
},
"download_url": {
"type": [
"string",
"null"
]
}
}
},
"package": {
"type": "object",
"description": "Reviewable package readiness and approval state.",
"properties": {
"status": {
"type": "string",
"enum": [
"missing",
"needs_review",
"approved",
"published",
"failed",
"blocked",
"manual_handoff",
"ready",
"rendering",
"render_required",
"stale"
]
},
"ready": {
"type": "boolean"
},
"approval_status": {
"type": "string"
},
"explicit_approval_required": {
"type": "boolean"
},
"kind": {
"type": "string"
},
"mode": {
"type": "string"
},
"review_url": {
"type": "string"
},
"checks_summary": {
"type": "object"
}
}
},
"copy": {
"type": "object",
"description": "Destination-copy readiness and formatting state.",
"properties": {
"status": {
"type": "string"
},
"format": {
"type": "string"
},
"ready": {
"type": "boolean"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"body_present": {
"type": "boolean"
},
"text_present": {
"type": "boolean"
},
"body_preview": {
"type": [
"string",
"null"
]
},
"message": {
"type": "string",
"description": "Plain-language copy readiness summary for primary UI and model responses."
},
"preview_lines": {
"type": "array",
"items": {
"type": "string"
},
"description": "First non-empty destination-copy lines, preserving platform-native paragraph and bullet structure for compact UI."
},
"line_count": {
"type": "integer"
},
"character_count": {
"type": "integer"
},
"platform_native": {
"type": "boolean"
}
}
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"platform": {
"type": "string"
},
"platform_key": {
"type": "string"
},
"label": {
"type": "string"
},
"readiness": {
"type": "string",
"enum": [
"connected",
"missing_auth",
"permission_limited",
"capped",
"unsupported",
"manual_handoff",
"blocked"
]
},
"configured": {
"type": "boolean"
},
"package_mode": {
"type": "string"
},
"package": {
"type": "object",
"properties": {
"status": {
"type": [
"string",
"null"
]
},
"ready": {
"type": [
"boolean",
"null"
]
},
"approval_id": {
"type": [
"string",
"null"
]
},
"approval_public_id": {
"type": [
"string",
"null"
]
},
"approval_status": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"mode": {
"type": [
"string",
"null"
]
},
"link_platform": {
"type": [
"string",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
}
}
},
"attempt_state": {
"type": "string"
},
"reconciliation_state": {
"type": [
"string",
"null"
]
},
"cleanup_state": {
"type": [
"string",
"null"
]
},
"latest_publish_record_id": {
"type": [
"string",
"null"
]
},
"external_url": {
"type": [
"string",
"null"
]
},
"external_urls": {
"type": "array",
"items": {
"type": "string"
}
},
"safe_to_retry": {
"type": "boolean"
},
"can_prepare_package": {
"type": [
"boolean",
"null"
]
},
"selected_by_default": {
"type": [
"boolean",
"null"
]
},
"can_publish_approval": {
"type": [
"boolean",
"null"
]
},
"attempts": {
"type": "array",
"items": {
"type": "object"
}
},
"next_action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"stage": {
"type": "object",
"description": "Compact product-language state for above-the-fold UI and model narration. Read this first.",
"required": [
"status",
"label",
"message",
"blocking",
"ready_to_publish"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ready_to_publish",
"ready_to_package",
"needs_review",
"needs_destination",
"destination_blocked",
"manual_handoff",
"copy_needs_review",
"needs_reconciliation",
"cleanup_failed",
"publishing",
"published",
"rendering",
"render_required",
"stale",
"missing",
"failed"
]
},
"label": {
"type": "string"
},
"message": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"ready_to_publish": {
"type": "boolean"
},
"action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
}
}
},
"next_action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
}
},
"required": [
"schema_version",
"object",
"media",
"package",
"copy",
"destinations",
"stage"
]
},
"route": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
},
"next_actions": {
"type": "array",
"description": "Optional follow-up BitterClip tool calls. Handles inside arguments are for tool calls only, not user-facing prose."
},
"handle_policy": {
"type": "string",
"description": "Reminder that raw BitterClip handles are tool-call-only and should not be shown to users."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"composition_not_found",
"recording_not_found",
"stale_composition_revision",
"episode_changed_during_read",
"invalid_time_range",
"invalid_input"
]review_points_place
Place review points
Save 1–20 source-backed, reviewable Moments on one existing Episode, then open the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this once and last only when the user explicitly asks to save or mark reviewable Moments; never use it for a read-only open/show request, and never follow it with workspace_open. Each range is a half-open [start_seconds, end_seconds) interval on the playable Episode clock. Retries converge on an existing active Moment at the exact same source-time range. This changes review metadata only; it never changes source footage or the Program, creates a reel, or renders media.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Exact Episode or derived Clip handle returned by BitterClip."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "Exact structural revision returned by episode_read. Stale revisions fail before any Moment is written."
},
"selections": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"description": "Review points to place in Episode time.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"range",
"title"
],
"properties": {
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "Short label for the review point."
},
"rationale": {
"type": "string",
"maxLength": 500,
"description": "Optional editorial reason the moment is useful."
}
}
}
}
},
"required": [
"episode_id",
"expected_revision",
"selections"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"opened": {
"type": "boolean"
},
"workspace_url": {
"type": "string"
},
"project_id": {
"type": "string"
},
"project": {
"type": "object"
},
"composition": {
"type": "object"
},
"workspace_navigation": {
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"target",
"route"
],
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.workspace-nav.v1"
]
},
"target": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"id"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string",
"pattern": "^comp_[A-Za-z0-9_-]{1,120}$"
}
}
},
"route": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"mode"
],
"properties": {
"name": {
"type": "string",
"enum": [
"composition"
]
},
"mode": {
"type": "string",
"enum": [
"review"
]
}
}
}
}
},
"editor_document": {
"type": "object",
"description": "Versioned application document consumed by the shared editor."
},
"moments": {
"type": "array",
"description": "Active source-backed review points visible on this Episode."
},
"selection_results": {
"type": "array",
"description": "One compact, handle-free placement result per requested review point.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"title": {
"type": "string"
},
"label": {
"type": "string"
},
"episode_start_seconds": {
"type": "number",
"description": "Requested Episode start."
},
"episode_end_seconds": {
"type": "number",
"description": "Requested Episode end."
},
"placed_episode_start_seconds": {
"type": "number",
"description": "Actual persisted Episode start."
},
"placed_episode_end_seconds": {
"type": "number",
"description": "Actual persisted Episode end."
},
"reason": {
"type": "string",
"description": "Closed placement, clamp, or failure reason."
},
"message": {
"type": "string"
},
"deduped": {
"type": "boolean",
"description": "True when an exact active review point already existed."
}
}
}
},
"route": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
},
"next_actions": {
"type": "array"
},
"handle_policy": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"invalid_input",
"stale_composition_revision",
"episode_changed_during_read"
]identity_assets_list
List project identity assets
Discover the saved Signature assets available in a project context: account-library opener entries, outro entries, cut-style entries, a compact curated identity-sound palette, and music beds, with quiet default marks for this project. Signature applies saved opener, outro, and cut style choices to new reels; saved project music creates a full-Episode music cue. Do not call this just to use known project defaults; for the Andrew trainer worked example in the server instructions, the right call is episode_create with identity:"project_default". Call this when defaults are absent or unclear, when the user names a specific look, sound, song, or asset, or when you need uses_title before passing opener_title. Use opener and outro library_entry_id refs in an explicit identity object. To change the sonic mark on an existing typed opener or outro, pass an identity_sounds id to episode_edit identity_part.customize set.sound_id. Use a music-bed id with music_cue_mutate. Music family, mood, and tags support compact genre matching; prompts describe the finer vibe.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID."
},
"include_archived": {
"type": "boolean",
"description": "Include archived music beds. Openers, outros, and cut styles come from the account identity library. Defaults false."
}
},
"required": [
"project_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string"
},
"project_title": {
"type": "string"
},
"enabled_for_reels": {
"type": "boolean",
"description": "Whether this project identity pack is enabled for future reels. This read reports the setting; it does not manage it."
},
"assets": {
"type": "object",
"properties": {
"openers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identity library entry public ID."
},
"library_entry_id": {
"type": "string"
},
"preset_id": {
"type": "string"
},
"name": {
"type": "string"
},
"duration_ms": {
"type": [
"integer",
"null"
]
},
"brand_id": {
"type": "string"
},
"aspect_ratios": {
"type": "array",
"items": {
"type": "string"
}
},
"scene_id": {
"type": [
"string",
"null"
]
},
"sound_id": {
"type": [
"string",
"null"
],
"description": "The preset's default sonic mark; customize the concrete identity part to override it."
},
"default": {
"type": "boolean"
},
"uses_title": {
"type": "boolean"
}
}
}
},
"outros": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identity library entry public ID."
},
"library_entry_id": {
"type": "string"
},
"preset_id": {
"type": "string"
},
"name": {
"type": "string"
},
"duration_ms": {
"type": [
"integer",
"null"
]
},
"brand_id": {
"type": "string"
},
"aspect_ratios": {
"type": "array",
"items": {
"type": "string"
}
},
"scene_id": {
"type": [
"string",
"null"
]
},
"sound_id": {
"type": [
"string",
"null"
],
"description": "The preset's default sonic mark; customize the concrete identity part to override it."
},
"default": {
"type": "boolean"
},
"uses_title": {
"type": "boolean"
}
}
}
},
"cut_styles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identity library entry public ID."
},
"library_entry_id": {
"type": "string"
},
"style_id": {
"type": "string"
},
"name": {
"type": "string"
},
"brand_id": {
"type": "string"
},
"default": {
"type": "boolean"
},
"uses_title": {
"type": "boolean"
}
}
}
},
"identity_sounds": {
"type": "array",
"description": "One representative curated take per identity-sound concept. Use an id with episode_edit identity_part.customize set.sound_id.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"family": {
"type": [
"string",
"null"
]
},
"notes": {
"type": [
"string",
"null"
]
},
"aliases": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"account_scenes": {
"type": "array",
"description": "Saved account-authored scenes. Use scene_id only through assets.signature_lab.account_scene_id_source for initial replacement or explicit later rebinding of an eligible typed opener/outro.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"scene_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"source_sha256": {
"type": "string"
},
"settings": {
"type": "object"
}
}
}
},
"signature_lab": {
"type": "object",
"description": "Authoritative compact Signature Lab recipe choices and references to the current dynamic asset rows. initial_apply describes episode_edit identity_part.replace for an occurrence whose fresh read reports identity_replace=true and no identity_customization; rebind describes episode_edit identity_part.customize for an occurrence whose read reports identity_customize=true and identity_customization.params.signature_lab. Neither changes Project defaults.",
"properties": {
"schema": {
"type": "string"
},
"layouts": {
"type": "array",
"items": {
"type": "string"
}
},
"curated_scene_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"account_scene_id_source": {
"type": "string"
},
"opener_preset_id_source": {
"type": "string"
},
"outro_preset_id_source": {
"type": "string"
},
"sound_id_source": {
"type": "string"
},
"initial_apply": {
"type": "object"
},
"rebind": {
"type": "object"
}
}
},
"music_beds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Music bed public ID."
},
"library_entry_id": {
"type": "string"
},
"title": {
"type": "string"
},
"duration_seconds": {
"type": [
"number",
"null"
]
},
"track_kind": {
"type": "string"
},
"status": {
"type": "string"
},
"family": {
"type": [
"string",
"null"
],
"maxLength": 80,
"description": "Compact musical family or collection label."
},
"mood": {
"type": [
"string",
"null"
],
"maxLength": 160,
"description": "Compact human-readable mood description."
},
"tags": {
"type": "array",
"maxItems": 8,
"items": {
"type": "string",
"maxLength": 48
},
"description": "Bounded genre/style tags, including account curation."
},
"prompt": {
"type": [
"string",
"null"
],
"maxLength": 240,
"description": "Compact taste/vibe excerpt used to distinguish otherwise similar tracks."
},
"default": {
"type": "boolean"
}
}
}
}
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]Examples
[
{
"label": "List identity assets for a branded reel",
"input": {
"project_id": "show_..."
}
},
{
"label": "Include archived music beds",
"input": {
"project_id": "show_...",
"include_archived": true
}
}
]identity_asset_ingest
Add an image or texture to FX Studio
Ingest an image/logo/texture from HTTPS or base64 into your account's asset library. Omit project_id for account authoring or supply an accessible Project for its account. Add returned asset IDs to a scene's settings.asset_ids to admit those exact bytes to the isolated scene runtime. A scene has no ambient network or account credentials.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID; this is the account boundary for the uploaded asset."
},
"url": {
"type": "string",
"description": "HTTPS image URL to fetch. Pass either url or data_base64, not both."
},
"data_base64": {
"type": "string",
"description": "Base64 image bytes, optionally as a data:image/...;base64 URL. Pass either data_base64 or url, not both."
},
"kind": {
"type": "string",
"enum": [
"logo",
"image"
],
"description": "Use logo for a brand mark/wordmark asset; image for supporting imagery."
},
"name": {
"type": "string",
"description": "Human name for the asset."
}
},
"required": [
"kind",
"name"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"asset": {
"type": "object",
"description": "Account-scoped asset ref with asset_id, kind, content_type, sha256, and authenticated url."
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]Examples
[
{
"label": "Upload a logo for a new brand",
"input": {
"project_id": "show_...",
"url": "https://example.com/logo.png",
"kind": "logo",
"name": "Acme mark"
}
}
]brand_pack_write
Write account Brand Studio pack
Create or update an account-scoped brand pack for an accessible Project: wordmark, organization, palette, fonts, tagline and optional ingested logo. Account IDs are namespaced to avoid collisions with curated packs. Brand is reusable context for programmable scenes, not a fixed visual template. Author a source scene, inspect rendered frames, and iterate before explicitly applying it to a production.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID; this is the account boundary for the brand pack."
},
"brand_id": {
"type": "string",
"description": "Requested brand id. It will be normalized/prefixed to acct-... unless already prefixed."
},
"pack_id": {
"type": "string",
"description": "Alias for brand_id."
},
"name": {
"type": "string"
},
"wordmark": {
"type": "string"
},
"organization": {
"type": "string"
},
"tagline": {
"type": "string"
},
"palette": {
"type": "object",
"description": "Partial palette override, e.g. {background, text, accent, accent2, line}."
},
"fonts": {
"type": "object",
"description": "Partial typography override, e.g. {family, cssFamily, weight, letterSpacing}."
},
"logo_asset_id": {
"type": "string",
"description": "Asset id returned by identity_asset_ingest."
},
"document": {
"type": "object",
"description": "Optional full or partial identity-studio.brand.v0 document. Explicit scalar args win where supplied."
}
},
"required": [
"project_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"brand_pack": {
"type": "object",
"description": "Account-scoped brand pack row with brand_id/pack_id and brand_url."
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]Examples
[
{
"label": "Build a two-tone reveal brand",
"input": {
"project_id": "show_...",
"brand_id": "acme-two-tone",
"wordmark": "Acme",
"organization": "Acme Labs",
"tagline": "proof in motion",
"palette": {
"background": "#101820",
"text": "#f7f2e8",
"accent": "#ff6b4a",
"accent2": "#4fc3f7"
},
"logo_asset_id": "ibrandasset_..."
}
}
]fx_studio_open
Open FX Studio
Open the live FX Studio creative workbench, optionally on a saved scene. The same view updates as you edit its actual HTML/CSS/JavaScript source with scene_read, scene_write or scene_edit and inspect images with scene_preview. Supports DOM, SVG, Canvas and WebGL through one programmable scene contract. Opening is read-only and does not create an effect or change production defaults. Returns a first-party studio link for hosts without app rendering. Keep this view open through successive edits; only this tool opens the app.
Input schema
{
"type": "object",
"properties": {
"scene_id": {
"type": "string",
"description": "Optional account-owned scene identifier. Omit to browse the effect library."
}
},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"account_id": {
"type": "string"
},
"scenes": {
"type": "array",
"items": {
"type": "object"
}
},
"scene": {
"type": [
"object",
"null"
]
},
"studio_url": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"account_not_found",
"invalid_input"
]Examples
[
{
"label": "Open the effect library",
"input": {}
}
]scene_write
Write FX scene source
Create or replace a complete programmable effect, not a fixed-template parameter preset. Supply an ES module exporting scene with id, mount(ctx), reset(ctx), frame(ctx), and optional dispose(ctx). mount appends under ctx.layer and returns refs including root. HTML/CSS, SVG, Canvas and WebGL are supported; ctx.elapsedMs is the authored clock. No ambient application, network or provider authority is available. New scenes use expected_revision:0. Before replacing an existing scene, read it and supply both its revision and sha256; a stale edit refuses without overwriting. Saved source versions are retained. Use scene_preview to inspect actual pixels and iterate; saving source does not apply an opener/outro or change any Episode. Omit project_id for your account library, or supply an accessible Project for its account scope. See bitterclip://docs/identity-scene-authoring for the runtime contract.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Optional Project scope; omitted means your own account."
},
"scene_id": {
"type": "string",
"description": "Stable account scene identifier, lowercase letters/numbers/hyphens."
},
"name": {
"type": "string",
"maxLength": 120
},
"source": {
"type": "string",
"maxLength": 131072,
"description": "Complete ES module source, up to 128 KiB."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "0 for creation; current scene revision for an existing scene."
},
"expected_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Required for changes to existing scenes; sha256 from scene_read."
},
"settings": {
"type": "object",
"additionalProperties": false,
"properties": {
"duration_ms": {
"type": "integer",
"minimum": 100,
"maximum": 60000
},
"fps": {
"type": "integer",
"enum": [
24,
30,
60
]
},
"aspect": {
"type": "string",
"enum": [
"1:1",
"16:9",
"9:16",
"4:5"
]
},
"asset_ids": {
"type": "array",
"maxItems": 16,
"uniqueItems": true,
"items": {
"type": "string"
},
"description": "Explicit account image/texture asset IDs from identity_asset_ingest; the runtime receives only these admitted bytes."
}
}
}
},
"required": [
"scene_id",
"source",
"expected_revision"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"scene": {
"type": "object"
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input",
"revision_conflict"
]Examples
[
{
"label": "Create a minimal scene",
"input": {
"scene_id": "light-study",
"expected_revision": 0,
"source": "export const scene = { id: 'light-study', mount(ctx) { const root = document.createElement('div'); root.textContent = 'Light'; ctx.layer.append(root); return { root }; }, reset() {}, frame(ctx) { ctx.refs.root.style.opacity = String(Math.min(1, ctx.elapsedMs / 1000)); } };"
}
}
]scene_read
Read FX scene source
Read a saved scene's source verbatim, its revision/hash, settings and version history before editing. Omit project_id for your account. Optional revision reads a retained version; restoring means writing that source as a new revision using the current guards. Optional line bounds limit a large read. Edit matching is literal, including whitespace; no regular-expression replacement expansion occurs.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string"
},
"scene_id": {
"type": "string"
},
"revision": {
"type": "integer",
"minimum": 1
},
"start_line": {
"type": "integer",
"minimum": 1
},
"end_line": {
"type": "integer",
"minimum": 1
}
},
"required": [
"scene_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"scene": {
"type": "object"
},
"source": {
"type": "string"
},
"byte_size": {
"type": "integer"
},
"sha256": {
"type": "string"
},
"history": {
"type": "array",
"items": {
"type": "object"
}
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]Examples
[
{
"label": "Read before editing",
"input": {
"scene_id": "light-study"
}
}
]scene_edit
Edit FX scene source
Apply a literal string replacement to the current scene source. Read first and supply expected_revision plus expected_sha256. old_string must match exactly once unless replace_all:true; include enough context to identify the intended code. Replacement bytes are literal, including JavaScript backslashes and dollar signs. Conflicts preserve source and return the current revision for rereading. Successful edits update the same open FX Studio view; inspect scene_preview images and revise again. JavaScript source changes do not mutate production defaults or an admitted Export.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string"
},
"scene_id": {
"type": "string"
},
"expected_revision": {
"type": "integer",
"minimum": 1
},
"expected_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"old_string": {
"type": "string",
"maxLength": 131072
},
"new_string": {
"type": "string",
"maxLength": 131072
},
"replace_all": {
"type": "boolean"
}
},
"required": [
"scene_id",
"old_string",
"new_string",
"expected_revision",
"expected_sha256"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"scene": {
"type": "object"
},
"replacements": {
"type": "integer"
},
"message": {
"type": "string"
},
"before_bytes": {
"type": "integer"
},
"after_bytes": {
"type": "integer"
},
"bytes_delta": {
"type": "integer"
},
"post_edit_context": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input",
"revision_conflict"
]scene_preview
Inspect rendered FX scene frames
Render exact frames of a saved scene in a contained browser and return real MCP PNG images. Inspect the images before judging a change, then iterate with scene_read and scene_edit. The snapshot binds source revision, settings, assets and runtime; it uses the same programmable scene contract as FX Studio. Omit project_id/brand_id for account FX authoring. at_ms selects explicit scene times; burst selects an evenly spaced set. contact_sheet returns one tiled image. This renders preview evidence without changing the scene, production defaults or an Episode.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID; this is the account boundary for the scene and brand."
},
"scene_id": {
"type": "string",
"description": "Account scene id written by scene_write."
},
"recipe": {
"type": "object",
"description": "Optional recipe object; scene_id/scene may be read from it."
},
"brand_id": {
"type": "string",
"description": "Checked-in brand id or account pack id returned by brand_pack_write."
},
"at_ms": {
"type": "array",
"minItems": 1,
"maxItems": 6,
"items": {
"type": "number",
"minimum": 0
},
"description": "Exact scene times in milliseconds, including fractional frame boundaries. Max 6."
},
"burst": {
"type": "object",
"description": "Alternative to at_ms: {count, duration_ms}. Max count 6."
},
"aspect": {
"type": "string",
"enum": [
"16:9",
"9:16",
"1:1",
"4:5"
],
"description": "Preview aspect. Defaults to the saved scene aspect."
},
"contact_sheet": {
"type": "boolean",
"description": "When true, model-visible content returns one tiled PNG contact sheet instead of individual frame image blocks. Per-frame data URLs remain in private app hydration and web-bridge results."
}
},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"frames": {
"type": "array",
"items": {
"type": "object"
},
"description": "Frame metadata with phase, width, height and byte_size. Web-bridge results also include data_url; MCP app hydration receives it privately."
},
"model_image_delivery": {
"type": "string",
"description": "How MCP image content was delivered: frames, sampled_frames, contact_sheet, or none."
},
"model_image_count": {
"type": "integer",
"description": "Number of model-visible image content blocks returned alongside text labels."
},
"content_bytes": {
"type": "integer",
"description": "Approximate bytes of model-visible PNG image content before JSON/base64 overhead."
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]Examples
[
{
"label": "Preview the reveal at start, peak, and hold",
"input": {
"project_id": "show_...",
"scene_id": "acme-two-tone-reveal",
"brand_id": "acct-acme-acme-two-tone",
"at_ms": [
0,
420,
900
],
"aspect": "16:9"
}
}
]identity_apply_to_project
Apply Brand Studio identity to project
Model-visible Signature apply for saving authored or selected Brand Studio defaults. Saves project defaults as account-library refs for NEW highlight reels; future episode_create calls can then trust identity:"project_default" when the user asks for their branding. Use it after an Identity scene preview is intentionally good enough to save the authored scene as the project's default opener or outro. Accepts opener/outro preset strings or structured slot objects, materializes them into the account identity library, imports alternates into the library without storing project alternates, validates enabled packs through the frozen identity resolver, writes an apply receipt, prewarms opener/outro sources through the existing identity moment bake path, and broadcasts the update to open editors. On first apply, callers must pass enabled/enabled_for_reels:true to turn identity on; omitting both flags saves the pack disabled. Set uses_title only for title-enabled openers/outros; static assets should leave it false so opener_title produces the typed ignored warning. Pass cut_style_id:"none" (or a cut_style style_id of "none") for normal cuts with no branded seam layer.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project public ID."
},
"brand_id": {
"type": "string",
"description": "Identity brand id. Defaults to the current project identity or BitterClip."
},
"opener_preset_id": {
"type": [
"string",
"object",
"null"
],
"description": "Source-backed opener preset id or structured opener slot {preset_id, params, gain_db}.",
"properties": {
"preset_id": {
"type": "string"
},
"id": {
"type": "string"
},
"params": {
"type": "object"
},
"gain_db": {
"type": "number"
},
"uses_title": {
"type": "boolean",
"description": "When true, new reels may fill this opener's title slot from episode_create opener_title."
}
}
},
"cut_style_id": {
"type": [
"string",
"null"
],
"description": "Duration-neutral cut style id. Pass none/null for normal cuts with no branded seam layer."
},
"cut_style": {
"type": [
"object",
"null"
],
"description": "Optional duration-neutral cut style payload. Used by Brand Studio controls for intensity/density without changing segment durations. Use style_id:none/null to clear the slot.",
"properties": {
"style_id": {
"type": [
"string",
"null"
]
},
"intensity": {
"type": "string"
},
"density": {
"type": "string"
}
}
},
"outro_preset_id": {
"type": [
"string",
"object",
"null"
],
"description": "Source-backed outro preset id or structured outro slot {preset_id, params, gain_db}.",
"properties": {
"preset_id": {
"type": "string"
},
"id": {
"type": "string"
},
"params": {
"type": "object"
},
"gain_db": {
"type": "number"
},
"uses_title": {
"type": "boolean",
"description": "Reserved for title-capable source-backed slots; default false."
}
}
},
"music_bed": {
"type": "object",
"description": "Music-bed slot. Pass enabled:false for no bed, or library_entry_id for an account-owned bed. Fades and ducking are optional; omitted values keep the current setting or the server defaults (400ms in, 1200ms out, 0dB duck).",
"properties": {
"enabled": {
"type": "boolean"
},
"library_entry_id": {
"type": "string"
},
"span": {
"type": "string",
"enum": [
"content_only",
"content_and_outro"
]
},
"fit": {
"type": "string",
"enum": [
"trim",
"loop"
]
},
"gain_db": {
"type": "number"
},
"duck_db": {
"type": "number"
},
"fade_in_ms": {
"type": "integer",
"description": "Fade-in length in milliseconds."
},
"fade_out_ms": {
"type": "integer",
"description": "Fade-out length in milliseconds."
}
}
},
"alternates": {
"type": "object",
"description": "Additive library entries by role. Supported keys: opener, outro, cut_style/cut_effect, music_bed. Opener/outro/cut_style entries are added to the account library; project defaults remain explicit refs only."
},
"star_alternate": {
"type": "object",
"description": "Promote a saved account-library entry to the project role default without mutating existing compositions. Shape: {role, library_entry_id}, {role, index}, or {role, alternate}.",
"properties": {
"role": {
"type": "string",
"enum": [
"opener",
"outro",
"cut_style",
"cut_effect",
"music_bed"
]
},
"index": {
"type": "integer"
},
"alternate": {
"type": "object"
},
"library_entry_id": {
"type": "string"
}
}
},
"enabled": {
"type": "boolean",
"description": "Whether the identity pack is enabled for future reels. Required to be true on first apply when the caller intends to turn identity on; omitted first apply defaults false."
},
"enabled_for_reels": {
"type": "boolean",
"description": "Alias for enabled, matching Brand Studio UI language. Required to be true on first apply when the caller intends to turn identity on; omitted first apply defaults false."
},
"prewarm": {
"type": "boolean",
"description": "Whether to enqueue opener/outro source-backed prewarm. Defaults true."
}
},
"required": [
"project_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"applied": {
"type": "boolean"
},
"receipt": {
"type": "object"
},
"prewarm": {
"type": "object"
},
"brand_identity": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input",
"identity_music_bed_not_found"
]episode_read
Read an episode
Read an EPISODE (comp_...) as stitched transcript prose with inline navigation hints, visual evidence, segment manifest, speaker legend (per-speaker word share/talk_seconds — "who spoke how much" is answerable here), and duration/revision. The Program map reports each source-backed occurrence's current caption treatment and each Junction's current Cut, Crossfade, or Produced transition treatment. The Camera Program reports exact Episode-local explicit picture decisions—including source-linked synchronized versus continuous picture time—plus access-scoped inherited/automatic intervals the renderer currently selects, so `none` means no local override rather than necessarily base footage. The Picture Program reports bounded exact simultaneous-layout reauthoring segments and Episode-scoped evidence. Follow every Picture-bearing continuation with the returned `expected_revision` and `picture_read_token`; never assemble Picture Program pages from different revisions or media generations. Typed opener/outro occurrences include safe current `identity_customization` state. A parent Episode read also returns bounded derived-Clip titles and exact reopen handles: to find a named existing Clip, read its likely parent once, then workspace_open the exact matching Clip once and last; docs and speaker tools are not Clip-title discovery. For a Project content-evidence ask, use transcript_search first and read its returned windows; unless the user explicitly requests a comprehensive recap, reserve at most one unwindowed Episode for wider context. For editing a chosen Episode, read it whole before judging. Also ACCEPTS a recording handle (src_...) and reads it as that recording's episode-of-one. All timestamps are EPISODE time unless a field ends in _source. Long transcripts are PAGINATED — read pages in sequence via `page`; when an Episode has Picture Scenes or evidence, those transcript continuations must echo both Picture pins too. Transcript words and times are approximate read-only semantic locators; inspect source media with narrow episode_zoom audio evidence or exact episode_sample_frames projection:"original" samples before placing a structural boundary. Program and angle previews never authorize structural boundaries. For a whole-Episode open, call workspace_open. For a read-only named range, open the Episode and report the timestamp without claiming focus. Only when the user explicitly asks to save or mark reviewable Moments, call review_points_place with exact Episode-time ranges and the revision returned here. Merely naming a timestamp in chat is not an open or saved review point. Returns prose only, never word-level rows. Does not modify anything.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "The episode public ID, such as comp_...; a recording src_... handle is also accepted for a recording's episode-of-one."
},
"composition_id": {
"type": "string",
"description": "Backward-compatible alias for episode_id."
},
"window": {
"type": "object",
"description": "Optional EPISODE-time span to read for long episodes. Lines overlapping the window are returned; omit for the whole episode.",
"properties": {
"from": {
"type": "number",
"description": "Window start in episode seconds. Omit for open start."
},
"to": {
"type": "number",
"description": "Window end in episode seconds. Omit for open end."
}
}
},
"page": {
"type": "integer",
"description": "1-indexed page of the transcript prose (default 1). A long transcript is split into M pages so each stays under the host's tool-output size cap; the returned page's header says 'page N of M' and its footer says how to fetch the next. Composes with `window`: `window` picks the time range, `page` paginates that range's prose."
},
"picture_page": {
"type": "integer",
"minimum": 1,
"description": "Independent 1-indexed page of bounded Picture Scene and Picture Evidence summaries. Follow the exact continuation returned in Picture Program prose."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "Required revision pin when following any continuation that carries Picture Program content. A changed Episode refuses instead of assembling mixed-revision pages."
},
"picture_read_token": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Required exact media-generation pin returned by Picture Program page 1 when following a Picture or transcript continuation that carries Picture content."
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"episode_id"
]
},
{
"required": [
"composition_id"
]
}
]
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"stale_picture_read",
"invalid_input"
]Examples
[
{
"label": "See a whole episode before clipping it",
"input": {
"episode_id": "comp_..."
}
}
]episode_zoom
Inspect episode media at a candidate boundary
Inspect chosen cut boundaries: at most 6 windows per call, each <=12 seconds (aim for 5–6), and at most 4 measured edges TOTAL across all windows. Use episode_read for broad transcript discovery. Paired boundary request: `{"episode_id":"comp_...","regions":[{"region":[122.5,128.0],"edges":[124.5]},{"region":[148.5,154.0],"edges":[151.0]}]}`. With detail omitted, nonempty edges selects edit and includes signed receipts for supported exact points; without edges the default stays lean. Explicit detail:"lean" keeps measurements without receipts. Inspect one or more narrow EPISODE-time regions with a compact, budgeted evidence payload: approximate word annotations, occurrence mapping, nearby silence/scene/visual measurements, the resolved Program camera plus alternative coverage, and compact cut measurements for requested edges. Each measured edge also carries `speech`: local forced alignment binding the same decoded PCM to nearby ORIGINAL source words, including words omitted by Program. If a wide disfluent phrase cannot align, the same probe retries a point-focused source window; `speech.scope` and `speech.source_window` disclose which PCM/word scope produced the result. At an existing Junction, `junction_sides` exposes the distinct outgoing and incoming occurrence/source coordinates; inspect both because one Program timestamp does not imply one source boundary. `rejected` + `inside_word` means do not use that point. A successful initial alignment may also return up to two `speech.candidate_points` per unsupported query: exact nearby word or safe-silence endpoints from that same PCM. These alternatives never replace the rejected query or choose the edit; choose explicitly and use a matching returned boundary evidence_id. No candidate means no additional authority. `supported` + `inter_word_silence` names a point inside explicit aligned silence; `supported` + `aligned_word_edge` names the exact acoustically aligned start/end of one word when natural speech has no silence. The latter authorizes the selected phoneme boundary but does not certify that the resulting seam sounds good. `near_word_edge`, `no_supported_boundary`, and `unresolved` remain diagnostic; query the disclosed exact aligned endpoint rather than asking BitterClip to snap a merely nearby point. For one changed Trim edge, use at most one narrow discovery read and one `detail:"edit"` measurement at the chosen point; once that point is supported, pass its exact evidence handle to `episode_edit` without repeating zoom or fetching a raw envelope. For a "next boundary" Trim, do not spend that measurement on the unchanged current occurrence edge: choose the next candidate from the discovery payload and measure that candidate once. Use after episode_read locates candidate boundaries. `speech.points[].relation` vocabulary: inter_word_silence | aligned_word_edge | near_word_edge | inside_word | no_supported_boundary | listen_required (only a human ear can decide; no receipt exists there). Unresolved `speech.reason` values and what to do: probe_busy — the aligner is ONE serialized resource, so issue zoom calls one at a time and simply retry; alignment_failed | alignment_sequence_mismatch | unsupported_transcript_token | out_of_vocabulary — the probe already retried a point-focused (and, where eligible, tail) window before answering, so re-zooming the same edge will not change the verdict: move the edge or treat the point as listen_required; remaining reasons describe invalid or insufficient input. Batch related windows to reduce model turns, but decoding and alignment work scales with the measured source sides. This is not for routine Project recap or post-open exploration. `detail` controls progressive disclosure: lean (semantic discovery), cut (adds raw audio envelopes), edit (adds signed exact boundary receipts), or diagnostic (adds raw detector provenance). Pass every evidence_id or inspection_token back unchanged when a structural Split or partial Range requires it. Transcript words remain approximate semantic locators; a millisecond-scale token tail or overlap is not by itself an edit-worthy defect. Forced alignment and amplitude are independent measurements, not taste or sentence-completeness proof. Require source-linked context plus exact rendered seam evidence for quality; when rendered speech and seam evidence are materially unchanged, preserve the cut rather than polishing timing metadata. Acoustic recommended_at/confidence describe envelope and onset geometry only: even confidence `ok` is not semantic, clause/sentence, or word-boundary proof and can land inside a spoken word. Inspect adjacent timed words, reconcile each source side with `speech.points`, keep every chosen point out of spoken-word interiors, and then listen to the rendered seam. Timestamps are episode time unless a field ends in _source. Measurements only—you judge and place the cut. Read-only. Details: bitterclip://docs/timestamp-rules.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "The episode public ID, such as comp_...; a recording src_... handle is also accepted for a recording's episode-of-one."
},
"composition_id": {
"type": "string",
"description": "Backward-compatible alias for episode_id."
},
"region": {
"type": "array",
"description": "EPISODE-time region [start_seconds, end_seconds] — a SMALL edge window only (target ~5–6s, hard cap 12s; a longer region is rejected). Zoom a tight window around ONE cut point, never the clip body — the full transcript is already in episode_read. Both bounds required; end must exceed start.",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"edges": {
"type": "array",
"description": "Optional candidate cut edges in EPISODE time. Nonempty edges with detail omitted selects edit, including signed receipts for supported exact points. Explicit lean omits receipts. Returns compact next-onset/gap measurements plus local speech alignment: point verdicts, aligned word ranges, and supported gaps. An existing Junction returns outgoing and incoming `junction_sides`; both must be inspected. Recommendation/confidence are amplitude geometry only; `ok` is not semantic or word-boundary proof and can be inside a word, so reconcile it with `speech`. Use detail:cut or include:[\"audio_envelope\"] only when raw 30ms bins are genuinely needed. Each edge must fall within this region. Up to 4.",
"items": {
"type": "number"
},
"maxItems": 4
},
"detail": {
"type": "string",
"enum": [
"lean",
"cut",
"edit",
"diagnostic"
],
"description": "Evidence depth. When omitted, nonempty edges selects edit and no edges selects lean. Explicit lean keeps compact measurements without signed receipts; cut adds raw audio envelopes; edit adds signed boundary receipts; diagnostic adds raw word/visual/detector provenance."
},
"include": {
"type": "array",
"description": "Optional additive evidence channels, combined with the selected or inferred detail. For an occurrence.caption word correction, request word_provenance to get the exact caption word_id and text; compact transcript tuples omit IDs and speech-alignment IDs are different. Request other raw channels only when needed.",
"items": {
"type": "string",
"enum": [
"audio_envelope",
"boundary_tokens",
"detector_provenance",
"visual_detail",
"word_provenance"
]
},
"uniqueItems": true
},
"max_bytes": {
"type": "integer",
"minimum": 4000,
"maximum": 32000,
"description": "Hard serialized UTF-8 JSON byte budget. Default 18000; omitted evidence is counted explicitly instead of overflowing the host."
},
"regions": {
"type": "array",
"description": "ONE-SHOT multi-window zoom: an array of SMALL candidate-boundary windows to inspect in a SINGLE call. Use this INSTEAD of `region` when placing a clip's two edges — a 45s clip = 2 small windows here, not one big region and not two calls. Each window is an edge window only (target ~5–6s, hard cap 12s; a longer window is rejected) — never the clip body. Each item: { region: [start_seconds, end_seconds], edges?: [episode-time points within that window] }. Up to 6 semantic windows and at most 4 measured edges total per call; all measured edges share one admitted local speech-alignment pass. Returns { episode_id, revision, regions: [<one result per window, same shape as a single zoom>] }.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 64,
"description": "Optional caller label echoed on this result window; maximum 64 serialized UTF-8 bytes (ASCII labels satisfy maxLength directly)."
},
"region": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "One EPISODE-time [start_seconds, end_seconds] window: end minus start must be <=12s (aim for 5–6s)."
},
"edges": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 4,
"description": "Candidate EPISODE-time points inside this window. All windows share ONE budget of 4 measured edges: sum every regions[].edges length across the entire call. Two windows with 2 edges each use the whole budget; additional semantic-only windows may omit edges."
}
},
"required": [
"region"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 6
}
},
"required": [],
"additionalProperties": false,
"allOf": [
{
"anyOf": [
{
"required": [
"episode_id"
]
},
{
"required": [
"composition_id"
]
}
]
},
{
"oneOf": [
{
"required": [
"region"
],
"not": {
"required": [
"regions"
]
}
},
{
"required": [
"regions"
],
"not": {
"anyOf": [
{
"required": [
"region"
]
},
{
"required": [
"edges"
]
}
]
}
}
]
}
]
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.episode_zoom.v2"
]
},
"episode_id": {
"type": "string"
},
"revision": {
"type": [
"integer",
"null"
]
},
"detail": {
"type": "string",
"enum": [
"lean",
"cut",
"edit",
"diagnostic"
]
},
"refs": {
"type": "object",
"description": "Request-local occurrence, speaker, and camera dictionaries used by compact rows."
},
"regions": {
"type": "array",
"description": "One result per requested window, in caller order. A single-region request also returns one item here.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 64,
"description": "Optional caller-provided region label (maximum 64 serialized UTF-8 bytes)."
},
"region": {
"type": "array",
"description": "The resolved [start, end] region in episode seconds."
},
"transcript": {
"type": "object",
"description": "Compact word tuples [start, end, text, speaker_ref, occurrence_ref] plus the total raw word count. Approximate annotations only."
},
"total_mappings": {
"type": "integer"
},
"mapping": {
"type": "array",
"description": "Compact object-form episode↔source mapping. Kept object-shaped for exact editor boundary verification."
},
"markers": {
"type": "object",
"description": "Budgeted silence, scene-change, and visual-action rows with total counts."
},
"cameras": {
"type": "object",
"description": "Resolved Program camera intervals and available alternative coverage, using refs.cameras handles."
},
"total_edges": {
"type": "integer"
},
"edges": {
"type": "array",
"description": "Compact edge summaries combining amplitude geometry with local forced speech alignment over original source context. Existing Junctions include outgoing and incoming junction_sides because one Program point maps to two source edges. Acoustic recommendation/confidence do not certify a word, clause, or sentence boundary; speech.points reports supported/rejected/unresolved separately, while nearby_words and safe_intervals bind waveform time to words. Raw amplitude bins appear only when explicitly requested."
},
"boundary_evidence": {
"type": "array",
"description": "Signed exact receipts, present only for edit detail or boundary_tokens include. Prefer the exact evidence_id when editing. Model responses omit the long inspection_token only while its matching token is cached; app/direct and diagnostic responses retain it, as does the cache-unavailable fallback. If using inspection_token, copy it unchanged.",
"items": {
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"evidence_id": {
"type": "string"
},
"base_revision": {
"type": "integer"
},
"program_digest": {
"type": "string"
},
"occurrence_id": {
"type": "string"
},
"source_id": {
"type": "string"
},
"source_media_generation": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.source_media_generation.v1"
]
},
"kind": {
"type": "string",
"enum": [
"active_storage_blob_generation",
"source_object_generation"
]
},
"fingerprint": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"required": [
"schema",
"kind",
"fingerprint"
],
"additionalProperties": false,
"description": "Privacy-safe identity of the exact immutable Recording bytes inspected. Replacing media makes the receipt stale."
},
"source_seconds": {
"type": "string"
},
"episode_seconds": {
"type": "string"
},
"zoom_region": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2
},
"channels": {
"type": "array",
"items": {
"type": "string"
}
},
"basis": {
"type": "string",
"enum": [
"aligned_gap",
"aligned_word_edge",
"sampled_frame"
]
},
"speech_alignment": {
"oneOf": [
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.dialogue_boundary_probe.v1"
]
},
"status": {
"type": "string",
"enum": [
"supported"
]
},
"model": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"model_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"pcm_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"offset_ms": {
"type": "integer"
},
"relation": {
"type": "string",
"enum": [
"inter_word_silence"
]
},
"between": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 2,
"maxItems": 2
},
"safe_source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"silence_source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": [
"schema",
"status",
"relation",
"model",
"version",
"model_digest",
"pcm_sha256",
"safe_source_range",
"silence_source_range"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.dialogue_boundary_probe.v1"
]
},
"status": {
"type": "string",
"enum": [
"supported"
]
},
"model": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"model_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"pcm_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"offset_ms": {
"type": "integer"
},
"relation": {
"type": "string",
"enum": [
"aligned_word_edge"
]
},
"word_edge": {
"type": "string",
"enum": [
"start",
"end"
]
},
"word": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"acoustic_density": {
"type": "number"
}
},
"required": [
"text",
"source_range",
"acoustic_density"
],
"additionalProperties": false
}
},
"required": [
"schema",
"status",
"relation",
"model",
"version",
"model_digest",
"pcm_sha256",
"word_edge",
"word"
],
"additionalProperties": false
}
],
"description": "Signed forced-alignment disclosure. It exists only when the exact cut point lies inside an explicit aligned inter-word silence or at one exact acoustically aligned word edge; near-word, inside-word, and unresolved points never receive a structural receipt."
},
"semantic_boundaries": {
"type": "array",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
},
"description": "Signed transcript anchors for this exact acoustic point. An aligned word edge carries that word and edge; an aligned gap carries left/end and right/start. These anchors narrow media evidence but never replace it."
},
"issued_at": {
"type": "string"
},
"inspection_token": {
"type": "string"
}
},
"required": [
"schema",
"evidence_id",
"base_revision",
"program_digest",
"occurrence_id",
"source_id",
"source_media_generation",
"source_seconds",
"episode_seconds",
"zoom_region",
"channels",
"basis",
"issued_at",
"inspection_token"
],
"additionalProperties": false
}
},
"boundary_evidence_total": {
"type": "integer"
},
"boundary_evidence_status": {
"type": "string",
"enum": [
"present",
"none_found",
"not_requested",
"no_edges_supplied"
],
"description": "Why boundary_evidence is empty, when it is. present means receipts are attached; none_found means the window was inspected and yielded nothing; not_requested means this detail level did not ask for it; no_edges_supplied means the call named no edges to certify."
},
"diagnostics": {
"type": "object",
"description": "Budgeted raw evidence requested through diagnostic detail or explicit include channels."
},
"diagnostics_total": {
"type": "integer"
},
"omitted": {
"type": "object",
"description": "Exact counts of rows omitted by the serialized UTF-8 byte budget."
}
},
"required": [
"region",
"transcript",
"total_mappings",
"mapping",
"markers",
"cameras",
"total_edges",
"edges"
],
"additionalProperties": false
}
},
"partial": {
"type": "boolean",
"description": "True when the budget omitted any rows; each region reports exact omitted counts."
},
"budget": {
"type": "object",
"properties": {
"limit_bytes": {
"type": "integer",
"description": "Applied serialized UTF-8 JSON byte limit."
},
"used_bytes": {
"type": "integer",
"description": "Actual bytes in the complete serialized response, including this budget object."
}
},
"required": [
"limit_bytes",
"used_bytes"
],
"additionalProperties": false
}
},
"required": [
"schema",
"episode_id",
"revision",
"detail",
"refs",
"regions",
"partial",
"budget"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"invalid_input"
]Examples
[
{
"label": "Place a clip's two edges in one call: a small start-window AND end-window (one-shot)",
"input": {
"episode_id": "comp_...",
"regions": [
{
"id": "start",
"region": [
122.5,
128
],
"edges": [
124.5
]
},
{
"id": "end",
"region": [
148.5,
154
],
"edges": [
151
]
}
]
}
},
{
"label": "Request signed exact receipts only when preparing a structural edit",
"input": {
"episode_id": "comp_...",
"region": [
148.5,
154
],
"edges": [
151
],
"detail": "edit"
}
}
]episode_framing_guidance
Read per-person framing evidence for episode occurrences
Read bounded, source-time framing EVIDENCE for up to 12 named source-backed occurrences in an Episode or Clip. Per occurrence: crop_window arithmetic for this canvas (pure math, not a preference) and every person with reviewed face-core geometry in the interval — horizontal extent with an honest observation state, spoke as current-transcript evidence (never a subject choice; "unknown" when the transcript is not current), a position-free fits/too_wide width fact, and a descriptive title_safe_side. It never recommends: no anointed subject, no framing to apply, no ranking. Choosing whom to show — the speaker, a listener's reaction, whatever is visually right — is your editorial judgment; correlate spoke/word_share with extents yourself, compute your own focal point, and apply it through episode_edit occurrence.reframe at this result's revision. people:[] with no_person_evidence means no face-core evidence exists for those seconds, not that nobody is visible. Read-only.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Episode or Clip public ID (comp_...). A recording src_... handle resolves through its episode-of-one, as with episode_read."
},
"composition_id": {
"type": "string",
"description": "Backward-compatible alias for episode_id."
},
"occurrence_ids": {
"type": "array",
"description": "Exact source-backed occurrence IDs from a fresh episode_read. Required; 1–12 IDs keeps this a bounded evidence read. Read the resulting revision again before each occurrence.reframe mutation.",
"items": {
"type": "string",
"pattern": "^occ_"
},
"minItems": 1,
"maxItems": 12,
"uniqueItems": true
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false,
"allOf": [
{
"anyOf": [
{
"required": [
"episode_id"
]
},
{
"required": [
"composition_id"
]
}
]
}
]
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.episode_framing_guidance.v2"
]
},
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer",
"description": "Program revision whose occurrence/source mapping was read. Pass this as expected_revision to the next episode_edit."
},
"program_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Current Program digest for the evidence mapping."
},
"canvas": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"fps": {
"type": "integer"
}
},
"required": [
"key",
"width",
"height",
"fps"
]
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string"
},
"recording_id": {
"type": "string"
},
"source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"state": {
"type": "string",
"enum": [
"evidence",
"unavailable"
]
},
"reason": {
"type": "string",
"enum": [
"occurrence_not_found",
"occurrence_not_source_backed",
"recording_not_video",
"subject_geometry_unavailable"
],
"description": "Only for state:unavailable. subject_geometry_unavailable means no current face-core geometry pass exists for this Recording's bytes."
},
"crop_window": {
"type": "object",
"description": "Pure aspect arithmetic for this canvas, no preference: width_fraction is the crop width as a fraction of source width at the target aspect; full_width means no horizontal crop is needed at all.",
"properties": {
"source_display_aspect": {
"type": "number"
},
"target_aspect": {
"type": "number"
},
"width_fraction": {
"type": "number"
},
"full_width": {
"type": "boolean"
}
},
"required": [
"source_display_aspect",
"target_aspect",
"width_fraction",
"full_width"
]
},
"people": {
"type": "array",
"description": "Every person with face-core geometry evidence in the interval, widest extent first (order is geometry, not precedence). Identity, geometry, and speech are independent evidence: a listener with spoke:false is as servable a frame as the speaker.",
"items": {
"type": "object",
"properties": {
"person": {
"type": "string",
"enum": [
"identified",
"unidentified"
]
},
"speaker_map_id": {
"type": "string",
"description": "Only when the person's speaker track is current for the current transcript; evidence bound to stale tracks stays, unnamed."
},
"display_name": {
"type": "string"
},
"observation": {
"type": "string",
"enum": [
"observed",
"uncertain",
"unknown"
]
},
"extent": {
"type": "object",
"description": "Normalized horizontal envelope where this person's face was observed inside the interval. Present only for observation:observed.",
"properties": {
"x_min": {
"type": "number"
},
"x_max": {
"type": "number"
}
},
"required": [
"x_min",
"x_max"
]
},
"spoke": {
"type": [
"boolean",
"string"
],
"enum": [
true,
false,
"unknown"
],
"description": "Whether current-transcript words by this person overlap the interval. false only against a current transcript; \"unknown\" when no current transcript or the person cannot be currently named."
},
"word_share": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Descriptive share of the interval's words attributed to this person; a weight, never a ranking."
},
"fit": {
"type": "string",
"enum": [
"fits",
"too_wide",
"uncertain",
"unknown"
],
"description": "Position-free width arithmetic: fits means this extent CAN fit a crop of width_fraction, not where to place one."
},
"title_safe_side": {
"type": [
"string",
"null"
],
"enum": [
"left",
"right",
null
],
"description": "Descriptive side-room derivation: which side would hold clear width if a crop were centered on this person. Names room that exists, never a placement to make."
}
},
"required": [
"person",
"observation",
"spoke",
"fit"
]
}
},
"people_truncated": {
"type": "boolean",
"description": "True when more than 6 people had evidence; the widest extents were kept."
},
"no_person_evidence": {
"type": "boolean",
"description": "True when the current geometry pass has no face-core rows for these seconds. Absence of evidence, not evidence of absence."
}
},
"required": [
"occurrence_id",
"state"
]
}
}
},
"required": [
"schema",
"episode_id",
"revision",
"program_digest",
"canvas",
"occurrences"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"invalid_input"
]Examples
[
{
"label": "Read per-person framing evidence before reframing a portrait Clip",
"input": {
"episode_id": "comp_...",
"occurrence_ids": [
"occ_..."
]
}
}
]episode_sample_frames
Sample video frames from an episode
Sample up to 4 explicit episode-time points, or up to 8 deterministic frames inside one <=30s EPISODE region (longer spans: multiple windows) — pixel evidence for visual inspection (form, framing, screens, gestures, reveals). To judge the picture the current edit will show, pass projection:"program", presentation:"canvas"; the default original/source sample shows only the base Recording before canvas framing and may differ from the committed camera. For a treatment self-check, omit times/region/count and pass projection:"program", presentation:"canvas", delivery:"inline". treatment_preview:{type:"speaker_title",speaker_title_id} chooses one fully settled title frame. treatment_preview:{type:"caption_treatment",occurrence_ids:[...]} chooses one calm cue frame or up to three successive timed active-word frames, using the same frozen caption cue model and caption engine policy as Export. Treatment pixels include the Program canvas, the named treatment, and the other committed text layer visible at the sampled instant, so speaker-title/subtitle collisions can be judged directly; other overlays, transition motion, and audio are explicitly omitted. For synchronized multi-camera review, pass camera_refs with 2–3 exact camera handles from episode_read (use original for the base picture): BitterClip samples every camera at every supplied time, up to 8 total cells, and with delivery omitted returns one contact sheet ordered as times in rows and camera_refs in columns. Use that survey first, then request high detail only for a finalist. Split widely separated evidence into separate calls of at most 4 explicit times so each request remains bounded and retryable. presentation:"source" (default) returns the selected source picture before Episode canvas framing. Without treatment_preview, Program canvas pixels are before captions and overlays. Canvas presentation cannot be combined with original, angle, or comparison sampling. Every result publishes public, unguessable frame artifact URLs plus a shareable gallery_url. With delivery omitted, ordinary frames arrive as adjacent JPEG image blocks when their extracted bytes fit the aggregate inline budget; otherwise BitterClip returns linked delivery from the same sampled artifacts. camera_refs returns one bounded comparison sheet. Explicit delivery:"inline" or delivery:"links" overrides automatic choice. Captions and source/Program camera provenance remain inline in either mode. Times are EPISODE time; optional angle_id and camera_refs entries must be handles received from episode_read/episode_zoom — never invent times or pass raw source ids. Only exact projection:"original", presentation:"source" samples may return signed boundary_evidence for a structural edit when audio evidence is unavailable. Program, angle, comparison, and treatment samples are preview evidence only and never authorize Episode structure. Not for transcript understanding (episode_read). BitterClip samples; you interpret. Strategy details: bitterclip://docs/visual-evidence.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Episode public ID, such as comp_.... A recording src_... handle is accepted and resolves to that recording's episode-of-one, same as episode_read."
},
"composition_id": {
"type": "string",
"description": "Backward-compatible alias for episode_id."
},
"times": {
"type": "array",
"description": "Explicit EPISODE-time seconds to sample. Use when you already know the moments to inspect. Exactly one of times or region is allowed. Maximum 4; split widely separated evidence into separate calls.",
"items": {
"type": "number",
"minimum": 0
},
"minItems": 1,
"maxItems": 4
},
"region": {
"type": "array",
"description": "EPISODE-time [start_seconds, end_seconds] region to sample at deterministic interior midpoints. Use for a short visible action. Exactly one of times or region is allowed. Hard cap 30 seconds.",
"items": {
"type": "number",
"minimum": 0
},
"minItems": 2,
"maxItems": 2
},
"count": {
"type": "integer",
"description": "Number of frames to sample from one <=30s region. Default 5, maximum 8. Ignored when times is provided.",
"minimum": 1,
"maximum": 8
},
"detail": {
"type": "string",
"enum": [
"standard",
"high"
],
"description": "Frame detail level. standard is the default and caps the long edge at 768 px; high caps the long edge at 1280 px for body form, small UI text, or fine visual details while still respecting payload caps."
},
"delivery": {
"type": "string",
"enum": [
"inline",
"links"
],
"description": "Optional explicit delivery override. When omitted, extracted JPEGs resolve to inline when their aggregate bytes fit the model-content budget and to links otherwise. inline returns adjacent JPEG image blocks plus URLs; links omits only the JPEG blocks while retaining inline captions, camera provenance, and public gallery/frame URLs."
},
"purpose": {
"type": "string",
"description": "Optional short reason for sampling, such as 'inspect squat form' or 'read the screen'. Echoed in the result for context."
},
"angle_id": {
"type": "string",
"description": "Optional camera-angle handle received from episode_read/episode_zoom. Times remain episode seconds; BitterClip maps them to that angle. Cannot be combined with projection."
},
"camera_refs": {
"type": "array",
"description": "Optional synchronized comparison columns: 2–3 unique camera handles from episode_read, using original for the base picture and ang_... for placed alternates. Requires explicit times, cannot combine with angle_id/projection/canvas, and times × camera_refs may not exceed 8. With delivery omitted the model receives one contact sheet, ordered as times in rows and this array in columns.",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 3,
"uniqueItems": true
},
"projection": {
"type": "string",
"enum": [
"original",
"program"
],
"description": "Which picture to sample when angle_id is omitted. original (default) samples the factual base recording; program samples the resolved committed Episode picture. Cannot be combined with angle_id."
},
"presentation": {
"type": "string",
"enum": [
"source",
"canvas"
],
"description": "How to present the sampled picture. source (default) returns source pixels before Episode canvas framing. canvas is exact Fit/Fill/focal-position proof on the Episode canvas before captions/overlays and requires projection:\"program\"."
},
"treatment_preview": {
"description": "Optional current-state treatment self-check. Omit times/region/count and set projection:\"program\", presentation:\"canvas\", delivery:\"inline\". Receipt provenance is reserved for the automatic post-mutation sample and cannot be supplied by callers.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"speaker_title"
]
},
"speaker_title_id": {
"type": "string"
}
},
"required": [
"type",
"speaker_title_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"caption_treatment"
]
},
"occurrence_ids": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"uniqueItems": true,
"items": {
"type": "string"
}
}
},
"required": [
"type",
"occurrence_ids"
],
"additionalProperties": false
}
]
}
},
"required": [],
"additionalProperties": false,
"allOf": [
{
"anyOf": [
{
"required": [
"episode_id"
]
},
{
"required": [
"composition_id"
]
}
]
},
{
"oneOf": [
{
"oneOf": [
{
"required": [
"times"
]
},
{
"required": [
"region"
]
}
],
"not": {
"required": [
"treatment_preview"
]
}
},
{
"required": [
"treatment_preview"
],
"not": {
"anyOf": [
{
"required": [
"times"
]
},
{
"required": [
"region"
]
},
{
"required": [
"count"
]
}
]
}
}
]
},
{
"not": {
"required": [
"angle_id",
"projection"
]
}
},
{
"not": {
"required": [
"camera_refs",
"angle_id"
]
}
},
{
"not": {
"required": [
"camera_refs",
"projection"
]
}
},
{
"anyOf": [
{
"not": {
"required": [
"camera_refs"
]
}
},
{
"required": [
"camera_refs",
"times"
]
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"presentation"
]
}
},
{
"properties": {
"presentation": {
"enum": [
"source"
]
}
},
"required": [
"presentation"
]
},
{
"properties": {
"presentation": {
"enum": [
"canvas"
]
},
"projection": {
"enum": [
"program"
]
}
},
"required": [
"presentation",
"projection"
]
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"treatment_preview"
]
}
},
{
"properties": {
"projection": {
"enum": [
"program"
]
},
"presentation": {
"enum": [
"canvas"
]
},
"delivery": {
"enum": [
"inline"
]
}
},
"required": [
"projection",
"presentation",
"delivery"
]
}
]
}
]
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Resolved episode public ID."
},
"purpose": {
"type": [
"string",
"null"
],
"description": "Echo of the optional request purpose."
},
"revision": {
"type": "integer",
"description": "Composition revision sampled. Episode seconds are meaningful relative to this revision."
},
"program_digest": {
"type": "string",
"description": "Exact committed Episode picture/structure digest sampled. Re-sample after any later visual mutation, even if a caller still holds old frame URLs."
},
"render_plan_hash": {
"type": [
"string",
"null"
],
"pattern": "^[0-9a-f]{64}$",
"description": "Exact full render-picture fingerprint for presentation:\"canvas\". Pass this value as expected_render_plan_hash to render_create to refuse rendering if camera, framing, canvas, or any other output dependency changed. Null for source presentation."
},
"duration_seconds": {
"type": "number",
"description": "Episode duration at this revision."
},
"detail": {
"type": "string",
"enum": [
"standard",
"high"
],
"description": "Resolved detail level."
},
"delivery": {
"type": "string",
"enum": [
"inline",
"links"
],
"description": "Resolved delivery mode after applying an explicit override or the automatic aggregate-JPEG-byte budget. links omits only JPEG image blocks; captions, camera provenance, and gallery/frame URLs remain present."
},
"projection": {
"type": "string",
"enum": [
"original",
"program",
"angle",
"comparison"
],
"description": "Resolved picture projection sampled by this call. comparison means synchronized camera_refs were sampled into one matrix."
},
"camera_refs": {
"type": [
"array",
"null"
],
"description": "Comparison contact-sheet column order; null for an ordinary single-camera sample.",
"items": {
"type": "string"
}
},
"presentation": {
"type": "string",
"enum": [
"source",
"canvas"
],
"description": "Resolved pixel presentation. canvas means the active Episode picture was framed through the target canvas before captions/overlays."
},
"treatment_preview": {
"type": [
"object",
"null"
],
"description": "Ready selected-treatment identity, settled Episode/render timestamps, exact layer inclusions/omissions, and snapshot binding; null for ordinary frame samples."
},
"model_image_delivery": {
"type": "string",
"enum": [
"frames",
"contact_sheet",
"none"
],
"description": "Shape of model-visible image content for this result."
},
"model_image_count": {
"type": "integer",
"description": "Number of adjacent MCP image blocks: one for a comparison contact sheet, individual frame count for ordinary inline delivery, or zero for links."
},
"canvas": {
"type": [
"object",
"null"
],
"description": "Target Episode canvas for presentation:\"canvas\"; null for source presentation.",
"properties": {
"key": {
"type": "string",
"description": "Persisted canvas key, for example 1080x1920@30."
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"fps": {
"type": "integer"
}
},
"required": [
"key",
"width",
"height",
"fps"
]
},
"angle_id": {
"type": [
"string",
"null"
],
"description": "Present only when sampling a camera angle."
},
"angle_label": {
"type": [
"string",
"null"
],
"description": "Human camera clip label when angle_id was used."
},
"content_bytes": {
"type": "integer",
"description": "Approximate total bytes of returned inline image content before JSON/base64 transport overhead; 0 when delivery is links."
},
"sampled_pixel_change": {
"type": "object",
"description": "Bounded mean-absolute channel difference between consecutive successful sampled stills in chronological Episode time on the same camera, compared on a 64×64 sRGB 3-band raster. Returned artifact dimensions stay native. This is a measurement at sampled instants only: it does not observe anything between samples and is not a motion, duration, payoff, quality, or taste claim. Camera comparison is unavailable rather than cross-camera compared. Decode failure is typed unavailable without fabricating a zero.",
"properties": {
"status": {
"type": "string",
"enum": [
"measured",
"insufficient",
"unavailable"
]
},
"reason": {
"type": [
"string",
"null"
],
"description": "Typed reason when status is insufficient or unavailable."
},
"metric": {
"type": [
"string",
"null"
],
"description": "mean_absolute_channel_difference when a pair could be scored."
},
"overall_level": {
"type": [
"string",
"null"
],
"enum": [
"none",
"near_zero",
"low",
"moderate",
"high",
null
],
"description": "Coarse class of the largest measured adjacent pair; null when unmeasured."
},
"overall_normalized_difference": {
"type": [
"number",
"null"
],
"description": "Largest adjacent-pair difference in [0, 1] when measured."
},
"summary": {
"type": "string",
"description": "Literal measurement sentence. Does not claim events between samples."
},
"pairs": {
"type": "array",
"description": "Chronological adjacent pairs on one camera. Request order is not used.",
"items": {
"type": "object",
"properties": {
"from_seconds": {
"type": "number"
},
"to_seconds": {
"type": "number"
},
"time_axis": {
"type": "string",
"enum": [
"episode",
"source"
]
},
"from_camera_ref": {
"type": "string"
},
"to_camera_ref": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"measured",
"unavailable"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"normalized_difference": {
"type": [
"number",
"null"
]
},
"level": {
"type": [
"string",
"null"
],
"enum": [
"none",
"near_zero",
"low",
"moderate",
"high",
null
]
}
},
"required": [
"from_seconds",
"to_seconds",
"status"
]
}
}
},
"required": [
"status",
"summary",
"pairs"
]
},
"mode": {
"type": "string",
"enum": [
"times",
"region"
],
"description": "Sampling mode used by the server."
},
"region": {
"type": [
"array",
"null"
],
"description": "Resolved [start, end] episode-time region when region mode was used.",
"items": {
"type": "number"
}
},
"sample_id": {
"type": "string",
"description": "Unguessable public frame-sample artifact ID for this sampling call."
},
"gallery_url": {
"type": "string",
"description": "Public gallery page showing the sampled frames with timestamp labels. Use this when the chat host will not inline markdown images."
},
"sample_expires_at": {
"type": [
"string",
"null"
],
"description": "Best-effort local artifact retention hint. CDN-backed image URLs are not signed grant URLs."
},
"manifest_url": {
"type": [
"string",
"null"
],
"description": "Public CDN manifest URL when durable object publishing is configured; null for local route fallback."
},
"frame_artifact_delivery": {
"type": "string",
"enum": [
"cdn",
"public_route"
],
"description": "cdn when all frame assets were published to the configured CDN; public_route when local/dev returned app-hosted public asset routes."
},
"boundary_evidence": {
"type": "array",
"description": "Signed exact-point media-inspection receipts. Present only for successfully sampled projection:\"original\" frames; never returned for projection:\"program\" or angle_id.",
"items": {
"type": "object",
"properties": {
"schema": {
"type": "string"
},
"evidence_id": {
"type": "string"
},
"base_revision": {
"type": "integer"
},
"program_digest": {
"type": "string"
},
"occurrence_id": {
"type": "string"
},
"source_id": {
"type": "string"
},
"source_media_generation": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.source_media_generation.v1"
]
},
"kind": {
"type": "string",
"enum": [
"active_storage_blob_generation",
"source_object_generation"
]
},
"fingerprint": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"required": [
"schema",
"kind",
"fingerprint"
],
"additionalProperties": false,
"description": "Privacy-safe identity of the exact immutable Recording bytes inspected. Replacing media makes the receipt stale."
},
"source_seconds": {
"type": "string"
},
"episode_seconds": {
"type": "string"
},
"zoom_region": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2
},
"channels": {
"type": "array",
"items": {
"type": "string"
}
},
"basis": {
"type": "string",
"enum": [
"aligned_gap",
"aligned_word_edge",
"sampled_frame"
]
},
"speech_alignment": {
"oneOf": [
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.dialogue_boundary_probe.v1"
]
},
"status": {
"type": "string",
"enum": [
"supported"
]
},
"model": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"model_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"pcm_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"offset_ms": {
"type": "integer"
},
"relation": {
"type": "string",
"enum": [
"inter_word_silence"
]
},
"between": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 2,
"maxItems": 2
},
"safe_source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"silence_source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": [
"schema",
"status",
"relation",
"model",
"version",
"model_digest",
"pcm_sha256",
"safe_source_range",
"silence_source_range"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.dialogue_boundary_probe.v1"
]
},
"status": {
"type": "string",
"enum": [
"supported"
]
},
"model": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"model_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"pcm_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"offset_ms": {
"type": "integer"
},
"relation": {
"type": "string",
"enum": [
"aligned_word_edge"
]
},
"word_edge": {
"type": "string",
"enum": [
"start",
"end"
]
},
"word": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"source_range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"acoustic_density": {
"type": "number"
}
},
"required": [
"text",
"source_range",
"acoustic_density"
],
"additionalProperties": false
}
},
"required": [
"schema",
"status",
"relation",
"model",
"version",
"model_digest",
"pcm_sha256",
"word_edge",
"word"
],
"additionalProperties": false
}
],
"description": "Signed forced-alignment disclosure. It exists only when the exact cut point lies inside an explicit aligned inter-word silence or at one exact acoustically aligned word edge; near-word, inside-word, and unresolved points never receive a structural receipt."
},
"semantic_boundaries": {
"type": "array",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
},
"description": "Signed transcript anchors for this exact acoustic point. An aligned word edge carries that word and edge; an aligned gap carries left/end and right/start. These anchors narrow media evidence but never replace it."
},
"issued_at": {
"type": "string"
},
"inspection_token": {
"type": "string"
}
},
"required": [
"schema",
"evidence_id",
"base_revision",
"program_digest",
"occurrence_id",
"source_id",
"source_media_generation",
"source_seconds",
"episode_seconds",
"zoom_region",
"channels",
"basis",
"issued_at",
"inspection_token"
],
"additionalProperties": false
}
},
"frames": {
"type": "array",
"description": "Sampled frames with exact episode/source/Program-camera provenance and public image URLs. Adjacent MCP image blocks are present only when resolved delivery is inline.",
"items": {
"type": "object",
"properties": {
"frame_id": {
"type": "string",
"description": "Deterministic cache-key ID for this sampled frame artifact, not a persisted database row."
},
"sample_id": {
"type": "string",
"description": "Public sample set this frame belongs to."
},
"file_name": {
"type": "string",
"description": "Stable boring JPEG filename inside the sample set, e.g. frame-004.jpg."
},
"thumbnail_file_name": {
"type": "string"
},
"download_file_name": {
"type": "string",
"description": "Stable source-quality JPEG filename inside the sample set, e.g. frame-004-download.jpg."
},
"caption": {
"type": "string",
"description": "Short model-visible caption emitted adjacent to this frame image block."
},
"episode_seconds": {
"type": "number",
"description": "Frame timestamp on the stitched episode axis."
},
"source_seconds": {
"type": "number",
"description": "Frame timestamp in the underlying source recording."
},
"episode_timecode": {
"type": "string"
},
"source_timecode": {
"type": "string"
},
"angle_id": {
"type": [
"string",
"null"
],
"description": "Present only when this frame was sampled from a camera angle."
},
"angle_label": {
"type": [
"string",
"null"
]
},
"projection": {
"type": "string",
"enum": [
"original",
"program",
"angle"
]
},
"presentation": {
"type": "string",
"enum": [
"source",
"canvas"
]
},
"canvas": {
"type": [
"object",
"null"
],
"description": "Full target canvas identity and dimensions for a canvas-presented frame.",
"properties": {
"key": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
},
"required": [
"key",
"width",
"height"
]
},
"framing": {
"type": [
"object",
"null"
],
"description": "Persisted occurrence framing applied to this canvas-presented frame.",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.picture_framing.v1"
]
},
"mode": {
"type": "string",
"enum": [
"fill",
"fit"
]
},
"canvas_fit": {
"type": "string",
"enum": [
"fill",
"4:5",
"1:1"
],
"description": "Persisted fit-at-ratio state of this frame: fill is the full-bleed crop; 4:5/1:1 letterbox the Fill crop at that ratio with black mattes."
},
"canvas_alignment": {
"type": "string",
"enum": [
"center",
"top",
"bottom"
],
"description": "Static placement of a fit-at-ratio picture. Center preserves symmetric mattes; top can reserve one lower subtitle band."
},
"crop_strategy": {
"type": "string",
"enum": [
"center_crop",
"fit_pad"
]
},
"focal_point": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y"
]
}
},
"required": [
"schema",
"mode",
"crop_strategy",
"focal_point"
]
},
"sampled_camera_ref": {
"type": "string",
"description": "original or the stable ang_ handle actually sampled."
},
"sampled_camera_label": {
"type": [
"string",
"null"
]
},
"program_context_status": {
"type": "string",
"enum": [
"resolved",
"unavailable"
],
"description": "Whether committed Program camera context resolved at this episode time. Original and explicit-angle evidence remain usable when this is unavailable; Program projection fails closed instead."
},
"program_camera_ref": {
"type": [
"string",
"null"
],
"description": "original or the stable ang_ handle resolved by the committed Program at this episode time; null only when program_context_status is unavailable."
},
"program_camera_label": {
"type": [
"string",
"null"
]
},
"program_basis": {
"type": [
"string",
"null"
],
"enum": [
"explicit",
"automatic",
"base",
null
]
},
"program_recording_id": {
"type": [
"string",
"null"
],
"description": "Recording handle used by the committed Program at this episode time; null when Program context is unavailable."
},
"program_source_id": {
"type": [
"string",
"null"
],
"description": "Alias of program_recording_id for source provenance."
},
"program_source_seconds": {
"type": [
"number",
"null"
],
"description": "Source time in the Program's resolved recording at this episode point; null when Program context is unavailable."
},
"recording_id": {
"type": "string",
"description": "Underlying Recording public ID."
},
"source_id": {
"type": "string",
"description": "Alias of recording_id for source-time provenance."
},
"source_title": {
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer"
},
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence sampled at this exact point."
},
"segment_index": {
"type": "integer"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"mime_type": {
"type": "string"
},
"image_sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "SHA-256 of the exact model-visible JPEG bytes for this frame."
},
"treatment_point_id": {
"type": [
"string",
"null"
],
"description": "Stable representative-point identity for a caption treatment preview."
},
"treatment_occurrence_id": {
"type": [
"string",
"null"
],
"description": "Selected occurrence represented by this caption treatment point."
},
"image_url": {
"type": "string",
"description": "Public direct JPEG URL. In production this is the clean CDN URL when durable object publishing is configured; in local/dev it is an unguessable public app route."
},
"thumbnail_url": {
"type": "string",
"description": "Public JPEG thumbnail URL for gallery/list display."
},
"download_url": {
"type": "string",
"description": "Public source-quality JPEG URL for user-facing download/share. This is not embedded into MCP image content and is not constrained by the chat payload budget."
},
"open_url": {
"type": "string",
"description": "Public gallery URL anchored to this frame."
},
"image_url_kind": {
"type": "string",
"enum": [
"cdn",
"public_route"
]
},
"thumbnail_url_kind": {
"type": "string",
"enum": [
"cdn",
"public_route"
]
},
"download_url_kind": {
"type": "string",
"enum": [
"cdn",
"public_route"
]
},
"image_url_expires_at": {
"type": [
"string",
"null"
],
"description": "Null for CDN-backed durable URLs; set for local route fallback retention."
},
"download_url_expires_at": {
"type": [
"string",
"null"
],
"description": "Null for CDN-backed durable URLs; set for local route fallback retention."
},
"download_width": {
"type": "integer",
"description": "Pixel width of download_url rendition; source-native when available."
},
"download_height": {
"type": "integer",
"description": "Pixel height of download_url rendition; source-native when available."
},
"download_bytes": {
"type": "integer",
"description": "Byte size of the source-quality download rendition."
},
"download_mime_type": {
"type": "string"
},
"download_quality": {
"type": "string",
"enum": [
"source_native",
"canvas_native",
"display_fallback"
],
"description": "source_native is a full source extraction; canvas_native is a full target-canvas presentation; display_fallback reuses the bounded display rendition."
}
},
"required": [
"frame_id",
"sample_id",
"file_name",
"caption",
"episode_seconds",
"source_seconds",
"recording_id",
"source_id",
"revision",
"occurrence_id",
"segment_index",
"projection",
"presentation",
"sampled_camera_ref",
"program_context_status",
"program_camera_ref",
"program_basis",
"program_recording_id",
"program_source_id",
"program_source_seconds",
"width",
"height",
"mime_type",
"image_sha256",
"image_url",
"thumbnail_url",
"download_url",
"open_url"
]
}
},
"errors": {
"type": "array",
"description": "Always present. Per-request or per-timestamp sampling errors when partial success is possible.",
"items": {
"type": "object",
"properties": {
"episode_seconds": {
"type": [
"number",
"null"
]
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error_code",
"message"
]
}
}
},
"required": [
"episode_id",
"sample_id",
"gallery_url",
"mode",
"projection",
"presentation",
"revision",
"program_digest",
"render_plan_hash",
"duration_seconds",
"detail",
"frames",
"errors",
"sampled_pixel_change"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"invalid_input",
"invalid_time_range",
"time_out_of_range",
"comparison_incomplete",
"source_media_unavailable",
"program_projection_unavailable",
"ffmpeg_busy",
"ffmpeg_missing",
"ffmpeg_timeout",
"frame_extraction_failed",
"frame_artifact_publish_failed",
"payload_budget_exceeded"
]Examples
[
{
"label": "Survey a visual action through automatically linked frames",
"input": {
"episode_id": "comp_...",
"region": [
1398,
1428
],
"count": 5,
"purpose": "locate the squat rep"
}
},
{
"label": "Token-efficient raw-frame proof for CLI/no-vision hosts",
"input": {
"episode_id": "comp_...",
"region": [
1398,
1428
],
"count": 3,
"delivery": "links",
"purpose": "confirm frame layer and share gallery"
}
},
{
"label": "Inspect form over one rep",
"input": {
"episode_id": "comp_...",
"region": [
1404,
1408
],
"count": 5,
"detail": "high",
"delivery": "inline",
"purpose": "inspect squat form"
}
}
]recording_sample_frames
Sample video frames from a recording
Inspect raw Recording pixels directly on the recording's SOURCE-time axis, including capture-session footage that intentionally has no Episode-of-one. Sample up to 4 explicit source-time points or up to 8 deterministic frames inside one <=30s region. This operation never creates or mutates an Episode, Program, or Recording. Use it to choose exact recording_id ranges before one multi-source episode_create; never create a throwaway Episode as a visual probe. Results contain source-time and recording identity only—no fabricated Episode revision, Program camera, or occurrence fields. Every call publishes bounded, unguessable frame URLs and a gallery. Omit delivery to inline extracted JPEGs that fit the aggregate model-content budget and use linked delivery from the same artifacts otherwise. BitterClip samples; you interpret.
Input schema
{
"type": "object",
"properties": {
"recording_id": {
"type": "string",
"description": "Exact src_... Recording handle returned by recordings_list or Project evidence."
},
"times": {
"type": "array",
"description": "Explicit Recording SOURCE-time seconds. Exactly one of times or region is allowed. Maximum 4.",
"items": {
"type": "number",
"minimum": 0
},
"minItems": 1,
"maxItems": 4
},
"region": {
"type": "array",
"description": "Recording SOURCE-time [start_seconds, end_seconds] region sampled at deterministic interior midpoints. Exactly one of times or region is allowed. Hard cap 30 seconds.",
"items": {
"type": "number",
"minimum": 0
},
"minItems": 2,
"maxItems": 2
},
"count": {
"type": "integer",
"description": "Frames from one <=30s region. Default 5, maximum 8.",
"minimum": 1,
"maximum": 8
},
"detail": {
"type": "string",
"enum": [
"standard",
"high"
],
"description": "standard is the default; high is for fine visual evidence."
},
"delivery": {
"type": "string",
"enum": [
"inline",
"links"
],
"description": "Optional explicit delivery override. When omitted, extracted JPEGs resolve to inline when their aggregate bytes fit the model-content budget and to links otherwise. inline returns adjacent JPEG image blocks plus URLs; links omits only the JPEG blocks while retaining inline captions, camera provenance, and public gallery/frame URLs."
},
"purpose": {
"type": "string",
"description": "Optional short reason for sampling, echoed in the result."
}
},
"required": [
"recording_id"
],
"additionalProperties": false,
"allOf": [
{
"oneOf": [
{
"required": [
"times"
]
},
{
"required": [
"region"
]
}
]
}
]
}Output schema
{
"type": "object",
"properties": {
"subject_type": {
"type": "string",
"enum": [
"recording"
]
},
"recording_id": {
"type": "string",
"description": "Authorized Recording sampled."
},
"purpose": {
"type": [
"string",
"null"
]
},
"duration_seconds": {
"type": "number",
"description": "Recording source duration used for this sample."
},
"detail": {
"type": "string",
"enum": [
"standard",
"high"
]
},
"delivery": {
"type": "string",
"enum": [
"inline",
"links"
]
},
"projection": {
"type": "string",
"enum": [
"original"
]
},
"presentation": {
"type": "string",
"enum": [
"source"
]
},
"content_bytes": {
"type": "integer"
},
"sampled_pixel_change": {
"type": "object",
"description": "Bounded mean-absolute channel difference between consecutive successful sampled stills in chronological Recording SOURCE time, compared on a 64×64 sRGB 3-band raster. Returned artifact dimensions stay native. This is a measurement at sampled instants only: it does not observe anything between samples and is not a motion, duration, payoff, quality, or taste claim. Decode failure is typed unavailable without fabricating a zero.",
"properties": {
"status": {
"type": "string",
"enum": [
"measured",
"insufficient",
"unavailable"
]
},
"reason": {
"type": [
"string",
"null"
],
"description": "Typed reason when status is insufficient or unavailable."
},
"metric": {
"type": [
"string",
"null"
],
"description": "mean_absolute_channel_difference when a pair could be scored."
},
"overall_level": {
"type": [
"string",
"null"
],
"enum": [
"none",
"near_zero",
"low",
"moderate",
"high",
null
],
"description": "Coarse class of the largest measured adjacent pair; null when unmeasured."
},
"overall_normalized_difference": {
"type": [
"number",
"null"
],
"description": "Largest adjacent-pair difference in [0, 1] when measured."
},
"summary": {
"type": "string",
"description": "Literal measurement sentence. Does not claim events between samples."
},
"pairs": {
"type": "array",
"description": "Chronological adjacent pairs on Recording SOURCE time. Request order is not used.",
"items": {
"type": "object",
"properties": {
"from_seconds": {
"type": "number"
},
"to_seconds": {
"type": "number"
},
"time_axis": {
"type": "string",
"enum": [
"episode",
"source"
]
},
"from_camera_ref": {
"type": "string"
},
"to_camera_ref": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"measured",
"unavailable"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"normalized_difference": {
"type": [
"number",
"null"
]
},
"level": {
"type": [
"string",
"null"
],
"enum": [
"none",
"near_zero",
"low",
"moderate",
"high",
null
]
}
},
"required": [
"from_seconds",
"to_seconds",
"status"
]
}
}
},
"required": [
"status",
"summary",
"pairs"
]
},
"mode": {
"type": "string",
"enum": [
"times",
"region"
]
},
"region": {
"type": [
"array",
"null"
],
"items": {
"type": "number"
},
"description": "Resolved source-time region in region mode."
},
"sample_id": {
"type": "string"
},
"gallery_url": {
"type": "string"
},
"sample_expires_at": {
"type": [
"string",
"null"
]
},
"manifest_url": {
"type": [
"string",
"null"
]
},
"frame_artifact_delivery": {
"type": "string",
"enum": [
"cdn",
"public_route"
]
},
"handle_policy": {
"type": "string",
"description": "Reminder that raw Recording handles are tool-call-only and should not be shown to users."
},
"frames": {
"type": "array",
"description": "Recording frames with source-time provenance and public image handles.",
"items": {
"type": "object",
"properties": {
"frame_id": {
"type": "string"
},
"sample_id": {
"type": "string"
},
"caption": {
"type": "string"
},
"source_seconds": {
"type": "number"
},
"source_timecode": {
"type": "string"
},
"recording_id": {
"type": "string"
},
"source_id": {
"type": "string"
},
"source_title": {
"type": [
"string",
"null"
]
},
"projection": {
"type": "string",
"enum": [
"original"
]
},
"presentation": {
"type": "string",
"enum": [
"source"
]
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"mime_type": {
"type": "string"
},
"image_url": {
"type": "string"
},
"thumbnail_url": {
"type": "string"
},
"download_url": {
"type": "string"
},
"open_url": {
"type": "string"
}
},
"required": [
"frame_id",
"sample_id",
"caption",
"source_seconds",
"source_timecode",
"recording_id",
"source_id",
"projection",
"presentation",
"width",
"height",
"mime_type",
"image_url",
"thumbnail_url",
"download_url",
"open_url"
]
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source_seconds": {
"type": [
"number",
"null"
]
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error_code",
"message"
]
}
}
},
"required": [
"subject_type",
"recording_id",
"sample_id",
"gallery_url",
"mode",
"projection",
"presentation",
"duration_seconds",
"detail",
"frames",
"errors",
"sampled_pixel_change"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"recording_not_found",
"stale_recording",
"invalid_input",
"invalid_time_range",
"time_out_of_range",
"source_media_unavailable",
"ffmpeg_busy",
"ffmpeg_missing",
"ffmpeg_timeout",
"frame_extraction_failed",
"frame_artifact_publish_failed",
"payload_budget_exceeded"
]Examples
[
{
"label": "Inspect one movement on raw footage",
"input": {
"recording_id": "src_...",
"region": [
1404,
1412
],
"count": 4,
"purpose": "choose the clearest squat repetitions"
}
}
]episodes_list
List episodes
List or find top-level EPISODES — the unit of work; the front door for browse, latest/open, project recaps or coaching prep. `query` matches episode, project, recording, or speaker names across fields ("mike john" finds the Mike & John Show; "me" usually means the studio owner). Rows carry `match_reason`, a dense indexed description, and `episode_shape`/`latest_open_hint` separating ready full-length episodes from short drafts — for "latest episode" asks prefer a ready full-length row and pass `order:"latest"`. Chronological project recaps: keep the default chronological order and read each episode before synthesizing. Returns row-carrying prose only, with each exact `episode_id` in brackets for the next tool call. For a relevant/latest Episode ask: episodes_list(query), shortlist 2–4; for Project content evidence, use transcript_search first, then returned-window episode_read. For a whole Episode, call workspace_open once and last. For a named read-only moment, first read the Episode, then call workspace_open once and last with focus_range and that exact expected_revision; this focuses transiently without saving. An explicit request to save or mark a range uses review_points_place instead. For an explicitly comprehensive recap, read the requested scope. Use episode_zoom only for a candidate edit/review boundary or measurable acoustic/scene seam, never physical-progress proof or post-open exploration. Raw recordings are a drawer (recordings_list); excludes render outputs and derived clips. Read-only.
Input schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Optional project public ID — scope the list to a single project's episodes."
},
"query": {
"type": "string",
"description": "Optional case-insensitive filter across episode title, project title, segment recording/source titles, and speaker names. Use this before reading a named episode."
},
"order": {
"type": "string",
"description": "Optional order: `latest` for newest-first latest/last/refresher tasks, or `chronological` for oldest-to-newest project recaps. Project-scoped default is chronological; account-wide default is latest."
},
"limit": {
"type": "integer",
"description": "Optional maximum number of recent episodes to return. For 'last few', pass 3 unless the user names another count."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"project_not_found",
"invalid_input"
]Examples
[
{
"label": "Find a named episode",
"input": {
"query": "Visual Analysis Prototype and Coaching Workflows"
}
},
{
"label": "List recent episodes",
"input": {}
},
{
"label": "List a project's episodes",
"input": {
"project_id": "proj_..."
}
},
{
"label": "Find latest session in a project",
"input": {
"project_id": "proj_...",
"order": "latest",
"limit": 3
}
}
]episode_create
Create an episode or derived reel
Assemble a new EPISODE or derived reel from ordered recording/episode/template ranges into ONE combined video. For a reel cut from an Episode, pass derived_from_id for lineage and one segment row per chosen moment in the canonical shape {episode_id, range:[start_seconds,end_seconds]}; segments[].range is a half-open [start,end) interval in EPISODE time. derived_from_id does not select a range. Creation selects Program ranges; compose simultaneous participant boxes afterwards with camera_program_set, never extra segment fields. Use when the user asks to make/cut together/export a multi-segment highlight, reel, montage, or supercut — NOT for suggestions (use review_points_place for those) and NOT for a single-range Clip (use clip_create). Choose the opening and key visual beats from actual source-linked images before measuring all cut boundaries. Before keeping any materially long candidate in a reel intended for strangers, inspect representative source-linked pixels across the candidate's beginning, middle, and end for visual progression/payoff; shorten or omit a span when those samples add no new visual information. A static or screen-share span is not automatically no-payoff; keep an intentional, legible demonstration or reveal when its duration is needed to understand the payoff. Branding: pass identity:"project_default" when the project has saved Signature defaults and the user asks for their branding; browse identity_assets_list only when defaults are absent/unclear or a specific asset is named (full rules: bitterclip://docs/identity-signature). Persists the edit only — does not render or charge. For ordinary multi-segment make/cut/create highlight, reel, or shareable-video intent, continue with render_create and render_status until ready using the exact returned target_type, target_id, and revision unless the user asks for draft-only, review-first, or no-render; publishing stays explicit. Always returns edge_warnings. A warning means a cut edge overlaps an approximate transcript word span, not that acoustic evidence proved a mid-word cut: keep the same created target and inspect each supplied episode_seconds directly with narrow episode_zoom regions and edges before rendering; occurrence_id and source_id identify the exact side. Read the target to map an edge only when these coordinates are absent. Preserve the point when speech evidence is supported inter_word_silence or supported aligned_word_edge; otherwise revise that same target with episode_edit using an exact supported point. Acoustic envelope/onset suggestions alone are not boundary authority. Do not call episode_create again or create/supersede another Clip merely to resolve edge_warnings (bitterclip://docs/errors). Accepts idempotency_key. A creation with derived_from_id produces a Clip (a derived Episode IS a Clip): pass target_type:"clip" to render_create/render_status/workspace_open for it. A canvas taller than the source picture (a portrait canvas over landscape footage) keeps only a vertical slice of each frame; episode_framing_guidance reports, per visible person, whether their measured extent fits that crop window (fits | too_wide | uncertain | unknown), and episode_edit occurrence.reframe carries the framing decision.
Input schema
{
"type": "object",
"properties": {
"segments": {
"type": "array",
"description": "Ordered episode/recording/template segments. The only model-visible boundary field is range: use {episode_id, range:[start,end]} in EPISODE time or {recording_id, range:[start,end]} in SOURCE time. Both are half-open [start,end) intervals. Do not send episode_range or start_seconds/end_seconds. Template rows use {template, params} and have no range.",
"minItems": 1,
"items": {
"type": "object",
"oneOf": [
{
"required": [
"episode_id",
"range"
]
},
{
"required": [
"recording_id",
"range"
]
},
{
"required": [
"template"
],
"not": {
"required": [
"range"
]
}
}
],
"properties": {
"episode_id": {
"type": "string",
"description": "Source Episode public ID. This row must also provide range in half-open EPISODE time."
},
"recording_id": {
"type": "string",
"description": "Source Recording public ID. This row must also provide range in half-open SOURCE time."
},
"template": {
"type": "string",
"description": "Curated block template key, such as show_open/studio_dissolve or outro/sting_chime."
},
"params": {
"type": "object",
"description": "Template parameters.",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"accent": {
"type": "string",
"description": "Hex color, for example #f28f84."
},
"sting": {
"type": "string",
"enum": [
"none",
"chime",
"bass",
"glitch",
"shutter"
]
}
}
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "Required for episode_id and recording_id rows. The field is named range and contains the half-open interval [start_seconds, end_seconds): EPISODE time for episode_id, SOURCE time for recording_id."
},
"crop_strategy": {
"type": "string",
"enum": [
"center_crop",
"fit_pad"
]
},
"audio_policy": {
"type": "string",
"enum": [
"source",
"mute"
]
},
"caption_mode": {
"type": "string",
"enum": [
"inherit",
"off",
"on"
]
},
"boundary_rationale": {
"type": "object",
"description": "Optional audit notes for selected boundaries.",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
}
},
"zoom_regions": {
"type": "array",
"description": "Optional audit list of consulted source/episode windows.",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
},
"required": [],
"additionalProperties": false
}
},
"title": {
"type": "string",
"description": "Title for the new episode."
},
"description": {
"type": "string",
"description": "Optional episode description."
},
"derived_from_id": {
"type": "string",
"description": "Optional parent Episode public ID used only for lineage/filing. It does not select media or replace segments[].range. Set it when a multi-segment reel is cut from one existing Episode and should be filed under that parent rather than listed as a primary project Episode."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "OMIT THIS unless the user asked for a specific shape or named a vertical destination (Reels/Shorts/TikTok). Left alone it follows the footage — the source recording's native aspect, nearest of 9:16/16:9/1:1, and 16:9 when unprobed — which is almost always what you want. \"Reel\" describes the edit, NOT the shape: setting 9:16 on landscape footage crops the sides away and can cut a second person out of frame."
},
"transition": {
"type": "string",
"enum": [
"cut",
"dip_to_black",
"overlap_dissolve"
],
"description": "Optional seam transition for segment boundaries. Defaults to cut."
},
"identity": {
"oneOf": [
{
"type": "string",
"enum": [
"project_default",
"none"
]
},
{
"type": "object",
"properties": {
"opener": {
"type": "string",
"description": "Explicit opener library_entry_id returned by identity_assets_list, or none. Use only when choosing a specific saved asset instead of project_default."
},
"outro": {
"type": "string",
"description": "Explicit outro library_entry_id returned by identity_assets_list, or none. Use only when choosing a specific saved asset instead of project_default."
}
},
"additionalProperties": false
}
],
"description": "Optional highlight-reel Signature. Use project_default when the project has saved Signature defaults and the user wants their branding; saved project music becomes a full-Episode music cue. Discover first with identity_assets_list only when defaults are absent or unclear, the user names a specific opener or outro, or you need uses_title. Use the object form to choose explicit saved opener and outro assets. Add or change a specific song with music_cue_mutate after creation. Omitted object keys mean none."
},
"opener_title": {
"type": "string",
"description": "Optional per-reel opener title. Pass only when the selected opener asset has uses_title:true; static or absent openers return identity_warnings:[\"opener_title_ignored_static_opener\"] and ignore this value."
},
"supersedes_episode_id": {
"type": "string",
"description": "Optional explicit lineage when the user deliberately asks for a replacement draft. Never use this for edge_warnings: verify and revise the same created target with episode_edit."
},
"idempotency_key": {
"type": "string",
"description": "Opaque key unique across the account for this logical creation. For a new create under a v3 editor ask, use the full requestId plus a distinct action suffix; otherwise choose a fresh opaque key once. Exact retry/recovery reuses the original complete key and arguments, including across later messages. Never derive keys from titles or media ranges or re-key an ambiguous write. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second row."
}
},
"required": [
"segments",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"near_duplicate": {
"type": "boolean",
"description": "True when nothing was created because this session already made a near-identical derived clip — the returned handles are that existing clip's. Refine it with episode_edit; do not retry the create."
},
"already_applied": {
"type": "boolean",
"description": "True when the returned persisted Clip was already in place: either an exact same-key replay, or (with near_duplicate:true) same-session range convergence."
},
"clip_id": {
"type": "string",
"description": "Present when target_type is clip. The episode_id alias remains for compatibility."
},
"target_type": {
"type": "string",
"enum": [
"episode",
"clip"
],
"description": "Structural kind of the created composition."
},
"target_id": {
"type": "string",
"description": "Canonical handle for the created Episode or Clip."
},
"title": {
"type": "string",
"description": "Persisted title of the created Episode or Clip."
},
"segment_count": {
"type": "integer",
"description": "Number of persisted Program segments in the returned target."
},
"creation_disposition": {
"type": "string",
"enum": [
"created",
"replayed",
"converged"
],
"description": "Whether this call created a target, replayed the exact idempotent create, or converged onto an existing near-duplicate."
},
"duration_seconds": {
"type": "number",
"description": "Kept play length in seconds."
},
"total_duration_seconds": {
"type": "number",
"description": "Total Program duration, including applied identity segments."
},
"content_duration_seconds": {
"type": "number",
"description": "Duration of the requested editorial content before identity additions."
},
"derived_from_id": {
"type": [
"string",
"null"
],
"description": "Parent Episode handle when the created target is a Clip."
},
"identity_opener": {
"type": [
"object",
"null"
],
"description": "Compact applied opener summary when present."
},
"project_id": {
"type": [
"string",
"null"
],
"description": "Owning Project handle when present."
},
"workspace_url": {
"type": "string",
"description": "BitterClip workspace URL for the created target."
},
"revision": {
"type": "integer",
"description": "Durable revision counter (starts at 1 for a fresh episode)."
},
"tool_outcome": {
"type": "object",
"description": "Persisted production receipt with the exact target, revision, and next Open action."
},
"segments": {
"type": "array",
"description": "The persisted segment manifest (index, source_id, source_label, source_range, episode_range, boundary)."
},
"block_segments": {
"type": "array",
"description": "Template-backed segments created during this request.",
"items": {
"type": "object",
"properties": {
"position": {
"type": "integer"
},
"template": {
"type": "string"
},
"source_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"ready",
"preparing",
"failed"
],
"description": "Whether the template-backed Recording is already renderable or still baking."
}
}
}
},
"edge_warnings": {
"type": "array",
"description": "Always present. Non-mutating flags for cut edges that overlap approximate transcript word spans; acoustic verification decides whether the existing point is supported.",
"items": {
"type": "object",
"properties": {
"segment_index": {
"type": "integer"
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
},
"at_seconds": {
"type": "number",
"description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
},
"source_id": {
"type": "string",
"description": "Recording containing the flagged source edge."
},
"occurrence_id": {
"type": "string",
"description": "Exact created-target occurrence containing this edge, when mapped."
},
"episode_seconds": {
"type": "number",
"description": "Exact flagged point on the created target's Episode clock. Use directly as an episode_zoom edge; occurrence_id identifies its source side."
},
"word": {
"type": "string"
},
"word_range_source": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
}
},
"identity_plan": {
"type": "object",
"description": "Frozen resolved identity plan when identity: project_default resolved to an applied project identity."
},
"identity_layers": {
"type": "array",
"description": "Resolved Signature layers such as opener, cut style, and outro."
},
"identity_segments": {
"type": "array",
"description": "Identity-inserted segment rows with role, final_position, and segment_id for follow-up edits."
},
"identity_warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Identity warnings such as project_identity_missing or unsupported identity config."
},
"request_row_map": {
"type": "array",
"description": "Mapping from requested rows to final composition positions, including segment_id. Identity insertion shifts these positions."
},
"derived": {
"type": "boolean",
"description": "True when this edit is filed under a parent episode via derived_from_id and hidden from the primary episode index."
},
"derived_episode": {
"type": "boolean",
"description": "Present and true only for a top-level montage assembled from episode_id segments without derived_from_id."
},
"derived_from_episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source episode IDs used to assemble a top-level montage episode."
},
"status": {
"type": "string",
"description": "Always draft — persisted but not rendered."
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [
"edge_warnings"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"recording_not_found",
"invalid_time_range",
"invalid_input",
"identity_asset_not_found",
"identity_brand_mismatch",
"music_range_derivation_unsupported"
]Examples
[
{
"label": "Create a top-level episode from recording ranges",
"input": {
"segments": [
{
"recording_id": "src_...",
"range": [
0,
300
]
}
],
"title": "Episode 3",
"idempotency_key": "episode-1"
}
},
{
"label": "Create a derived highlight reel under one parent episode",
"input": {
"derived_from_id": "comp_parent",
"segments": [
{
"episode_id": "comp_parent",
"range": [
124.5,
151
]
},
{
"episode_id": "comp_parent",
"range": [
421,
455
]
}
],
"title": "Best moments",
"idempotency_key": "episode-reel-1"
}
},
{
"label": "Create a top-level montage from multiple episodes",
"input": {
"segments": [
{
"episode_id": "comp_a",
"range": [
124.5,
151
]
},
{
"episode_id": "comp_b",
"range": [
421,
455
]
}
],
"title": "Cross-episode best moments",
"idempotency_key": "episode-montage-1"
}
}
]episode_clone
Clone an episode
Create a clean draft branch from an existing top-level episode only when the user explicitly wants a separate version for comparison or a workshop reset. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. Do not use clone to assemble a new reel from Project sources; use one episode_create with ordered source ranges. Use episode_edit when the current visible draft should change in place.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
},
"title": {
"type": "string",
"description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
},
"description": {
"type": "string",
"description": "Optional description for the clone. Defaults to the source episode's displayed description."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry of the same clone request."
}
},
"required": [
"episode_id",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "New clone episode public ID."
},
"source_episode_id": {
"type": "string",
"description": "Episode public ID the clone branched from."
},
"cloned_from_episode_id": {
"type": "string",
"description": "Alias for source_episode_id for lineage displays."
},
"cloned_from_revision": {
"type": "integer",
"description": "Source episode revision captured by the clone."
},
"duration_seconds": {
"type": "number",
"description": "Kept play length in seconds."
},
"revision": {
"type": "integer",
"description": "Durable revision counter, always 1 for a fresh clone."
},
"segments": {
"type": "array",
"description": "The cloned segment manifest (index, source_id, source_range, episode_range, boundary)."
},
"edge_warnings": {
"type": "array",
"description": "Always present. Non-mutating warnings for cloned cut edges that land strictly inside transcript words.",
"items": {
"type": "object",
"properties": {
"segment_index": {
"type": "integer"
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
},
"at_seconds": {
"type": "number",
"description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
},
"source_id": {
"type": "string",
"description": "Recording containing the flagged source edge."
},
"occurrence_id": {
"type": "string",
"description": "Exact created-target occurrence containing this edge, when mapped."
},
"episode_seconds": {
"type": "number",
"description": "Exact flagged point on the created target's Episode clock. Use directly as an episode_zoom edge; occurrence_id identifies its source side."
},
"word": {
"type": "string"
},
"word_range_source": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
}
}
},
"status": {
"type": "string",
"description": "Always draft — cloned but not rendered."
},
"workspace_url": {
"type": "string",
"description": "Same-origin path that opens the new clone in the composite editor."
},
"already_applied": {
"type": "boolean",
"description": "true when this idempotency_key already created the same clone and the existing clone was returned."
},
"next_action": {
"type": "object",
"description": "Suggested next tool call: edit the clone with episode_edit using its current revision."
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"recording_not_found",
"idempotency_conflict",
"invalid_input"
]Examples
[
{
"label": "Branch an episode before trying an alternate cut",
"input": {
"episode_id": "comp_...",
"title": "Workshop branch A",
"idempotency_key": "clone-branch-a"
}
}
]episode_update
Update episode metadata
Update the saved episode's own title, description, Episode-time chapters, and/or Episode date. Read the exact Episode first and pass its draft_revision; a stale token fails without overwriting newer human copy. Episode date is the durable project chronology field; date-only input is interpreted as 12:00 UTC and sets the basis to manual. This is metadata-only; structural timeline edits use the separate episode_edit patch primitive. Do not use this for YouTube/LinkedIn/X package copy unless the user explicitly asks to rename, redescribe, or correct the date of the episode itself; use publish_prepare or publish_update for channel/package copy.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Episode public ID."
},
"title": {
"type": "string",
"description": "Optional new title."
},
"description": {
"type": "string",
"description": "Optional new description."
},
"chapters": {
"type": "array",
"maxItems": 250,
"description": "Optional user-authored Episode-time chapters. Omit to preserve the current field; pass [] to clear it.",
"items": {
"type": "object",
"properties": {
"start_seconds": {
"type": "number",
"minimum": 0,
"description": "Chapter start on the playable Episode clock."
},
"title": {
"type": "string"
}
},
"required": [
"start_seconds",
"title"
]
}
},
"episode_date": {
"type": "string",
"description": "Optional ISO8601 date or timestamp for the Episode date. Date-only values are stored at 12:00 UTC."
},
"expected_revision": {
"type": "string",
"description": "Required opaque draft_revision from a fresh episode_read or binding receipt. A stale token is rejected before any metadata write."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry."
}
},
"required": [
"episode_id",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"draft_revision": {
"type": "string",
"description": "Authoritative opaque draft revision after the metadata write."
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"chapters": {
"type": "array"
},
"chapter_timebase": {
"type": "string",
"enum": [
"episode"
]
},
"stale_media": {
"type": "boolean"
},
"episode_date": {
"type": "string"
},
"episode_date_basis": {
"type": "string"
},
"episode_date_label": {
"type": "string"
},
"already_applied": {
"type": "boolean"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input"
]clip_create_portrait_sibling
Create a portrait sibling clip
Create a separate 9:16 portrait sibling from one current rendered 16:9 landscape Clip. Read the landscape Clip first and pass its exact revision, draft_revision, and program_digest. BitterClip copies only its source-backed editorial timing, captions, audio policy, transitions, and safely mappable music; the child starts as a draft with independently editable centered framing and no Render, Export, package, credit, or publication. It does not invent speaker geometry or silently carry landscape crop decisions: apply source-time geometry through episode_edit occurrence.reframe before render_create. A 9:16 canvas over 16:9 footage keeps only a vertical slice of each frame; episode_framing_guidance reports, per visible person, whether their measured extent fits that crop window (fits | too_wide | uncertain | unknown). Local camera choices, overlays, identity/baked material, malformed music anchors, stale source state, or a non-landscape/unrendered source fail before a child exists. Retrying the identical idempotency key returns the same sibling.
Input schema
{
"type": "object",
"properties": {
"source_clip_id": {
"type": "string",
"description": "Current derived landscape Clip public ID (comp_...). Read it first; a top-level Episode or legacy Clip row is refused."
},
"expected_source_revision": {
"type": "integer",
"description": "Current integer revision from episode_read for source_clip_id."
},
"expected_source_draft_revision": {
"type": "string",
"description": "Current opaque draft_revision from episode_read for source_clip_id."
},
"expected_source_program_digest": {
"type": "string",
"description": "Current SHA-256 program_digest from episode_read for source_clip_id."
},
"title": {
"type": "string",
"description": "Optional title for the portrait sibling. Omit to derive one from the landscape Clip."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for an exact safe retry."
}
},
"required": [
"source_clip_id",
"expected_source_revision",
"expected_source_draft_revision",
"expected_source_program_digest",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"clip_id": {
"type": "string",
"description": "New independently editable portrait Clip (comp_...)."
},
"parent_episode_id": {
"type": [
"string",
"null"
],
"description": "Shared top-level Episode lineage, when present."
},
"source_clip_id": {
"type": "string"
},
"source_revision": {
"type": "integer"
},
"source_draft_revision": {
"type": "string"
},
"source_program_digest": {
"type": "string"
},
"revision": {
"type": "integer"
},
"draft_revision": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft"
]
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16"
]
},
"canvas": {
"type": "string",
"enum": [
"1080x1920@30"
]
},
"duration_seconds": {
"type": "number"
},
"occurrence_map": {
"type": "array",
"items": {
"type": "object"
},
"description": "Landscape Clip occurrence to portrait Clip occurrence mapping; composition decisions remain child-local."
},
"framing": {
"type": "object",
"description": "Truthful initial framing state and the next geometry-aware action."
},
"render_status": {
"type": "string",
"enum": [
"not_requested"
]
},
"receipt_id": {
"type": [
"string",
"null"
]
},
"already_applied": {
"type": "boolean"
},
"next_action": {
"type": "object"
},
"render_next_action": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input",
"portrait_sibling_source_not_clip",
"portrait_sibling_source_not_landscape",
"portrait_sibling_source_empty",
"portrait_sibling_source_not_currently_rendered",
"portrait_sibling_source_invalid_lineage",
"portrait_sibling_overlays_unsupported",
"portrait_sibling_local_camera_program_unsupported",
"portrait_sibling_identity_unsupported",
"portrait_sibling_baked_material_unsupported",
"portrait_sibling_music_unsupported",
"music_asset_missing",
"music_asset_mismatch",
"music_anchor_unavailable",
"music_range_inverted",
"music_ranges_overlap",
"music_asset_too_short",
"music_trim_out_of_range",
"music_fades_too_long",
"music_presentation_map_unsupported"
]clip_create
Create a clip
Create a short derived Clip from one current Program range. Use typed input:{type:clip|episode,id:comp_...} plus a stable variant_id for an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. This is for a single-range Clip; several moments combined into one video should use episode_create, not N clips. If this Clip must show a simultaneous Picture layout, first prove complete distinct-camera coverage for the entire range; never create a Clip as a coverage probe, and explain any necessary range shift before writing. This persists the Clip only; it does not open or render. For ordinary make/cut/create Clip intent, continue with render_create using target_type:"clip", the exact returned clip_id as target_id, and the returned revision, then render_status until ready unless the user asks for draft-only, review-first, or no-render. Report private Download/editor Open; never quote or retain its capability URL. Publishing stays explicit. Optional aspect_ratio sets the draft/render default, not a finished Export.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Compatibility top-level Episode input. Mutually exclusive with input."
},
"input": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
"variant_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Required with typed input. Stable identity of the explicitly requested alternative; retain on retries. A separate requested alternative uses a new variant_id and idempotency_key."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
},
"expected_revision": {
"type": "integer",
"description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Clip title. When supplied, use 1-200 characters with no surrounding whitespace."
},
"description": {
"type": "string",
"description": "Optional clip description."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "OMIT THIS unless the user asked for a specific shape or named a vertical destination. Left alone a typed variant preserves its input shape; legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry. Scope it to the ask (conversation + attempt), never derive it from the media range — a range-derived key changes when you refine the cut, so idempotency never fires. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
}
},
"required": [
"range",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"episode_id"
],
"not": {
"anyOf": [
{
"required": [
"input"
]
},
{
"required": [
"variant_id"
]
}
]
}
},
{
"required": [
"input",
"variant_id"
],
"not": {
"required": [
"episode_id"
]
}
}
]
}Output schema
{
"type": "object",
"properties": {
"clip_id": {
"type": "string"
},
"title": {
"type": "string",
"description": "The persisted Clip title, reread from the created or converged Clip."
},
"range": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "The exact persisted parent-Episode [start_seconds, end_seconds] range represented by this Clip."
},
"episode_id": {
"type": "string"
},
"episode_title": {
"type": "string"
},
"project_id": {
"type": "string"
},
"project_title": {
"type": "string"
},
"status": {
"type": "string"
},
"duration_seconds": {
"type": "number"
},
"revision": {
"type": "integer"
},
"edge_warnings": {
"type": "array",
"items": {
"type": "object"
},
"description": "Recording boundary evidence requiring review before delivery."
},
"tool_outcome": {
"type": "object",
"description": "Persisted production receipt with the exact target, revision, and next Open action."
},
"near_duplicate": {
"type": "boolean",
"description": "True when nothing was created: this session already made a near-identical clip of this episode and the returned handles are that clip's. Refine it with episode_edit; do not retry the create."
},
"already_applied": {
"type": "boolean",
"description": "True when the returned persisted Clip was already in place: either an exact same-key replay, or (with near_duplicate:true) same-session range convergence."
},
"user_presence": {
"type": "object",
"description": "Present when a live editor session on the parent episode is active: this is presence only, not visible navigation acknowledgement. Always preserve the exact Open Clip action. Absent means visibility is unknown; do not claim it."
},
"opened": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"created_not_opened",
"idempotency_replay_returned",
"near_duplicate_returned"
]
},
"next_action": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"recording_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_time_range",
"invalid_input"
]clip_update
Update clip metadata
Update one exact Clip's title and/or description. Read that Clip first and pass its draft_revision; a stale token fails without overwriting newer human copy. This does not structurally edit the parent episode; choose render aspect ratio with render_create.
Input schema
{
"type": "object",
"properties": {
"clip_id": {
"type": "string",
"description": "Clip public ID."
},
"title": {
"type": "string",
"description": "Optional new title."
},
"description": {
"type": "string",
"description": "Optional new description."
},
"expected_revision": {
"type": "string",
"description": "Required opaque draft_revision from a fresh episode_read or binding receipt."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry."
}
},
"required": [
"clip_id",
"expected_revision",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"clip_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"draft_revision": {
"type": "string"
},
"stale_media": {
"type": "boolean"
},
"already_applied": {
"type": "boolean"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input"
]episode_edit
Arrange an existing episode Program
Edit the current Program in place through one stable occurrence operation. For several partial shortenings inspected on one revision, use one occurrence.remove with selection.ranges in current Program order (up to 64 disjoint ranges): all boundaries are verified against that frozen snapshot and settle atomically under one receipt. Sequential edits stale unused evidence from the changed Program; do not send those removals as separate trims or change-set items. Read the episode first, then address exact occurrence IDs and a revision-bound semantic Junction; never use pixels, mutable positions, transcript words, filenames, or source chronology as arrangement identity. occurrence.split retires one source-backed parent and mints exact children. occurrence.duplicate duplicates a whole supported occurrence or geometric Range with new identities. occurrence.move preserves whole-occurrence identity and moves material to a beginning/interior/end Junction. occurrence.remove drops whole supported occurrences, one geometric Range, or up to 64 disjoint Ranges while preserving a nonempty Program. occurrence.restore_cut takes exactly two adjacent occurrences from the same Recording, restores their omitted source interval, preserves the left identity, and retires the right; it needs no boundary evidence because it only reinstates source truth, but you must reread before addressing the resulting occurrence. occurrence.trim changes one source-backed occurrence's source in/out points while preserving that same occurrence, its caption/framing/audio treatment, and its incoming Junction treatment; it may shorten or extend into inspected source handles and is the correction for "start this excerpt earlier" or "trim the ending tighter." occurrence.reframe changes one source-backed clip between Fill and Fit and optionally positions its normalized focal point without changing time or identity; a Fill framing may also carry canvas_fit "4:5" or "1:1", which crops at that ratio around the same focal point and letterboxes the picture inside the canvas with black mattes — a choice that exists when framing evidence reports a subject too_wide for the full-canvas crop window, and one that is yours to make or decline. canvas_alignment keeps that ratio window static at center, top, or bottom; top creates one deterministic lower matte that captions automatically use as a subtitle band. occurrence.caption applies one caption treatment to one or more contiguous source-backed occurrences. Use Signal for restrained long-form interview typography. All caption presets use the same HTML paint as the editor preview. Signal keeps restrained interview typography; Active Word adds the timed accent word. Long Episodes use bounded raster chunks rather than a whole-caption duration cap. Auto remains matte-aware, Upper/Lower are stable semantic lanes, and Custom is one static normalized center/width/alignment box that can be corrected without face tracking or rerunning analysis. The successful response attempts to attach representative Export-geometry JPEGs containing both the changed caption and any committed speaker title visible at those instants; inspect them for punch-state quality and text-layer collisions before another nudge. vertical_offset is only a small semantic-lane correction. Caption treatment never changes canonical transcript text or timing. For a visible misspelling or proper noun only, one occurrence may carry display-only word_corrections bound to exact word IDs and current token text from episode_zoom; omit them to preserve, pass [] to clear, and re-read instead of retrying if transcript drift makes one stale. junction.transition owns one adjacent source-backed edit point: Cut removes treatment, Crossfade overlaps available source handles, and Produced applies the Project's restrained flash/swish bridge without changing Program source time. Use Produced selectively between cold-open excerpts, not mechanically on body edits or multicamera switches; duration, intensity, and sound gain are cheap corrections on the same Junction. The intrinsic capability profiles printed by episode_read describe role/media affordances; current attachments and boundary evidence are still validated when episode_edit runs. Self-contained typed Program material may support whole-occurrence Move/Duplicate/Remove, while Trim, picture framing, captions, and Junction transitions are source-backed only. For a plan-backed typed opener or outro, use identity_part.customize with its exact occurrence_id; requested_aspect_ratio rebakes the same identity moment for a landscape, portrait, square, or feed canvas without treating it as camera footage. When a self-contained typed opener or outro reports identity_replace=true and has no identity_customization, identity_part.replace converts that same occurrence in place to a Project default, saved library entry, or explicit curated preset configuration; use Replace only when Customize is unavailable. operation.revert applies the server-owned exact inverse named by a prior receipt. Whole-occurrence Move/Duplicate/Remove/Restore, Reframe, Caption treatment, identity_part.customize, identity_part.replace, and junction.transition need no new boundary evidence; Split, partial Range, an interior destination Point, and every changed Trim edge require exact signed evidence returned by episode_zoom, or by an exact episode_sample_frames projection:"original" call when audio is unavailable. A Trim may use evidence from the source-linked parent Episode when extending beyond the derived Clip's current window. Program-projection and angle frame samples never authorize structural edits. One call settles one occurrence operation atomically and returns a durable receipt plus the current revision/digest. A stale revision, unsupported attachment, invalid evidence, or changed Junction fails without partial mutation. A program_attachment_conflict is non-retryable for the identical failed input: do not repeat it with a new idempotency key or in parallel. Change the operation according to its typed reason, or report the blocker while preserving the Episode. Re-read before addressing the next structural revision.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "The episode (composition) public ID, such as comp_..."
},
"expected_revision": {
"type": "integer",
"description": "Required integer revision from a fresh episode_read. A stale value is rejected; re-read before retrying."
},
"ops": {
"type": "array",
"description": "Exactly one stable occurrence operation. The operation itself may transform one contiguous multi-occurrence Range or up to 64 disjoint removal Ranges atomically. To trim an inspected prefix, use occurrence.remove with selection:{range:{start:{occurrence_id,source_seconds:<existing start>},end:{occurrence_id,source_seconds:<inspected boundary>}}}. Prefer short evidence_id handles from episode_zoom detail edit for every interior edge. For dense dialogue work, put every partial removal inspected on this revision—across one or many occurrences—in one selection.ranges array. Any Program mutation changes the whole digest, so all unused evidence from the prior revision becomes stale even when its occurrence was untouched. BitterClip applies the current attachment-safety policy server-side.",
"minItems": 1,
"maxItems": 1,
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.split"
]
},
"point": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
},
"base_revision": {
"type": "integer",
"description": "Must equal the top-level expected_revision."
}
},
"required": [
"occurrence_id",
"source_seconds",
"base_revision"
],
"additionalProperties": false
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Media-inspection evidence for every new interior source boundary, from episode_zoom or from an exact episode_sample_frames projection:\"original\" call when audio is unavailable. PASS THE SHORT evidence_id, not the long inspection_token: copy `evidence_id` (biev_...) exactly as returned, the same way you copy an occurrence id. The inspection_token is still accepted for hosts that already send it, but it is ~900 opaque characters and any single altered character rejects the whole edit. Program-projection and angle samples never authorize structural edits.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred. The biev_... id returned alongside this evidence. Copy it exactly."
},
"inspection_token": {
"type": "string",
"description": "Legacy alternative to evidence_id. ~900 characters; must be byte-identical."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
}
},
"required": [
"op",
"point",
"boundary_evidence"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.duplicate"
],
"description": "For an ordinary request such as 'duplicate this beat', send only op and selection. BitterClip places the new copy immediately after the selected occurrence. Do not send attachment_policy."
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string"
}
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"range"
],
"additionalProperties": false
}
],
"description": "The exact current occurrence or geometric Program Range to duplicate. Use the selected Program occurrence ID when the editor ask supplies one."
},
"destination": {
"oneOf": [
{
"type": "object",
"properties": {
"base_revision": {
"type": "integer"
},
"left_occurrence_id": {
"type": [
"string",
"null"
]
},
"right_occurrence_id": {
"type": [
"string",
"null"
]
}
},
"required": [
"base_revision",
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"base_revision": {
"type": "integer"
},
"at": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"base_revision",
"at"
],
"additionalProperties": false
}
],
"description": "Optional. Supply only when the user explicitly names a different placement; otherwise omit it and use the adjacent-copy default."
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Media-inspection evidence for every new interior source boundary, from episode_zoom or from an exact episode_sample_frames projection:\"original\" call when audio is unavailable. PASS THE SHORT evidence_id, not the long inspection_token: copy `evidence_id` (biev_...) exactly as returned, the same way you copy an occurrence id. The inspection_token is still accepted for hosts that already send it, but it is ~900 opaque characters and any single altered character rejects the whole edit. Program-projection and angle samples never authorize structural edits.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred. The biev_... id returned alongside this evidence. Copy it exactly."
},
"inspection_token": {
"type": "string",
"description": "Legacy alternative to evidence_id. ~900 characters; must be byte-identical."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
}
},
"required": [
"op",
"selection"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.move"
]
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string"
}
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"range"
],
"additionalProperties": false
}
]
},
"destination": {
"oneOf": [
{
"type": "object",
"properties": {
"base_revision": {
"type": "integer"
},
"left_occurrence_id": {
"type": [
"string",
"null"
]
},
"right_occurrence_id": {
"type": [
"string",
"null"
]
}
},
"required": [
"base_revision",
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"base_revision": {
"type": "integer"
},
"at": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"base_revision",
"at"
],
"additionalProperties": false
}
]
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Media-inspection evidence for every new interior source boundary, from episode_zoom or from an exact episode_sample_frames projection:\"original\" call when audio is unavailable. PASS THE SHORT evidence_id, not the long inspection_token: copy `evidence_id` (biev_...) exactly as returned, the same way you copy an occurrence id. The inspection_token is still accepted for hosts that already send it, but it is ~900 opaque characters and any single altered character rejects the whole edit. Program-projection and angle samples never authorize structural edits.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred. The biev_... id returned alongside this evidence. Copy it exactly."
},
"inspection_token": {
"type": "string",
"description": "Legacy alternative to evidence_id. ~900 characters; must be byte-identical."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
},
"attachment_policy": {
"type": "string",
"enum": [
"content_v1"
],
"description": "Compatibility-only; omit this field. BitterClip applies the current attachment-safety policy server-side."
}
},
"required": [
"op",
"selection",
"destination"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.remove"
]
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string"
}
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"range"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ranges": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"items": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"description": "Stable Program occurrence ID."
},
"source_seconds": {
"type": "number",
"description": "Exact source-media second, resolved to a millisecond boundary."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
"description": "Disjoint source-linked Ranges across one or many current occurrences, listed in current Program order. Every partial removal inspected on this revision belongs in this same array: any earlier Program edit changes the whole digest and stales later evidence, even when a later Range touches a different occurrence. All cuts settle atomically as one receipt."
}
},
"required": [
"ranges"
],
"additionalProperties": false
}
]
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Media-inspection evidence for every new interior source boundary, from episode_zoom or from an exact episode_sample_frames projection:\"original\" call when audio is unavailable. PASS THE SHORT evidence_id, not the long inspection_token: copy `evidence_id` (biev_...) exactly as returned, the same way you copy an occurrence id. The inspection_token is still accepted for hosts that already send it, but it is ~900 opaque characters and any single altered character rejects the whole edit. Program-projection and angle samples never authorize structural edits.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred. The biev_... id returned alongside this evidence. Copy it exactly."
},
"inspection_token": {
"type": "string",
"description": "Legacy alternative to evidence_id. ~900 characters; must be byte-identical."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
}
},
"required": [
"op",
"selection"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.restore_cut"
]
},
"selection": {
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"uniqueItems": true,
"items": {
"type": "string"
},
"description": "Exactly two adjacent same-Recording occurrence IDs in current Program order. The left identity survives and the right retires."
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
}
},
"required": [
"op",
"selection"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.trim"
]
},
"occurrence_id": {
"type": "string",
"description": "Stable source-backed occurrence ID to preserve while changing its in/out points."
},
"source_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
},
"description": "Exact [start_seconds, end_seconds] in the occurrence's existing Recording. May shorten or extend the occurrence; end must be greater than start."
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Media-inspection evidence for every new interior source boundary, from episode_zoom or from an exact episode_sample_frames projection:\"original\" call when audio is unavailable. PASS THE SHORT evidence_id, not the long inspection_token: copy `evidence_id` (biev_...) exactly as returned, the same way you copy an occurrence id. The inspection_token is still accepted for hosts that already send it, but it is ~900 opaque characters and any single altered character rejects the whole edit. Program-projection and angle samples never authorize structural edits.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred. The biev_... id returned alongside this evidence. Copy it exactly."
},
"inspection_token": {
"type": "string",
"description": "Legacy alternative to evidence_id. ~900 characters; must be byte-identical."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
}
},
"required": [
"op",
"occurrence_id",
"source_range",
"boundary_evidence"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.reframe"
]
},
"occurrence_id": {
"type": "string",
"description": "Stable occurrence ID for one source-backed video clip."
},
"framing": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"fill",
"fit"
],
"description": "Fill covers the canvas; Fit preserves the whole picture with padding."
},
"canvas_fit": {
"type": "string",
"enum": [
"4:5",
"1:1"
],
"description": "Optional intermediate crop ratio for Fill framing. Absent, the Fill crop covers the whole canvas. \"4:5\" or \"1:1\" crops at that ratio around the same focal point and letterboxes the picture onto the canvas with black mattes — an alternative that exists when episode_framing_guidance reports a person extent too_wide for the full-canvas crop window. Whether full bleed or a letterboxed ratio serves the story is your editorial judgment. Invalid with Fit, which already shows the whole picture."
},
"canvas_alignment": {
"type": "string",
"enum": [
"center",
"top",
"bottom"
],
"description": "Optional static placement of a 4:5 or 1:1 picture inside the canvas. Center keeps symmetric mattes; top reserves the full remaining lower matte as a stable subtitle band; bottom reserves it above. Invalid without canvas_fit."
},
"focal_point": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Horizontal subject position from left (0) to right (1)."
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Vertical subject position from top (0) to bottom (1)."
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"mode"
],
"additionalProperties": false
}
},
"required": [
"op",
"occurrence_id",
"framing"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.caption"
]
},
"selection": {
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string"
},
"description": "One or more contiguous source-backed occurrence IDs in current Program order."
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
"treatment": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.caption_treatment.v1"
],
"description": "Optional explicit schema marker."
},
"mode": {
"type": "string",
"enum": [
"inherit",
"off",
"on"
],
"description": "Caption visibility for the selected occurrences. Off suppresses burned captions while retaining the authored style and placement for a later correction; On explicitly enables them; Inherit follows the Episode default."
},
"preset": {
"type": "string",
"enum": [
"inherit",
"clean_lower",
"signal",
"punch_word_highlight",
"active_word"
],
"description": "Active Word is BitterClip's expressive HTML social treatment with stable phrase geometry and a timed accent word. Signal is the restrained professional interview treatment. clean_lower keeps clean phrase captions; punch_word_highlight follows each spoken word. Inherit removes the occurrence-level preset override without changing caption visibility."
},
"placement": {
"type": "object",
"properties": {
"lane": {
"type": "string",
"enum": [
"auto",
"upper",
"lower",
"custom"
],
"description": "Auto keeps matte-aware/default placement. Upper or Lower locks one stable shot-level lane. Custom uses one static normalized box for Active Word and is the contract a future direct-manipulation editor can move; no lane follows a face box. Omit lane when correcting an already-authored placement."
},
"vertical_offset": {
"type": "number",
"minimum": -0.15,
"maximum": 0.15,
"description": "Small canvas-relative semantic-lane correction. Positive moves down; negative moves up. Auto requires zero; Custom uses anchor instead."
},
"anchor": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0.05,
"maximum": 0.95,
"description": "Static normalized box center from the canvas left; partial correction preserves an existing x."
},
"y": {
"type": "number",
"minimum": 0.05,
"maximum": 0.95,
"description": "Static normalized box center from the canvas top; partial correction preserves an existing y."
}
},
"required": [],
"additionalProperties": false
},
"width": {
"type": "number",
"minimum": 0.3,
"maximum": 0.94,
"description": "Custom box width as a normalized fraction of the destination canvas."
},
"alignment": {
"type": "string",
"enum": [
"left",
"center",
"right"
],
"description": "Text alignment inside the Custom box."
}
},
"required": [],
"additionalProperties": false
},
"appearance": {
"type": "object",
"properties": {
"accent_color": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Active Word accent as a six-digit hex color; this remains typed data, never arbitrary CSS."
},
"font_scale": {
"type": "number",
"minimum": 0.8,
"maximum": 1.25,
"description": "Bounded Active Word type-size correction around the curated preset."
}
},
"required": [],
"additionalProperties": false
},
"word_corrections": {
"type": "array",
"maxItems": 32,
"description": "Optional complete set of display-only token corrections for exactly one selected occurrence. Use only for a visibly misspelled word or proper noun. Request episode_zoom with include:[\"word_provenance\"] over the word's small window; copy word_id and exact text from that channel's word evidence into word_id and from. Compact transcript tuples omit IDs, and speech-alignment point IDs are not caption word IDs. Increase max_bytes or narrow the window if word_provenance was omitted by the response budget. to is rendered copy only; canonical transcript text and timing remain unchanged. Omit this field to preserve the current set; pass [] to clear all occurrence-local corrections.",
"items": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Exact transcript word_id from episode_zoom include:[\"word_provenance\"] for this occurrence; do not use speech-alignment point IDs."
},
"from": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"description": "Exact current transcript token; stale or mismatched copy fails without mutation."
},
"to": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"description": "Corrected burned-caption display token. Do not use this to paraphrase speech."
}
},
"required": [
"word_id",
"from",
"to"
],
"additionalProperties": false
}
}
},
"required": [],
"additionalProperties": false
}
},
"required": [
"op",
"selection",
"treatment"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"identity_part.customize"
]
},
"occurrence_id": {
"type": "string",
"description": "Stable typed opener/outro occurrence ID from episode_read."
},
"set": {
"type": "object",
"properties": {
"label": {
"type": [
"string",
"null"
],
"description": "Optional editor label for this identity moment; null clears it."
},
"params": {
"type": "object",
"description": "Scene-specific typed parameters deep-merged into the existing identity moment. Omitted keys, scene choice, and sound remain unchanged; read the occurrence's current identity_customization first."
},
"gain_db": {
"type": "number",
"description": "Gain for the identity moment's existing sonic mark."
},
"sound_id": {
"type": "string",
"description": "Curated identity sound ID returned by identity_assets_list.assets.identity_sounds. Rebakes this opener or outro with the selected sonic mark while preserving its visual preset."
},
"requested_aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "Rebake the same typed identity moment for this destination shape. Use the Episode canvas aspect for a copied landscape-to-portrait opener or outro."
}
},
"required": [],
"additionalProperties": false
}
},
"required": [
"op",
"occurrence_id",
"set"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"identity_part.replace"
]
},
"occurrence_id": {
"type": "string",
"description": "Stable self-contained typed opener/outro occurrence ID whose read capability reports identity_replace=true."
},
"configuration": {
"oneOf": [
{
"type": "string",
"enum": [
"project_default"
],
"description": "Use the Project's saved default for this opener/outro role."
},
{
"type": "object",
"properties": {
"library_entry_id": {
"type": "string",
"minLength": 1,
"description": "Saved same-account opener/outro entry returned by identity_assets_list."
}
},
"required": [
"library_entry_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"preset_id": {
"type": "string",
"minLength": 1,
"description": "Checked-in identity preset whose placement matches the target role."
},
"params": {
"type": "object",
"description": "Typed preset or Signature Lab parameters. Account-authored scenes and curated sounds are validated by the shared identity resolver."
},
"gain_db": {
"type": "number"
},
"sound_id": {
"type": "string",
"minLength": 1,
"description": "Optional curated identity sound override."
},
"brand_id": {
"type": "string",
"minLength": 1,
"description": "Optional account-owned brand pack ID; omit to use the Project's brand."
}
},
"required": [
"preset_id"
],
"additionalProperties": false
}
]
}
},
"required": [
"op",
"occurrence_id",
"configuration"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"junction.transition"
]
},
"junction": {
"type": "object",
"properties": {
"base_revision": {
"type": "integer",
"description": "Must equal the top-level expected_revision."
},
"left_occurrence_id": {
"type": "string",
"description": "Stable occurrence immediately before the edit point."
},
"right_occurrence_id": {
"type": "string",
"description": "Stable occurrence immediately after the edit point."
}
},
"required": [
"base_revision",
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false
},
"transition": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"cut",
"crossfade",
"produced"
],
"description": "Cut removes treatment. Crossfade overlaps source handles and ripples later Episode time earlier. Produced uses the Project's existing flash/swish seam while preserving Program source time."
},
"duration_seconds": {
"type": "number",
"minimum": 0,
"maximum": 10,
"description": "Crossfade duration up to 10 seconds; Produced duration 0.12–1.0 seconds controls the full visual-and-audio seam envelope; use 0 for Cut."
},
"sound_gain_db": {
"type": "integer",
"minimum": -40,
"maximum": -6,
"description": "Optional Produced-only sound gain. Omit to preserve the current or Project value; restrained interview seams are typically around -26 dB."
},
"intensity": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Optional Produced-only visual intensity. Prefer low for a professional interview cold open."
}
},
"required": [
"kind",
"duration_seconds"
],
"additionalProperties": false
}
},
"required": [
"op",
"junction",
"transition"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"operation.revert"
]
},
"receipt_id": {
"type": "string",
"description": "Server-owned Program edit receipt ID."
}
},
"required": [
"op",
"receipt_id"
],
"additionalProperties": false
}
]
}
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for exact retry. Same key plus changed input conflicts."
}
},
"required": [
"episode_id",
"expected_revision",
"ops",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"operation_type": {
"type": "string",
"description": "The exact occurrence operation settled by this receipt."
},
"selection_kind": {
"type": "string",
"enum": [
"range",
"occurrences"
],
"description": "Whether the settled operation addressed a geometric Program Range or whole occurrences."
},
"base_revision": {
"type": "integer"
},
"revision": {
"type": "integer",
"description": "Revision committed by this operation."
},
"current_revision": {
"type": "integer",
"description": "Current durable head, which may be newer on an exact retry."
},
"current_program_digest": {
"type": "string",
"description": "Current durable occurrence-state fingerprint. On an exact retry, compare this with program_digest to detect later structural or occurrence-local changes even when the integer revision is unchanged."
},
"before_duration": {
"type": "number",
"description": "Kept (play) length in seconds immediately before this edit."
},
"duration": {
"type": "number",
"description": "Kept (play) length in seconds after the edit."
},
"duration_delta": {
"type": "number",
"description": "Exact after-minus-before change in kept length; negative means footage was removed."
},
"operation_receipt_id": {
"type": "string"
},
"reverts_receipt_id": {
"type": "string",
"description": "For operation.revert, the exact prior Program receipt restored by this result."
},
"before_program_digest": {
"type": "string"
},
"program_digest": {
"type": "string"
},
"resulting_order": {
"type": "array",
"items": {
"type": "string"
}
},
"minted_occurrence_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"retired_occurrence_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"surviving_occurrence_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"occurrence_lineage": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string"
},
"settlement": {
"type": "string",
"enum": [
"minted",
"retired",
"surviving"
]
},
"lineage": {
"type": "object"
}
},
"required": [
"occurrence_id",
"settlement",
"lineage"
],
"additionalProperties": false
}
},
"inverse": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"operation.revert"
]
},
"receipt_id": {
"type": "string"
}
},
"required": [
"op",
"receipt_id"
],
"additionalProperties": false
},
"stale_media": {
"type": "boolean",
"description": "true when a prior render is now behind the edit (re-render to refresh)."
},
"stale_copy": {
"type": "boolean",
"description": "true when title/description lag the current transcript revision (refresh copy)."
},
"already_applied": {
"type": "boolean",
"description": "true when this idempotency_key was already applied (the op was a no-op retry)."
},
"caption_visual_snapshot": {
"type": "object",
"description": "Receipt-protected render-plan, caption-execution, and selected-treatment digests captured under Export dependency locks for occurrence.caption. Automatic positioning proof requires this complete snapshot; legacy receipts omit it.",
"properties": {
"render_plan_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"caption_execution_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"caption_treatments_digest": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"occurrence_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"render_plan_hash",
"caption_execution_digest",
"caption_treatments_digest",
"occurrence_ids"
],
"additionalProperties": false
},
"materialization_status": {
"type": "string",
"enum": [
"ready",
"preparing",
"unavailable"
],
"description": "For typed identity treatment, whether the destination-shaped media is ready."
},
"next_action": {
"type": "object",
"description": "Bounded continuation when typed media is still preparing."
},
"tool_outcome": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"enum": [
"bitterclip.tool_outcome.v1"
]
},
"tool": {
"type": "string",
"enum": [
"episode_edit"
]
},
"status": {
"type": "string",
"enum": [
"applied",
"replayed"
]
},
"target": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"episode"
]
},
"id": {
"type": "string",
"pattern": "^comp_[a-z0-9]+$"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
"operation": {
"type": "string",
"enum": [
"occurrence.split",
"occurrence.duplicate",
"occurrence.move",
"occurrence.remove",
"occurrence.restore_cut",
"occurrence.trim",
"occurrence.reframe",
"occurrence.caption",
"junction.transition",
"operation.revert"
]
},
"selection_kind": {
"type": "string",
"enum": [
"range",
"occurrences"
]
},
"revisions": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": 0
},
"committed": {
"type": "integer",
"minimum": 1
},
"current": {
"type": "integer",
"minimum": 1
}
},
"required": [
"base",
"committed",
"current"
],
"additionalProperties": false
},
"duration": {
"type": "object",
"properties": {
"before_seconds": {
"type": "number",
"minimum": 0
},
"after_seconds": {
"type": "number",
"minimum": 0
},
"delta_seconds": {
"type": "number"
}
},
"required": [
"before_seconds",
"after_seconds",
"delta_seconds"
],
"additionalProperties": false
},
"receipt": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
},
"inverse": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"operation.revert"
]
},
"receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
}
},
"required": [
"op",
"receipt_id"
],
"additionalProperties": false
},
"reverts_receipt_id": {
"type": "string",
"pattern": "^rcpt_[a-z0-9]+$"
}
},
"required": [
"id",
"inverse"
],
"additionalProperties": false
},
"program_move_target": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"pattern": "^occ_[a-z0-9]{20}$"
},
"destination": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"adjacency"
]
},
"left_occurrence_id": {
"type": [
"string",
"null"
],
"pattern": "^occ_[a-z0-9]{20}$"
},
"right_occurrence_id": {
"type": [
"string",
"null"
],
"pattern": "^occ_[a-z0-9]{20}$"
}
},
"required": [
"kind",
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false,
"anyOf": [
{
"properties": {
"left_occurrence_id": {
"type": "string",
"pattern": "^occ_[a-z0-9]{20}$"
}
}
},
{
"properties": {
"right_occurrence_id": {
"type": "string",
"pattern": "^occ_[a-z0-9]{20}$"
}
}
}
]
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"point"
]
},
"occurrence_id": {
"type": "string",
"pattern": "^occ_[a-z0-9]{20}$"
},
"source_seconds": {
"type": "number",
"minimum": 0
}
},
"required": [
"kind",
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
]
},
"episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
}
}
},
"required": [
"occurrence_id",
"destination",
"episode_range"
],
"additionalProperties": false,
"description": "Optional receipt-derived Move effect, emitted only when this tools/call opts into bitterclip/toolOutcomeCapabilities program_move_target.v1. It is descriptive on historical replay; offer Open or Undo only when revisions.current equals revisions.committed and digests.current equals digests.result."
},
"program_occurrence_target": {
"type": "object",
"properties": {
"occurrence_id": {
"type": "string",
"pattern": "^occ_[a-z0-9]{20}$"
},
"episode_range": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"minimum": 0
}
}
},
"required": [
"occurrence_id",
"episode_range"
],
"additionalProperties": false,
"description": "Optional receipt-derived exact Duplicate or Trim effect, emitted only when this tools/call opts into bitterclip/toolOutcomeCapabilities program_occurrence_target.v1 and one whole Program occurrence is addressable. Range or multi-occurrence results omit it and remain generic. It is descriptive on historical replay; offer Open or Undo only when revisions.current equals revisions.committed and digests.current equals digests.result."
},
"digests": {
"type": "object",
"properties": {
"before": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"result": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"current": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"required": [
"before",
"result",
"current"
],
"additionalProperties": false
}
},
"required": [
"schema",
"tool",
"status",
"target",
"operation",
"revisions",
"duration",
"receipt",
"digests"
],
"additionalProperties": false
},
"caption_positioning_sample": {
"type": "object",
"description": "For occurrence.caption, automatic post-commit visual proof. ready carries one calm cue still or up to three timed active-word stills plus durable gallery/frame references. Each still also includes any committed speaker title visible at that instant so text-layer collisions are observable; superseded, unavailable, and not_applicable never undo the committed receipt."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"idempotency_conflict",
"invalid_input",
"program_snapshot_invalid",
"program_occurrence_not_found",
"program_occurrence_identity_conflict",
"program_target_not_contiguous",
"program_range_invalid",
"program_boundary_invalid",
"program_boundary_evidence_required",
"program_boundary_evidence_invalid",
"program_junction_conflict",
"program_destination_inside_selection",
"program_attachment_conflict",
"program_typed_operation_required",
"program_would_be_empty",
"program_occurrence_limit",
"operation_receipt_not_found",
"operation_receipt_invalid",
"program_revert_conflict",
"picture_framing_invalid",
"picture_framing_unsupported",
"transition_source_handles_unavailable",
"program_source_range_unplayable",
"identity_slot_not_configured",
"identity_asset_not_found",
"identity_brand_mismatch",
"music_anchor_transform_unsupported",
"music_range_inverted",
"music_ranges_overlap",
"music_asset_too_short"
]Examples
[
{
"label": "Duplicate one Program occurrence immediately",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.duplicate",
"selection": {
"occurrence_ids": [
"occ_..."
]
}
}
],
"idempotency_key": "duplicate-1"
}
},
{
"label": "Move one Program occurrence to the end",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.move",
"selection": {
"occurrence_ids": [
"occ_..."
]
},
"destination": {
"base_revision": 4,
"left_occurrence_id": "occ_last...",
"right_occurrence_id": null
}
}
],
"idempotency_key": "move-1"
}
},
{
"label": "Trim an inspected prefix from the opening occurrence",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.remove",
"selection": {
"range": {
"start": {
"occurrence_id": "occ_opening...",
"source_seconds": 5.25
},
"end": {
"occurrence_id": "occ_opening...",
"source_seconds": 7.5
}
}
},
"boundary_evidence": [
{
"evidence_id": "biev_..."
}
]
}
],
"idempotency_key": "trim-opening-prefix-1"
}
},
{
"label": "Restore omitted footage between two adjacent occurrences",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.restore_cut",
"selection": {
"occurrence_ids": [
"occ_left...",
"occ_right..."
]
}
}
],
"idempotency_key": "restore-cut-1"
}
},
{
"label": "Extend one contextless excerpt earlier without rebuilding the Clip",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.trim",
"occurrence_id": "occ_excerpt...",
"source_range": [
625.02,
675.65
],
"boundary_evidence": [
{
"evidence_id": "biev_..."
}
]
}
],
"idempotency_key": "extend-excerpt-context-1"
}
},
{
"label": "Fill a vertical frame around the subject",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.reframe",
"occurrence_id": "occ_...",
"framing": {
"mode": "fill",
"focal_point": {
"x": 0.42,
"y": 0.5
}
}
}
],
"idempotency_key": "reframe-1"
}
},
{
"label": "Letterbox one clip at 4:5 inside the canvas",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "occurrence.reframe",
"occurrence_id": "occ_...",
"framing": {
"mode": "fill",
"canvas_fit": "4:5",
"focal_point": {
"x": 0.42,
"y": 0.5
}
}
}
],
"idempotency_key": "reframe-2"
}
},
{
"label": "Rebake a copied opener for a portrait canvas",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "identity_part.customize",
"occurrence_id": "occ_opener...",
"set": {
"requested_aspect_ratio": "9:16"
}
}
],
"idempotency_key": "portrait-opener-1"
}
},
{
"label": "Crossfade one edit point and ripple later Episode time",
"input": {
"episode_id": "comp_...",
"expected_revision": 4,
"ops": [
{
"op": "junction.transition",
"junction": {
"base_revision": 4,
"left_occurrence_id": "occ_left...",
"right_occurrence_id": "occ_right..."
},
"transition": {
"kind": "crossfade",
"duration_seconds": 0.5
}
}
],
"idempotency_key": "crossfade-1"
}
},
{
"label": "Revert one exact Program operation",
"input": {
"episode_id": "comp_...",
"expected_revision": 5,
"ops": [
{
"op": "operation.revert",
"receipt_id": "rcpt_..."
}
],
"idempotency_key": "revert-1"
}
}
]episode_fx_insert
Insert an FX clip
Insert one configured opener or outro as ordinary, time-bearing media at a revision-bound Episode point or edit point. Use this for the built-in FX artifacts; do not describe them as overlays. Read the Episode first, pass its current revision, and use either a playable Episode second or the exact neighboring occurrence IDs. The operation uses the same identity-part planner, source bake, camera settlement, music validation, idempotency, and exact reversible receipt path as the visible editor.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Editable Episode public ID."
},
"expected_revision": {
"type": "integer",
"description": "Current integer revision from a fresh episode_read."
},
"role": {
"type": "string",
"enum": [
"opener",
"outro"
],
"description": "FX category to insert."
},
"at": {
"type": "object",
"description": "Revision-bound insertion target: a playable Episode point or a semantic edit point.",
"oneOf": [
{
"type": "object",
"properties": {
"base_revision": {
"type": "integer"
},
"composition_seconds": {
"type": "number",
"minimum": 0,
"description": "Playable Episode second."
}
},
"required": [
"base_revision",
"composition_seconds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"base_revision": {
"type": "integer"
},
"left_occurrence_id": {
"type": [
"string",
"null"
],
"minLength": 1
},
"right_occurrence_id": {
"type": [
"string",
"null"
],
"minLength": 1
}
},
"required": [
"base_revision",
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false,
"anyOf": [
{
"properties": {
"left_occurrence_id": {
"type": "string",
"minLength": 1
}
}
},
{
"properties": {
"right_occurrence_id": {
"type": "string",
"minLength": 1
}
}
}
]
}
]
},
"configuration": {
"description": "Which saved FX asset or checked-in typed template to use. Omit only when the project already has a default for this role.",
"oneOf": [
{
"type": "string",
"enum": [
"project_default"
]
},
{
"type": "object",
"properties": {
"library_entry_id": {
"type": "string",
"minLength": 1,
"description": "Saved account FX library entry."
}
},
"required": [
"library_entry_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"template_key": {
"type": "string",
"enum": [
"outro/sting_bass",
"outro/sting_chime",
"outro/sting_glitch",
"outro/sting_shutter",
"show_open/aperture_beam",
"show_open/obscura_signal",
"show_open/studio_dissolve"
],
"description": "Checked-in template key."
},
"params": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 120
},
"subtitle": {
"type": "string",
"maxLength": 180
},
"accent": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$"
},
"sting": {
"type": "string",
"enum": [
"none",
"chime",
"bass",
"glitch",
"shutter"
]
}
},
"additionalProperties": false
}
},
"required": [
"template_key"
],
"additionalProperties": false
}
]
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable retry key for this exact insertion."
}
},
"required": [
"episode_id",
"expected_revision",
"role",
"at",
"idempotency_key"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string"
},
"revision": {
"type": "integer"
},
"duration": {
"type": "number"
},
"changed_segments": {
"type": "array",
"items": {
"type": "integer"
}
},
"inserted_occurrence_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"edge_warnings": {
"type": "array",
"items": {
"type": "object"
}
},
"stale_media": {
"type": "boolean"
},
"stale_copy": {
"type": "boolean"
},
"already_applied": {
"type": "boolean"
},
"operation_receipt_id": {
"type": "string",
"description": "Exact reversible edit receipt."
},
"before_program_digest": {
"type": "string"
},
"program_digest": {
"type": "string"
},
"camera_program_digest": {
"type": "string"
},
"audio_program_digest": {
"type": "string"
},
"inverse": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"operation.revert"
]
},
"receipt_id": {
"type": "string"
}
},
"required": [
"op",
"receipt_id"
],
"additionalProperties": false
},
"materialization_status": {
"type": "string",
"enum": [
"ready",
"preparing",
"unavailable"
]
},
"next_action": {
"type": "object"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"stale_boundary",
"idempotency_conflict",
"invalid_input",
"invalid_time_range",
"identity_slot_not_configured",
"identity_asset_not_found",
"identity_brand_mismatch",
"camera_program_conflict",
"music_anchor_transform_unsupported",
"operation_receipt_invalid",
"program_revert_conflict"
]Examples
[
{
"label": "Insert a configured opener after a sizzle",
"input": {
"episode_id": "comp_...",
"expected_revision": 7,
"role": "opener",
"at": {
"base_revision": 7,
"composition_seconds": 18.4
},
"configuration": {
"template_key": "show_open/studio_dissolve",
"params": {
"title": "Park Session",
"accent": "#f28f84",
"sting": "none"
}
},
"idempotency_key": "park-opener-after-sizzle-v1"
}
}
]episode_change_set_mutate
Run, stop, resume, or revert a durable Program edit run
One durable Program change-set action per call: start, resume, stop, or revert. start applies 1–250 ordered, receipt-backed Program occurrence operations under one durable change-set identity — the server settles each item through the ordinary episode_edit authority in bounded batches (at most 25 per internal batch), rechecks permission before every item, and may adopt only provably non-overlapping intervening edits; use result_as plus change_set_ref to address identities minted earlier in the same run; the call directly commits authorized edits without proposals or per-edit approval, and supported self-contained typed occurrences participate through the same whole-occurrence Move/Duplicate/Remove operations. Revision-bound partial removals inspected together belong in one occurrence.remove item with selection.ranges (up to 64 disjoint Ranges) and short evidence_id handles: that one item verifies a frozen snapshot and returns one exact receipt. Do not spread those Ranges across sequential items, because item one advances the revision and may retire the occurrence identities named by later evidence. resume continues the unsettled items after an interrupted request or expired worker lease; already receipted items replay idempotently and are never duplicated. stop requests a durable Stop barrier — the currently claimed atomic operation may finish, no later operation is claimed, and completed edits remain committed and individually recoverable. revert creates a new forward, revision-checked recovery change set applying the original receipts in reverse order, failing closed before the first inverse on any later overlapping work or missing receipt. The model-visible camera_program_set operation, audio-policy operations, and typed-specific object operations remain direct shared operations outside this grouped occurrence-edit schema; stop and whole-run revert do not cover them. Subject scope rides top-level: start takes episode_id; resume, stop, and revert take the durable change_set_id.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Required for start: the episode (composition) public ID, such as comp_..."
},
"change_set_id": {
"type": "string",
"description": "Required for resume, stop, and revert: durable Program change-set public ID returned by a prior start."
},
"expected_revision": {
"type": "integer",
"description": "Required for start and revert: current episode revision from a fresh episode_read."
},
"idempotency_key": {
"type": "string",
"description": "Required for start and revert: caller-stable key for exact retry. The same key plus changed input conflicts."
},
"action": {
"type": "object",
"description": "One durable change-set action. Subject ids ride top-level: episode_id for start; change_set_id for resume, stop, and revert.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"start"
]
},
"ops": {
"type": "array",
"description": "Ordered stable occurrence operations. At most 25 settle in each internal batch; one change set may contain at most 250.",
"minItems": 1,
"maxItems": 250,
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.split"
]
},
"point": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"attachment_policy": {
"type": "string",
"enum": [
"content_v1"
]
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Signed evidence for every interior Range edge. Prefer the short evidence_id returned by episode_zoom detail edit; the legacy inspection_token is accepted but is too brittle for dense model-authored runs.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred short biev_... handle."
},
"inspection_token": {
"type": "string",
"description": "Legacy full signed token."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
},
"result_as": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,39}$",
"description": "Optional name used by later change_set_ref values in this run."
}
},
"required": [
"op",
"point",
"attachment_policy",
"boundary_evidence"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.duplicate"
]
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"range"
],
"additionalProperties": false
}
]
},
"destination": {
"oneOf": [
{
"type": "object",
"properties": {
"left_occurrence_id": {
"oneOf": [
{
"type": "null"
},
{
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
]
},
"right_occurrence_id": {
"oneOf": [
{
"type": "null"
},
{
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
]
}
},
"required": [
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"at": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"at"
],
"additionalProperties": false
}
]
},
"attachment_policy": {
"type": "string",
"enum": [
"content_v1"
]
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Signed evidence for every interior Range edge. Prefer the short evidence_id returned by episode_zoom detail edit; the legacy inspection_token is accepted but is too brittle for dense model-authored runs.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred short biev_... handle."
},
"inspection_token": {
"type": "string",
"description": "Legacy full signed token."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
},
"result_as": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,39}$",
"description": "Optional name used by later change_set_ref values in this run."
}
},
"required": [
"op",
"selection",
"attachment_policy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.move"
]
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"range"
],
"additionalProperties": false
}
]
},
"destination": {
"oneOf": [
{
"type": "object",
"properties": {
"left_occurrence_id": {
"oneOf": [
{
"type": "null"
},
{
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
]
},
"right_occurrence_id": {
"oneOf": [
{
"type": "null"
},
{
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
]
}
},
"required": [
"left_occurrence_id",
"right_occurrence_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"at": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"at"
],
"additionalProperties": false
}
]
},
"attachment_policy": {
"type": "string",
"enum": [
"content_v1"
]
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Signed evidence for every interior Range edge. Prefer the short evidence_id returned by episode_zoom detail edit; the legacy inspection_token is accepted but is too brittle for dense model-authored runs.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred short biev_... handle."
},
"inspection_token": {
"type": "string",
"description": "Legacy full signed token."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
},
"result_as": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,39}$",
"description": "Optional name used by later change_set_ref values in this run."
}
},
"required": [
"op",
"selection",
"destination",
"attachment_policy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"occurrence.remove"
]
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"occurrence_ids": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"occurrence_ids"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"required": [
"range"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ranges": {
"type": "array",
"minItems": 1,
"maxItems": 64,
"items": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"occurrence_id": {
"oneOf": [
{
"type": "string",
"description": "Stable Program occurrence ID."
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"minted_occurrence_ids",
"retired_occurrence_ids",
"surviving_occurrence_ids",
"resulting_order"
]
},
"index": {
"type": "integer",
"minimum": 0
}
},
"required": [
"change_set_ref",
"field",
"index"
],
"additionalProperties": false
}
]
},
"source_seconds": {
"type": "number",
"description": "Exact inspected source-media second."
}
},
"required": [
"occurrence_id",
"source_seconds"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
"description": "Disjoint source-linked Ranges across one or many current occurrences, all inspected on the change set's starting revision and listed in current Program order. Put every partial removal from that revision in this one array; they settle atomically as one occurrence.remove item and one receipt."
}
},
"required": [
"ranges"
],
"additionalProperties": false
}
]
},
"attachment_policy": {
"type": "string",
"enum": [
"content_v1"
]
},
"boundary_evidence": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Signed evidence for every interior Range edge. Prefer the short evidence_id returned by episode_zoom detail edit; the legacy inspection_token is accepted but is too brittle for dense model-authored runs.",
"items": {
"type": "object",
"properties": {
"evidence_id": {
"type": "string",
"description": "Preferred short biev_... handle."
},
"inspection_token": {
"type": "string",
"description": "Legacy full signed token."
},
"semantic_boundary": {
"type": "object",
"properties": {
"word_id": {
"type": "string",
"pattern": "^word_[a-z0-9]{20}$",
"description": "Stable public transcript-word handle returned by the same Episode evidence surface."
},
"edge": {
"type": "string",
"enum": [
"start",
"end"
]
}
},
"required": [
"word_id",
"edge"
],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
}
},
"result_as": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,39}$",
"description": "Optional name used by later change_set_ref values in this run."
}
},
"required": [
"op",
"selection",
"attachment_policy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"operation.revert"
]
},
"receipt_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"change_set_ref": {
"type": "string",
"description": "A prior result_as name from this same change set."
},
"field": {
"type": "string",
"enum": [
"operation_receipt_id"
]
}
},
"required": [
"change_set_ref",
"field"
],
"additionalProperties": false
}
]
},
"result_as": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,39}$",
"description": "Optional name used by later change_set_ref values in this run."
}
},
"required": [
"op",
"receipt_id"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"type",
"ops"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"resume"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"stop"
]
},
"expected_activity_revision": {
"type": "integer",
"description": "Optional exact activity revision from the latest episode_change_set_read. Pass it whenever available so a stale Stop request fails closed."
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"revert"
]
}
},
"required": [
"type"
],
"additionalProperties": false
}
]
}
},
"required": [
"action"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"change_set_id": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"edit",
"revert"
]
},
"status": {
"type": "string"
},
"activity_revision": {
"type": "integer"
},
"total_operations": {
"type": "integer"
},
"committed_operations": {
"type": "integer"
},
"counts": {
"type": "object"
},
"head_revision": {
"type": "integer"
},
"head_program_digest": {
"type": "string"
},
"attribution": {
"type": "string"
},
"can_stop": {
"type": "boolean"
},
"can_revert": {
"type": "boolean"
},
"exact_revertible": {
"type": "boolean"
},
"external_adoptions": {
"type": "integer"
},
"error": {
"type": [
"object",
"null"
]
},
"summary": {
"type": "object"
},
"started_at": {
"type": [
"string",
"null"
]
},
"finished_at": {
"type": [
"string",
"null"
]
},
"stopped_at": {
"type": [
"string",
"null"
]
},
"reverted_at": {
"type": [
"string",
"null"
]
},
"reverts_change_set_id": {
"type": [
"string",
"null"
]
},
"reverted_by_change_set_id": {
"type": [
"string",
"null"
]
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"program_change_set_not_found",
"stale_composition_revision",
"stale_change_set_revision",
"idempotency_conflict",
"invalid_input",
"change_set_operation_not_supported",
"change_set_reference_invalid",
"change_set_reference_unresolved",
"change_set_authority_revoked",
"change_set_in_progress",
"change_set_reinspection_required",
"change_set_target_conflict",
"change_set_junction_conflict",
"change_set_operation_failed",
"change_set_receipt_invalid",
"change_set_revert_conflict",
"program_attachment_conflict",
"program_revert_conflict"
]episode_change_set_read
Read a Program edit run
Read authoritative progress, recovery state, and a bounded page of individual operation receipts for one durable Program change set. This does not move the Program, transport, selection, focus, viewport, zoom, or Peek state.
Input schema
{
"type": "object",
"properties": {
"change_set_id": {
"type": "string",
"description": "Durable Program change-set public ID."
},
"after": {
"type": "integer",
"description": "Optional last item position already seen."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Optional item page size; defaults to 50."
}
},
"required": [
"change_set_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"change_set_id": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"edit",
"revert"
]
},
"status": {
"type": "string"
},
"activity_revision": {
"type": "integer"
},
"total_operations": {
"type": "integer"
},
"committed_operations": {
"type": "integer"
},
"counts": {
"type": "object"
},
"head_revision": {
"type": "integer"
},
"head_program_digest": {
"type": "string"
},
"attribution": {
"type": "string"
},
"can_stop": {
"type": "boolean"
},
"can_revert": {
"type": "boolean"
},
"exact_revertible": {
"type": "boolean"
},
"external_adoptions": {
"type": "integer"
},
"error": {
"type": [
"object",
"null"
]
},
"summary": {
"type": "object"
},
"started_at": {
"type": [
"string",
"null"
]
},
"finished_at": {
"type": [
"string",
"null"
]
},
"stopped_at": {
"type": [
"string",
"null"
]
},
"reverted_at": {
"type": [
"string",
"null"
]
},
"reverts_change_set_id": {
"type": [
"string",
"null"
]
},
"reverted_by_change_set_id": {
"type": [
"string",
"null"
]
},
"items": {
"type": "array",
"items": {
"type": "object"
}
},
"next_after": {
"type": "integer"
},
"has_more": {
"type": "boolean"
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"program_change_set_not_found",
"invalid_input"
]align_span
Align or reject a span
Promote a provisional transcript-backed span to a cited span, or explicitly reject it. Accepts exactly one target: a composition segment (episode_id/composition_id plus segment_id or position) or a moment_id. Alignment only records transcript-unit anchors and boundary offsets; it preserves the existing media seconds and never invents anchors. If the recording lacks a word-timed transcript or no units overlap the evidence window, the operation returns ok:false with a typed error instead of writing fake anchors.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Episode/composition public ID when aligning a composition segment. Alias: composition_id."
},
"composition_id": {
"type": "string",
"description": "Backward-compatible alias for episode_id."
},
"segment_id": {
"type": "string",
"description": "CompositionSegment UUID when aligning a segment. Segments do not have public IDs in the current schema."
},
"position": {
"type": "integer",
"description": "Segment position within the episode, as an alternative to segment_id."
},
"moment_id": {
"type": "string",
"description": "Moment public ID to align or reject."
},
"action": {
"type": "string",
"enum": [
"auto",
"accept",
"reject"
],
"description": "auto/accept computes anchors when possible; reject records an explicit rejection marker and receipt while keeping the span provisional."
},
"transcript_window": {
"type": "object",
"description": "Optional source-time evidence window for transcript-unit overlap search. Omit to use the target's current media seconds.",
"properties": {
"start_seconds": {
"type": "number"
},
"end_seconds": {
"type": "number"
}
}
},
"reason": {
"type": "string",
"description": "Optional rejection reason or operator note."
}
},
"required": [],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"aligned",
"rejected",
"failed"
]
},
"target": {
"type": "object"
},
"span": {
"type": "object"
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
},
"receipt_id": {
"type": "string"
},
"transcript_id": {
"type": "string"
},
"transcript_version": {
"type": "string"
},
"unit_ids": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}Errors
[
"composition_not_found",
"moment_not_found",
"clip_not_found",
"invalid_time_range",
"transcript_not_word_timed",
"no_overlapping_units",
"invalid_input"
]Examples
[
{
"label": "Align a Moment",
"input": {
"moment_id": "moment_...",
"action": "accept"
}
},
{
"label": "Reject a provisional segment",
"input": {
"episode_id": "comp_...",
"segment_id": "00000000-0000-0000-0000-000000000000",
"action": "reject",
"reason": "Imported range does not match transcript evidence."
}
}
]render_create
Render an episode or clip
Render an Episode or Clip to downloadable media. Multi-segment highlight/reel/shareable-video creation uses episode_create; a single-range Clip uses clip_create. Render only the exact creator result, never a list/search result: pass its target_type, target_id, and revision as required expected_revision. Ordinary make/cut/create language is explicit private-render intent unless the user asks for draft-only, review first, or do not render. Exact-result feedback inherits one private render only when a prior ready-Output receipt or pre-edit render_status proves that exact target has a current ready Output: after committed render-affecting edits, render the final revision once under the same exceptions. Never infer this from list/search recency or mere Output existence. Publishing remains separately explicit; inherited private render intent never grants publication. First-use intro/outro blocks with new text may take a few minutes to prepare; the render waits and starts automatically once ready. This is the object-agnostic replacement for episode_render. It has no idempotency_key; the server reuses a current in-flight or ready render for the same exact revision/settings.
Input schema
{
"type": "object",
"properties": {
"target_type": {
"type": "string",
"enum": [
"episode",
"clip"
],
"description": "Object type to render."
},
"target_id": {
"type": "string",
"description": "Episode or clip public ID."
},
"format": {
"type": "string",
"enum": [
"mp4"
],
"description": "Currently mp4."
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
],
"description": "Optional render aspect ratio."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "Required exact structural revision returned by the creator (episode_create or clip_create), an edit, or a fresh episode_read. Missing or stale custody is rejected before billing or render work."
},
"expected_render_plan_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Optional exact picture fingerprint from a canvas-presented episode_sample_frames result. A mismatch is rejected before billing, queueing, or reuse of older media."
},
"title": {
"type": "string",
"description": "Optional title to apply to this render."
}
},
"required": [
"target_type",
"target_id",
"expected_revision"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"render_id": {
"type": [
"string",
"null"
]
},
"target_type": {
"type": "string"
},
"target_id": {
"type": "string"
},
"title": {
"type": "string",
"description": "Current title of the exact render target."
},
"episode_id": {
"type": "string",
"description": "Present when target_type is episode."
},
"clip_id": {
"type": "string",
"description": "Present when target_type is clip."
},
"revision": {
"type": "integer",
"description": "Authoritative current structural revision for exact Render custody and any render_create recovery."
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"render_phase": {
"type": [
"string",
"null"
]
},
"segment_count": {
"type": "integer"
},
"duration_seconds": {
"type": [
"number",
"null"
]
},
"span_summary": {
"type": "object"
},
"render_plan_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact current picture fingerprint queued, reused, or reported by this render request."
},
"media": {
"type": "object"
},
"render_generation": {
"type": [
"string",
"null"
],
"pattern": "^[0-9a-f]{64}$",
"description": "Opaque immutable identity of the exact ready MP4/poster generation. It is not render_id."
},
"exact_export_id": {
"type": [
"string",
"null"
],
"pattern": "^rxpt_[a-z0-9]+$",
"description": "Immutable retained Export identity for an Episode or Clip."
},
"export_id": {
"type": [
"string",
"null"
],
"pattern": "^rxpt_[a-z0-9]+$",
"description": "Immutable retained exact Export matching this completed render; null for imported playback without render evidence. Its absence does not prevent basic playback."
},
"download_available": {
"type": "boolean",
"description": "True only when a current private Download capability is present, including verified imported playback."
},
"download_url": {
"type": [
"string",
"null"
],
"description": "Private current Download capability when available."
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "Expiry of the returned private Download capability."
},
"skipped": {
"type": "boolean"
},
"poll": {
"type": "object",
"description": "Model-visible polling instruction; when present, wait at least poll.after_seconds before calling the named tool again."
},
"next_action": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
},
"dialogue_seam_review": {
"type": "object",
"description": "Exact-render, measurement-only evidence when this call reuses an already-current MP4."
},
"picture_program_render_receipt": {
"type": "object",
"description": "Bounded authoritative receipt for a simultaneous Picture Program already materialized when this call reuses an exact ready MP4. Absent while queued or when no Picture Program was rendered."
},
"error": {
"type": [
"object",
"null"
]
},
"render_error": {
"type": [
"object",
"null"
],
"description": "Last public render failure, retained while a retry is in flight."
},
"last_error": {
"type": [
"object",
"null"
],
"description": "Compatibility-explicit alias of render_error."
},
"render_error_history": {
"type": "array",
"items": {
"type": "object"
},
"description": "At most the three most recent public render failures."
},
"render_request_id": {
"type": [
"string",
"null"
],
"pattern": "^rrq_[a-z0-9]+$",
"description": "Exact admitted customer render request when known. Retain it with the result for recovery after navigation or a newer revision."
},
"render_attempt": {
"type": [
"integer",
"null"
]
},
"render_attempt_started_at": {
"type": [
"string",
"null"
]
},
"receipt_id": {
"type": [
"string",
"null"
]
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"music_presentation_map_unsupported",
"proof_clip_mismatch",
"invalid_input",
"billing_required"
]render_status
Check render status
Check render lifecycle and return the target's current structural revision, available render-plan hash, current-render custody, and its private/current Download when ready. A ready render includes exact rendered dialogue-seam preflight evidence in both the result and model-facing summary: inspect every flagged timestamp before accepting the edit; no markers means only that deterministic checks were clear, never that listening or taste passed. When a simultaneous Picture Program was rendered, picture_program_render_receipt is authoritative evidence of the layouts and maximum simultaneous picture count in this exact MP4; it does not certify framing taste. When render_create is needed, copy next_action.arguments exactly: they bind the current revision and available render-plan hash, so do not search documentation or reconstruct the call. Prefer render_id when available; target lookup is allowed when the target identifies one current render. The bounded wait itself is read-only and incurs no render charge. Status may refresh verified render-dependency cache stamps, but creates no Compositions or exact Exports. A never-rendered draft omits its hash on ordinary polls; include_render_plan_hash true resolves the current fingerprint for an interactive Export preflight without starting work. An in-flight hash names the queued attempt, not a newly computed current plan. Imported playback can be ready while the Composition is draft, with no render-plan hash, exact Export, or render evidence. When next_action.kind is poll_until_ready, wait at least next_action.poll_after_seconds and call render_status again until ready. When ready, inspect exact Export pixels with export_sample_frames using the returned exact export_id, render_generation, and render_plan_hash. Report private Download/editor Open; never quote or retain download_url. playback_url is embedded-app media plumbing and must never be shown or labeled as human review.
Input schema
{
"type": "object",
"properties": {
"read_scope": {
"type": "string",
"enum": [
"current",
"recorded"
],
"description": "Default current keeps existing editor semantics. recorded observes only the named target and expected_revision, optionally pinned by plan, request or exact Export. It never starts work. Its result is bitterclip.result_delivery.v1, separate from current-render status."
},
"exact_export_id": {
"type": "string",
"pattern": "^rxpt_[a-z0-9]+$",
"description": "Recorded scope only: immutable exact Export (rxpt_...). Never redirects to a newer version."
},
"render_request_id": {
"type": "string",
"pattern": "^rrq_[a-z0-9]+$",
"description": "Recorded scope only: exact admitted render request."
},
"include_download": {
"type": "boolean",
"description": "Recorded scope only: reauthorize an exact retained Export for an explicit download. Capabilities are ephemeral; do not retain them in history or model prose."
},
"render_id": {
"type": "string",
"description": "Render public ID when available."
},
"target_type": {
"type": "string",
"enum": [
"episode",
"clip"
]
},
"target_id": {
"type": "string",
"description": "Episode or clip public ID."
},
"episode_id": {
"type": "string",
"description": "Compatibility alias for a target Episode handle."
},
"clip_id": {
"type": "string",
"description": "Compatibility alias for a target Clip handle."
},
"include_render_plan_hash": {
"type": "boolean",
"description": "Current scope only: resolve the exact current fingerprint for a never-rendered draft before interactive Export. Default false keeps ordinary polls plan-free. In-flight status still reports its queued attempt hash; imported playback has no computed render hash. Does not start a render."
},
"wait_for_seconds": {
"type": "integer",
"minimum": 0,
"maximum": 20,
"description": "Optional server-backed bounded wait. Returns immediately on ready, failed, stale identity, or another terminal state; default 0."
},
"expected_revision": {
"type": "integer",
"minimum": 0,
"description": "Optional exact structural revision. A mismatch fails immediately instead of settling a newer edit."
},
"expected_render_plan_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Optional exact render-plan fingerprint. Missing or changed identity fails closed."
},
"format": {
"type": "string",
"enum": [
"mp4"
]
},
"aspect_ratio": {
"type": "string",
"enum": [
"9:16",
"16:9",
"1:1"
]
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"render_id"
]
},
{
"required": [
"target_id"
]
},
{
"required": [
"episode_id"
]
},
{
"required": [
"clip_id"
]
}
]
}Output schema
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "bitterclip.result_delivery.v1",
"description": "Present only for read_scope recorded; fields below describe the exact recorded work, with no replacement title."
},
"target": {
"type": "object",
"properties": {
"type": {
"enum": [
"episode",
"clip"
]
},
"id": {
"type": "string"
}
}
},
"execution": {
"type": "string",
"enum": [
"saved",
"queued",
"rendering",
"ready",
"failed",
"cancelling",
"cancelled",
"unknown"
]
},
"current_revision": {
"type": "integer",
"minimum": 0,
"description": "Recorded reads only: current visible structural revision, independent of the recorded revision."
},
"currentness": {
"type": "string",
"enum": [
"current",
"earlier"
]
},
"availability": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"request_id": {
"type": [
"string",
"null"
],
"pattern": "^rrq_[a-z0-9]+$"
},
"attempt_id": {
"type": "string"
},
"reason": {
"type": "string",
"enum": [
"ambiguous_result",
"export_unavailable",
"no_admitted_render",
"superseded"
]
},
"render_id": {
"type": [
"string",
"null"
]
},
"target_type": {
"type": "string"
},
"target_id": {
"type": "string"
},
"title": {
"type": "string",
"description": "Current title of the exact render target."
},
"episode_id": {
"type": "string",
"description": "Present when target_type is episode."
},
"clip_id": {
"type": "string",
"description": "Present when target_type is clip."
},
"revision": {
"type": "integer",
"minimum": 0,
"description": "Current structural revision of the target."
},
"render_plan_hash": {
"type": [
"string",
"null"
],
"pattern": "^[0-9a-f]{64}$",
"description": "Resolved current fingerprint when available; during an in-flight attempt this is the durable queued fingerprint, and imported playback has none. Never-rendered drafts return it only with include_render_plan_hash true. When available for render_create, it is also present as next_action.arguments.expected_render_plan_hash."
},
"status": {
"type": "string"
},
"progress": {
"type": "number"
},
"render_phase": {
"type": [
"string",
"null"
]
},
"span_summary": {
"type": "object"
},
"media": {
"type": "object"
},
"render_generation": {
"type": [
"string",
"null"
],
"pattern": "^[0-9a-f]{64}$",
"description": "Opaque immutable identity of the exact ready MP4/poster generation. It is not render_id."
},
"exact_export_id": {
"type": [
"string",
"null"
],
"pattern": "^rxpt_[a-z0-9]+$",
"description": "Immutable retained Export identity for an Episode or Clip."
},
"export_id": {
"type": [
"string",
"null"
],
"pattern": "^rxpt_[a-z0-9]+$",
"description": "Immutable retained exact Export matching this completed render; null for imported playback without render evidence. Its absence does not prevent basic playback."
},
"download_available": {
"type": "boolean",
"description": "True only when a current private Download capability is present, including verified imported playback."
},
"playback_url": {
"type": [
"string",
"null"
],
"description": "Embedded-app-only inline media. Never expose it as user-facing review or delivery; use private/current download_url plus editor Open."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "Embedded-app-only exact current Render poster. Never expose or retain it in model prose."
},
"download_url": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
]
},
"poll": {
"type": "object",
"description": "Model-visible polling instruction; when present, wait at least poll.after_seconds before calling render_status again."
},
"next_action": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
},
"dialogue_seam_review": {
"type": "object",
"description": "Exact-render, measurement-only evidence for ordinary dialogue Junctions, including treated Crossfade regions. Markers prioritize bounded review; they are not a quality score or automatic rejection."
},
"picture_program_render_receipt": {
"type": "object",
"description": "Bounded authoritative receipt for a simultaneous Picture Program materialized in this exact current MP4: layout keys, scene count, maximum simultaneous pictures, and Program-audio authority. Present only when the renderer used a Picture Program; not a framing-quality score."
},
"error": {
"type": [
"object",
"null"
]
},
"render_error": {
"type": [
"object",
"null"
],
"description": "Last public render failure, retained while a retry is in flight."
},
"last_error": {
"type": [
"object",
"null"
],
"description": "Compatibility-explicit alias of render_error."
},
"render_error_history": {
"type": "array",
"items": {
"type": "object"
},
"description": "At most the three most recent public render failures."
},
"render_request_id": {
"type": [
"string",
"null"
],
"pattern": "^rrq_[a-z0-9]+$",
"description": "Exact admitted customer render request when known. Retain it with the result for recovery after navigation or a newer revision."
},
"render_attempt": {
"type": [
"integer",
"null"
]
},
"render_attempt_started_at": {
"type": [
"string",
"null"
]
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"composition_not_found",
"stale_composition_revision",
"invalid_input"
]export_sample_frames
Sample pixels from the exact current Export
Pure-read pixel inspection of one exact rendered Export MP4, including burned overlays and captions. Pass the exact export_id, expected_render_generation, and expected_render_plan_hash from render_status plus 1–4 finite nonnegative Export-timeline seconds. This does not settle status, mint URLs, publish frames, bill, render, or mutate. Exact retained Export frames establish only the content of each sampled still, including burned overlays and captions at that instant. Report only literal visible content at that sampled instant. A visible anomaly may be described as a candidate for further review. A still alone does not establish an objective Export or renderer defect, its cause, a violated invariant, or overall quality. Those conclusions require independently bound temporal or implementation evidence, or human review. Keep Program structure, sampled still pixels, decoded temporal artifact evidence, implementation evidence, and human judgment distinct. Not observable from isolated stills: motion, transition smoothness, cut abruptness or naturalness, caption synchronization or correctness across time, audio, overall taste, and human acceptance. Plan one bounded 1–4-frame board for this still inspection pass; do not repeat identical or subset points in the same user turn. At most one explicitly novel follow-up may add evidence. For a short multi-cut Export, retained inspection includes the opening picture, the near-EOF final picture, and both sides of every render_status-flagged Junction. When four frames cannot cover that set, use the allowed novel follow-up. A seam-only board leaves endpoint inspection incomplete and cannot support a quality-ready or finished claim. Render-ready remains lifecycle state. Tool-use-only custody; no capability URLs. Do not use render_status or episode_status as a pixel observer. Frames are tool-use-only; no capability URLs.
Input schema
{
"type": "object",
"properties": {
"export_id": {
"type": "string",
"description": "Exact retained Export handle (rxpt_...) from render_status or result delivery. Foreign handles fail closed and no handle redirects to another generation."
},
"expected_render_generation": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact 64-hex current render generation for this Export. A mismatch fails closed."
},
"expected_render_plan_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact 64-hex current render-plan hash for this Export. A mismatch fails closed."
},
"times": {
"type": "array",
"description": "Explicit Export-timeline seconds to sample from the finished MP4. Plan one bounded 1–4-frame board for this still inspection pass; do not repeat identical or subset points in the same user turn. One through four finite nonnegative values only. At most one explicitly novel follow-up may add evidence.",
"items": {
"type": "number",
"minimum": 0
},
"minItems": 1,
"maxItems": 4
}
},
"required": [
"export_id",
"expected_render_generation",
"expected_render_plan_hash",
"times"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"export_id": {
"type": "string",
"description": "Exact Export sampled."
},
"clip_id": {
"type": "string",
"description": "Composition handle of the Clip or Episode that owns this Export."
},
"composition_id": {
"type": "string",
"description": "Same Composition handle as clip_id."
},
"render_generation": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact generation sampled."
},
"render_plan_hash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact render-plan hash sampled."
},
"duration_seconds": {
"type": "number",
"description": "Export timeline duration."
},
"model_image_count": {
"type": "integer",
"description": "Number of adjacent JPEG image blocks; at most four."
},
"custody": {
"type": "string",
"enum": [
"tool_use_only"
],
"description": "Frames exist only for this tool turn. They mint no capability URLs."
},
"limitations": {
"type": "string",
"description": "Exact retained Export frames establish only the content of each sampled still, including burned overlays and captions at that instant. Report only literal visible content at that sampled instant. A visible anomaly may be described as a candidate for further review. A still alone does not establish an objective Export or renderer defect, its cause, a violated invariant, or overall quality. Those conclusions require independently bound temporal or implementation evidence, or human review. Keep Program structure, sampled still pixels, decoded temporal artifact evidence, implementation evidence, and human judgment distinct. Not observable from isolated stills: motion, transition smoothness, cut abruptness or naturalness, caption synchronization or correctness across time, audio, overall taste, and human acceptance. Plan one bounded 1–4-frame board for this still inspection pass; do not repeat identical or subset points in the same user turn. At most one explicitly novel follow-up may add evidence. For a short multi-cut Export, retained inspection includes the opening picture, the near-EOF final picture, and both sides of every render_status-flagged Junction. When four frames cannot cover that set, use the allowed novel follow-up. A seam-only board leaves endpoint inspection incomplete and cannot support a quality-ready or finished claim. Render-ready remains lifecycle state. Tool-use-only custody; no capability URLs."
},
"frames": {
"type": "array",
"description": "Per-frame Export-timeline captions and dimensions. Adjacent MCP image blocks are the pixels; no gallery or capability URLs.",
"items": {
"type": "object",
"properties": {
"caption": {
"type": "string",
"description": "Truthful Export-timeline caption bound to this export, generation, and plan. Each still establishes only that frame's pixels; isolated stills cannot observe motion, cut abruptness, or caption synchronization across time. Report only literal visible content at that sampled instant. A visible anomaly may be described as a candidate for further review. A still alone does not establish an objective Export or renderer defect, its cause, a violated invariant, or overall quality. Those conclusions require independently bound temporal or implementation evidence, or human review. Keep Program structure, sampled still pixels, decoded temporal artifact evidence, implementation evidence, and human judgment distinct."
},
"export_seconds": {
"type": "number"
},
"export_timecode": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"mime_type": {
"type": "string",
"enum": [
"image/jpeg"
]
}
},
"required": [
"caption",
"export_seconds",
"export_timecode",
"width",
"height",
"mime_type"
]
}
}
},
"required": [
"export_id",
"clip_id",
"composition_id",
"render_generation",
"render_plan_hash",
"duration_seconds",
"model_image_count",
"custody",
"limitations",
"frames"
],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"invalid_input",
"time_out_of_range",
"export_not_found",
"export_not_current",
"render_changed",
"render_output_unavailable",
"ffmpeg_busy",
"ffmpeg_missing",
"export_sample_timeout",
"frame_extraction_failed",
"frame_extraction_containment_unknown",
"frame_sample_cleanup_failed",
"payload_budget_exceeded"
]Examples
[
{
"label": "Inspect two points on the exact current Export",
"input": {
"export_id": "rxpt_...",
"expected_render_generation": "0000000000000000000000000000000000000000000000000000000000000000",
"expected_render_plan_hash": "0000000000000000000000000000000000000000000000000000000000000000",
"times": [
0,
1.2
]
}
}
]output_public_url
Create public MP4 review and download links
Create expiring public review and direct-download URLs for one exact finished BitterClip render. The review URL is the practical human handoff; download_url remains the primitive for external services that ingest a public video URL (captioning/styling connectors like Submagic, Zapier steps, publishing tools). Pass exactly ONE target: episode_id when you have an Episode/derived-clip handle, OR render_id when you only have the ready render artifact; never pass both. A derived clip's comp_... handle goes in episode_id. This tool never starts or retries rendering: if render_not_ready, call episode_render and wait for episode_status/render_status to report ready, then retry with one target. Repeating the call for the same ready render is safe and does not enqueue or mutate a render; it only returns fresh expiring bearer URLs. A later render invalidates these links rather than silently showing a different cut. When a UI supplied expected_render_generation, pass it back so a stale card fails instead of sharing a newer Render. Pair download_url with title and dictionary when the receiving service wants context.
Input schema
{
"type": "object",
"properties": {
"episode_id": {
"type": "string",
"description": "Use this single target when you have an Episode or derived-clip composition ID such as comp_...; recording handles src_... resolve to their episode-of-one. Do not also pass render_id."
},
"render_id": {
"type": "string",
"description": "Use this single target only when you have the ready rart_... render artifact from episode_status/render_status. Do not also pass episode_id."
},
"expires_in_days": {
"type": "integer",
"minimum": 1,
"maximum": 14,
"description": "Link lifetime in days. Default 7; minimum 1, maximum 14."
},
"expected_render_generation": {
"type": "string",
"description": "Optional opaque optimistic precondition from an Outputs result. If that exact rendered generation changed, this call fails instead of sharing a newer cut."
}
},
"required": [],
"additionalProperties": false,
"oneOf": [
{
"required": [
"episode_id"
],
"not": {
"required": [
"render_id"
]
}
},
{
"required": [
"render_id"
],
"not": {
"required": [
"episode_id"
]
}
}
]
}Output schema
{
"type": "object",
"properties": {
"review_url": {
"type": "string",
"description": "Public, expiring review page for this exact Render."
},
"download_url": {
"type": "string",
"description": "Public, expiring direct-download MP4 URL."
},
"watch_url": {
"type": "string",
"description": "Compatibility alias for review_url."
},
"title": {
"type": "string",
"description": "Episode/clip title, for the receiving service."
},
"content_type": {
"type": "string",
"enum": [
"video/mp4"
]
},
"duration_seconds": {
"type": [
"number",
"null"
]
},
"size_bytes": {
"type": [
"integer",
"null"
]
},
"render_generation": {
"type": "string",
"description": "Opaque identity for the exact rendered bytes and poster bound to these URLs."
},
"expires_at": {
"type": "string",
"description": "ISO8601 expiry timestamp."
},
"dictionary": {
"type": "array",
"items": {
"type": "string"
},
"description": "Account, project, speaker, and brand names a captioning service should preserve."
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": true
}Errors
[
"render_not_ready",
"render_output_unavailable",
"render_changed",
"not_found",
"forbidden",
"invalid_input"
]Examples
[
{
"label": "Handoff a ready Episode or derived clip",
"input": {
"episode_id": "comp_...",
"expires_in_days": 7
}
},
{
"label": "Handoff when only the ready render artifact is in context",
"input": {
"render_id": "rart_...",
"expires_in_days": 7
}
}
]publish_prepare
Prepare a publish package
Create reviewable publish packages for an episode or clip. This never publishes externally; a fresh server-bound final confirmation is required before any send and is ordinarily surfaced in the first-party workspace. App-only descriptor visibility does not itself restrict authenticated MCP transport or prove human review. Put improved YouTube/LinkedIn/X titles, descriptions, and copy here (or in publish_update) rather than mutating the saved episode with episode_update.
Input schema
{
"type": "object",
"properties": {
"target_type": {
"type": "string",
"enum": [
"episode",
"clip"
],
"description": "Object to publish."
},
"target_id": {
"type": "string",
"description": "Rendered episode/clip public ID or ready export public ID."
},
"channels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"youtube",
"linkedin",
"x"
]
}
},
"title": {
"type": "string",
"description": "Optional publish title."
},
"description": {
"type": "string",
"description": "Optional publish description."
},
"copy": {
"type": [
"object",
"string"
],
"description": "Optional channel copy hints. Object values may be keyed by channel plus default."
},
"idempotency_key": {
"type": "string",
"description": "Caller-stable key for safe retry."
}
},
"required": [
"target_type",
"target_id"
],
"additionalProperties": false
}Output schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": [
"string",
"null"
]
},
"target_type": {
"type": "string"
},
"target_id": {
"type": "string"
},
"status": {
"type": "string"
},
"publish_mode": {
"type": "string",
"enum": [
"approval"
]
},
"channels": {
"type": "array"
},
"approvals": {
"type": "array"
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"next_action": {
"type": [
"object",
"null"
]
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"export_not_found",
"composition_not_ready",
"composition_has_no_source",
"publish_not_ready",
"invalid_platforms",
"idempotency_conflict",
"invalid_input"
]publish_update
Update a publish package
Edit copy for a reviewable publish package or approval item before it is published. If the package was already approved, the edit supersedes that decision and returns the package to review. This does not publish externally.
Input schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": "string",
"description": "Approval/package public ID."
},
"approval_id": {
"type": "string",
"description": "Approval/package public ID alias."
},
"title": {
"type": "string",
"description": "Optional title. Currently retained by package-specific backends when supported."
},
"description": {
"type": "string",
"description": "Optional description. Currently maps to channel copy where supported."
},
"copy": {
"type": [
"object",
"string"
],
"description": "Optional channel body copy. Object values may be keyed by channel plus default."
},
"boost": {
"type": "string",
"description": "Optional X quote-boost copy."
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"publish_package_id"
]
},
{
"required": [
"approval_id"
]
}
]
}Output schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": "string"
},
"approval_id": {
"type": "string"
},
"status": {
"type": "string"
},
"ready_to_publish": {
"type": "boolean"
},
"composed_copy": {
"type": "object",
"description": "Refreshed channel copy, such as post_body and boost when present."
},
"publish_state": {
"type": "object",
"description": "Canonical BitterClip publish-state envelope for web, mobile, MCP/App widgets, and AI cockpit tools. Use stage first for the current product state and next action.",
"properties": {
"schema_version": {
"type": "string"
},
"object": {
"type": "object",
"description": "Current publish object identity, using public IDs only.",
"properties": {
"kind": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"recording_id": {
"type": [
"string",
"null"
]
},
"clip_id": {
"type": [
"string",
"null"
]
},
"composition_id": {
"type": [
"string",
"null"
]
},
"export_id": {
"type": [
"string",
"null"
]
},
"approval_id": {
"type": "string"
},
"platform": {
"type": "string"
}
}
},
"media": {
"type": "object",
"description": "Whether the media asset can be published.",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"rendering",
"failed",
"missing",
"render_required",
"stale"
]
},
"ready": {
"type": "boolean"
},
"source": {
"type": "string"
},
"message": {
"type": "string"
},
"download_url": {
"type": [
"string",
"null"
]
}
}
},
"package": {
"type": "object",
"description": "Reviewable package readiness and approval state.",
"properties": {
"status": {
"type": "string",
"enum": [
"missing",
"needs_review",
"approved",
"published",
"failed",
"blocked",
"manual_handoff",
"ready",
"rendering",
"render_required",
"stale"
]
},
"ready": {
"type": "boolean"
},
"approval_status": {
"type": "string"
},
"explicit_approval_required": {
"type": "boolean"
},
"kind": {
"type": "string"
},
"mode": {
"type": "string"
},
"review_url": {
"type": "string"
},
"checks_summary": {
"type": "object"
}
}
},
"copy": {
"type": "object",
"description": "Destination-copy readiness and formatting state.",
"properties": {
"status": {
"type": "string"
},
"format": {
"type": "string"
},
"ready": {
"type": "boolean"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"body_present": {
"type": "boolean"
},
"text_present": {
"type": "boolean"
},
"body_preview": {
"type": [
"string",
"null"
]
},
"message": {
"type": "string",
"description": "Plain-language copy readiness summary for primary UI and model responses."
},
"preview_lines": {
"type": "array",
"items": {
"type": "string"
},
"description": "First non-empty destination-copy lines, preserving platform-native paragraph and bullet structure for compact UI."
},
"line_count": {
"type": "integer"
},
"character_count": {
"type": "integer"
},
"platform_native": {
"type": "boolean"
}
}
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"platform": {
"type": "string"
},
"platform_key": {
"type": "string"
},
"label": {
"type": "string"
},
"readiness": {
"type": "string",
"enum": [
"connected",
"missing_auth",
"permission_limited",
"capped",
"unsupported",
"manual_handoff",
"blocked"
]
},
"configured": {
"type": "boolean"
},
"package_mode": {
"type": "string"
},
"package": {
"type": "object",
"properties": {
"status": {
"type": [
"string",
"null"
]
},
"ready": {
"type": [
"boolean",
"null"
]
},
"approval_id": {
"type": [
"string",
"null"
]
},
"approval_public_id": {
"type": [
"string",
"null"
]
},
"approval_status": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"mode": {
"type": [
"string",
"null"
]
},
"link_platform": {
"type": [
"string",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
}
}
},
"attempt_state": {
"type": "string"
},
"reconciliation_state": {
"type": [
"string",
"null"
]
},
"cleanup_state": {
"type": [
"string",
"null"
]
},
"latest_publish_record_id": {
"type": [
"string",
"null"
]
},
"external_url": {
"type": [
"string",
"null"
]
},
"external_urls": {
"type": "array",
"items": {
"type": "string"
}
},
"safe_to_retry": {
"type": "boolean"
},
"can_prepare_package": {
"type": [
"boolean",
"null"
]
},
"selected_by_default": {
"type": [
"boolean",
"null"
]
},
"can_publish_approval": {
"type": [
"boolean",
"null"
]
},
"attempts": {
"type": "array",
"items": {
"type": "object"
}
},
"next_action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"stage": {
"type": "object",
"description": "Compact product-language state for above-the-fold UI and model narration. Read this first.",
"required": [
"status",
"label",
"message",
"blocking",
"ready_to_publish"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ready_to_publish",
"ready_to_package",
"needs_review",
"needs_destination",
"destination_blocked",
"manual_handoff",
"copy_needs_review",
"needs_reconciliation",
"cleanup_failed",
"publishing",
"published",
"rendering",
"render_required",
"stale",
"missing",
"failed"
]
},
"label": {
"type": "string"
},
"message": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"ready_to_publish": {
"type": "boolean"
},
"action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
}
}
},
"next_action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
}
},
"required": [
"schema_version",
"object",
"media",
"package",
"copy",
"destinations",
"stage"
]
},
"next_action": {
"type": [
"object",
"null"
],
"description": "Safe next action or recovery action in product terms. Tool fields are partial instructions; callers must supply any required_fields that are not present in arguments.",
"properties": {
"kind": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"message": {
"type": [
"string",
"null"
]
},
"safe_to_retry": {
"type": [
"boolean",
"null"
]
},
"publish_record_id": {
"type": [
"string",
"null"
]
},
"publish_record_public_id": {
"type": [
"string",
"null"
]
},
"cleanup_tool": {
"type": [
"string",
"null"
]
},
"reconcile_tool": {
"type": [
"string",
"null"
]
},
"inspect_tool": {
"type": [
"string",
"null"
]
},
"retry_tool": {
"type": [
"string",
"null"
]
},
"publish_tool": {
"type": [
"string",
"null"
]
},
"tool_name": {
"type": [
"string",
"null"
]
},
"poll_tool": {
"type": [
"string",
"null"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"arguments": {
"type": "object"
},
"url": {
"type": [
"string",
"null"
]
},
"review_url": {
"type": [
"string",
"null"
]
},
"settings_path": {
"type": [
"string",
"null"
]
},
"authorize_path": {
"type": [
"string",
"null"
]
}
}
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"approval_not_found",
"publish_not_editable",
"no_changes",
"invalid_input"
]publish_send
Open publish review
Return a no-effect workspace review handoff for supplied ApprovalItem/package ID(s). This model-visible handoff never creates a PublishRecord, queues work, resolves authorization, or sends anything externally. The ordinary product flow resolves and displays the exact package, destination, copy, and thumbnail in the workspace before a fresh server-bound final confirmation can publish; its app-only descriptor visibility is not an authenticated-MCP transport or human-review boundary.
Input schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": "string",
"description": "Approval/package public ID."
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Approval item IDs to review. To review multiple prepared channels, pass every approval_id from publish_prepare.approval_ids."
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"publish_package_id"
]
},
{
"required": [
"approval_ids"
]
}
]
}Output schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": "string"
},
"approval_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"review_required"
]
},
"publish_records": {
"type": "array",
"items": {
"type": "object"
}
},
"next_action": {
"type": [
"object",
"null"
]
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"invalid_input"
]publish_status
Get publish status
Check package, approval, or external publish lifecycle. Returns concrete external URLs only when BitterClip has verified them.
Input schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": "string",
"description": "Approval/package public ID."
},
"approval_id": {
"type": "string",
"description": "Approval/package public ID alias."
},
"publish_record_id": {
"type": "string",
"description": "Publish record public ID."
}
},
"required": [],
"additionalProperties": false,
"anyOf": [
{
"required": [
"publish_package_id"
]
},
{
"required": [
"approval_id"
]
},
{
"required": [
"publish_record_id"
]
}
]
}Output schema
{
"type": "object",
"properties": {
"publish_package_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"approvals": {
"type": "array"
},
"publish_records": {
"type": "array",
"items": {
"type": "object"
}
},
"recovery": {
"type": "object"
},
"blockers": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [],
"additionalProperties": false
}Annotations
{
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}Errors
[
"approval_not_found",
"publish_record_not_found",
"invalid_input"
]