{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/codai-ro/json-schema/codai-ro-music-room-schema.json",
  "title": "Music Room song",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/codai-ro-gateway-openapi.yml#/components/schemas/MusicRoom",
  "type": "object",
  "required": [
    "id",
    "object",
    "status",
    "phase",
    "gate",
    "brief",
    "language",
    "genre_id",
    "title",
    "creative_id",
    "demo_asset_id",
    "final_asset_id",
    "stems_asset_ids",
    "team",
    "critique",
    "listening",
    "robot_score",
    "copy_risk",
    "credits",
    "quota",
    "budget_micro_usd",
    "spent_micro_usd",
    "warnings",
    "error",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "object": {
      "type": "string",
      "enum": [
        "studio.music_room"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "running",
        "waiting",
        "succeeded",
        "failed"
      ],
      "description": "`running` while the team works, `waiting` at a gate, then `succeeded` or `failed`."
    },
    "phase": {
      "type": "string",
      "enum": [
        "plan",
        "gate_plan",
        "compose",
        "lyrics",
        "arrange",
        "parts",
        "render_demo",
        "gate_demo",
        "vocals",
        "mix",
        "master",
        "critique",
        "gate_final",
        "ready",
        "failed"
      ],
      "description": "plan → gate_plan → compose → lyrics → arrange → parts → render_demo → gate_demo → vocals → mix → master → critique → gate_final → ready | failed."
    },
    "gate": {
      "type": [
        "object",
        "null"
      ],
      "description": "The gate the song waits at (`null` when it is not waiting).",
      "required": [
        "kind",
        "since"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "plan",
            "demo",
            "final"
          ]
        },
        "since": {
          "type": "string",
          "format": "date-time"
        },
        "variants": {
          "type": "array",
          "description": "Plan gate only: up to 3 plan variants to choose from.",
          "items": {
            "$ref": "#/$defs/MusicRoomPlanVariant"
          }
        }
      }
    },
    "brief": {
      "type": "string"
    },
    "language": {
      "type": "string",
      "enum": [
        "ro",
        "en"
      ]
    },
    "genre_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "creative_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The editable audio creative holding the song."
    },
    "demo_asset_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "final_asset_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "stems_asset_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "team": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "role",
          "name",
          "status"
        ],
        "properties": {
          "role": {
            "$ref": "#/$defs/MusicRole"
          },
          "name": {
            "type": "string"
          },
          "instrument_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "track_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "rationale": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "done",
              "playing",
              "waiting"
            ]
          }
        }
      }
    },
    "critique": {
      "type": [
        "object",
        "null"
      ],
      "description": "The critic's last review.",
      "required": [
        "round",
        "scores",
        "verdict",
        "issues"
      ],
      "properties": {
        "round": {
          "type": "integer"
        },
        "scores": {
          "type": "object",
          "description": "Scores from 0 to 10 per aspect (`groove`, `harmony`, `melody`, `arrangement`, `mix`, `humanness`, `genre_fit`).",
          "additionalProperties": {
            "type": "number"
          }
        },
        "verdict": {
          "type": "string",
          "enum": [
            "ship",
            "revise"
          ]
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "role",
              "problem",
              "fix"
            ],
            "properties": {
              "role": {
                "$ref": "#/$defs/MusicRole"
              },
              "section_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "problem": {
                "type": "string"
              },
              "fix": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "listening": {
      "oneOf": [
        {
          "$ref": "#/$defs/MusicRoomListening"
        },
        {
          "type": "null"
        }
      ],
      "description": "What the critic heard on the master of the latest round (MR-11): measured listening features of codai-studio-media (spectral, dynamics, stereo width, a 16-point loudness timeline) with Meta Audiobox Aesthetics (CE content enjoyment, CU content usefulness, PC production complexity, PQ production quality, about 1-10), and a Gemini listener's verdict (0-10 impressions, timestamped notes, audible AI tells). null before the critic ran. Either half is null when that listener was unavailable; when both are, the song carries the `critic_text_only` warning."
    },
    "robot_score": {
      "type": [
        "number",
        "null"
      ],
      "description": "Symbolic AI-tell metric: 0 sounds human, 1 sounds robotic."
    },
    "copy_risk": {
      "type": [
        "object",
        "null"
      ],
      "description": "Melody similarity against the reference corpus.",
      "required": [
        "max_score",
        "matches"
      ],
      "properties": {
        "max_score": {
          "type": "number"
        },
        "matches": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "score": {
                "type": "number"
              }
            }
          }
        }
      }
    },
    "credits": {
      "type": "array",
      "description": "Credit lines to publish with the song (CC-BY sample libraries, plugins used, `Built with Llama`…).",
      "items": {
        "type": "string"
      }
    },
    "quota": {
      "type": "object",
      "required": [
        "within",
        "used",
        "included"
      ],
      "properties": {
        "within": {
          "type": "boolean",
          "description": "The song is covered by the monthly plan quota (free)."
        },
        "used": {
          "type": "integer"
        },
        "included": {
          "type": "integer"
        }
      }
    },
    "budget_micro_usd": {
      "type": "string"
    },
    "spent_micro_usd": {
      "type": "string"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Non-fatal notes. Voice passport values: `voice_passport_beta` (sung with your voice, beta: approximates your timbre), `voice_passport_needs_singing_consent` (the voice has no active singing consent, or it was revoked during the song), `voice_passport_not_found` (not one of your active voices), `voice_passport_unavailable` (voice cloning is not enabled for your account, or the voice is paused), `voice_passport_lyrics_refused` (the lyrics failed the voice-safety text check, so the passport was not used). Others: `artist_reference_removed: N`, `vocal_asr_check_unavailable`, `critic_text_only` (the critic could not listen to the master and judged from the score), `local_plugin_fallback: N` (N desktop-only plugin tracks were not rendered by your desktop in time and used their instrument), `<step>_skipped: <reason>`."
    },
    "error": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "MusicRole": {
      "type": "string",
      "title": "Music Room role",
      "description": "A member of the Music Room team.",
      "enum": [
        "producer",
        "composer",
        "lyricist",
        "arranger",
        "drums",
        "bass",
        "guitar",
        "keys",
        "strings",
        "brass",
        "winds",
        "balkan_lead",
        "balkan_rhythm",
        "percussion",
        "synth",
        "vocal_producer",
        "sound_designer",
        "mix_engineer",
        "mastering_engineer",
        "critic",
        "rights"
      ]
    },
    "MusicRoomListening": {
      "type": "object",
      "title": "Music Room listening",
      "required": [
        "features",
        "verdict",
        "model"
      ],
      "properties": {
        "features": {
          "type": [
            "object",
            "null"
          ],
          "description": "Measured listening features of the master (codai-studio-media). `null` when the measurement was unavailable.",
          "properties": {
            "duration_seconds": {
              "type": [
                "number",
                "null"
              ],
              "description": "Length of the master in seconds."
            },
            "spectral_centroid_hz": {
              "type": [
                "number",
                "null"
              ],
              "description": "Mean spectral centroid (brightness) in Hz."
            },
            "spectral_centroid_std_hz": {
              "type": [
                "number",
                "null"
              ],
              "description": "Standard deviation of the spectral centroid in Hz."
            },
            "spectral_flatness": {
              "type": [
                "number",
                "null"
              ],
              "description": "Mean spectral flatness (0 tonal, 1 noise-like)."
            },
            "onset_rate_per_s": {
              "type": [
                "number",
                "null"
              ],
              "description": "Note onsets per second."
            },
            "onset_rate_cv": {
              "type": [
                "number",
                "null"
              ],
              "description": "Coefficient of variation of the onset rate (how much the rhythmic density changes)."
            },
            "crest_factor_db": {
              "type": [
                "number",
                "null"
              ],
              "description": "Crest factor in dB (peak to RMS; low means heavily compressed)."
            },
            "loudness_range_lu": {
              "type": [
                "number",
                "null"
              ],
              "description": "Loudness range in LU."
            },
            "stereo_width": {
              "type": [
                "number",
                "null"
              ],
              "description": "Stereo width (0 mono, higher is wider)."
            },
            "loudness_timeline_lufs": {
              "type": "array",
              "description": "Integrated loudness in LUFS for each 1/16 of the song (16 points; `null` for a silent slice).",
              "items": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "aesthetics": {
              "type": [
                "object",
                "null"
              ],
              "description": "Meta Audiobox Aesthetics, about 1-10: CE content enjoyment, CU content usefulness, PC production complexity, PQ production quality. `null` when unavailable.",
              "required": [
                "CE",
                "CU",
                "PC",
                "PQ"
              ],
              "properties": {
                "CE": {
                  "type": "number"
                },
                "CU": {
                  "type": "number"
                },
                "PC": {
                  "type": "number"
                },
                "PQ": {
                  "type": "number"
                }
              }
            }
          }
        },
        "verdict": {
          "type": [
            "object",
            "null"
          ],
          "description": "The Gemini listener's verdict. `null` when the listener was unavailable.",
          "required": [
            "impressions",
            "notes",
            "ai_tells",
            "summary"
          ],
          "properties": {
            "impressions": {
              "type": "object",
              "description": "Impressions from 0 to 10 per aspect; `vocals` is `null` for an instrumental.",
              "required": [
                "groove",
                "melody",
                "mix",
                "vocals",
                "humanness",
                "genre_fit"
              ],
              "properties": {
                "groove": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 10
                },
                "melody": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 10
                },
                "mix": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 10
                },
                "vocals": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "minimum": 0,
                  "maximum": 10
                },
                "humanness": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 10
                },
                "genre_fit": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 10
                }
              }
            },
            "notes": {
              "type": "array",
              "maxItems": 8,
              "description": "Up to 8 timestamped notes.",
              "items": {
                "type": "object",
                "required": [
                  "at_seconds",
                  "note"
                ],
                "properties": {
                  "at_seconds": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Position in the master, in seconds."
                  },
                  "note": {
                    "type": "string"
                  }
                }
              }
            },
            "ai_tells": {
              "type": "array",
              "maxItems": 6,
              "description": "Up to 6 audible signs of AI or MIDI generation (empty if none).",
              "items": {
                "type": "string"
              }
            },
            "summary": {
              "type": "string",
              "description": "One-paragraph summary of what the listener heard."
            }
          }
        },
        "model": {
          "type": [
            "string",
            "null"
          ],
          "description": "The listener model."
        }
      }
    },
    "MusicRoomPlanVariant": {
      "type": "object",
      "title": "Music Room plan variant",
      "required": [
        "title",
        "genre_id",
        "bpm",
        "meter",
        "mode_id",
        "sections",
        "instrumentation",
        "rationale"
      ],
      "properties": {
        "title": {
          "type": "string"
        },
        "genre_id": {
          "type": "string"
        },
        "bpm": {
          "type": "number"
        },
        "meter": {
          "type": "string",
          "description": "Time signature, e.g. `4/4` or `7/8`."
        },
        "mode_id": {
          "type": "string",
          "description": "Scale / mode id, e.g. `major`, `minor`, `hijaz`."
        },
        "sections": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "kind",
              "bars"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              },
              "bars": {
                "type": "integer"
              }
            }
          }
        },
        "instrumentation": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "role",
              "instrument_id"
            ],
            "properties": {
              "role": {
                "$ref": "#/$defs/MusicRole"
              },
              "instrument_id": {
                "type": "string"
              }
            }
          }
        },
        "rationale": {
          "type": "string"
        }
      }
    }
  }
}