---
title: "QoS & Voice Quality Monitoring"
description: "Documentation for QoS & Voice Quality"
---

## Table of Contents
1. [Overview & Voice Quality Architecture](#1-overview--voice-quality-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Dashboard Layout](#4-visual-interface--dashboard-layout)
5. [Field & Metrics Reference](#5-field--metrics-reference)
6. [RTPEngine Telemetry Engine & MOS Calculation](#6-rtpengine-telemetry-engine--mos-calculation)
7. [Voice QoS Alert Thresholds & SLA Governance](#7-voice-qos-alert-thresholds--sla-governance)
8. [Troubleshooting & Diagnostic Commands](#8-troubleshooting--diagnostic-commands)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Voice Quality Architecture

In **Ring2All SBC**, the **QoS & Voice Quality** module delivers real-time acoustic telemetry, Mean Opinion Score (MOS) calculation, and network impairment tracking for every active audio stream transiting the carrier perimeter. Operating in deep coordination with the **RTPEngine Media Relay** subsystem, the SBC samples RTP packet arrival deltas, sequence integrity, and RTCP Extended Reports (RTCP-XR) to derive continuous quality ratings without inserting intrusive test probes.

```
Caller Endpoint (WebRTC / SIP)             Ring2All SBC (RTPEngine Media Relay)           Callee Endpoint (Carrier / PBX)
        │                                              │                                               │
        │════════════ Active RTP Audio Stream ════════>│════════════ Relayed RTP Stream ══════════════>│
        │<─────────── RTCP Receiver Reports ──────────│<─────────── RTCP Receiver Reports ─────────────│
        │                                              │
        │                                    ┌─────────┴─────────┐
        │                                    │  Telemetry Engine │
        │                                    │  • Jitter Delta   │
        │                                    │  • Packet Loss %  │
        │                                    │  • RTT Roundtrip  │
        │                                    │  • Codec Profile  │
        │                                    └─────────┬─────────┘
        │                                              │
        │                                              ▼
        │                                  ┌────────────────────────┐
        │                                  │   ITU-T G.107 E-Model  │
        │                                  │   R-Factor Calculation │
        │                                  │   MOS Score (1.0 - 5.0)│
        │                                  └───────────┬────────────┘
        │                                              │
        ▼                                              ▼
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                          Ring2All SBC Management Console (/reports/qos)                               │
│      • Real-Time MOS Distribution    • Codec Utilization    • SLA Threshold Alarm Enforcement         │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

By decoupling signaling analysis from media inspection, Ring2All SBC ensures that:
1. **Zero-Overhead Sampling**: RTP packets pass through kernel-space forwarding tables with sub-millisecond latency.
2. **Continuous Scoring**: Quality scores update dynamically across the entire duration of each telephone call.
3. **Multi-Codec Normalization**: Wideband codecs (Opus, G.722) and standard narrowband codecs (G.711u/a, G.729) are accurately evaluated against their respective theoretical maximum R-factors.

---

## 2. Business & Operational Significance

* **Proactive SLA Violation Detection**: Identifies carrier link degradation, route flapping, or ISP peering congestion before subscribers file quality tickets.
* **Carrier Interconnect Quality Auditing**: Compares voice performance across multiple upstream termination carriers to automatically penalize or deselect degrading routes in Quality-Based Routing profiles.
* **HD Voice Adoption Visibility**: Tracks wideband codec adoption (Opus HD / G.722) versus legacy narrowband codecs to evaluate network modernization initiatives.
* **Dispute Defense & Root Cause Analysis**: Provides incontrovertible packet-level telemetry (jitter variance, burst loss, and round-trip delay) to pinpoint whether audio distortion originated in the local enterprise LAN or the remote carrier network.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **Voice Network Engineer** | Acoustic Optimization & Codec Tuning | Monitor real-time MOS score distributions, inspect jitter buffers, and adjust RTPEngine transcoder settings. |
| **Carrier NOC Specialist** | Upstream Route Quality Verification | Correlate trunk-level packet loss with upstream carrier peering, triggering automated failover when thresholds breach. |
| **SBC Administrator** | SLA Governance & Alert Thresholding | Define global alert policies for minimum MOS, maximum jitter, and packet loss; configure notification webhooks. |
| **Enterprise Telecom Manager** | Customer Experience Auditing | Review historical voice quality trends, generate executive SLA compliance summaries, and verify HD voice delivery. |
| **AI Platform Copilot / NOC Diagnostic Agent** | Automated Acoustic Diagnosis & SLA Remediation | Interrogate live media stream telemetry, detect carrier jitter anomalies, trigger RTPEngine node health checks, and dynamically adjust QoS SLA alert thresholds. |

---

## 4. Visual Interface & Dashboard Layout

The QoS dashboard provides executive summaries, quality distribution graphs, codec utilization statistics, and a granular DataGrid of individual audio streams.

### 4.1 Real-Time QoS Telemetry Dashboard
The main view provides immediate situational awareness with color-coded telemetry cards, an interactive MOS distribution progress bar, and a live stream session ledger.

![QoS and Voice Quality Dashboard](/screenshots/sbc/reports/cdr/qos/qos-monitoring-list.png)

### 4.2 Voice QoS Alert Thresholds Modal
Clicking the **Thresholds** button opens the policy configuration modal, where administrators define the quantitative boundaries that trigger SLA degradation alarms.

![Voice QoS Alert Thresholds Configuration](/screenshots/sbc/reports/cdr/qos/qos-policy-modal.png)

---

## 5. Field & Metrics Reference

### Executive KPI Cards

| Metric Card | Unit / Range | Optimal Value | Description |
| :--- | :--- | :--- | :--- |
| **Average MOS Score** | Score (`1.00` to `5.00`) | `>= 4.10` (HD Voice) | Cluster-wide Mean Opinion Score computed over the selected time window. |
| **Network Jitter** | Milliseconds (`ms`) | `< 20.0 ms` | Statistical variance in RTP packet inter-arrival times across all monitored sessions. |
| **Packet Loss** | Percentage (`%`) | `< 0.50 %` | Proportion of audio packets dropped or discarded due to buffer exhaustion. |
| **Monitored Streams** | Count | Dynamic | Number of distinct active or recently analyzed audio streams handled by RTPEngine. |

### MOS Quality Score Breakdown

| Quality Tier | Score Range | Audio Experience Description |
| :--- | :--- | :--- |
| **HD Voice** | `4.10` - `5.00` | Pristine studio-grade audio clarity; typical of wideband Opus or G.722 codecs under optimal network conditions. |
| **Good** | `3.60` - `4.09` | High-quality toll audio; equivalent to standard PSTN landline connections (G.711u/a) with negligible latency. |
| **Fair** | `3.10` - `3.59` | Noticeable impairment, minor clipping, or perceptible delay; conversation remains intelligible without repetition. |
| **Poor** | `< 3.10` | Severe distortion, packet dropouts, or synthetic artifacting; unacceptable for commercial enterprise communications. |

### Session Stream Ledger Columns

| Column | Data Type | Description |
| :--- | :--- | :--- |
| **Call ID / Session** | String / Monospace | Unique SIP Call-ID and carrier group identity associated with the audio stream. |
| **Caller / Callee** | String / URI | Originating source URI and destination target URI of the two communicating legs. |
| **Voice Codec** | Badge | Active audio encoding format (e.g., `Opus HD`, `G.722`, `PCMU`, `PCMA`, `G.729`). |
| **Duration** | Formatted | Total elapsed media transmission duration (e.g., `45s`, `2m 14s`). |
| **MOS Score** | Numeric Badge | Real-time computed MOS rating for the specific session. |
| **Jitter / Loss** | String | Concurrently reported packet arrival delta (ms) and transmission loss percentage. |
| **Quality Status** | Status Badge | Qualitative evaluation tag (`HD Voice`, `Good`, `Fair`, or `Degraded`). |

---

## 6. RTPEngine Telemetry Engine & MOS Calculation

Ring2All SBC calculates Mean Opinion Scores using the **ITU-T G.107 E-Model**, translating network transmission parameters into a transmission rating factor ($R$), which is subsequently mapped to an estimated MOS score ($1.0 \le \text{MOS} \le 5.0$).

### 1. Transmission Rating Factor ($R$)
$$R = R_0 - I_s - I_d - I_{e\text{-eff}} + A$$

Where:
* $R_0$: Basic signal-to-noise ratio (standard baseline $\approx 93.2$ for narrowband, $\approx 129$ for wideband).
* $I_s$: Simultaneous impairment factor (quantizing distortion, side-tone).
* $I_d$: Delay impairment factor (latency, round-trip echo, jitter buffer transit time).
* $I_{e\text{-eff}}$: Effective equipment impairment factor (codec intrinsic distortion and packet loss sensitivity).
* $A$: Advantage factor (expectation factor; typically $0$ for fixed IP links).

### 2. MOS Derivation Formula
$$\text{MOS} = 1 + 0.035 R + R (R - 60)(100 - R) \times 7 \times 10^{-6}$$
*(Constrained between 1.0 and 4.5 for narrowband, up to 4.9 for Opus HD).*

---

## 7. Voice QoS Alert Thresholds & SLA Governance

Administrators manage system-wide threshold policies via the **Voice QoS Alert Thresholds** modal:

| Parameter | Type | Default | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- |
| **Enable Real-Time QoS Telemetry** | Toggle | `Enabled` | Boolean | Activates automated parsing of RTCP XR packets from RTPEngine relays. |
| **Alert on SLA Degradation** | Toggle | `Enabled` | Boolean | Generates active dashboard alerts and raises alarms when streams violate thresholds. |
| **Minimum MOS Score** | Numeric | `3.50` | `1.0` - `5.0` | Sessions dropping below this score are flagged as degraded. |
| **Max Allowable Jitter** | Numeric | `45 ms` | `1` - `500 ms` | Maximum tolerable packet arrival variance before triggering jitter alarms. |
| **Max Packet Loss** | Numeric | `2.50 %` | `0.0` - `50.0 %` | Maximum permissible packet loss ratio over a 10-second rolling window. |
| **Max RTT Latency** | Numeric | `150 ms` | `10` - `1000 ms` | Round-trip signaling and media transmission ceiling for SLA compliance. |

---

## 8. Troubleshooting & Diagnostic Commands

### Inspecting Live RTPEngine Media Statistics
Operators can query RTPEngine in real time via the Unix control socket:

```bash
# Query active calls and stream metrics directly from RTPEngine
rtpengine-ctl list totals

# Inspect active media sessions on the local node
rtpengine-ctl list sessions
```

### Checking QoS Policy in PostgreSQL
Verify the active alert threshold policy configured in the database:

```bash
psql -U sbc_admin -d sbc_admin -c "
SELECT min_mos_score, max_jitter_ms, max_packet_loss_pct, max_rtt_latency_ms, alert_on_degradation, is_active 
FROM qos_alert_policies 
WHERE is_active = true;"
```

---

## 9. Model Context Protocol (MCP) AI Integration

The QoS & Voice Quality monitoring subsystem is fully exposed through the Ring2All SBC Model Context Protocol (MCP) server. Autonomous diagnostic agents and NOC assistants use these tools to investigate acoustic degradation, inspect RTPEngine media proxies, and govern quality thresholds.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_voice_qos_telemetry` | Real-time Telemetry Query | `read` | Retrieve aggregated Voice QoS telemetry, MOS ratings, RTCP XR jitter, packet loss %, and active codec distribution across the cluster. |
| `analyze_call_qos_stream` | Deep Acoustic Forensics | `read` | Conduct deep-dive quality analysis for a specific Call-ID or endpoint IP, pinpointing codec negotiation and degradation root cause. |
| `get_rtpengine_status` | Media Relay Health | `read` | Check connectivity, round-trip ping latency, active media streams, and relay capacity across all RTPEngine instances. |
| `get_qos_alert_policy` | Policy Inspection | `read` | Retrieve current SLA violation thresholds (minimum MOS score, maximum jitter ms, max packet loss %, and max RTT latency). |
| `update_qos_alert_policy` | Threshold Mutation | `operational` | Update Voice QoS SLA threshold policies and toggle real-time degradation alerting. |
| `diagnose_one_way_audio` | Media Stream Diagnostics | `diagnostic` | Evaluates RTPEngine call telemetry and SIP SDP offer/answer messages to detect one-way audio, asymmetric packet loss, extreme jitter, and NAT IP mismatches. |

---

### Tool Schemas & Payloads

#### 1. `get_voice_qos_telemetry`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": ["5m", "15m", "1h", "24h", "7d"],
      "description": "Time window for QoS evaluation (default: '1h')."
    },
    "min_mos": {
      "type": "number",
      "description": "Filter streams with MOS score less than or equal to this threshold (e.g. 3.5)."
    },
    "carrier": {
      "type": "string",
      "description": "Filter telemetry by specific wholesale carrier or gateway name."
    }
  }
}
```

##### Output Payload Example
```json
{
  "period": "1h",
  "total_streams": 1420,
  "average_mos": 4.28,
  "degraded_streams_count": 14,
  "average_jitter_ms": 14.2,
  "average_packet_loss_pct": 0.18,
  "codec_breakdown": {
    "Opus_HD": 68.4,
    "PCMU_G711u": 24.1,
    "G729": 7.5
  },
  "sla_violations": [
    {
      "call_id": "8fa2-991b-4cd1@192.168.11.130",
      "carrier": "Level3-Interconnect",
      "mos": 2.94,
      "jitter_ms": 78.4,
      "packet_loss_pct": 4.8,
      "primary_cause": "Burst Packet Loss on Carrier Transit"
    }
  ]
}
```

---

#### 2. `analyze_call_qos_stream`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The SIP Call-ID string to inspect for voice quality."
    },
    "ip": {
      "type": "string",
      "description": "Endpoint or carrier IP address to inspect recent QoS streams for."
    }
  }
}
```

##### Output Payload Example
```json
{
  "call_id": "8fa2-991b-4cd1@192.168.11.130",
  "ingress_leg": {
    "source_ip": "192.168.11.130",
    "codec": "Opus",
    "mos": 4.45,
    "jitter_ms": 8.1,
    "packet_loss_pct": 0.0,
    "rtt_ms": 18.4
  },
  "egress_leg": {
    "destination_ip": "203.0.113.50",
    "codec": "PCMU",
    "mos": 2.94,
    "jitter_ms": 78.4,
    "packet_loss_pct": 4.8,
    "rtt_ms": 142.1
  },
  "transcoder_active": true,
  "diagnosis": "Severe egress link congestion detected between RTPEngine node rtp01 and destination carrier gateway 203.0.113.50."
}
```

---

#### 3. `get_rtpengine_status`

##### Input Schema
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "total_nodes": 2,
  "nodes": [
    {
      "node_id": "rtp01",
      "socket": "udp:127.0.0.1:22222",
      "status": "online",
      "latency_ms": 0.42,
      "active_sessions": 348,
      "total_relayed_packets": 18492040,
      "cpu_load_pct": 14.8
    },
    {
      "node_id": "rtp02",
      "socket": "udp:192.168.10.32:22222",
      "status": "online",
      "latency_ms": 1.15,
      "active_sessions": 290,
      "total_relayed_packets": 14201880,
      "cpu_load_pct": 11.2
    }
  ]
}
```

---

#### 4. `update_qos_alert_policy`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "min_mos_score": {
      "type": "number",
      "description": "Minimum acceptable Mean Opinion Score (1.0 to 5.0, e.g. 3.60)."
    },
    "max_jitter_ms": {
      "type": "number",
      "description": "Maximum allowable RTP network jitter in milliseconds (e.g. 40)."
    },
    "max_packet_loss_pct": {
      "type": "number",
      "description": "Maximum allowable packet loss percentage (e.g. 2.0)."
    },
    "max_rtt_latency_ms": {
      "type": "number",
      "description": "Maximum round-trip time latency in milliseconds (e.g. 150)."
    },
    "alert_on_degradation": {
      "type": "boolean",
      "description": "Whether to trigger active alerts when stream quality drops below thresholds."
    }
  }
}
```

##### Output Payload Example
```json
{
  "success": true,
  "policy": {
    "min_mos_score": 3.6,
    "max_jitter_ms": 40,
    "max_packet_loss_pct": 2.0,
    "max_rtt_latency_ms": 150,
    "alert_on_degradation": true,
    "updated_at": "2026-09-08T15:30:00.000Z"
  }
}
```

---

### Natural Language AI Prompts

#### English Examples
* *"Diagnose if there is one-way audio on Call-ID 1984b966-0c7f-1240-ea97-bc2411e57092."*
* *"Check our cluster voice QoS telemetry over the last 15 minutes and identify any audio streams with MOS under 3.5."*
* *"Perform a deep quality analysis on Call-ID 8fa2-991b-4cd1@192.168.11.130 and explain why it degraded."*
* *"Are all RTPEngine media proxy instances responsive, and what is their current session load?"*
* *"Update our voice QoS alert policy: set maximum jitter to 40 ms and minimum MOS to 3.60."*

#### Spanish Examples (Español)
* *"Diagnostica si hay audio unidireccional en el Call-ID 1984b966-0c7f-1240-ea97-bc2411e57092."*
* *"Revisa la telemetría de calidad de voz de los últimos 15 minutos e identifica si hay flujos con MOS menor a 3.5."*
* *"Realiza un diagnóstico profundo de calidad para el Call-ID 8fa2-991b-4cd1@192.168.11.130 y explica la causa de degradación."*
* *"¿Están todos los nodos de RTPEngine operativos y cuál es su carga de llamadas en curso?"*
* *"Actualiza la política de alertas QoS: establece jitter máximo en 40 ms y MOS mínimo en 3.60."*

---

### Enterprise Safeguards & Access Governance
1. **Mathematical Constraints**: All numeric threshold mutations are bounded by strict sanity checks (`min_mos_score` between 1.0 and 5.0, `max_jitter_ms` between 1 and 500, `max_packet_loss_pct` between 0.0 and 50.0%).
2. **Zero In-Call Disruption**: Querying QoS telemetry and RTPEngine health via MCP operates strictly via asynchronous sockets and PostgreSQL caches, ensuring zero interruption to active media streams.
3. **Role-Based Execution Isolation**: Mutations via `update_qos_alert_policy` require operational roles (`noc_network_engineer` or `super_admin`). Read-only users (`read_only_monitor`) are restricted to telemetry and health queries.

---

## 10. Glossary

* **E-Model (ITU-T G.107)**: Computational model that uses transmission parameters to predict voice quality as experienced by the user.
* **Jitter**: Statistical variation in packet arrival times caused by network congestion, queuing delays, or route drift.
* **MOS (Mean Opinion Score)**: Standard numerical measure (`1.0` to `5.0`) representing subjective human evaluation of voice call clarity.
* **Opus**: Highly versatile audio codec standardized by the IETF, capable of dynamically scaling between 6 kbps narrowband and 510 kbps fullband stereo.
* **RTCP XR (RFC 3611)**: Extended Reports format for RTP Control Protocol, carrying VoIP performance metrics including round-trip delay and burst loss.