{
  "version": "1.0",
  "site": "https://metronome.franclambrecht.com",
  "description": "A browser-based metronome. All settings can be pre-configured via URL parameters — no interaction required to reach a specific state. Audio playback requires a direct user gesture (Space or Play button) due to Web Audio API autoplay policy.",
  "actions": [
    {
      "id": "configure-metronome",
      "name": "Configure Metronome",
      "description": "Open the metronome at a specific BPM, time signature, sound, groove pattern, and other settings by constructing a URL. The app initialises from query parameters — no clicks needed. Audio playback requires a final user gesture due to browser autoplay policy.",
      "method": "declarative",
      "agent_note": "Audio playback requires a direct user gesture due to Web Audio API autoplay policy. An agent can pre-configure all settings via URL — the user then presses Space or the Play button to start audio. Pass autoplay=1 to attempt immediate playback (may still be blocked by browser policy without a prior gesture).",
      "endpoint": "/",
      "parameters": {
        "required": [],
        "optional": [
          { "name": "bpm", "type": "integer", "minimum": 20, "maximum": 300, "default": 120, "description": "Tempo in beats per minute" },
          { "name": "meter", "type": "string", "enum": ["2/4","3/4","4/4","5/4","7/4","6/8","7/8","9/8","12/8"], "default": "4/4", "description": "Time signature" },
          { "name": "sub", "type": "integer", "enum": [1,2,3,4,5,6,7,8,9,10,11], "default": 1, "description": "Subdivision pattern: 1=quarter, 2=eighths, 3=eighth-note triplet, 4=sixteenths, 5=shuffle triplet, 6=dotted eighth + sixteenth, 7=sixteenth + dotted eighth (Scotch snap), 8=eighth + two sixteenths, 9=two sixteenths + eighth, 10=quintuplet, 11=septuplet" },
          { "name": "sound", "type": "string", "enum": ["studio","wood","sine","beep","hihat","rimshot","clave","marimba","bell","vibes","cat"], "default": "studio", "description": "Click sound. 'cat' activates cat-mode theme with meow sounds and animated visuals." },
          { "name": "swing", "type": "integer", "minimum": 0, "maximum": 50, "default": 0, "description": "Swing percentage (0 = straight, 50 = maximum shuffle)" },
          { "name": "groove", "type": "string", "enum": ["tresillo","habanera","cinquillo","charleston","clave32","clave23","rumba32","baiao","samba","kpanlogo","kuku","fanga","afrobeat","maqsum","baladi","reggae","ska","funk","secondline","fourfloor"], "description": "Groove pattern ID. Omit for no groove." },
          { "name": "view", "type": "string", "enum": ["simple","full","conductor"], "default": "full", "description": "UI view. 'conductor' shows full-screen large BPM for music stands and band rooms." },
          { "name": "vol", "type": "integer", "minimum": 0, "maximum": 100, "default": 80, "description": "Beat volume percentage" },
          { "name": "subvol", "type": "integer", "minimum": 0, "maximum": 100, "default": 70, "description": "Subdivision volume percentage" },
          { "name": "accent", "type": "boolean", "default": true, "description": "Accent beat 1 of each bar with a louder click" },
          { "name": "audiblesubs", "type": "boolean", "default": true, "description": "Play audible subdivision clicks between main beats" },
          { "name": "countin", "type": "boolean", "default": false, "description": "Enable count-in bars of silent beats before playback starts" },
          { "name": "countinbars", "type": "integer", "enum": [1,2], "default": 1, "description": "Number of count-in bars (1 or 2)" },
          { "name": "autoplay", "type": "boolean", "default": false, "description": "Attempt to start playback on load (subject to browser autoplay policy — a prior user gesture may be required)" },
          { "name": "settings", "type": "boolean", "default": false, "description": "Open the Settings panel on load" },
          { "name": "trainmode", "type": "boolean", "default": false, "description": "Enable Tempo Ramp mode (auto-increments BPM on a schedule)" },
          { "name": "trainstart", "type": "integer", "minimum": 20, "maximum": 300, "default": 60, "description": "Ramp start BPM" },
          { "name": "trainstep", "type": "integer", "minimum": -280, "maximum": 280, "default": 5, "description": "BPM change per ramp interval (positive = accelerate, negative = decelerate)" },
          { "name": "trainevery", "type": "integer", "minimum": 1, "maximum": 999, "default": 8, "description": "Number of bars between BPM steps" },
          { "name": "trainstopena", "type": "boolean", "default": false, "description": "Enable ramp stop BPM cap" },
          { "name": "trainstop", "type": "integer", "minimum": 20, "maximum": 300, "default": 160, "description": "BPM at which the ramp stops (requires trainstopena=1)" },
          { "name": "trainmidena", "type": "boolean", "default": false, "description": "Enable two-stage ramp with a different step size after a switch BPM" },
          { "name": "trainmidtarget", "type": "integer", "minimum": 20, "maximum": 300, "default": 120, "description": "BPM at which Stage 2 begins (requires trainmidena=1)" },
          { "name": "trainstep2", "type": "integer", "minimum": -280, "maximum": 280, "default": 2, "description": "BPM change per interval in Stage 2" },
          { "name": "trainevery2", "type": "integer", "minimum": 1, "maximum": 999, "default": 16, "description": "Bars between BPM steps in Stage 2" }
        ]
      },
      "example_urls": [
        "https://metronome.franclambrecht.com/?bpm=120&meter=4/4",
        "https://metronome.franclambrecht.com/?bpm=80&meter=3/4&sound=wood",
        "https://metronome.franclambrecht.com/?bpm=100&groove=clave32&swing=30",
        "https://metronome.franclambrecht.com/?bpm=90&meter=6/8&sub=3&sound=marimba&swing=25",
        "https://metronome.franclambrecht.com/?trainmode=1&trainstart=60&trainstep=5&trainevery=8&trainstop=120&trainstopena=1",
        "https://metronome.franclambrecht.com/?bpm=120&view=conductor"
      ]
    }
  ]
}