Browser (Web Audio API)
    ↓ MediaRecorder taps the AudioContext output node
    ↓ Uploads WebM blob via HTTP POST
Express Middleware (your dev server)
    ↓ Stores captures in memory, dispatches commands via SSE
MCP Server (stdio — runs inside your IDE)
    ↓ Retrieves captures, sends to CodedSwitch analysis API
AI Coding Assistant
    → "Your bass band is 42% of the mix (high), spectral centroid
       is 580 Hz (muddy), and timing jitter is 23ms — the scheduler
       is drifting under load."

npm install webear

import express from 'express'
import { webearMiddleware } from 'webear/middleware'

const app = express()
app.use(express.json())

// Mount the audio debug bridge (automatically disabled in production)
app.use('/api/webear', webearMiddleware())

app.listen(5000)

import WebEar from 'webear/client'
WebEar.init()

const ctx = new AudioContext()
const masterGain = ctx.createGain()
masterGain.connect(ctx.destination)

WebEar.init({ audioContext: ctx, outputNode: masterGain })

import * as Tone from 'tone'
WebEar.init({ toneJs: true })

import * as THREE from 'three'
const listener = new THREE.AudioListener()
camera.add(listener)
WebEar.init({ tapNode: listener.getInput() })

WebEar.init()

{
  "mcpServers": {
    "webear": {
      "command": "npx",
      "args": ["webear"],
      "env": {
        "WEBEAR_BASE_URL": "http://localhost:5000",
        "CODEDSWITCH_API_KEY": "your-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "webear": {
      "command": "npx",
      "args": ["webear"],
      "env": {
        "WEBEAR_BASE_URL": "http://localhost:5000",
        "CODEDSWITCH_API_KEY": "your-key-here"
      }
    }
  }
}

{
  "webear": {
    "command": "npx",
    "args": ["webear"],
    "disabled": false,
    "env": {
      "WEBEAR_BASE_URL": "http://localhost:5000",
      "CODEDSWITCH_API_KEY": "your-key-here"
    }
  }
}

── Audio Analysis Report ──────────────────────────────
Duration:          3.02s

── Loudness ─────────────────────────────────────────
RMS:               -12.4 dBFS
Peak:              -1.2 dBFS
Dynamic range:     11.2 dB
Crest factor:      3.63
Clipping:          none

── Tone ──────────────────────────────────────────────
Spectral centroid: 2847 Hz
DC offset:         0.00012 (ok)

── Frequency Bands ───────────────────────────────────
Sub  (20-80 Hz):   8.2%
Bass (80-250 Hz):  22.1%
Mid  (250-2k Hz):  38.4%
Hi-mid (2-6k Hz):  21.8%
High (6k+ Hz):     9.5%

── Rhythm ────────────────────────────────────────────
Estimated BPM:     92
Onset count:       12
Timing jitter:     4.2 ms std dev

── Summary ───────────────────────────────────────────
Loudness: -12.4 dBFS RMS, peak -1.2 dBFS. Tone: balanced (centroid 2847 Hz).
Band mix — sub: 8% | bass: 22% | mid: 38% | hi-mid: 22% | high: 10%.
Rhythm: estimated 92 BPM, 12 onsets detected. Timing: very tight (= 18
- A browser that supports `MediaRecorder` (Chrome, Firefox, Edge, Safari 14+)
- A `CODEDSWITCH_API_KEY` for analysis (free at [codedswitch.com](https://www.codedswitch.com))

---

## Who Is This For?

- **Web Audio / Tone.js developers** — debug beats, synths, effects, and mixing without leaving your IDE
- **Game audio developers** — verify sound effects, spatial audio, and mixing in real-time
- **Music app builders** — catch regressions between code changes with `diff_audio`
- **Podcast / streaming apps** — validate audio quality, levels, and encoding
- **Anyone whose app makes sound** — if it has a Web Audio graph, your AI can now hear it

---

## Why Not Just Use the Microphone?

Microphone MCPs capture room sound — your fan noise, chair creaks, and room reverb are all in the recording. `webear` taps the Web Audio API **before it hits the DAC**, giving you a clean digital signal with no room artifacts.

---

## Web Perception — Full Sensor Suite

WebEar started as audio-only. **Web Perception** expands it to 6 senses:

| Sensor | What it perceives |
|---|---|
| **WebEar** | Audio — mix quality, rhythm, instruments, clipping |
| **WebEye** | Visual — canvas, UI layout, animations, screenshots |
| **WebSense** | Performance — frame rate, memory, audio latency |
| **WebNerve** | Network — API latencies, connection quality, storage |
| **WebShield** | Security — cookies, storage exposure, CSP, framing |
| **WebLog** | Console — logs, warnings, errors, uncaught exceptions |

### Install the full browser SDK

Or use a single sensor:

### Connect via MCP (hosted relay — no local server required)

### Available MCP Tools

| Sensor | Tool | Credits | Description |
|---|---|---|---|
| **Ear** | `capture_audio` | Free | Record live tab audio |
| **Ear** | `analyze_audio` | 1 | BPM, loudness, frequency bands, clipping, dynamic range |
| **Ear** | `describe_audio` | 2 | AI plain-English description — instruments, genre, mood, mix notes |
| **Ear** | `diff_audio` | 1 | Compare two captures — loudness, tone, timing deltas |
| **Ear** | `groove_score` | 2 | Grid alignment, swing factor, consistency (0–100%) |
| **Ear** | `capture_and_analyze` | 1 | Capture + analysis in one call |
| **Ear** | `mix_coach` | 3 | Structured mixing feedback |
| **Eye** | `capture_video` | Free | Record canvas/video from the tab |
| **Eye** | `describe_video` | 2 | AI visual description — layout, colors, bugs |
| **Eye** | `diff_visuals` | 2 | Compare two visual captures |
| **Sense** | `capture_telemetry` | Free | FPS, memory, layout shifts, audio latency |
| **Sense** | `analyze_telemetry` | 1 | Frame drops, memory pressure, audio underruns |
| **Nerve** | `capture_nerve` | Free | API timings, connection quality, storage size |
| **Nerve** | `analyze_nerve` | 1 | Slow APIs, connection quality, storage bloat |
| **Shield** | `capture_shield` | Free | Cookies, CSP, storage exposure, framing |
| **Shield** | `analyze_shield` | 1 | CORS issues, non-HttpOnly cookies, missing CSP |
| **Log** | `capture_logs` | Free | Console output + uncaught exceptions |
| **Log** | `analyze_logs` | 1 | Error patterns, stack traces, repeated warnings |

### Get an API Key

1. Create a free account at **[codedswitch.com](https://www.codedswitch.com)**.
2. Open **[codedswitch.com/developer](https://www.codedswitch.com/developer)** — also linked as **Developer API** in the account menu.
3. Click **Generate API Key** and copy it. Keys start with `wbr_`.

Free tier: 50 analyses/day, no credit card required.

---

## Changelog

### 2.0.1
- **Fixed the getting-started path for API keys.** The previous instruction
  ("Settings → WebEar") was wrong — there is no WebEar section under Settings.
  Keys live at **[codedswitch.com/developer](https://www.codedswitch.com/developer)**
  (linked as **Developer API** in the account menu). Both the Quick Start and the
  Web Perception sections now point to the correct place.
- The SDK's "missing API key" console error now links straight to the key page.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT — see [LICENSE](./LICENSE)

## Author

Built by [@asume21](https://github.com/asume21) — [CodedSwitch](https://www.codedswitch.com)