webear

webear

让你的 AI 拥有真正的感官——聆听、观察并感受任意 Web 应用。

一个 MCP 服务 + 浏览器 SDK，让 AI 编码助手能够直接感知正在运行的 Web 应用。音频、视觉、性能、网络、安全和控制台信息——从浏览器中采集、实时分析，并通过 MCP 传递。

“节拍听起来很浑浊” → 你的 AI 会采集 3 秒音频，测得频谱质心为 580 Hz、250 Hz 以下的能量占 45%，并准确告诉你原因。

---

---

功能介绍

工具	描述
capture_audio	录制一段短音频（500ms–30s），捕获 Web 应用此刻输出的声音
analyze_audio	信号分析：RMS、峰值 dB、削波、频谱质心、频段、BPM、时间抖动
describe_audio	用通俗易懂的语言描述音频——“底鼓低沉轰鸣，约 80 Hz 处的超低频堆积严重”
diff_audio	比较两次采集并标出变化——响度、音色、节奏、削波

工作原理

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."

与其他所有音频 MCP 的关键区别是：它直接从 Web Audio 图中采集信号，绕过室内声学环境和麦克风硬件，也无需导出文件。

---

快速开始

1. 安装

npm install webear

2. 将 Express 中间件添加到开发服务器

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)

3. 将客户端代码片段添加到 Web 应用

选项 A — 自动检测所有内容（Tone.js 或原生 Web Audio）

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

选项 B — 显式指定 AudioContext

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

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

选项 C — Tone.js 项目

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

选项 D — Three.js WebGL 游戏

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

选项 E — 普通脚本标签

<script src="node_modules/webear/client-snippet.js"></script>
<script>WebEar.init()</script>

4. 配置 IDE

Claude Code（项目根目录中的 .mcp.json）：

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

Cursor（.cursor/mcp.json）：

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

Windsurf（mcp_config.json）：

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

5. 获取 API 密钥——可选，开始使用时无需密钥

analyze_audio 无需密钥或账号即可使用。如果 ffmpeg 在你的 PATH 中， 它会在你的设备上解码并分析采集到的音频，并返回基础报告： 时长、响度、峰值电平，以及音频是否发生削波。不会上传任何内容。 先试用工具，再决定是否注册。

API 密钥可解锁需要更复杂分析的功能：

	无密钥	使用密钥
capture_audio	✓	✓
analyze_audio	基础 — 时长、响度、峰值、削波（本地）	完整 — 频谱质心、频段能量、波峰因数、BPM、时间抖动
describe_audio — 听起来是什么样	—	✓
mix_coach — 测量 + 听感分析	—	✓
diff_audio — 前后对比	—	✓

获取密钥：

1. 在 codedswitch.com 创建免费账号。
2. 前往 codedswitch.com/developer（也可在账号菜单中选择 Developer API）。
3. 点击 Generate API Key——该值就是你的 CODEDSWITCH_API_KEY。密钥以 wbr_ 开头。

免费额度：每天 50 次分析。无需信用卡。

6. 启动开发服务器，打开应用并播放音频，然后向 AI 提问：

“采集 3 秒音频，告诉我为什么低音听起来很浑浊。”

“比较我上次提交前后的音频。”

“高频范围有没有削波？”

---

输出示例

analyze_audio

── 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 (< 5 ms jitter).

diff_audio

── Audio Diff: a1b2c3d4… → e5f6g7h8… ──

── Loudness ──────────────────────────────────────────
  RMS: -14.2 dBFS → -12.4 dBFS  (+1.8 dBFS)
⚠ Peak: -3.1 dBFS → -0.2 dBFS  (+2.9 dBFS)
⚠ CLIPPING INTRODUCED — gain staging regression

── Tone ──────────────────────────────────────────────
⚠ Spectral centroid: 2847.0 Hz → 1920.0 Hz  (-927.0 Hz)

── Interpretation ────────────────────────────────────
A gain bug was introduced that causes clipping.
Tonal character changed noticeably — EQ or filter behaviour may have shifted.

---

配置

环境变量

变量	默认值	描述
WEBEAR_BASE_URL	http://localhost:4000	开发服务器的 URL（中间件挂载的位置）
CODEDSWITCH_API_KEY	—	来自 codedswitch.com 的 API 密钥 — analyze_audio 和 describe_audio 必需
MCP_API_URL	https://www.codedswitch.com	覆盖分析 API 基础地址（高级 / 可自托管）

中间件选项

webearMiddleware({
  maxCaptures: 50,       // Max captures in memory (default: 50)
  maxAgeMins: 10,        // Auto-evict after N minutes (default: 10)
  maxUploadBytes: 50e6,  // Max upload size (default: 50MB)
  devOnly: true,         // Disable in production (default: true)
})

客户端选项

WebEar.init({
  audioContext: myCtx,             // Your AudioContext instance
  outputNode: myGainNode,          // The node to tap (defaults to destination)
  toneJs: true,                    // Auto-detect Tone.js context
  bridgeBase: '/api/webear',  // Override API path
  devOnly: true,                   // Only init outside of production (default: true)
})

---

要求

• Node.js >= 18
• 支持 MediaRecorder 的浏览器（Chrome、Firefox、Edge、Safari 14+）
• 用于分析的 CODEDSWITCH_API_KEY（可在 codedswitch.com 免费获取）

---

适用人群

• Web Audio / Tone.js 开发者 — 无需离开 IDE，即可调试节拍、合成器、效果和混音
• 游戏音频开发者 — 实时验证音效、空间音频和混音
• 音乐应用开发者 — 使用 diff_audio 检测代码变更导致的回归
• 播客 / 流媒体应用开发者 — 验证音频质量、音量和编码
• 任何开发会发出声音的应用的人 — 只要应用有 Web Audio 图表，你的 AI 现在就能听见它

---

为什么不直接使用麦克风？

麦克风 MCP 会捕捉房间里的声音 — 风扇噪声、椅子吱响和房间混响都会录进去。webear 会在音频到达 DAC 之前接入 Web Audio API，提供干净的数字信号，不受房间环境影响。

---

Web Perception — 完整传感器套件

WebEar 最初仅支持音频。Web Perception 将其扩展为 6 种感知能力：

传感器	感知内容
WebEar	音频 — 混音质量、节奏、乐器、削波
WebEye	视觉 — 画布、UI 布局、动画、截图
WebSense	性能 — 帧率、内存、音频延迟
WebNerve	网络 — API 延迟、连接质量、存储
WebShield	安全 — Cookie、存储暴露、CSP、框架嵌入
WebLog	控制台 — 日志、警告、错误、未捕获的异常

安装完整的浏览器 SDK

import { WebPerception } from 'webear/perception'

WebPerception.init({
  apiKey: 'wbr_YOUR_API_KEY',
  relayUrl: 'https://www.codedswitch.com',
  sensors: ['ear', 'eye', 'sense', 'nerve', 'shield', 'log'],
})

也可以只使用单个传感器：

import { WebEar } from 'webear/perception'

WebEar.init({
  apiKey: 'wbr_YOUR_API_KEY',
  ear: { audioContext: myCtx, audioNode: masterGain },
})

通过 MCP 连接（托管中继 — 无需本地服务器）

{
  "mcpServers": {
    "webear": {
      "url": "https://www.codedswitch.com/api/webear/mcp/sse",
      "headers": {
        "Authorization": "Bearer wbr_YOUR_API_KEY"
      }
    }
  }
}

可用的 MCP 工具

传感器	工具	点数	描述
Ear	capture_audio	免费	录制当前标签页的实时音频
Ear	analyze_audio	1	BPM、响度、频段、削波、动态范围
Ear	describe_audio	2	AI 生成的通俗描述 — 乐器、流派、情绪、混音备注
Ear	diff_audio	1	对比两次捕获结果 — 响度、音色、时序差异
Ear	groove_score	2	网格对齐度、摇摆系数、一致性（0–100%）
Ear	capture_and_analyze	1	一次调用完成捕获和分析
Ear	mix_coach	3	结构化混音反馈
Eye	capture_video	免费	录制当前标签页中的画布 / 视频
Eye	describe_video	2	AI 生成的视觉描述 — 布局、颜色、错误
Eye	diff_visuals	2	对比两次视觉捕获结果
Sense	capture_telemetry	免费	FPS、内存、布局偏移、音频延迟
Sense	analyze_telemetry	1	帧丢失、内存压力、音频欠载
Nerve	capture_nerve	免费	API 耗时、连接质量、存储大小
Nerve	analyze_nerve	1	慢速 API、连接质量、存储膨胀
Shield	capture_shield	免费	Cookie、CSP、存储暴露、框架嵌入
Shield	analyze_shield	1	CORS 问题、非 HttpOnly Cookie、缺少 CSP
Log	capture_logs	免费	控制台输出 + 未捕获的异常
Log	analyze_logs	1	错误模式、堆栈跟踪、重复警告

获取 API 密钥

1. 在 codedswitch.com 创建免费账户。
2. 打开 codedswitch.com/developer——账户菜单中也有 Developer API 链接。
3. 点击 Generate API Key 并复制密钥。密钥以 wbr_ 开头。

免费版：每天可进行 50 次分析，无需信用卡。

---

更新日志

2.0.1

• 修正了 API 密钥的入门指引。 之前的说明 （“Settings → WebEar”）有误——Settings 下没有 WebEar 部分。 密钥位于 codedswitch.com/developer （账户菜单中有 Developer API 链接）。快速入门和 Web 感知部分现已指向正确位置。
• SDK 的“缺少 API 密钥”控制台错误现在会直接链接到密钥页面。

参与贡献

请参阅 CONTRIBUTING.md。

许可证

MIT——请参阅 LICENSE

作者

由 @asume21 构建——CodedSwitch