{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ajturner.github.io/tutti-music/schema/tutti-song.schema.json",
  "title": "Tutti song",
  "description": "A Tutti symphonic-tracker song, format version 4. Vocabulary: docs/domain.md. A song is arranged from sections, a section is made of phrases, a phrase is a few bars for every instrument, and the ideas inside it are patterns placed on instruments. Timing is in ticks at 960 pulses per quarter note. Pitches are MIDI note numbers (60 = C4). Velocities and controller values follow MIDI (0-127).",
  "type": "object",
  "required": [
    "format",
    "version",
    "title",
    "bpm",
    "instruments",
    "phrases",
    "sections",
    "arrangement"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri"
    },
    "format": {
      "const": "tutti-song",
      "description": "File format marker."
    },
    "version": {
      "const": 4,
      "description": "Format version. 4: sections arranged into a song, phrases as the block for every instrument, patterns placed with transformations. Earlier versions are not read."
    },
    "uid": {
      "type": "string",
      "description": "Stable identifier used by autosave to match a stored song to a built-in example or an earlier save."
    },
    "title": {
      "type": "string"
    },
    "notes": {
      "type": "string",
      "description": "Free text shown under the grid."
    },
    "bpm": {
      "type": "number",
      "minimum": 20,
      "maximum": 300,
      "description": "Base tempo; the tempo lane of each phrase overrides it while that phrase plays."
    },
    "key": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/key"
        }
      ],
      "description": "Key and scale used for scale highlighting and diatonic transposition. null or absent means no key (chromatic)."
    },
    "banks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Sound banks the song's instruments need: bundled bank ids (jazz, folk, electronica) or URLs of bank.json files. Loaded before the song plays."
    },
    "instruments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/instrument"
      },
      "description": "The players of the song, in score order. Each is made from a sound and carries its own name, mix and shaping; several may use one sound."
    },
    "patterns": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/pattern"
      },
      "description": "Reusable single-voice lines (what musicians call a motif, riff, lick, figure or hook). Only placed, never arranged."
    },
    "phrases": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/phrase"
      },
      "description": "A few bars for every instrument: the unit the grid shows and the only owner of time."
    },
    "sections": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/section"
      },
      "description": "Named spans of the song (intro, verse, chorus, bridge; A, B; exposition, coda), each made of phrases in order."
    },
    "arrangement": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/arrangementItem"
      },
      "description": "The sections in playing order."
    }
  },
  "$defs": {
    "tick": {
      "type": "integer",
      "minimum": 0,
      "description": "Ticks from the start of the phrase at 960 PPQ."
    },
    "midiValue": {
      "type": "integer",
      "minimum": 0,
      "maximum": 127
    },
    "articulation": {
      "type": "string",
      "enum": [
        "sus",
        "leg",
        "stc",
        "mrc",
        "trm",
        "piz",
        "mut",
        "rll"
      ],
      "description": "sus sustain, leg legato, stc staccato, mrc marcato, trm tremolo, piz pizzicato, mut muted, rll roll. Each instrument supports a subset; the first in its list is the default."
    },
    "point": {
      "type": "object",
      "required": [
        "tick",
        "value"
      ],
      "additionalProperties": false,
      "properties": {
        "tick": {
          "$ref": "#/$defs/tick"
        },
        "value": {
          "type": "number"
        },
        "interp": {
          "type": "string",
          "enum": [
            "lin",
            "step"
          ],
          "default": "lin",
          "description": "lin ramps to the next point; step holds until it."
        }
      }
    },
    "lane": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/point"
      },
      "description": "Points sorted by tick; at most one point per tick."
    },
    "phrase": {
      "type": "object",
      "required": [
        "id",
        "name",
        "rows",
        "ticksPerRow"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$",
          "description": "Stable key used by sections."
        },
        "name": {
          "type": "string"
        },
        "rows": {
          "type": "integer",
          "minimum": 1,
          "maximum": 512
        },
        "ticksPerRow": {
          "type": "integer",
          "minimum": 1,
          "description": "240 = one sixteenth note at 960 PPQ."
        },
        "meter": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "prefixItems": [
            {
              "type": "integer",
              "minimum": 1,
              "maximum": 16
            },
            {
              "type": "integer",
              "enum": [
                2,
                4,
                8
              ]
            }
          ],
          "default": [
            4,
            4
          ],
          "description": "Beats per bar and beat unit, as in a time signature."
        },
        "tempo": {
          "$ref": "#/$defs/lane",
          "description": "Tempo lane in bpm (20-300). Only a phrase has one."
        },
        "groove": {
          "type": "array",
          "maxItems": 16,
          "items": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "description": "Row-length multipliers applied cyclically and normalised to keep the phrase length; [1.33, 0.67] swings pairs of rows. Empty, absent or all 1 means straight."
        },
        "key": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/key"
            }
          ],
          "description": "Key override for this phrase; null or absent inherits the song key."
        },
        "material": {
          "type": "object",
          "description": "Material per instrument, keyed by instrument id.",
          "additionalProperties": {
            "$ref": "#/$defs/material"
          }
        }
      },
      "description": "A few bars for every instrument, with its own length, row size, meter, tempo lane, groove and optional key."
    },
    "instrument": {
      "type": "object",
      "required": [
        "id",
        "name",
        "sound",
        "channel"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$",
          "description": "Stable key used by phrase.material."
        },
        "name": {
          "type": "string"
        },
        "sound": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$",
          "description": "Id of the sound this instrument is made from, provided by a bank; see tutti-instrument.schema.json."
        },
        "channel": {
          "type": "integer",
          "minimum": 1,
          "maximum": 16,
          "description": "MIDI channel, 1-based."
        },
        "columns": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "default": 1,
          "description": "Note columns (divisi voices)."
        },
        "mute": {
          "type": "boolean",
          "default": false
        },
        "solo": {
          "type": "boolean",
          "default": false,
          "description": "When any instrument is soloed, only soloed instruments play. Transient performance state; saved for convenience."
        },
        "volume": {
          "type": "integer",
          "minimum": 0,
          "maximum": 127,
          "default": 100,
          "description": "Mixer volume, sent as CC7 at the start."
        },
        "pan": {
          "type": "integer",
          "minimum": 0,
          "maximum": 127,
          "default": 64,
          "description": "Mixer pan, sent as CC10 at the start; 64 is centre."
        },
        "tune": {
          "type": "integer",
          "minimum": -24,
          "maximum": 24,
          "default": 0,
          "description": "Tuning of the preview sound in semitones. Audio only: exported MIDI carries the written pitch."
        },
        "cents": {
          "type": "number",
          "minimum": -100,
          "maximum": 100,
          "default": 0,
          "description": "Fine tuning of the preview sound in cents. Audio only."
        },
        "trim": {
          "type": "number",
          "minimum": -24,
          "maximum": 24,
          "default": 0,
          "description": "Level trim of the preview sound in dB, before the mixer volume. Audio only."
        },
        "release": {
          "type": "number",
          "minimum": 0.25,
          "maximum": 4,
          "default": 1,
          "description": "Scale of the preview sound's release time. Audio only."
        }
      },
      "description": "A player in this song, made from a sound: name, MIDI channel, note columns, mix (volume, pan, mute, solo) and shaping of the sound (tune, cents, trim, release)."
    },
    "fx": {
      "type": "object",
      "required": [
        "tick",
        "cmd",
        "value"
      ],
      "additionalProperties": false,
      "properties": {
        "tick": {
          "$ref": "#/$defs/tick"
        },
        "cmd": {
          "type": "string",
          "enum": [
            "CHA",
            "RET",
            "DEL",
            "ARP",
            "TSP",
            "EXP"
          ],
          "description": "CHA chance (value/255), RET retrigger count, DEL delay by value/256 row, ARP arpeggio (two nibbles of semitones), TSP transpose (signed byte, persists until the next TSP). EXP expression shape: high nibble 1 swell, 2 sfz, 3 fade in, 4 fade out; low nibble depth."
        },
        "value": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        }
      }
    },
    "key": {
      "type": "object",
      "required": [
        "root",
        "scale"
      ],
      "additionalProperties": false,
      "properties": {
        "root": {
          "type": "integer",
          "minimum": 0,
          "maximum": 11,
          "description": "Pitch class of the tonic, 0 = C."
        },
        "scale": {
          "type": "string",
          "enum": [
            "major",
            "natural-minor",
            "harmonic-minor",
            "melodic-minor",
            "dorian",
            "phrygian",
            "lydian",
            "mixolydian",
            "pentatonic-major",
            "pentatonic-minor",
            "whole-tone",
            "chromatic"
          ]
        }
      }
    },
    "note": {
      "type": "object",
      "required": [
        "tick",
        "len",
        "pitch",
        "vel",
        "col"
      ],
      "additionalProperties": false,
      "properties": {
        "tick": {
          "$ref": "#/$defs/tick"
        },
        "len": {
          "type": "integer",
          "minimum": 1,
          "description": "Duration in ticks."
        },
        "pitch": {
          "$ref": "#/$defs/midiValue"
        },
        "vel": {
          "type": "integer",
          "minimum": 1,
          "maximum": 127
        },
        "col": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3,
          "description": "Note column (divisi voice) on the instrument. Notes in one column never overlap."
        },
        "art": {
          "oneOf": [
            {
              "$ref": "#/$defs/articulation"
            },
            {
              "type": "null"
            }
          ],
          "description": "null means the instrument's default articulation."
        },
        "chance": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "The note's own chance of playing, in percent. Absent means 100. Takes the place of CHA on its row for this note."
        },
        "retrigger": {
          "type": "integer",
          "minimum": 1,
          "maximum": 8,
          "description": "How many times the note plays, evenly spaced across its length. Absent means 1. Takes the place of RET on its row for this note."
        },
        "offset": {
          "type": "integer",
          "minimum": -50,
          "maximum": 50,
          "description": "How far the note's start moves, in percent of a row; negative is earlier. Absent means 0. Takes the place of DEL on its row for this note."
        }
      },
      "description": "A pitch at a tick in a note column with velocity, length and articulation, and optionally its own chance, retrigger and offset."
    },
    "material": {
      "type": "object",
      "properties": {
        "notes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/note"
          }
        },
        "dyn": {
          "$ref": "#/$defs/lane",
          "description": "Dynamics lane, 0-127, sent as the instrument's dynamics controller (CC1 by default)."
        },
        "expr": {
          "$ref": "#/$defs/lane",
          "description": "Expression lane, 0-127, sent as the instrument's expression controller (CC11 by default)."
        },
        "fx": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/fx"
          },
          "description": "FX column: at most one command per row."
        },
        "placements": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/placement"
          },
          "description": "Patterns played inside this material."
        }
      },
      "description": "Notes, lanes, fx and placements for one instrument over some rows. The one shape a phrase (per instrument) and a pattern hold."
    },
    "placement": {
      "type": "object",
      "required": [
        "pattern",
        "row"
      ],
      "additionalProperties": false,
      "description": "One use of a pattern on a instrument of a phrase, with its transformations.",
      "properties": {
        "pattern": {
          "type": "string",
          "description": "Id of a pattern in the song."
        },
        "row": {
          "type": "integer",
          "minimum": 0,
          "description": "Row of the phrase where the pattern starts."
        },
        "transpose": {
          "type": "integer",
          "minimum": -48,
          "maximum": 48,
          "default": 0,
          "description": "Semitones added to every note."
        },
        "shift": {
          "type": "integer",
          "minimum": -28,
          "maximum": 28,
          "default": 0,
          "description": "Scale degrees moved in the key in force where the placement sounds (phrase, else section, else song). Applied before transpose."
        },
        "octave": {
          "type": "integer",
          "minimum": -4,
          "maximum": 4,
          "default": 0,
          "description": "Octaves added to every note."
        },
        "dynamics": {
          "type": "integer",
          "minimum": -96,
          "maximum": 96,
          "default": 0,
          "description": "Added to every note's velocity: negative is softer."
        },
        "repeat": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 1,
          "description": "How many times the pattern plays back to back from the row."
        }
      }
    },
    "pattern": {
      "type": "object",
      "required": [
        "id",
        "name",
        "rows",
        "material"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$"
        },
        "name": {
          "type": "string"
        },
        "rows": {
          "type": "integer",
          "minimum": 1,
          "maximum": 512
        },
        "ticksPerRow": {
          "type": "integer",
          "minimum": 1,
          "default": 240,
          "description": "Row size the pattern was written at; ticks scale when placed in a phrase with another row size."
        },
        "columns": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "default": 1,
          "description": "Note columns the pattern uses. Columns beyond the placing instrument's are dropped at render time."
        },
        "material": {
          "$ref": "#/$defs/lineMaterial"
        }
      },
      "description": "A reusable line for one voice, written once and placed many times."
    },
    "lineMaterial": {
      "type": "object",
      "properties": {
        "notes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/note"
          }
        },
        "dyn": {
          "$ref": "#/$defs/lane",
          "description": "Dynamics lane, 0-127, sent as the instrument's dynamics controller (CC1 by default)."
        },
        "expr": {
          "$ref": "#/$defs/lane",
          "description": "Expression lane, 0-127, sent as the instrument's expression controller (CC11 by default)."
        },
        "fx": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/fx"
          },
          "description": "FX column: at most one command per row."
        },
        "placements": {
          "type": "array",
          "maxItems": 0,
          "description": "Always empty: a pattern never places another pattern."
        }
      },
      "description": "Notes, lanes and fx of one voice. The shape a pattern holds."
    },
    "section": {
      "type": "object",
      "required": [
        "id",
        "name",
        "phrases"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$"
        },
        "name": {
          "type": "string"
        },
        "key": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/key"
            }
          ],
          "description": "The section's own key: overrides the song's for every phrase in it that has none. Where a modulation lives."
        },
        "phrases": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "phrase"
            ],
            "additionalProperties": false,
            "properties": {
              "phrase": {
                "type": "string",
                "description": "Id of a phrase in the song."
              },
              "repeat": {
                "type": "integer",
                "minimum": 1,
                "maximum": 64,
                "default": 1
              }
            }
          }
        }
      }
    },
    "arrangementItem": {
      "type": "object",
      "required": [
        "section"
      ],
      "additionalProperties": false,
      "properties": {
        "section": {
          "type": "string",
          "description": "Id of a section in the song."
        },
        "repeat": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 1
        }
      }
    }
  }
}
