View as Markdown

All MCP tools

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.

Surface: Default model and app

Product release 1dce717408a55fac1047e7d779177fa3ef8ede51
Public contract commit 1ce47f7857ae3d9b6933fe83d5c33de3ae5efc64
Public contract SHA-256 241d47d25e4b4c1dae9d2263793874d06fc4ba7bc3c78d4cf2bc63fbb32ed7dc
Captured 2026-09-24T16:39:30.100Z. Review or improve this contract on GitHub.

These blocks show the complete MCP descriptors captured from serving Rails. Security schemes and resource URIs can differ by connected host.

Default model descriptor

{
  "name": "clip_create_portrait_sibling",
  "title": "Create a portrait sibling clip",
  "description": "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.",
  "inputSchema": {
    "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
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  }
}

App descriptor

{
  "name": "clip_create_portrait_sibling",
  "title": "Create a portrait sibling clip",
  "description": "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.",
  "inputSchema": {
    "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
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  },
  "outputSchema": {
    "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
  }
}

Live Workspace descriptor

{
  "name": "clip_create_portrait_sibling",
  "title": "Create a portrait sibling clip",
  "description": "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.",
  "inputSchema": {
    "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
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  },
  "outputSchema": {
    "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"
        }
      },
      "workspace_binding": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "bitterclip.workspace-binding.v2"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "live_workspace"
            ]
          },
          "project_id": {
            "type": "string"
          },
          "target_kind": {
            "type": "string",
            "enum": [
              "episode",
              "clip"
            ]
          },
          "target_id": {
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "draft_revision": {
            "type": "string"
          },
          "workspace_url": {
            "type": "string"
          },
          "output_id": {
            "type": "string"
          },
          "output_status": {
            "type": "string",
            "enum": [
              "missing",
              "stale",
              "rendering",
              "ready",
              "failed"
            ]
          },
          "output_revision": {
            "type": "integer"
          },
          "parent_episode_id": {
            "type": "string"
          }
        },
        "required": [
          "schema",
          "mode",
          "target_kind",
          "target_id",
          "revision",
          "draft_revision",
          "workspace_url",
          "output_status"
        ],
        "additionalProperties": false
      }
    },
    "required": [],
    "additionalProperties": 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",
  "angle_interval_exceeds_recording"
]

Examples

[]