madoo.caption-block-family/v1

Madoo caption block family — Caption block emitted in ordinary v1 mode or duration-aware v2 mode.

Reference	madoo.caption-block-family/v1
Schema id	urn:madoo:schema:caption-block-family:v1
Version	1.0.0
Served at	GET /api/v1/json-schemas/madoo.caption-block-family/v1 · MCP get_json_schema

Where it appears

• Produced by: enumerate/caption_blocks → block
• Read by: ai/caption_translation → block

Fields

Field	Type	Required	Rules	Description
schema	one of "madoo.caption-block/v1", "madoo.caption-block/v2"	yes
track_id	string	yes	min length 1; max length 256
block_id	string	yes	min length 1; max length 256
block_index	integer	yes	≥ 0; ≤ 9999
source_language	string or null	yes	max length 35
cues	array of objects	yes	min items 1; max items 100
cues[].id	string	yes	min length 1; max length 128
cues[].text	string	yes	min length 1; max length 20000
cues[].speaker	string or null	yes	max length 128
cues[].kind	string	yes	min length 1; max length 64
context_before	string or null	yes	max length 20000
context_after	string or null	yes	max length 20000
timing	object		no other fields
timing.planId	string	yes	pattern “^[a-f0-9]{64}$”
timing.cueId	string	yes	min length 1; max length 128
timing.round	integer	yes	≥ 1; ≤ 3
timing.originalIndex	integer	yes	≥ 0; ≤ 9999
timing.slotMilliseconds	integer	yes	≥ 50; ≤ 21600000
timing.targetLanguage	string	yes	min length 1; max length 35
timing.initialTranslation	string	yes	min length 1; max length 20000
timing.previousText	string or null	yes	max length 20000
timing.previousDurationMilliseconds	integer or null	yes	≥ 1; ≤ 21600000
timing.previousSpeakingRate	number or null	yes	> 0
timing.maximumFitRate	number	yes	≥ 1; ≤ 2
timing.maximumCombinedRate	number	yes	≥ 1; ≤ 2
timing.previousHasAudibleSignal	boolean
timing.targetMaximumCharacters	integer		≥ 1; ≤ 20000

The complete schema

madoo.caption-block-family/v1 (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:madoo:schema:caption-block-family:v1",
  "title": "Madoo caption block family",
  "description": "The port emits an ordinary v1 translation block, or a one-cue v2 block with measured timing feedback when duration_aware is enabled.",
  "examples": [
    {
      "schema": "madoo.caption-block/v1",
      "track_id": "source-track",
      "block_id": "source-track:block:0000",
      "block_index": 0,
      "source_language": "en",
      "cues": [
        {
          "id": "cue-0001",
          "text": "Welcome to our product update.",
          "speaker": "speaker_0",
          "kind": "speech"
        }
      ],
      "context_before": null,
      "context_after": "Next source cue."
    }
  ],
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "track_id",
    "block_id",
    "block_index",
    "source_language",
    "cues",
    "context_before",
    "context_after"
  ],
  "properties": {
    "schema": {
      "type": "string",
      "enum": [
        "madoo.caption-block/v1",
        "madoo.caption-block/v2"
      ]
    },
    "track_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "examples": [
        "source-track"
      ]
    },
    "block_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "examples": [
        "source-track:block:0000"
      ]
    },
    "block_index": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9999
    },
    "source_language": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 35,
      "examples": [
        "en"
      ]
    },
    "cues": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "$ref": "#/$defs/cue"
      }
    },
    "context_before": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 20000
    },
    "context_after": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 20000
    },
    "timing": {
      "$ref": "#/$defs/timing"
    }
  },
  "oneOf": [
    {
      "properties": {
        "schema": {
          "const": "madoo.caption-block/v1"
        }
      },
      "not": {
        "required": [
          "timing"
        ]
      }
    },
    {
      "properties": {
        "schema": {
          "const": "madoo.caption-block/v2"
        },
        "cues": {
          "maxItems": 1,
          "items": {
            "properties": {
              "kind": {
                "const": "speech"
              }
            }
          }
        }
      },
      "required": [
        "timing"
      ]
    }
  ],
  "$defs": {
    "cue": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "text",
        "speaker",
        "kind"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "examples": [
            "cue-0001"
          ]
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20000,
          "examples": [
            "Welcome to our product update."
          ]
        },
        "speaker": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 128,
          "examples": [
            "speaker_0"
          ]
        },
        "kind": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "examples": [
            "speech"
          ]
        }
      }
    },
    "timing": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "planId",
        "cueId",
        "round",
        "originalIndex",
        "slotMilliseconds",
        "targetLanguage",
        "initialTranslation",
        "previousText",
        "previousDurationMilliseconds",
        "previousSpeakingRate",
        "maximumFitRate",
        "maximumCombinedRate"
      ],
      "properties": {
        "planId": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "cueId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "round": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3
        },
        "originalIndex": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999
        },
        "slotMilliseconds": {
          "type": "integer",
          "minimum": 50,
          "maximum": 21600000
        },
        "targetLanguage": {
          "type": "string",
          "minLength": 1,
          "maxLength": 35
        },
        "initialTranslation": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20000
        },
        "previousText": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 20000
        },
        "previousDurationMilliseconds": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 21600000
        },
        "previousSpeakingRate": {
          "type": [
            "number",
            "null"
          ],
          "exclusiveMinimum": 0
        },
        "maximumFitRate": {
          "type": "number",
          "minimum": 1,
          "maximum": 2
        },
        "maximumCombinedRate": {
          "type": "number",
          "minimum": 1,
          "maximum": 2
        },
        "previousHasAudibleSignal": {
          "type": "boolean"
        },
        "targetMaximumCharacters": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20000
        }
      }
    }
  }
}