madoo.speech-timing-plan/v1
Madoo speech timing plan — Immutable aligned caption plan and conservative speaking/fit policy.
| Reference | madoo.speech-timing-plan/v1 |
| Schema id | urn:madoo:schema:speech-timing-plan:v1 |
| Version | 1.0.0 |
| Served at | GET /api/v1/json-schemas/madoo.speech-timing-plan/v1 · MCP get_json_schema |
Where it appears
Section titled “Where it appears”Carried inside the natural-speech timing state and the dubbing manifest v2.
Fields
Section titled “Fields”| Field | Type | Required | Rules | Description |
|---|---|---|---|---|
schema |
"madoo.speech-timing-plan/v1" |
yes | ||
planId |
string | yes | pattern “^[a-f0-9]{64}$” | |
organizationID |
integer | yes | ≥ 1; ≤ 9007199254740991 | |
workspaceID |
integer | yes | ≥ 1; ≤ 9007199254740991 | |
durationMilliseconds |
integer | yes | ≥ 50; ≤ 21600000 | |
sourceCaptions |
object | yes | no other fields | |
sourceCaptions.schema |
"madoo.caption-track/v1" |
yes | ||
sourceCaptions.track_id |
string | yes | min length 1; max length 512 | |
sourceCaptions.language |
string | yes | min length 1; max length 64 | |
sourceCaptions.source_language |
string or null | yes | max length 64 | |
sourceCaptions.granularity |
string | yes | min length 1; max length 64 | |
sourceCaptions.cues |
array of objects | yes | min items 1; max items 10000 | |
sourceCaptions.cues[].id |
string | yes | min length 1; max length 128 | |
sourceCaptions.cues[].start |
number | yes | ≥ 0; ≤ 21600 | |
sourceCaptions.cues[].end |
number | yes | ≥ 0; ≤ 21600 | |
sourceCaptions.cues[].text |
string | yes | min length 1; max length 20000 | |
sourceCaptions.cues[].speaker |
string or null | yes | max length 512 | |
sourceCaptions.cues[].speaker_scope |
string or null | yes | max length 512 | |
sourceCaptions.cues[].kind |
"speech" |
yes | ||
sourceCaptions.cues[].source_segment_ids |
array of string | yes | min items 0; max items 10000 | |
sourceCaptions.generation |
object | yes | no other fields | |
sourceCaptions.generation.normalizer |
string | yes | min length 1; max length 256 | |
sourceCaptions.generation.version |
string | yes | min length 1; max length 128 | |
sourceCaptions.generation.segment_count |
integer | yes | ≥ 0; ≤ 10000 | |
sourceCaptions.generation.overlap_reconciled |
boolean | yes | ||
sourceCaptions.warnings |
array of objects | yes | min items 0; max items 10000 | |
sourceCaptions.warnings[].code |
string | yes | min length 1; max length 128 | |
sourceCaptions.warnings[].message |
string | yes | min length 1; max length 20000 | |
targetCaptions |
object | yes | no other fields | |
targetCaptions.schema |
"madoo.caption-track/v1" |
yes | ||
targetCaptions.track_id |
string | yes | min length 1; max length 512 | |
targetCaptions.language |
string | yes | min length 1; max length 64 | |
targetCaptions.source_language |
string or null | yes | max length 64 | |
targetCaptions.granularity |
string | yes | min length 1; max length 64 | |
targetCaptions.cues |
array of objects | yes | min items 1; max items 10000 | |
targetCaptions.cues[].id |
string | yes | min length 1; max length 128 | |
targetCaptions.cues[].start |
number | yes | ≥ 0; ≤ 21600 | |
targetCaptions.cues[].end |
number | yes | ≥ 0; ≤ 21600 | |
targetCaptions.cues[].text |
string | yes | min length 1; max length 20000 | |
targetCaptions.cues[].speaker |
string or null | yes | max length 512 | |
targetCaptions.cues[].speaker_scope |
string or null | yes | max length 512 | |
targetCaptions.cues[].kind |
"speech" |
yes | ||
targetCaptions.cues[].source_segment_ids |
array of string | yes | min items 0; max items 10000 | |
targetCaptions.generation |
object | yes | no other fields | |
targetCaptions.generation.normalizer |
string | yes | min length 1; max length 256 | |
targetCaptions.generation.version |
string | yes | min length 1; max length 128 | |
targetCaptions.generation.segment_count |
integer | yes | ≥ 0; ≤ 10000 | |
targetCaptions.generation.overlap_reconciled |
boolean | yes | ||
targetCaptions.warnings |
array of objects | yes | min items 0; max items 10000 | |
targetCaptions.warnings[].code |
string | yes | min length 1; max length 128 | |
targetCaptions.warnings[].message |
string | yes | min length 1; max length 20000 | |
policy |
object | yes | no other fields | |
policy.maximumRounds |
integer | yes | ≥ 1; ≤ 3 | |
policy.minimumSpeakingRate |
number | yes | ≥ 0.95; ≤ 1 | |
policy.maximumSpeakingRate |
number | yes | ≥ 1; ≤ 1.05 | |
policy.maximumFitRate |
number | yes | ≥ 1; ≤ 2 | |
policy.maximumCombinedRate |
number | yes | ≥ 1; ≤ 2 | |
policy.toleranceMilliseconds |
integer | yes | ≥ 1; ≤ 250 | |
cues |
array of objects | yes | min items 1; max items 10000 | |
cues[].cueId |
string | yes | min length 1; max length 128 | |
cues[].originalIndex |
integer | yes | ≥ 0; ≤ 9999 | |
cues[].sourceText |
string | yes | min length 1; max length 20000 | |
cues[].initialTranslation |
string | yes | min length 1; max length 20000 | |
cues[].speaker |
string or null | yes | max length 512 | |
cues[].startMilliseconds |
integer | yes | ≥ 0; ≤ 21600000 | |
cues[].endMilliseconds |
integer | yes | ≥ 50; ≤ 21600000 | |
cues[].contextBefore |
string or null | yes | max length 20000 | |
cues[].contextAfter |
string or null | yes | max length 20000 | |
elasticity |
object | no other fields | ||
elasticity.maximumEndExtensionMilliseconds |
integer | yes | ≥ 1; ≤ 250 | |
elasticity.evidence |
object | yes | no other fields | |
elasticity.evidence.referenceAudioStorageRef |
string | yes | max length 4096; pattern “^storage://[^?#\s]+$” | |
elasticity.evidence.referenceAudioSha256 |
string | yes | pattern “^[a-f0-9]{64}$” | |
elasticity.evidence.durationMilliseconds |
integer | yes | ≥ 50; ≤ 21600000 | |
elasticity.evidence.silence |
array of objects | yes | max items 1026 | |
elasticity.evidence.silence[].startMilliseconds |
integer | yes | ≥ 0; ≤ 21600000 | |
elasticity.evidence.silence[].endMilliseconds |
integer | yes | ≥ 1; ≤ 21600000 | |
elasticity.windows |
array of objects | yes | max items 10000 | |
elasticity.windows[].cueId |
string | yes | min length 1; max length 128 | |
elasticity.windows[].startMilliseconds |
integer | yes | ≥ 0; ≤ 21600000 | |
elasticity.windows[].endMilliseconds |
integer | yes | ≥ 1; ≤ 21600000 | |
availableWindows |
object | no other fields | ||
availableWindows.maximumEndExtensionMilliseconds |
integer | yes | ≥ 1; ≤ 2000 | |
availableWindows.safetyGapMilliseconds |
integer | yes | ≥ 20; ≤ 500 | |
availableWindows.windows |
array of objects | yes | max items 10000 | |
availableWindows.windows[].cueId |
string | yes | min length 1; max length 128 | |
availableWindows.windows[].startMilliseconds |
integer | yes | ≥ 0; ≤ 21600000 | |
availableWindows.windows[].endMilliseconds |
integer | yes | ≥ 1; ≤ 21600000 |
Example
Section titled “Example”{ "schema": "madoo.speech-timing-plan/v1", "planId": "df9f0828ea2c188dc4f90ef01e1c53ff04956e4f6f7199e1368bf01d54c18f7f", "organizationID": 1, "workspaceID": 2, "durationMilliseconds": 1000, "sourceCaptions": { "schema": "madoo.caption-track/v1", "track_id": "source", "language": "en", "source_language": null, "granularity": "segment", "cues": [ { "id": "cue-1", "start": 0, "end": 1, "text": "Hello", "speaker": "speaker", "speaker_scope": "track", "kind": "speech", "source_segment_ids": [] } ], "generation": { "normalizer": "fixture", "version": "1", "segment_count": 1, "overlap_reconciled": false }, "warnings": [] }, "targetCaptions": { "schema": "madoo.caption-track/v1", "track_id": "target", "language": "it", "source_language": null, "granularity": "segment", "cues": [ { "id": "cue-1", "start": 0, "end": 1, "text": "Ciao", "speaker": "speaker", "speaker_scope": "track", "kind": "speech", "source_segment_ids": [] } ], "generation": { "normalizer": "fixture", "version": "1", "segment_count": 1, "overlap_reconciled": false }, "warnings": [] }, "policy": { "maximumRounds": 3, "minimumSpeakingRate": 0.95, "maximumSpeakingRate": 1.05, "maximumFitRate": 1.1, "maximumCombinedRate": 1.15, "toleranceMilliseconds": 80 }, "cues": [ { "cueId": "cue-1", "originalIndex": 0, "sourceText": "Hello", "initialTranslation": "Ciao", "speaker": "speaker", "startMilliseconds": 0, "endMilliseconds": 1000, "contextBefore": null, "contextAfter": null } ]}The complete schema
Section titled “The complete schema”madoo.speech-timing-plan/v1 (JSON Schema)
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "urn:madoo:schema:speech-timing-plan:v1", "title": "Madoo speech timing plan", "description": "Shape validation only. Correlation, timing policy, tenant authorization and trusted measurement provenance require Application validation.", "$ref": "#/$defs/plan", "$defs": { "warning": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 128 }, "message": { "type": "string", "minLength": 1, "maxLength": 20000 } } }, "captionCue": { "type": "object", "additionalProperties": false, "required": [ "id", "start", "end", "text", "speaker", "speaker_scope", "kind", "source_segment_ids" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "start": { "type": "number", "minimum": 0, "maximum": 21600 }, "end": { "type": "number", "minimum": 0, "maximum": 21600 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000 }, "speaker": { "type": [ "string", "null" ], "maxLength": 512 }, "speaker_scope": { "type": [ "string", "null" ], "maxLength": 512 }, "kind": { "const": "speech" }, "source_segment_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 10000, "minItems": 0 } } }, "captionTrack": { "type": "object", "additionalProperties": false, "required": [ "schema", "track_id", "language", "source_language", "granularity", "cues", "generation", "warnings" ], "properties": { "schema": { "const": "madoo.caption-track/v1" }, "track_id": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "source_language": { "type": [ "string", "null" ], "maxLength": 64 }, "granularity": { "type": "string", "minLength": 1, "maxLength": 64 }, "cues": { "type": "array", "items": { "$ref": "#/$defs/captionCue" }, "maxItems": 10000, "minItems": 1 }, "generation": { "type": "object", "additionalProperties": false, "required": [ "normalizer", "version", "segment_count", "overlap_reconciled" ], "properties": { "normalizer": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 }, "segment_count": { "type": "integer", "minimum": 0, "maximum": 10000 }, "overlap_reconciled": { "type": "boolean" } } }, "warnings": { "type": "array", "items": { "$ref": "#/$defs/warning" }, "maxItems": 10000, "minItems": 0 } } }, "policy": { "type": "object", "additionalProperties": false, "required": [ "maximumRounds", "minimumSpeakingRate", "maximumSpeakingRate", "maximumFitRate", "maximumCombinedRate", "toleranceMilliseconds" ], "properties": { "maximumRounds": { "type": "integer", "minimum": 1, "maximum": 3 }, "minimumSpeakingRate": { "type": "number", "minimum": 0.95, "maximum": 1 }, "maximumSpeakingRate": { "type": "number", "minimum": 1, "maximum": 1.05 }, "maximumFitRate": { "type": "number", "minimum": 1, "maximum": 2 }, "maximumCombinedRate": { "type": "number", "minimum": 1, "maximum": 2 }, "toleranceMilliseconds": { "type": "integer", "minimum": 1, "maximum": 250 } } }, "cue": { "type": "object", "additionalProperties": false, "required": [ "cueId", "originalIndex", "sourceText", "initialTranslation", "speaker", "startMilliseconds", "endMilliseconds", "contextBefore", "contextAfter" ], "properties": { "cueId": { "type": "string", "minLength": 1, "maxLength": 128 }, "originalIndex": { "type": "integer", "minimum": 0, "maximum": 9999 }, "sourceText": { "type": "string", "minLength": 1, "maxLength": 20000 }, "initialTranslation": { "type": "string", "minLength": 1, "maxLength": 20000 }, "speaker": { "type": [ "string", "null" ], "maxLength": 512 }, "startMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 }, "endMilliseconds": { "type": "integer", "minimum": 50, "maximum": 21600000 }, "contextBefore": { "type": [ "string", "null" ], "maxLength": 20000 }, "contextAfter": { "type": [ "string", "null" ], "maxLength": 20000 } } }, "plan": { "type": "object", "additionalProperties": false, "required": [ "schema", "planId", "organizationID", "workspaceID", "durationMilliseconds", "sourceCaptions", "targetCaptions", "policy", "cues" ], "properties": { "schema": { "const": "madoo.speech-timing-plan/v1" }, "planId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "organizationID": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceID": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "durationMilliseconds": { "type": "integer", "minimum": 50, "maximum": 21600000 }, "sourceCaptions": { "$ref": "#/$defs/captionTrack" }, "targetCaptions": { "$ref": "#/$defs/captionTrack" }, "policy": { "$ref": "#/$defs/policy" }, "cues": { "type": "array", "items": { "$ref": "#/$defs/cue" }, "maxItems": 10000, "minItems": 1 }, "elasticity": { "$ref": "#/$defs/elasticity" }, "availableWindows": { "$ref": "#/$defs/availableWindows" } } }, "candidate": { "type": "object", "additionalProperties": false, "required": [ "planId", "cueId", "round", "text", "audioStorageRef", "audioSha256", "durationMilliseconds", "speakingRate", "modelId", "profileVersion", "voice", "expectedMilliCredits", "hasAudibleSignal" ], "properties": { "planId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "cueId": { "type": "string", "minLength": 1, "maxLength": 128 }, "round": { "type": "integer", "minimum": 1, "maximum": 3 }, "text": { "type": "string", "minLength": 1, "maxLength": 20000 }, "audioStorageRef": { "type": "string", "pattern": "^storage://[^?#\\s]+$", "maxLength": 4096 }, "audioSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "durationMilliseconds": { "type": "integer", "minimum": 1, "maximum": 21600000 }, "speakingRate": { "type": "number", "exclusiveMinimum": 0, "maximum": 10 }, "modelId": { "type": "string", "minLength": 1, "maxLength": 256 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 256 }, "voice": { "type": "string", "minLength": 1, "maxLength": 512 }, "hasAudibleSignal": { "type": "boolean" }, "headSilenceMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 }, "tailSilenceMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 }, "trimStartMilliseconds": { "type": "integer", "minimum": 0, "maximum": 1000 }, "trimEndMilliseconds": { "type": "integer", "minimum": 0, "maximum": 1000 }, "expectedMilliCredits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "assessment": { "type": "object", "additionalProperties": false, "required": [ "schema", "candidate", "accepted", "requiredFitRate", "paddingMilliseconds", "reason" ], "properties": { "schema": { "const": "madoo.speech-timing-assessment/v1" }, "candidate": { "$ref": "#/$defs/candidate" }, "accepted": { "type": "boolean" }, "requiredFitRate": { "type": "number", "minimum": 1, "maximum": 432000 }, "paddingMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 }, "reason": { "enum": [ "SPEECH_TIMING_ACCEPTED", "SPEECH_TIMING_REQUIRES_ADAPTATION", "SPEECH_TIMING_NO_AUDIBLE_SIGNAL", "SPEECH_TIMING_REFLOWED", "SPEECH_TIMING_DEGRADED_REFLOW" ] }, "targetDurationMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 } } }, "state": { "type": "object", "additionalProperties": false, "required": [ "schema", "plan", "completedRounds", "history" ], "properties": { "schema": { "const": "madoo.speech-timing-state/v1" }, "plan": { "$ref": "#/$defs/plan" }, "completedRounds": { "type": "integer", "minimum": 0, "maximum": 3 }, "history": { "type": "array", "items": { "$ref": "#/$defs/assessment" }, "maxItems": 30000, "minItems": 0 } } }, "silenceInterval": { "type": "object", "additionalProperties": false, "required": [ "startMilliseconds", "endMilliseconds" ], "properties": { "startMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 }, "endMilliseconds": { "type": "integer", "minimum": 1, "maximum": 21600000 } } }, "deliveryWindow": { "type": "object", "additionalProperties": false, "required": [ "cueId", "startMilliseconds", "endMilliseconds" ], "properties": { "cueId": { "type": "string", "minLength": 1, "maxLength": 128 }, "startMilliseconds": { "type": "integer", "minimum": 0, "maximum": 21600000 }, "endMilliseconds": { "type": "integer", "minimum": 1, "maximum": 21600000 } } }, "availableWindows": { "type": "object", "additionalProperties": false, "required": [ "maximumEndExtensionMilliseconds", "safetyGapMilliseconds", "windows" ], "properties": { "maximumEndExtensionMilliseconds": { "type": "integer", "minimum": 1, "maximum": 2000 }, "safetyGapMilliseconds": { "type": "integer", "minimum": 20, "maximum": 500 }, "windows": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/$defs/deliveryWindow" } } } }, "elasticity": { "type": "object", "additionalProperties": false, "required": [ "maximumEndExtensionMilliseconds", "evidence", "windows" ], "properties": { "maximumEndExtensionMilliseconds": { "type": "integer", "minimum": 1, "maximum": 250 }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "referenceAudioStorageRef", "referenceAudioSha256", "durationMilliseconds", "silence" ], "properties": { "referenceAudioStorageRef": { "type": "string", "pattern": "^storage://[^?#\\s]+$", "maxLength": 4096 }, "referenceAudioSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "durationMilliseconds": { "type": "integer", "minimum": 50, "maximum": 21600000 }, "silence": { "type": "array", "maxItems": 1026, "items": { "$ref": "#/$defs/silenceInterval" } } } }, "windows": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/$defs/deliveryWindow" } } } } }}