{
  "name": "AI3D Music-Detection API",
  "version": "1.4",
  "description": "Real-time, in-browser audio-analysis + visual engine powering the AI3D visualizer.",
  "runtime": "client-side (Web Audio API + Three.js) — zero perceptible latency",
  "embed_namespace": "window.AI3D",
  "analysis": {
    "getBands":   {"returns":"{low,mid,high}","range":"0..1"},
    "getBeat":    {"returns":"number","range":"0..1","note":"decaying pulse, ~1 on a beat"},
    "getBPM":     {"returns":"number","note":"spectral-flux onset detection + interval median"},
    "getCentroid":{"returns":"number","range":"0..1","note":"spectral brightness"},
    "getEnergy":  {"returns":"number","range":"0..1"},
    "getMood":    {"returns":"string","note":"calm | deep | bright | balanced"},
    "getSpectrum":{"returns":"number[128]","range":"0..255"},
    "onBeat":     {"args":"callback({bpm,time})","returns":"unsubscribe()"},
    "isRunning":  {"returns":"boolean"}
  },
  "source_separation_ai": {
    "note": "Single-layer neural net over a 12-D spectral feature vector; self-trains online (homeostatic plasticity + adaptive per-channel calibration) and persists to localStorage.",
    "getInstruments": {"returns":"{bass,drums,guitar,rhythm,orchestral,experimental,voice}","range":"0..1"},
    "getVoice":       {"returns":"{level,pitch,present}","note":"voice channel detected across all frequencies; drives a separate 3D model"},
    "instruments":    {"returns":"string[]"},
    "getTraining":    {"returns":"{frames,seconds,channels}","note":"live training state"},
    "resetTraining":  {"note":"clears the learned model"}
  },
  "visual_control": {
    "setMode":    {"args":"key","options":["nebula","ring","terrain","bars","circle","waves","ripple","fire","explode","blobs","rain","snow","drops","merges"]},
    "setStretch": {"args":"boolean"},
    "setText":    {"args":"boolean","note":"floating 3D text words"},
    "modes":      {"returns":"string[]"},
    "setPalette": {"args":"key","options":["aurora","sunset","neon","fire","ice","auto"]},
    "palettes":   {"returns":"string[]"},
    "setTexture": {"args":"boolean","note":"glow sprite on/off"},
    "setFacts":   {"args":"boolean","note":"live web-facts overlay on/off"}
  },
  "inputs": ["microphone (requires HTTPS)","audio file upload (mp3/wav/ogg/m4a/flac)","drag-and-drop","?audio=URL auto-load"],
  "roadmap_visuals": ["drops","stretch","merges","fade","3D text"],
  "roadmap_server_side_ai": ["genre classification","mood detection","stem separation","auto-theming per track"]
}