Skip to content
MadooMadooDocs

madoo.audio-timeline/v1

Madoo audio timeline — Deterministic evidence for audio clips placed on an absolute master timeline.
Reference madoo.audio-timeline/v1
Schema id urn:madoo:schema:audio-timeline:v1
Version 1.0.0
Served at GET /api/v1/json-schemas/madoo.audio-timeline/v1 · MCP get_json_schema

Where it appears

Section titled “Where it appears”
  • Produced by: aggregate/audio_timeline → timeline_manifest
  • Read by: utility/dubbing_manifest → timeline_manifest

Fields

Section titled “Fields”
Field Type Required Rules Description
schema "madoo.audio-timeline/v1" yes
targetDurationMilliseconds integer yes ≥ 1; ≤ 21600000
actualDurationMilliseconds integer yes ≥ 1; ≤ 21600000
sampleRateHz integer yes ≥ 8000; ≤ 384000
channels integer yes ≥ 1; ≤ 8
outputFormat one of "wav", "flac" yes
overlapPolicy one of "fail", "mix", "trim_previous" yes
gapFill "silence" yes
expectedCueCount integer yes ≥ 0; ≤ 10000
receivedCueCount integer yes ≥ 0; ≤ 10000
missingCueCount integer yes ≥ 0; ≤ 10000
duplicateCueCount integer yes ≥ 0; ≤ 10000
cues array of objects yes max items 10000
cues[].cueId string yes min length 1; max length 128
cues[].iterationIndex integer yes ≥ 0; ≤ 9999
cues[].startMilliseconds integer yes ≥ 0; ≤ 21600000
cues[].endMilliseconds integer yes ≥ 1; ≤ 21600000
cues[].slotDurationMilliseconds integer yes ≥ 1; ≤ 21600000
cues[].clipDurationMilliseconds integer yes ≥ 1; ≤ 21600000
cues[].appliedAction string yes pattern “^(placed|trim_clip_to_slot|pad_clip_to_slot)(\+(mix_overlap|trimmed_for_overlap))*$”
cues[].speaker string or null yes max length 256
cues[].inputSha256 string or null yes pattern “^[a-f0-9]{64}$”
cues[].warnings array of objects yes max items 256
cues[].warnings[].code string yes min length 1; max length 128
cues[].warnings[].message string yes min length 1; max length 1000
cues[].warnings[].path string or null yes max length 500
gaps array of objects yes max items 10001
gaps[].startMilliseconds integer yes ≥ 0; ≤ 21600000
gaps[].endMilliseconds integer yes ≥ 0; ≤ 21600000
gaps[].durationMilliseconds integer yes ≥ 0; ≤ 21600000
gaps[].cueIds array of string yes max items 32
overlaps array of objects yes max items 10000
overlaps[].startMilliseconds integer yes ≥ 0; ≤ 21600000
overlaps[].endMilliseconds integer yes ≥ 0; ≤ 21600000
overlaps[].durationMilliseconds integer yes ≥ 0; ≤ 21600000
overlaps[].cueIds array of string yes max items 32
durationErrorMilliseconds integer yes ≥ -21600000; ≤ 21600000
withinTolerance boolean yes
technique object yes no other fields
technique.name string yes min length 1; max length 128
technique.version string yes min length 1; max length 64
technique.engine string yes min length 1; max length 64
technique.engineVersion string yes min length 1; max length 128
warnings array of objects yes max items 256
warnings[].code string yes min length 1; max length 128
warnings[].message string yes min length 1; max length 1000
warnings[].path string or null yes max length 500

Example

Section titled “Example”
{
  "schema": "madoo.audio-timeline/v1",
  "targetDurationMilliseconds": 5000,
  "actualDurationMilliseconds": 5000,
  "sampleRateHz": 48000,
  "channels": 2,
  "outputFormat": "wav",
  "overlapPolicy": "fail",
  "gapFill": "silence",
  "expectedCueCount": 2,
  "receivedCueCount": 2,
  "missingCueCount": 0,
  "duplicateCueCount": 0,
  "cues": [
    {
      "cueId": "cue-0001",
      "iterationIndex": 0,
      "startMilliseconds": 500,
      "endMilliseconds": 1700,
      "slotDurationMilliseconds": 1200,
      "clipDurationMilliseconds": 1198,
      "appliedAction": "placed",
      "speaker": "speaker-0",
      "inputSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "warnings": []
    },
    {
      "cueId": "cue-0002",
      "iterationIndex": 1,
      "startMilliseconds": 2500,
      "endMilliseconds": 3400,
      "slotDurationMilliseconds": 900,
      "clipDurationMilliseconds": 900,
      "appliedAction": "placed",
      "speaker": "speaker-0",
      "inputSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "warnings": []
    }
  ],
  "gaps": [
    { "startMilliseconds": 0, "endMilliseconds": 500, "durationMilliseconds": 500, "cueIds": [] },
    { "startMilliseconds": 1700, "endMilliseconds": 2500, "durationMilliseconds": 800, "cueIds": [] },
    { "startMilliseconds": 3400, "endMilliseconds": 5000, "durationMilliseconds": 1600, "cueIds": [] }
  ],
  "overlaps": [],
  "durationErrorMilliseconds": 0,
  "withinTolerance": true,
  "technique": {
    "name": "madoo.ffmpeg-audio-timeline",
    "version": "1.0.0",
    "engine": "ffmpeg",
    "engineVersion": "qualification-pending"
  },
  "warnings": []
}

The complete schema

Section titled “The complete schema”
madoo.audio-timeline/v1 (JSON Schema) 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:madoo:schema:audio-timeline:v1",
  "title": "Madoo Audio Timeline v1",
  "description": "Deterministic evidence for audio clips placed on an absolute master timeline.",
  "type": "object",
  "required": [
    "schema",
    "targetDurationMilliseconds",
    "actualDurationMilliseconds",
    "sampleRateHz",
    "channels",
    "outputFormat",
    "overlapPolicy",
    "gapFill",
    "expectedCueCount",
    "receivedCueCount",
    "missingCueCount",
    "duplicateCueCount",
    "cues",
    "gaps",
    "overlaps",
    "durationErrorMilliseconds",
    "withinTolerance",
    "technique",
    "warnings"
  ],
  "properties": {
    "schema": {
      "const": "madoo.audio-timeline/v1"
    },
    "targetDurationMilliseconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 21600000
    },
    "actualDurationMilliseconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 21600000
    },
    "sampleRateHz": {
      "type": "integer",
      "minimum": 8000,
      "maximum": 384000
    },
    "channels": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8
    },
    "outputFormat": {
      "type": "string",
      "enum": [
        "wav",
        "flac"
      ]
    },
    "overlapPolicy": {
      "type": "string",
      "enum": [
        "fail",
        "mix",
        "trim_previous"
      ]
    },
    "gapFill": {
      "const": "silence"
    },
    "expectedCueCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "receivedCueCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "missingCueCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "duplicateCueCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "cues": {
      "type": "array",
      "maxItems": 10000,
      "items": {
        "$ref": "#/$defs/cue"
      }
    },
    "gaps": {
      "type": "array",
      "maxItems": 10001,
      "items": {
        "$ref": "#/$defs/interval"
      }
    },
    "overlaps": {
      "type": "array",
      "maxItems": 10000,
      "items": {
        "$ref": "#/$defs/interval"
      }
    },
    "durationErrorMilliseconds": {
      "type": "integer",
      "minimum": -21600000,
      "maximum": 21600000
    },
    "withinTolerance": {
      "type": "boolean"
    },
    "technique": {
      "$ref": "#/$defs/technique"
    },
    "warnings": {
      "$ref": "#/$defs/warnings"
    }
  },
  "$defs": {
    "cue": {
      "type": "object",
      "required": [
        "cueId",
        "iterationIndex",
        "startMilliseconds",
        "endMilliseconds",
        "slotDurationMilliseconds",
        "clipDurationMilliseconds",
        "appliedAction",
        "speaker",
        "inputSha256",
        "warnings"
      ],
      "properties": {
        "cueId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "iterationIndex": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9999
        },
        "startMilliseconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 21600000
        },
        "endMilliseconds": {
          "type": "integer",
          "minimum": 1,
          "maximum": 21600000
        },
        "slotDurationMilliseconds": {
          "type": "integer",
          "minimum": 1,
          "maximum": 21600000
        },
        "clipDurationMilliseconds": {
          "type": "integer",
          "minimum": 1,
          "maximum": 21600000
        },
        "appliedAction": {
          "type": "string",
          "pattern": "^(placed|trim_clip_to_slot|pad_clip_to_slot)(\\+(mix_overlap|trimmed_for_overlap))*$"
        },
        "speaker": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 256
        },
        "inputSha256": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[a-f0-9]{64}$"
        },
        "warnings": {
          "$ref": "#/$defs/warnings"
        }
      },
      "additionalProperties": false
    },
    "interval": {
      "type": "object",
      "required": [
        "startMilliseconds",
        "endMilliseconds",
        "durationMilliseconds",
        "cueIds"
      ],
      "properties": {
        "startMilliseconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 21600000
        },
        "endMilliseconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 21600000
        },
        "durationMilliseconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 21600000
        },
        "cueIds": {
          "type": "array",
          "maxItems": 32,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "additionalProperties": false
    },
    "technique": {
      "type": "object",
      "required": [
        "name",
        "version",
        "engine",
        "engineVersion"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "version": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "engine": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "engineVersion": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "additionalProperties": false
    },
    "warning": {
      "type": "object",
      "required": [
        "code",
        "message",
        "path"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1000
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500
        }
      },
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/warning"
      }
    }
  },
  "additionalProperties": false
}