SonicForgeStudio/app/models/project_schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "DAWProject",
  "type": "object",
  "properties": {
    "project_id": { "type": "string" },
    "metadata": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "bpm": { "type": "number", "minimum": 20.0, "maximum": 999.0, "default": 120.0 },
        "time_signature_numerator": { "type": "integer", "default": 4 },
        "time_signature_denominator": { "type": "integer", "default": 4 },
        "sample_rate": { "type": "integer", "default": 44100 }
      },
      "required": ["title", "bpm", "time_signature_numerator", "time_signature_denominator", "sample_rate"]
    },
    "main_session": { "$ref": "#/definitions/SessionContainer" },
    "section_store": {
      "type": "object",
      "description": "Auxiliary registry mapping section_id to sub-session containers",
      "additionalProperties": { "$ref": "#/definitions/SessionContainer" }
    }
  },
  "required": ["project_id", "metadata", "main_session", "section_store"],
  "definitions": {
    "SessionContainer": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "is_root": { "type": "boolean" },
        "length_bars": { "type": "number", "description": "Computed or manually set total length in bars" },
        "auto_compute_length": { "type": "boolean", "default": true },
        "tracks": {
          "type": "array",
          "items": { "$ref": "#/definitions/Track" }
        },
        "master": {
          "type": "object",
          "description": "Master bus strip: per-channel L/R faders + LINK + MUTE",
          "properties": {
            "volume_db": { "type": "number", "default": 0.0, "description": "Legacy single fader (fallback khi khong co volumeL_db)" },
            "volumeL_db": { "type": "number", "default": 0.0 },
            "volumeR_db": { "type": "number", "default": 0.0 },
            "link_lr": { "type": "boolean", "default": false, "description": "LINK: keo L/R cung luc (R theo L)" },
            "muted": { "type": "boolean", "default": false, "description": "MUTE master: zero output" },
            "mute": { "type": "boolean", "default": false },
            "bypass": { "type": "boolean", "default": false },
            "fx_chain": {
              "type": "array",
              "items": { "$ref": "#/definitions/FXPlugin" }
            },
            "automation": {
              "type": "object",
              "description": "Gap 7: master automation lanes (volume_db)", 
              "properties": {
                "volume_db": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "time": { "type": "number", "description": "giây" },
                      "db": { "type": "number", "minimum": -30.0, "maximum": 3.0 }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "required": ["id", "is_root", "tracks"]
    },
    "Track": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "type": { "type": "string", "enum": ["AUDIO", "MIDI", "SECTION"] },
        "color": { "type": ["string", "null"], "default": null },
        "volume_db": { "type": "number", "default": 0.0 },
        "pan": { "type": "number", "minimum": -1.0, "maximum": 1.0, "default": 0.0 },
        "mute": { "type": "boolean", "default": false },
        "solo": { "type": "boolean", "default": false },
        "fx_chain": {
          "type": "array",
          "items": { "$ref": "#/definitions/FXPlugin" }
        },
        "synth_engine": { "$ref": "#/definitions/SynthPlugin" },
        "items": {
          "type": "array",
          "items": { "$ref": "#/definitions/TimelineItem" }
        }
      },
      "required": ["id", "name", "type", "items"]
    },
    "TimelineItem": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "type": { "type": "string", "enum": ["AUDIO_ITEM", "MIDI_ITEM", "SECTION_ITEM"] },
        "start_bar": { "type": "number", "description": "Global timeline position where the item starts" },
        "duration_bars": { "type": "number", "description": "Visible duration on the track timeline in bars" },
        "clip_start_offset_bars": { "type": "number", "description": "Internal start offset inside the source buffer/item" },
        "source_data": {
          "type": "object",
          "oneOf": [
            { "$ref": "#/definitions/AudioSourceData" },
            { "$ref": "#/definitions/MIDISourceData" },
            { "$ref": "#/definitions/SectionSourceData" }
          ]
        }
      },
      "required": ["id", "type", "start_bar", "duration_bars", "clip_start_offset_bars", "source_data"]
    },
    "AudioSourceData": {
      "type": "object",
      "properties": {
        "audio_file_url": { "type": "string" },
        "sample_rate": { "type": "integer" },
        "channels": { "type": "integer" },
        "gain": { "type": "number", "default": 1.0 }
      },
      "required": ["audio_file_url"]
    },
    "MIDISourceData": {
      "type": "object",
      "properties": {
        "total_buffer_bars": { "type": "number", "default": 8.0 },
        "notes": {
          "type": "array",
          "items": { "$ref": "#/definitions/MIDINote" }
        }
      },
      "required": ["total_buffer_bars", "notes"]
    },
    "SectionSourceData": {
      "type": "object",
      "properties": {
        "referenced_section_id": { "type": "string", "description": "Pointer to section_store key" }
      },
      "required": ["referenced_section_id"]
    },
    "MIDINote": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "pitch": { "type": "integer", "minimum": 0, "maximum": 127 },
        "start_beat": { "type": "number", "description": "Beat offset relative to the start of the source buffer (bar 0)" },
        "duration_beats": { "type": "number" },
        "velocity": { "type": "number", "minimum": 0.0, "maximum": 1.0, "default": 0.8 },
        "pan": { "type": "number", "minimum": -1.0, "maximum": 1.0, "default": 0.0 },
        "expression_curve": {
          "type": "array",
          "description": "CC11 expression automation: normalized position 0..1 in note, value 0..127",
          "items": {
            "type": "object",
            "properties": {
              "position_ratio": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
              "value": { "type": "integer", "minimum": 0, "maximum": 127 }
            },
            "required": ["position_ratio", "value"]
          }
        }
      },
      "required": ["id", "pitch", "start_beat", "duration_beats", "velocity"]
    },
    "FXPlugin": {
      "type": "object",
      "properties": {
        "plugin_id": { "type": "string" },
        "name": { "type": "string" },
        "bypass": { "type": "boolean", "default": false },
        "parameters": { "type": "object" }
      }
    },
    "SynthPlugin": {
      "type": "object",
      "properties": {
        "plugin_id": { "type": "string" },
        "preset_id": { "type": "string" },
        "parameters": { "type": "object" }
      }
    }
  }
}