io.github.Gomess8/voice-quality-api
Measure voice/VoIP path quality -> estimated MOS + live network metrics
Open source Repository Open in the app JSON README (API)
About
Measure voice/VoIP path quality -> estimated MOS + live network metrics
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- gomess8
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.0
- Last push
- 2026-07-02T02:27:31Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-29 03:01:56
- Updated
- 2026-08-29 03:01:56
- Origin id
io.github.Gomess8/voice-quality-api
README
# Voice Quality API
**Measure the network path quality to a voice/VoIP destination and get an
estimated MOS (1–5) — live, from an API.** Built for AI voice agents. Available
as REST and as an **MCP tool**, paid per call via
**[x402](https://github.com/coinbase/x402)** (USDC on Base).
🌐 **Live:** [voice-quality.com](https://voice-quality.com) · REST
`api.voice-quality.com` · MCP `mcp.voice-quality.com`
---
## Try it
```bash
curl https://api.voice-quality.com/health # {"status":"ok"}
curl -s https://api.voice-quality.com/v1/voice-quality \
-H 'content-type: application/json' \
-d '{ "target": "your-voice-endpoint.example", "target_port": 10000, "codec": "G711" }'
```
You get an **estimated MOS** + live **RTT / jitter / packet loss**. Point it at an
endpoint that answers media — your own voice infra, or a tiny reflector you run
([`probe-agent/cmd/reflector`](./probe-agent/cmd/reflector)). **20 free/day**;
beyond that it's pay-per-call via x402 (no account needed).
```jsonc
{
"request_id": "vq_2ibc6qqq",
"target": "your-voice-endpoint.example",
"codec": "G711",
"measured_at": "2026-07-01T10:15:13.795Z",
"summary": { "mos_estimate": 4.38, "mos_class": "excellent", "r_factor": 91.8 },
"by_probe": [ /* per-probe metrics + R-factor + MOS */ ],
"methodology": {
"model": "ITU-T G.107 E-model",
"confidence": "estimate",
"assumptions": ["owd = rtt/2 (symmetric path)", "adaptive jitter buffer = 2x jitter"]
},
"credits_used": 0
}
```
## Why it exists
Free network-measurement platforms (Globalping, RIPE Atlas) measure
ping/traceroute/DNS/HTTP — they do **not** measure RTP media quality or estimate
MOS. The tools that do (Cyara, Spearline) are enterprise sales motions. This
fills the gap: **voice path quality as a clean, self-serve, agent-native API** —
check it before you route a call, or monitor the path to your voice endpoints.
## Trustworthy by design
- **Honest metric.** An *objective* G.107 E-model estimate from measured network
metrics — never sold as a perceptual (PESQ/POLQA) score. Every response carries
`methodology.confidence: "estimate"` and its assumptions.
- **Verified constants.** The codec `Ie`/`Bpl` values are verified against
**ITU-T G.113 (09/2024), App. I, Table I.4** — rows matched to the probe profile
(no PLC, no VAD/DTX). Not "representative"; cited.
- **SSRF-guarded.** ~36.7% of public MCP servers ship SSRF issues — this one
blocks internal/private targets by default (orchestrator **and** probe), plus a
per-target allowlist and rate limit.
- **Hardened.** TLS/mTLS on the probe channel, non-root containers,
`pnpm audit` clean, structured machine-readable errors, `Idempotency-Key`,
Prometheus `/metrics`, per-identity API keys.
## Pricing
| Tier | What you get |
|------|--------------|
| **Free** | 20 measurements/day per identity (`credits_used: 0`). |
| **Pay-per-call** | Beyond that, a sub-cent–cents micropayment per call via **x402** (USDC on Base). Unpaid → `402` with the payment requirements; pay and retry. Agents pay transparently. |
## Agent-native (MCP + x402)
One MCP tool, `measure_voice_quality`. The server wraps the REST API and pays
x402 transparently from a configured wallet once the free tier is exhausted — no
human in the loop.
```jsonc
{
"mcpServers": {
"voice-quality": {
"url": "https://mcp.voice-quality.com/",
"env": { "MCP_CLIENT_PRIVATE_KEY": "0x…" } // optional; only for paid calls
}
}
}
```
## Architecture
```
[AI agent / dev] ──(HTTP + x402 / MCP)──► [Orchestrator] ──► [E-model (G.107): R → MOS]
└──► [regional probe] ──(emulated UDP/RTP)──► target
```
| Component | Stack | Role |
|-----------|-------|------|
| **Orchestrator** ([`packages/orchestrator`](./packages/orchestrator)) | TypeScript + Hono | REST API, E-model, x402 paywall, AUP, rate limit, probe dispatch |
| **MCP server** ([`packages/mcp-server`](./packages/mcp-server)) | TypeScript + MCP SDK | `measure_voice_quality`; wraps REST + transparent x402 |
| **Probe agent** ([`probe-agent`](./probe-agent)) | Go | UDP/RTP emulation + RFC 3550 metrics; cheap regional VPS |
| **Shared** ([`packages/shared`](./packages/shared)) | TypeScript | Zod schemas, types, G.113 codec constants |
## Self-host
```bash
cp .env.example .env # fill in values
docker compose up --build -d # orchestrator + MCP + probe + reflector + landing
curl localhost:8080/health
```
Full deploy (public HTTPS via Caddy or Cloudflare Tunnel, regional probes with
mTLS): [`docs/deploy.md`](./docs/deploy.md). Going to production (mainnet x402,
codec verification, registries): [`docs/go-live.md`](./docs/go-live.md).
## Docs
[Methodology](./docs/methodology.md) · [OpenAPI](./docs/openapi.yaml) ·
[Deploy](./docs/deploy.md) · [Go-live](./docs/go-live.md) ·
[Discovery & registries](./docs/registration.md)
---
*The MOS is an objective estimate from network conditions, not a guarantee of
call quality. Maintained actively.*