madoo.caption-track/v1

Madoo caption track — Provider-neutral ordered caption cues on an absolute media timeline.

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

Where it appears

• Produced by: aggregate/caption_track → caption_track, aggregate/caption_track → pending_captions, aggregate/transcript → caption_track, ai/speech_to_text → caption_track, utility/caption_timeline_project → caption_track, utility/speech_timing_plan → pending_captions, utility/speech_timing_reconcile → delivery_captions, utility/speech_timing_reconcile → pending_captions, utility/speech_timing_reconcile → speech_aligned_captions
• Read by: aggregate/caption_track → baseline_track, aggregate/caption_track → source_track, aggregate/video_highlight_plan → caption_track, enumerate/caption_blocks → caption_track, enumerate/speakers → caption_track, utility/caption_timeline_project → caption_track, utility/dubbing_manifest → source_captions, utility/dubbing_manifest → target_captions, utility/speaker_voices → caption_track, utility/speech_timing_plan → source_captions, utility/speech_timing_plan → target_captions

Fields

Field	Type	Required	Rules	Description
schema	"madoo.caption-track/v1"	yes
track_id	string	yes	min length 1; max length 256
language	string or null	yes	max length 35
source_language	string or null	yes	max length 35
granularity	string	yes	min length 1; max length 64
cues	array of objects	yes	min items 1; max items 10000
cues[].id	string	yes	min length 1; max length 128
cues[].start	number	yes	≥ 0; ≤ 21600
cues[].end	number	yes	≤ 21600; > 0
cues[].text	string	yes	min length 1; max length 20000
cues[].speaker	string or null	yes	max length 256
cues[].speaker_scope	string or null	yes	max length 256
cues[].kind	string	yes	min length 1; max length 64
cues[].source_segment_ids	array of string	yes	max items 1024
generation	object	yes	no other fields
generation.normalizer	string	yes	min length 1; max length 256
generation.version	string	yes	min length 1; max length 64
generation.segment_count	integer	yes	≥ 0; ≤ 100000
generation.overlap_reconciled	boolean	yes
warnings	array of objects	yes	max items 1000
warnings[].code	string	yes	min length 1; max length 128
warnings[].message	string	yes	min length 1; max length 2000

Example

{"schema":"madoo.caption-track/v1","track_id":"track-it","language":"it","source_language":"en","granularity":"segment","cues":[{"id":"cue-1","start":0.25,"end":1.75,"text":"Benvenuti in Madoo.","speaker":"speaker-0","speaker_scope":"track","kind":"speech","source_segment_ids":["segment-1"]}],"generation":{"normalizer":"aggregate/caption_track","version":"1.0.0","segment_count":1,"overlap_reconciled":false},"warnings":[]}

The complete schema

madoo.caption-track/v1 (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:madoo:schema:caption-track:v1",
  "title": "Madoo caption track",
  "description": "Provider-neutral ordered caption cues on an absolute media timeline. Cue identity, ordering and end-after-start are also checked semantically by the runtime.",
  "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": 256
    },
    "language": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 35
    },
    "source_language": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 35
    },
    "granularity": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "cues": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10000,
      "items": {
        "$ref": "#/$defs/cue"
      }
    },
    "generation": {
      "$ref": "#/$defs/generation"
    },
    "warnings": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "$ref": "#/$defs/warning"
      }
    }
  },
  "$defs": {
    "cue": {
      "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",
          "exclusiveMinimum": 0,
          "maximum": 21600
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20000
        },
        "speaker": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 256
        },
        "speaker_scope": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 256
        },
        "kind": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "source_segment_ids": {
          "type": "array",
          "maxItems": 1024,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        }
      }
    },
    "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": 64
        },
        "segment_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000
        },
        "overlap_reconciled": {
          "type": "boolean"
        }
      }
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        }
      }
    }
  }
}