Madoo contracts
Madoo describes the JSON its nodes exchange with versioned contracts, written in JSON Schema (Draft 2020-12) and named
madoo.<name>/v<N>. Each page below is generated from the schema the platform serves, so it is always the contract
in force: its fields, where it appears in the node catalog, an example when there is one, and the complete schema.
The same schemas are served by GET /api/v1/json-schemas and get_json_schema; why they exist and how to check a
document against one is explained in Schemas and contracts.
| Contract | Name | What it is |
|---|---|---|
madoo.dataset-profile/v1 |
Madoo dataset profile | Bounded inspection result used to author and qualify a tabular data source. |
madoo.dataset-row/v1 |
Madoo dataset row | One normalized dataset row with stable identity and explicit value presence. |
madoo.dataset/v1 |
Madoo dataset | Format-neutral descriptor for a normalized tabular dataset and its row store. |
Assets
Section titled “Assets”| Contract | Name | What it is |
|---|---|---|
madoo.bundle-manifest/v1 |
Madoo bundle manifest | Portable manifest for an authorized logical collection of uploaded assets. |
Quality and media
Section titled “Quality and media”| Contract | Name | What it is |
|---|---|---|
madoo.media-policy/v1 |
Madoo media policy | Deterministic technical constraints evaluated against media facts. |
madoo.media-technical-info/v1 |
Madoo media technical information | Normalized technical facts for a storage-backed image, audio, or video asset. |
madoo.quality-check/v1 |
Madoo quality check | One deterministic check with explicit measurements, violations, and technique version. |
madoo.quality-policy/v1 |
Madoo quality policy | Rules for aggregating one or more portable quality checks. |
madoo.quality-report/v1 |
Madoo quality report | Self-contained, explainable result of a quality-gate decision. |
madoo.quality-violations/v1 |
Madoo quality violations | Bounded portable quality violations emitted by deterministic probes. |
Documents and images
Section titled “Documents and images”| Contract | Name | What it is |
|---|---|---|
madoo.design-document/2.0 |
Madoo DesignDocument 2.0 | A whole document template as the editor saves it; read, create and replace templates in this format. |
madoo.design-pages-manifest/v1 |
DesignDocument page images manifest (v1) | Results of runs before the public template ids: numeric document and version ids. |
madoo.design-pages-manifest/v2 |
DesignDocument page images manifest | Selected raster pages and durable image references from a published document template. |
madoo.image-detail/v1 |
Madoo image detail | Fine detail and residuals of an image on small patches, globally and per tone band, and the patches to look at closely with a context rectangle ready for Crop (Image Detail). |
madoo.image-faces/v1 |
Madoo image faces | Where the faces of an image are (Face Detect): score, box and six points (eyes, nose tip, mouth, ears) of each face, and the crop region framed around the selected one. Locates faces, never identifies anyone. |
madoo.image-instances/v1 |
Madoo image instances | The people, animals and objects a model found in an image (80 COCO classes): class, score, box, mask area and edges reached of each instance, and which ones form the output mask (Instance Segment). A prediction, not a measurement. |
madoo.image-layout-report/v1 |
Madoo professional still-image layout report | Authoritative exact-font, fitting, clipping, bounding-box and safe-area evidence for each rendered layer. |
madoo.image-set/v1 |
Madoo image set | A list of images, each a Madoo storage reference with an optional label and metadata: frames of a video, pages, any set of pictures. |
madoo.image-statistics/v1 |
Madoo image statistics | Tone and colour of an image, of grid cells or regions, optionally inside a mask: luma quantiles, near-black and near-white shares, luminance, Oklab means, colour per tone band (Image Statistics). |
madoo.image-text-layers/v1 |
Madoo professional still-image text layers | One to 32 stable-ID text layers with deterministic z-order and optional complete style snapshots. |
madoo.image-typography/v1 |
Madoo professional still-image typography | Exact-font sizing, layout, safe-area and readability style for deterministic still-image text. |
madoo.template-layout-report/v1 |
DesignDocument template layout report (v1) | Results of runs before the public template ids: numeric document and version ids. |
madoo.template-layout-report/v2 |
DesignDocument template layout report | Public template identity, page selection, repeated content, image loading and timing evidence. |
| Contract | Name | What it is |
|---|---|---|
madoo.audio-processing-report/v1 |
Madoo audio processing report | Explainable before-and-after envelope for an Audio Finishing transformation. |
madoo.audio-quality-report/v1 |
Madoo audio quality report | Deterministic loudness, peak, clipping, and silence measurements for one audio signal. |
madoo.audio-timeline/v1 |
Madoo audio timeline | Deterministic evidence for audio clips placed on an absolute master timeline. |
madoo.stem-separation/v1 |
Madoo stem separation receipt | Provider-neutral evidence for a named four-stem source-separation result. |
madoo.tts-generation/v1 |
Madoo text-to-speech generation receipt | Provider-neutral evidence describing one synthesized speech clip and its effective controls. |
Transcripts and captions
Section titled “Transcripts and captions”| Contract | Name | What it is |
|---|---|---|
madoo.caption-block-family/v1 |
Madoo caption block family | Caption block emitted in ordinary v1 mode or duration-aware v2 mode. |
madoo.caption-block/v1 |
Madoo caption block | One bounded group of caption cues plus read-only neighbouring context for translation. |
madoo.caption-block/v2 |
Madoo duration-aware caption block | One pending cue with original context and measured feedback for bounded spoken adaptation. |
madoo.caption-track/v1 |
Madoo caption track | Provider-neutral ordered caption cues on an absolute media timeline. |
madoo.caption-translation-block/v1 |
Madoo translated caption block | Validated translated texts aligned one-to-one with the immutable cue IDs of a caption block. |
madoo.caption-translation-quality/v1 |
Madoo caption translation quality | Cue coverage, timing preservation, bounded-repair counts and warnings for a translated caption track. |
madoo.transcript-aggregation-quality/v1 |
Madoo transcript aggregation quality | Coverage, overlap reconciliation, cleanup counts, duration and warnings for an aggregated transcript. |
madoo.transcript-segments/v1 |
Madoo timed transcript | Provider-neutral speech segments or words with media-relative timestamps. |
Dubbing and natural speech
Section titled “Dubbing and natural speech”| Contract | Name | What it is |
|---|---|---|
madoo.dubbing-cue-evidence/v1 |
Madoo dubbing cue evidence | Per-cue TTS generation and duration-fit evidence collected for the dubbing manifest. |
madoo.dubbing-manifest/v1 |
Madoo dubbing manifest | Auditable delivery manifest for a timeline-aware localized dubbing workflow. |
madoo.dubbing-manifest/v2 |
Madoo natural speech dubbing manifest | Delivery evidence with immutable plan, measured candidates and complete attempt history. |
madoo.speech-timing-assessment/v1 |
Madoo speech timing assessment | Measured speech candidate with deterministic acceptance and natural padding evidence. |
madoo.speech-timing-candidate-rows/v1 |
Madoo measured speech candidate rows | Candidate rows collected by aggregate/json for one speech-timing reconciliation round. |
madoo.speech-timing-candidate/v1 |
Madoo measured speech candidate | One authenticated synthesized speech candidate with measured duration and signal evidence. |
madoo.speech-timing-delivery/v1 |
Madoo selected natural speech | Authenticated accepted speech rows for ordinary enumeration and finishing. |
madoo.speech-timing-plan/v1 |
Madoo speech timing plan | Immutable aligned caption plan and conservative speaking/fit policy. |
madoo.speech-timing-policy/v1 |
Madoo speech timing policy | Bounded round, speaking-rate, fit-rate and tolerance controls for natural speech. |
madoo.speech-timing-state/v1 |
Madoo speech timing state | Bounded round checkpoint preserving accepted candidates and all rejected attempts. |
Video highlights
Section titled “Video highlights”| Contract | Name | What it is |
|---|---|---|
madoo.video-edit-manifest/v1 |
Madoo video edit manifest | Measured mapping between source ranges and an assembled output-video timeline. |
madoo.video-highlight-candidates/v1 |
Madoo video highlight candidates | Bounded, provider-neutral highlight suggestions for one source-video segment. |
madoo.video-highlight-plan/v1 |
Madoo video highlight plan | Deterministic chronological edit plan selected under an explicit duration budget. |
madoo.video-scenes/v1 |
Madoo video scenes | What a video is made of: its scenes between cuts and black gaps, the gaps, and the frames chosen for each scene (Extract Scenes). |
madoo.video-text-track/v1 |
Madoo video text track | Timed text events rendered together over a video by Video Text Overlay, in one encoding pass. |
madoo.video-typography/v1 |
Madoo video typography | Exact font, size, colour, safe-area layout, outline, shadow, background box and motion of video text. |
Diagnostics
Section titled “Diagnostics”| Contract | Name | What it is |
|---|---|---|
madoo.attempts-report/v1 |
Madoo attempts report | What Repeat Until Accepted did: the body and its version, the policy, every attempt with its run, acceptance, score and feedback, and which attempt was delivered and why. |
madoo.color-palette/v1 |
Madoo color palette | The colors an image is made of, by share: hex, OKLCh, CSS name, dominant, accent and background roles, a readable text color (Color Palette). |
madoo.decision-questions/v1 |
Madoo decision questions | The questions Decide with a Model asks about its content: yes/no, a choice between options or a score on levels, each with its instructions and the threshold its answer must reach. Each question names output ports of the step. |
madoo.decision/v1 |
Madoo decision | What Decide with a Model answered: for each question the answer, the probability of every option or level and whether it reached its threshold (accepted, uncertain, refused or invalid). |
madoo.json-schema-errors/v1 |
JSON Schema validation errors | Structured diagnostics emitted by utility/json_schema_validate. |
madoo.keyframe-map/v1 |
Madoo keyframe map | Where each image sits in a clip generated by Keyframes to Video: evenly spread or at explicit frames. |
madoo.mask-measurements/v1 |
Madoo mask measurements | Where the subject of an image is and how big it is, per region: box, area, coverage, centroid, edges touched, bands and profile (Measure Subject). |
madoo.speaker-voices/v1 |
Madoo speaker voices | The voice every speaker of a recording is voiced with. |
madoo.string-list/v1 |
Madoo string list | Bounded list of non-empty identifiers such as failed quality-check IDs. |
madoo.subject-location/v1 |
Madoo subject location | Where Locate Subject found the subject of the reference pictures (or of the description) in a picture: its box and the crop region framed around it, its share of the picture, the edges it touches, whether it was ambiguous and the other candidates. A prediction, not a measurement. |