motionvector.dev

{
  "type": "object",
  "additionalProperties": false,
  "description": "A proposed exercise, escrowed for human review. Never auto-applied: the human sees title, reason, tempo, and the full note pattern, then presses Apply exercise (or Keep mine) before anything changes on screen.",
  "required": [
    "baseRevision",
    "title",
    "reason",
    "instrument",
    "beats",
    "bpm",
    "events"
  ],
  "properties": {
    "baseRevision": {
      "type": "integer",
      "minimum": 0,
      "description": "The `revision` value from the most recent music_get_state call. Detects state drift between reading state and proposing; call music_get_state first if unsure. Required."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Short human-facing title for the proposed exercise, 1-80 characters. Required."
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "One or two sentences explaining why this exercise is proposed; shown to the human before they can apply it. 1-300 characters. Required."
    },
    "instrument": {
      "enum": [
        "drums",
        "keys",
        "guitar"
      ],
      "description": "Instrument the proposal is for: drums, keys, or guitar. Must match the instrument of the lesson currently open (from music_get_state). Required."
    },
    "beats": {
      "enum": [
        4,
        8,
        16
      ],
      "description": "Length of the exercise loop in quarter-note beats: 4, 8, or 16. Required."
    },
    "bpm": {
      "type": "integer",
      "minimum": 40,
      "maximum": 120,
      "description": "Tempo in beats per minute, 40-120. Required."
    },
    "guitar": {
      "type": "object",
      "additionalProperties": false,
      "description": "Guitar configuration snapshot. Required when instrument is \"guitar\"; must be omitted for drums or keys proposals.",
      "properties": {
        "tuning": {
          "type": "array",
          "minItems": 6,
          "maxItems": 6,
          "items": {
            "type": "integer"
          },
          "description": "Standard guitar tuning as six MIDI note numbers, low string first. Must exactly equal [40,45,50,55,59,64] — alternate tunings are not supported. Required inside guitar."
        },
        "capo": {
          "type": "integer",
          "minimum": 0,
          "maximum": 5,
          "description": "Capo position in frets, 0-5. 0 means no capo. Required inside guitar."
        },
        "preset": {
          "enum": [
            "acoustic",
            "clean",
            "overdrive"
          ],
          "description": "Guitar tone preset: acoustic, clean, or overdrive. Required inside guitar."
        },
        "frets": {
          "type": "array",
          "minItems": 6,
          "maxItems": 6,
          "items": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 12
          },
          "description": "Six entries, one per string low to high: the fretted position 0-12, or null if that string does not sound. At least one entry must be non-null. Required inside guitar."
        },
        "shapes": {
          "type": "array",
          "minItems": 1,
          "maxItems": 10,
          "items": {
            "type": "string"
          },
          "uniqueItems": true,
          "description": "Names of reviewed chord shapes available for this proposal, 1-10 unique entries drawn from the app's reviewed shape library. Optional — defaults to every reviewed shape when omitted."
        }
      }
    },
    "events": {
      "type": "array",
      "minItems": 1,
      "maxItems": 64,
      "description": "Ordered list of 1-64 note events making up the exercise loop, strictly increasing by beat. Required.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "beat",
          "notes"
        ],
        "properties": {
          "beat": {
            "type": "number",
            "minimum": 0,
            "description": "Zero-based quarter-note position within the loop, from 0 up to (but excluding) beats. Must be strictly greater than the previous event's beat. Required."
          },
          "notes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6,
            "items": {
              "type": "integer"
            },
            "uniqueItems": true,
            "description": "1-6 unique catalogue indices sounded together at this beat. Range depends on instrument: 0-11 for drums, 0-24 for keys, 0-77 for guitar (stringIndex × 13 + fret; a capo shifts pitch, never the index). Required."
          },
          "duration": {
            "type": "number",
            "minimum": 0.05,
            "maximum": 4,
            "description": "Note length in beats, 0.05-4. Optional — defaults to 0.65 when omitted."
          },
          "velocity": {
            "type": "number",
            "minimum": 0.1,
            "maximum": 1,
            "description": "Note loudness from 0.1 (quiet) to 1 (loud). Optional — defaults to 0.75 when omitted."
          },
          "kind": {
            "enum": [
              "pluck",
              "strum"
            ],
            "description": "Guitar only: pluck sounds exactly one note, strum sounds a chord across up to 6 notes with one fret per string. Required for guitar events; must be omitted for drums or keys."
          },
          "direction": {
            "enum": [
              "down",
              "up"
            ],
            "description": "Guitar strum only: down or up, the order strings ring out. Required when kind is strum; must be omitted for a pluck or for drums/keys."
          },
          "spread": {
            "type": "number",
            "minimum": 0,
            "maximum": 0.12,
            "description": "Guitar strum only: seconds between adjacent strings ringing out, 0-0.12. Required when kind is strum; must be omitted for a pluck or for drums/keys."
          }
        }
      }
    }
  }
}