SNR results from captures run via the sidebar. Configure signal, ref mic, and speaker in the Capture panel.

Work through each qualification step. Use the links to navigate to the relevant test, capture, then come back and link the result.

Distance rolloff test — measures mic response at multiple distances using an iPhone as the sweep source.

Export, import, and manage your capture database. All captures are stored in your browser's IndexedDB.

# Microphone Analysis Tool — Device API Specification

Implement these HTTP endpoints on any WiFi-capable microcontroller (ESP32, etc.)
to make it compatible with the Microphone Analysis Tool web UI.

All endpoints must include CORS headers:
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, OPTIONS
  Access-Control-Allow-Headers: Content-Type
All POST endpoints need a matching OPTIONS handler returning 204.

---

## REQUIRED: GET /api/discover

Device identification and capabilities. Called once on connect.

Response (application/json):
```json
{
  "type": "my-device-type",
  "mac": "AA:BB:CC:DD:EE:FF",
  "hostname": "my-device-eeff",
  "fw": "1.0.0",
  "board": "esp32s3-custom",
  "sta_ip": "192.168.0.100",
  "running": false,
  "mics": [
    {"id": "main", "label": "Built-in MEMS Mic", "channel": 0}
  ],
  "capabilities": {
    "sample_rates": [16000, 48000],
    "gains": [0, 6, 12, 18, 24, 30, 36, 40],
    "hp_cutoffs": [80, 100, 120, 150, 200],
    "dc_remove": true,
    "hp_filter": true,
    "subsystems": [
      {"id": "wifi", "label": "WiFi", "toggle": true, "default": true},
      {"id": "amp", "label": "Amplifier", "toggle": true, "default": false}
    ]
  }
}
```

Fields:
- type: string identifier for your device
- mac: device MAC address
- hostname: mDNS hostname (without .local)
- fw: firmware version string
- board: hardware revision
- sta_ip: WiFi station IP (empty string if AP-only)
- running: true if a capture is in progress
- mics: array of available microphones
  - id: string passed as ?mic= parameter to /api/mic_test
  - label: human-readable name shown in the UI
  - channel: numeric channel index
- capabilities: (optional) what settings the device supports
  - sample_rates: array of supported sample rates in Hz
  - gains: array of supported gain values in dB (UI shows these as processing options)
  - hp_cutoffs: array of HP filter cutoff frequencies in Hz
  - dc_remove: boolean — show DC removal option in UI
  - hp_filter: boolean — show HP filter option in UI (also implied by hp_cutoffs)
  - dsr: array of {value, label} for PDM downsample ratio (PDM mics only)
  - mclk: array of MCLK multiples (PDM mics only)
  - subsystems: array of toggleable hardware subsystems
    - id: used in /api/toggle/{id} endpoint
    - label: shown in UI
    - toggle: true if the UI can toggle it, false for observe-only
    - default: initial checkbox state (true = on at boot)

If capabilities is omitted, the UI shows default controls.
Only include fields your device actually supports.

---

## REQUIRED: GET /api/mic_test

Capture audio from the microphone and return a WAV file.

Query parameters:
- mic: (string) mic id from the mics array in /api/discover
- duration: (int) capture duration in seconds, 1-30, default 10

Response: audio/wav
- Standard 44-byte RIFF WAV header
- Mono (1 channel)
- 16-bit signed PCM, little-endian
- Sample rate matching the device's current setting

IMPORTANT: Return RAW audio. Do NOT apply gain, DC removal, or filtering.
All signal processing is done client-side in the web UI. This enables
non-destructive analysis where users can change processing after capture.

Implementation pattern:
1. Parse ?mic= and ?duration= from query string
2. Initialize audio peripheral (I2S, PDM, etc.)
3. Discard 500ms-1000ms of samples (filter settling)
4. Capture (sample_rate * duration) samples into a buffer
5. Deinitialize audio peripheral
6. Send WAV header (44 bytes) with correct sample rate and data size
7. Send raw PCM data in chunks

For devices without PSRAM, use streaming: capture a chunk, send it,
capture the next chunk. Only needs ~4KB buffer regardless of duration.

---

## OPTIONAL: GET /api/state

Device status, polled periodically.

Response (application/json):
```json
{
  "mac": "AA:BB:CC:DD:EE:FF",
  "running": false,
  "current_test": -1,
  "current_run": -1,
  "overall": "PENDING",
  "results": [],
  "metrics": [],
  "log": "",
  "syslog": ""
}
```

The key field is "running" — the UI disables capture while true.
All other fields can be empty/default if not implementing test suites.

---

## OPTIONAL: GET/POST /api/pdm_tuning

Read and write device settings.

GET response (application/json):
```json
{"sample_rate": 16000, "mic_sel": 0}
```

POST: settings via query parameters. Only include what your device supports.
- rate: sample rate in Hz
- mic: mic channel index (0, 1, ...)
- dsr: downsample ratio (0 or 1)
- mclk: MCLK multiple (128, 256, 384, 512)

Example: POST /api/pdm_tuning?rate=48000&mic=0

---

## OPTIONAL: POST /api/toggle/{id}?on=0|1

Toggle a hardware subsystem. The {id} matches subsystem id from capabilities.

Response (application/json):
```json
{"wifi": "off"}
```

---

## MINIMAL IMPLEMENTATION CHECKLIST

For a basic compatible device, implement:
1. GET /api/discover — return type, mics array, optional capabilities
2. GET /api/mic_test?mic={id}&duration={sec} — capture raw audio, return WAV
3. CORS headers on all responses
4. OPTIONS handlers for POST endpoints

The web UI reads the sample rate from the WAV header automatically.
No capabilities = default UI controls shown.
No /api/state = UI works but won't show device status.
No /api/pdm_tuning = settings can't be pushed to device.
No /api/toggle = subsystem toggles won't work.