episode_zoom
Inspect episode media at a candidate boundary
Inspects chosen cut boundaries: at most 6 windows per call, each <=12 seconds (typically 5–6), and at most 4 measured edges TOTAL across all windows. Broad transcript discovery is episode_read. 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. It inspects 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, because one Program timestamp does not imply one source boundary. Zoom measures what resolved Program Audio plays at each point: the occurrence's own Recording, a pinned or Replace Recording at its mapped source second (named `inspected_recording_id`; speech source coordinates are in it), or nothing under mute or silence, where a `silent_authority` receipt certifies only that no Program Audio speech edge is there. `audible_authority` names the side and authority (occurrence_base, pinned_primary, explicit_replace, explicit_silence, silence; `unresolved` certifies nothing). Where an authority begins exactly at a point, its before and after sides are measured and signed separately; an edit needs the receipt for each side it plays. A receipt stays valid across other edits until its occurrence, the inspected media or transcript, or Program Audio at that point changes. `rejected` + `inside_word` marks a point inside a word, which receives no receipt. 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; each has its own 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; BitterClip does not snap a merely nearby point to the disclosed exact aligned endpoint, which a query can name directly. A supported point's evidence handle is accepted by `episode_edit` as is; for a Trim, only a changed edge needs a `detail:"edit"` measurement. It follows episode_read, which 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: probe_busy means the aligner, ONE serialized resource, was busy with another call, and a later single call can succeed; alignment_failed | alignment_sequence_mismatch | unsupported_transcript_token | out_of_vocabulary mean the probe already retried a point-focused (and, where eligible, tail) window, so re-zooming the same edge returns the same verdict and the point stays listen_required unless the edge moves; remaining reasons describe invalid or insufficient input. One call can batch related windows; decoding and alignment work scales with the measured source sides. It measures candidate edit and review boundaries, not Project recaps. `detail` controls progressive disclosure: lean (semantic discovery), cut (adds raw audio envelopes), edit (adds signed exact boundary receipts), or diagnostic (adds raw detector provenance). A structural Split or partial Range accepts each evidence_id or inspection_token only unchanged. 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. 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. Timestamps are episode time unless a field ends in _source. Measurements only; it places no cut. Read-only.
Surface: Default model and app
Product release eb8538f4a297f331d0399351c1e175bffcd212d2
Public contract commit 20688e11af473a363145ed880d5019c90a7ec1e2
Public contract SHA-256 87a94b85a84dc19245fc03f9b544c70d64bd9f5e08585dcccb38157cace5700d
Captured 2026-10-04T11:55:45.577Z. 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": "episode_zoom",
"title": "Inspect episode media at a candidate boundary",
"description": "Inspects chosen cut boundaries: at most 6 windows per call, each <=12 seconds (typically 5–6), and at most 4 measured edges TOTAL across all windows. Broad transcript discovery is episode_read. 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. It inspects 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, because one Program timestamp does not imply one source boundary. Zoom measures what resolved Program Audio plays at each point: the occurrence's own Recording, a pinned or Replace Recording at its mapped source second (named `inspected_recording_id`; speech source coordinates are in it), or nothing under mute or silence, where a `silent_authority` receipt certifies only that no Program Audio speech edge is there. `audible_authority` names the side and authority (occurrence_base, pinned_primary, explicit_replace, explicit_silence, silence; `unresolved` certifies nothing). Where an authority begins exactly at a point, its before and after sides are measured and signed separately; an edit needs the receipt for each side it plays. A receipt stays valid across other edits until its occurrence, the inspected media or transcript, or Program Audio at that point changes. `rejected` + `inside_word` marks a point inside a word, which receives no receipt. 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; each has its own 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; BitterClip does not snap a merely nearby point to the disclosed exact aligned endpoint, which a query can name directly. A supported point's evidence handle is accepted by `episode_edit` as is; for a Trim, only a changed edge needs a `detail:\"edit\"` measurement. It follows episode_read, which 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: probe_busy means the aligner, ONE serialized resource, was busy with another call, and a later single call can succeed; alignment_failed | alignment_sequence_mismatch | unsupported_transcript_token | out_of_vocabulary mean the probe already retried a point-focused (and, where eligible, tail) window, so re-zooming the same edge returns the same verdict and the point stays listen_required unless the edge moves; remaining reasons describe invalid or insufficient input. One call can batch related windows; decoding and alignment work scales with the measured source sides. It measures candidate edit and review boundaries, not Project recaps. `detail` controls progressive disclosure: lean (semantic discovery), cut (adds raw audio envelopes), edit (adds signed exact boundary receipts), or diagnostic (adds raw detector provenance). A structural Split or partial Range accepts each evidence_id or inspection_token only unchanged. 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. 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. Timestamps are episode time unless a field ends in _source. Measurements only; it places no cut. Read-only.",
"inputSchema": {
"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 around ONE cut point (typically ~5–6s, hard cap 12s; a longer region is rejected), not the clip body, whose full transcript episode_read already returns. 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`, one per source side. Recommendation/confidence are amplitude geometry only; `ok` is not semantic or word-boundary proof and can be inside a word, while `speech` carries the word evidence. Raw 30ms bins come only from detail:cut or include:[\"audio_envelope\"]. 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. word_provenance returns the exact caption word_id and text for an occurrence.caption word correction; compact transcript tuples omit IDs and speech-alignment IDs are different. Other raw channels are opt-in.",
"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 inspected in a SINGLE call, the alternative to `region` for a clip's two edges (a 45s clip is 2 small windows here, not one big region or two calls). Each window is an edge window only (typically ~5–6s, hard cap 12s; a longer window is rejected), not 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 (typically 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, counted across every regions[].edges in the 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"
]
}
]
}
}
]
}
]
},
"annotations": {
"title": "Inspect episode media at a candidate boundary",
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
],
"ui": {
"visibility": [
"model",
"app"
]
},
"openai/widgetAccessible": true
}
}App descriptor
{
"name": "episode_zoom",
"title": "Inspect episode media at a candidate boundary",
"description": "Inspects chosen cut boundaries: at most 6 windows per call, each <=12 seconds (typically 5–6), and at most 4 measured edges TOTAL across all windows. Broad transcript discovery is episode_read. 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. It inspects 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, because one Program timestamp does not imply one source boundary. Zoom measures what resolved Program Audio plays at each point: the occurrence's own Recording, a pinned or Replace Recording at its mapped source second (named `inspected_recording_id`; speech source coordinates are in it), or nothing under mute or silence, where a `silent_authority` receipt certifies only that no Program Audio speech edge is there. `audible_authority` names the side and authority (occurrence_base, pinned_primary, explicit_replace, explicit_silence, silence; `unresolved` certifies nothing). Where an authority begins exactly at a point, its before and after sides are measured and signed separately; an edit needs the receipt for each side it plays. A receipt stays valid across other edits until its occurrence, the inspected media or transcript, or Program Audio at that point changes. `rejected` + `inside_word` marks a point inside a word, which receives no receipt. 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; each has its own 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; BitterClip does not snap a merely nearby point to the disclosed exact aligned endpoint, which a query can name directly. A supported point's evidence handle is accepted by `episode_edit` as is; for a Trim, only a changed edge needs a `detail:\"edit\"` measurement. It follows episode_read, which 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: probe_busy means the aligner, ONE serialized resource, was busy with another call, and a later single call can succeed; alignment_failed | alignment_sequence_mismatch | unsupported_transcript_token | out_of_vocabulary mean the probe already retried a point-focused (and, where eligible, tail) window, so re-zooming the same edge returns the same verdict and the point stays listen_required unless the edge moves; remaining reasons describe invalid or insufficient input. One call can batch related windows; decoding and alignment work scales with the measured source sides. It measures candidate edit and review boundaries, not Project recaps. `detail` controls progressive disclosure: lean (semantic discovery), cut (adds raw audio envelopes), edit (adds signed exact boundary receipts), or diagnostic (adds raw detector provenance). A structural Split or partial Range accepts each evidence_id or inspection_token only unchanged. 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. 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. Timestamps are episode time unless a field ends in _source. Measurements only; it places no cut. Read-only.",
"inputSchema": {
"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 around ONE cut point (typically ~5–6s, hard cap 12s; a longer region is rejected), not the clip body, whose full transcript episode_read already returns. 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`, one per source side. Recommendation/confidence are amplitude geometry only; `ok` is not semantic or word-boundary proof and can be inside a word, while `speech` carries the word evidence. Raw 30ms bins come only from detail:cut or include:[\"audio_envelope\"]. 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. word_provenance returns the exact caption word_id and text for an occurrence.caption word correction; compact transcript tuples omit IDs and speech-alignment IDs are different. Other raw channels are opt-in.",
"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 inspected in a SINGLE call, the alternative to `region` for a clip's two edges (a 45s clip is 2 small windows here, not one big region or two calls). Each window is an edge window only (typically ~5–6s, hard cap 12s; a longer window is rejected), not 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 (typically 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, counted across every regions[].edges in the 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"
]
}
]
}
}
]
}
]
},
"annotations": {
"title": "Inspect episode media at a candidate boundary",
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
],
"ui": {
"visibility": [
"model",
"app"
]
},
"openai/widgetAccessible": true
}
}Live Workspace descriptor
{
"name": "episode_zoom",
"title": "Inspect episode media at a candidate boundary",
"description": "Inspects chosen cut boundaries: at most 6 windows per call, each <=12 seconds (typically 5–6), and at most 4 measured edges TOTAL across all windows. Broad transcript discovery is episode_read. 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. It inspects 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, because one Program timestamp does not imply one source boundary. Zoom measures what resolved Program Audio plays at each point: the occurrence's own Recording, a pinned or Replace Recording at its mapped source second (named `inspected_recording_id`; speech source coordinates are in it), or nothing under mute or silence, where a `silent_authority` receipt certifies only that no Program Audio speech edge is there. `audible_authority` names the side and authority (occurrence_base, pinned_primary, explicit_replace, explicit_silence, silence; `unresolved` certifies nothing). Where an authority begins exactly at a point, its before and after sides are measured and signed separately; an edit needs the receipt for each side it plays. A receipt stays valid across other edits until its occurrence, the inspected media or transcript, or Program Audio at that point changes. `rejected` + `inside_word` marks a point inside a word, which receives no receipt. 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; each has its own 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; BitterClip does not snap a merely nearby point to the disclosed exact aligned endpoint, which a query can name directly. A supported point's evidence handle is accepted by `episode_edit` as is; for a Trim, only a changed edge needs a `detail:\"edit\"` measurement. It follows episode_read, which 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: probe_busy means the aligner, ONE serialized resource, was busy with another call, and a later single call can succeed; alignment_failed | alignment_sequence_mismatch | unsupported_transcript_token | out_of_vocabulary mean the probe already retried a point-focused (and, where eligible, tail) window, so re-zooming the same edge returns the same verdict and the point stays listen_required unless the edge moves; remaining reasons describe invalid or insufficient input. One call can batch related windows; decoding and alignment work scales with the measured source sides. It measures candidate edit and review boundaries, not Project recaps. `detail` controls progressive disclosure: lean (semantic discovery), cut (adds raw audio envelopes), edit (adds signed exact boundary receipts), or diagnostic (adds raw detector provenance). A structural Split or partial Range accepts each evidence_id or inspection_token only unchanged. 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. 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. Timestamps are episode time unless a field ends in _source. Measurements only; it places no cut. Read-only.",
"inputSchema": {
"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 around ONE cut point (typically ~5–6s, hard cap 12s; a longer region is rejected), not the clip body, whose full transcript episode_read already returns. 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`, one per source side. Recommendation/confidence are amplitude geometry only; `ok` is not semantic or word-boundary proof and can be inside a word, while `speech` carries the word evidence. Raw 30ms bins come only from detail:cut or include:[\"audio_envelope\"]. 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. word_provenance returns the exact caption word_id and text for an occurrence.caption word correction; compact transcript tuples omit IDs and speech-alignment IDs are different. Other raw channels are opt-in.",
"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 inspected in a SINGLE call, the alternative to `region` for a clip's two edges (a 45s clip is 2 small windows here, not one big region or two calls). Each window is an edge window only (typically ~5–6s, hard cap 12s; a longer window is rejected), not 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 (typically 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, counted across every regions[].edges in the 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"
]
}
]
}
}
]
}
]
},
"annotations": {
"title": "Inspect episode media at a candidate boundary",
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
}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"
}
}
]