{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://fl-control/schemas/song-definition.json",
  "title": "SongDefinition",
  "description": "Complete song definition — the source of truth for one .rpp file",
  "type": "object",
  "required": ["meta"],
  "properties": {
    "meta": { "$ref": "#/definitions/SongMeta" },
    "tracks": {
      "type": "array",
      "description": "List of REAPER tracks with clips and plugins",
      "default": [],
      "items": { "$ref": "#/definitions/TrackDef" }
    },
    "patterns": {
      "type": "array",
      "description": "Pattern definitions for arrangement",
      "default": [],
      "items": { "$ref": "#/definitions/PatternDef" }
    },
    "items": {
      "type": "array",
      "description": "Arrangement items referencing patterns",
      "default": [],
      "items": { "$ref": "#/definitions/ArrangementItemDef" }
    },
    "progression_name": {
      "type": "string",
      "description": "Chord progression name (e.g. i-VII-VI-VII)",
      "default": "i-VII-VI-VII"
    },
    "section_template": {
      "type": "string",
      "description": "Section template name",
      "default": "standard"
    },
    "samples": {
      "type": "object",
      "description": "Sample file map (name → filename)",
      "default": {},
      "additionalProperties": { "type": "string" }
    },
    "sections": {
      "type": "array",
      "description": "Section definitions in playback order",
      "default": [],
      "items": { "$ref": "#/definitions/SectionDef" }
    },
    "master_plugins": {
      "type": "array",
      "description": "List of plugin registry keys for master FX chain",
      "default": [],
      "items": { "type": "string" }
    }
  },
  "definitions": {
    "SongMeta": {
      "title": "SongMeta",
      "description": "Song metadata — tempo, key, time signature",
      "type": "object",
      "required": ["bpm", "key"],
      "properties": {
        "bpm": {
          "type": "number",
          "description": "Tempo 20–999",
          "minimum": 20,
          "maximum": 999
        },
        "key": {
          "type": "string",
          "description": "Key string e.g. Am, Dm, Gm",
          "pattern": "^[A-G][b#]?m?$"
        },
        "title": {
          "type": "string",
          "description": "Song title",
          "default": ""
        },
        "ppq": {
          "type": "integer",
          "description": "Ticks per quarter note (REAPER default)",
          "default": 960
        },
        "time_sig_num": {
          "type": "integer",
          "description": "Time signature numerator",
          "default": 4
        },
        "time_sig_den": {
          "type": "integer",
          "description": "Time signature denominator",
          "default": 4
        },
        "calibrate": {
          "type": "boolean",
          "description": "Enable post-processing mix calibration",
          "default": true
        }
      }
    },
    "MidiNote": {
      "title": "MidiNote",
      "description": "A single MIDI note event",
      "type": "object",
      "required": ["pitch", "start", "duration"],
      "properties": {
        "pitch": {
          "type": "integer",
          "description": "MIDI note number 0–127 (60 = middle C)",
          "minimum": 0,
          "maximum": 127
        },
        "start": {
          "type": "number",
          "description": "Start time in beats from item start"
        },
        "duration": {
          "type": "number",
          "description": "Duration in beats"
        },
        "velocity": {
          "type": "integer",
          "description": "Velocity 0–127",
          "minimum": 0,
          "maximum": 127,
          "default": 64
        }
      }
    },
    "CCEvent": {
      "title": "CCEvent",
      "description": "A MIDI CC event within a clip",
      "type": "object",
      "required": ["controller", "time", "value"],
      "properties": {
        "controller": {
          "type": "integer",
          "description": "CC number (e.g. 11 = Expression)"
        },
        "time": {
          "type": "number",
          "description": "Position in beats from clip start"
        },
        "value": {
          "type": "integer",
          "description": "CC value 0–127",
          "minimum": 0,
          "maximum": 127
        }
      }
    },
    "ClipDef": {
      "title": "ClipDef",
      "description": "A clip placed on a track — either audio or MIDI",
      "type": "object",
      "required": ["position", "length"],
      "properties": {
        "position": {
          "type": "number",
          "description": "Start position in beats"
        },
        "length": {
          "type": "number",
          "description": "Duration in beats"
        },
        "name": {
          "type": "string",
          "description": "Display name",
          "default": ""
        },
        "audio_path": {
          "type": ["string", "null"],
          "description": "Absolute path to audio file (for audio clips)",
          "default": null
        },
        "midi_notes": {
          "type": "array",
          "description": "List of MIDI notes (for MIDI clips)",
          "default": [],
          "items": { "$ref": "#/definitions/MidiNote" }
        },
        "midi_cc": {
          "type": "array",
          "description": "MIDI CC events",
          "default": [],
          "items": { "$ref": "#/definitions/CCEvent" }
        },
        "loop": {
          "type": "boolean",
          "description": "Whether the audio clip loops",
          "default": false
        },
        "fade_in": {
          "type": "number",
          "description": "Fade-in duration in seconds",
          "default": 0.0
        },
        "fade_out": {
          "type": "number",
          "description": "Fade-out duration in seconds",
          "default": 0.0
        },
        "vol_mult": {
          "type": "number",
          "description": "Volume multiplier applied at clip level",
          "default": 1.0
        }
      }
    },
    "PluginDef": {
      "title": "PluginDef",
      "description": "A VST plugin instance on a track",
      "type": "object",
      "required": ["name", "path"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name (e.g. Serum 2)"
        },
        "path": {
          "type": "string",
          "description": "Plugin path/identifier (e.g. VST3: Serum 2 (Xfer Records))"
        },
        "index": {
          "type": "integer",
          "description": "Chain position (0 = first)",
          "default": 0
        },
        "params": {
          "type": "object",
          "description": "Optional dict of parameter index → value",
          "default": {},
          "additionalProperties": { "type": "number" }
        },
        "preset_data": {
          "type": ["array", "null"],
          "description": "Base64 preset chunks",
          "default": null,
          "items": { "type": "string" }
        },
        "role": {
          "type": "string",
          "description": "Track role for role-aware preset lookup (e.g. bass, lead, pad)",
          "default": ""
        },
        "builtin": {
          "type": "boolean",
          "description": "True → deferred to ReaScript, not written to .rpp",
          "default": false
        }
      }
    },
    "TrackDef": {
      "title": "TrackDef",
      "description": "A track in the REAPER project",
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Track display name"
        },
        "volume": {
          "type": "number",
          "description": "0.0–1.0 (maps to REAPER volume fader)",
          "default": 0.85
        },
        "pan": {
          "type": "number",
          "description": "-1.0 to 1.0",
          "default": 0.0
        },
        "color": {
          "type": "integer",
          "description": "REAPER color index (0–67), 0 = default",
          "default": 0
        },
        "clips": {
          "type": "array",
          "description": "Audio/MIDI clips placed on this track",
          "default": [],
          "items": { "$ref": "#/definitions/ClipDef" }
        },
        "plugins": {
          "type": "array",
          "description": "VST plugins on this track",
          "default": [],
          "items": { "$ref": "#/definitions/PluginDef" }
        },
        "send_reverb": {
          "type": "number",
          "description": "Reverb send level 0.0–1.0",
          "default": 0.0
        },
        "send_delay": {
          "type": "number",
          "description": "Delay send level 0.0–1.0",
          "default": 0.0
        },
        "send_level": {
          "type": "object",
          "description": "Dict mapping return track index → send level 0.0–1.0",
          "default": {},
          "additionalProperties": { "type": "number" }
        }
      }
    },
    "SectionDef": {
      "title": "SectionDef",
      "description": "A section in the song arrangement with energy and dynamics",
      "type": "object",
      "required": ["name", "bars"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name (e.g. intro, chorus, verse)"
        },
        "bars": {
          "type": "integer",
          "description": "Length in bars"
        },
        "energy": {
          "type": "number",
          "description": "Energy level 0.0–1.0 (controls velocity multiplier)",
          "default": 0.5
        },
        "velocity_mult": {
          "type": "number",
          "description": "Velocity multiplier applied to all notes in section",
          "default": 1.0
        },
        "vol_mult": {
          "type": "number",
          "description": "Volume multiplier applied to track in section",
          "default": 1.0
        }
      }
    },
    "PatternDef": {
      "title": "PatternDef",
      "description": "A pattern definition with generator and variation axes",
      "type": "object",
      "required": ["id", "name", "instrument", "channel", "bars", "generator"],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Unique pattern ID"
        },
        "name": {
          "type": "string",
          "description": "Display name (e.g. Kick Main)"
        },
        "instrument": {
          "type": "string",
          "description": "Sample/instrument key (e.g. kick, snare)"
        },
        "channel": {
          "type": "integer",
          "description": "MIDI channel (11 = kick, 12 = snare, etc.)"
        },
        "bars": {
          "type": "integer",
          "description": "Length in bars"
        },
        "generator": {
          "type": "string",
          "description": "Generator function name"
        },
        "velocity_mult": {
          "type": "number",
          "description": "Velocity multiplier (0.85–1.1)",
          "default": 1.0
        },
        "density": {
          "type": "number",
          "description": "Note density 0.0–1.0",
          "default": 1.0
        }
      }
    },
    "ArrangementItemDef": {
      "title": "ArrangementItemDef",
      "description": "An item placed in the arrangement referencing a pattern on a track",
      "type": "object",
      "required": ["pattern", "bar", "bars", "track"],
      "properties": {
        "pattern": {
          "type": "integer",
          "description": "Pattern ID"
        },
        "bar": {
          "type": "number",
          "description": "Start position in bars"
        },
        "bars": {
          "type": "number",
          "description": "Length in bars"
        },
        "track": {
          "type": "integer",
          "description": "Track index"
        }
      }
    },
    "ArrangementTrack": {
      "title": "ArrangementTrack",
      "description": "A track in the REAPER arrangement with index and display name",
      "type": "object",
      "required": ["index", "name"],
      "properties": {
        "index": {
          "type": "integer",
          "description": "Track index"
        },
        "name": {
          "type": "string",
          "description": "Display name"
        }
      }
    }
  }
}