webear

webear

AI に本物の感覚を与えましょう。あらゆるウェブアプリを聞き、見て、感じられます。

MCP サーバーとブラウザー SDK を組み合わせ、AI コーディングアシスタントが稼働中のウェブアプリに直接、感覚的にアクセスできるようにします。音声、ビジュアル、パフォーマンス、ネットワーク、セキュリティ、コンソールの情報をブラウザーから取得し、リアルタイムで分析して MCP 経由で提供します。

「ビートが濁って聞こえます」 → AI が 3 秒間の音声をキャプチャし、スペクトル重心が 580 Hz、250 Hz 未満のエネルギーが 45％であることを測定して、その理由を具体的に説明します。

---

---

できること

ツール	説明
capture_audio	ウェブアプリが現在出力している音声を 500 ms～30 秒間録音します
analyze_audio	信号を分析します。RMS、ピーク dB、クリッピング、スペクトル重心、周波数帯、BPM、タイミングジッター
describe_audio	平易な言葉で AI が説明します — 「キック音は、80 Hz 付近でサブベースが大きく膨らみ、低音がこもっています」
diff_audio	2 つのキャプチャを比較し、音量、音色、タイミング、クリッピングの変化を検出します

仕組み

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. ウェブアプリにクライアントのスニペットを追加する

オプション 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 タグ

<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 にある場合、キャプチャをお使いのマシン上でデコードして分析し、基本的なレポートを返します。レポートには、長さ、音量、ピークレベル、クリッピングの有無が含まれます。アップロードは一切行われません。何かに登録する前に、ツールをお試しください。

キーを取得すると、計算だけではできない機能を利用できます。

	キーなし	キーあり
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_ で始まります。

無料枠では 1 日 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 のベース URL を上書きします（上級者向け／セルフホスト）

ミドルウェアのオプション

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 は Web Audio API の信号を DAC に届く前に取り込むため、室内の影響を受けないクリーンなデジタル信号を取得できます。

---

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	2 つのキャプチャを比較 — ラウドネス、音色、タイミングの差分
Ear	groove_score	2	グリッドとの整合性、スウィング係数、一貫性（0～100%）
Ear	capture_and_analyze	1	1 回の呼び出しでキャプチャと分析を実行
Ear	mix_coach	3	構造化されたミキシングのフィードバック
Eye	capture_video	無料	タブのキャンバス／動画を録画
Eye	describe_video	2	AI によるビジュアルの説明 — レイアウト、色、バグ
Eye	diff_visuals	2	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_ で始まります。

無料プランでは、クレジットカードの登録なしで1日50回分析できます。

---

変更履歴

2.0.1

• API キーの取得手順を修正しました。 以前の手順（「Settings → WebEar」）は誤りでした。Settings に WebEar セクションはありません。 キーは codedswitch.com/developer にあります（アカウントメニューの Developer API からアクセスできます）。クイックスタートと Web Perception の両セクションで、正しい場所を案内するようになりました。
• SDK で「API キーがありません」というコンソールエラーが発生した場合に、キーのページへ直接リンクするようになりました。

コントリビューション

CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

作者

@asume21 が開発しました — CodedSwitch