---
title: "Media Engines (RTPEngine)"
description: "Documentation for Media Engines"
---

## Table of Contents
1. [Overview & Media Plane Architecture](#1-overview--media-plane-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Media Node Parameters](#5-field-reference--media-node-parameters)
6. [Kamailio RTPEngine NG Protocol Mechanics](#6-kamailio-rtpengine-ng-protocol-mechanics)
7. [Kernel-Space Forwarding (`xt_RTPENGINE`) Performance](#7-kernel-space-forwarding-xt_rtpengine-performance)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Media Plane Architecture

In **Ring2All SBC**, the **Media Engines** module coordinates, load-balances, and monitors the distributed cluster of **RTPEngine** media proxy daemons. While Kamailio manages the SIP signaling plane, RTPEngine anchors the voice and video media streams, performing NAT traversal, kernel-level packet forwarding, WebRTC DTLS-SRTP bridging, audio transcoding, and real-time RTCP XR quality telemetry.

```
       ┌─────────────────────────────────────────────────────────────┐
       │                Kamailio Core Signaling Plane                │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
                   Bencode NG Protocol (UDP/TCP 2223)
                                      │
             ┌────────────────────────┴────────────────────────┐
             │                                                 │
┌────────────▼──────────────┐                    ┌─────────────▼─────────────┐
│  RTPEngine Node 01 (Local)│                    │  RTPEngine Node 02 (Remote)│
│    127.0.0.1:2223 (Wt 10) │                    │  192.168.10.35:2223 (Wt 10)│
└────────────┬──────────────┘                    └─────────────┬─────────────┘
             │                                                 │
             │   Dual-Homed RTP / SRTP Media Streams           │
             │◄═══════════════════════════════════════════════►│
   Subscribers (WebRTC / SIP)                       Carrier Trunks (G.711 / G.729)
```

Communication between the signaling core and the media engines occurs via the high-speed **Bencode NG protocol**, enabling sub-millisecond port allocation and dynamic SDP rewriting during call setup.

---

## 2. Business & Operational Significance

* **Complete NAT Traversal & Topology Hiding**: Bridges audio between private LAN endpoints, public Internet subscribers, and carrier interconnect networks without leaking internal IP architecture.
* **Seamless WebRTC Interoperability**: Transcodes ICE, DTLS-SRTP, and Opus media from browser-based WebRTC endpoints into standard RTP and PCMA/PCMU for legacy PSTN trunks.
* **Carrier-Grade Throughput with Kernel Module**: Leverages the Linux kernel module (`xt_RTPENGINE`) to route RTP packets directly in kernel space, bypassing user-space context switching to sustain tens of thousands of concurrent calls.
* **Real-Time Call Quality Telemetry**: Continuously extracts RTCP Extended Reports (XR) to calculate Mean Opinion Scores (MOS), jitter, packet loss, and round-trip delay for the CDR and QoS reporting modules.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **Voice Media Engineer** | Media Cluster Balancing & Topology | Configure RTPEngine node sockets, assign distribution weights, and define network interface pairs (internal vs external). |
| **SBC Infrastructure Specialist** | High-CPS Throughput Optimization | Validate `xt_RTPENGINE` kernel module binding, adjust UDP buffer pools, and monitor media relay CPU utilization. |
| **WebRTC Solutions Architect** | Browser Media Bridging | Configure DTLS certificate profiles, ICE gathering timeouts, and SRTP cipher negotiation for WebRTC clients. |
| **Quality of Service (QoS) Analyst** | Media Health Governance | Audit media node operational states, track packet drop counters, and investigate MOS degradations. |
| **AI Media Plane Copilot / QoS Diagnostics Agent** | Real-Time Media Telemetry | Probe RTPEngine node health, inspect active media streams, diagnose audio packet degradation, and tune QoS thresholds via MCP. |

---

## 4. Visual Interface & Layout

The Media Engines interface displays all registered RTPEngine instances, their control socket URIs, distribution weights, active sessions, and live health metrics.

![Media Engines Management List View](/screenshots/sbc/settings/technology/media-engines/media-engines-list.png)

---

## 5. Field Reference & Media Node Parameters

| Parameter | Data Type | Default | Description |
| :--- | :--- | :--- | :--- |
| **Node Name** | String | `rtpe-media-01` | Unique administrative label for the media engine instance. |
| **Control Socket** | String / URI | `udp:127.0.0.1:2223` | Bencode NG protocol socket (`udp:<ip>:<port>` or `tcp:<ip>:<port>`). |
| **Weight** | Integer | `10` | Relative distribution weight for round-robin and least-loaded load-balancing across the media cluster. |
| **Interfaces** | String | `internal/external` | Declared IP address interfaces configured in `rtpengine.conf` for bridging different network zones. |
| **Kernel Mode** | Badge | `Enabled` | Indicates whether the node is utilizing the high-performance `xt_RTPENGINE` netfilter kernel module. |
| **Active Sessions** | Counter | `0` | Real-time count of concurrent two-way media dialogs anchored on this specific media node. |
| **Health Status** | Badge | `Active` | Health state evaluated via periodic NG `ping` probes (`Active` Green, `Probing` Amber, `Disabled` Red). |

---

## 6. Kamailio RTPEngine NG Protocol Mechanics

The Kamailio signaling script controls media streams using the `rtpengine` module functions:

```text
# Intercept SDP Offer on Inbound INVITE
route[RELAY_MEDIA_OFFER] {
    if (proto == WSS || proto == WS) {
        # Bridge WebRTC to standard SIP Trunk
        rtpengine_offer("direction=webrtc direction=external ICE=remove RTP/AVP replace-origin replace-session-connection");
    } else {
        # Standard SIP to Carrier Trunk
        rtpengine_offer("direction=internal direction=external replace-origin replace-session-connection");
    }
}

# Intercept SDP Answer on 200 OK / 183 Session Progress
route[RELAY_MEDIA_ANSWER] {
    rtpengine_answer("direction=external direction=internal replace-origin replace-session-connection");
}

# Teardown Media on BYE / CANCEL
route[TEARDOWN_MEDIA] {
    rtpengine_delete();
}
```

---

## 7. Kernel-Space Forwarding (`xt_RTPENGINE`) Performance

When `xt_RTPENGINE` is loaded, audio packets are intercepted directly by the Linux `iptables`/`nftables` packet filtering framework:

1. **User Space (NG Control Only)**: The user-space daemon handles SDP negotiation, ICE candidate validation, and DTLS key exchange.
2. **Kernel Table (`xt_RTPENGINE`)**: Once keys are established, the daemon installs routing table entries directly into kernel memory.
3. **Zero Copy Forwarding**: Voice packets entering the network interface card (NIC) are rewritten and dispatched out the outbound NIC without copying memory buffers into user space.

```
Incoming RTP Packet ───► NIC ───► [xt_RTPENGINE Kernel Module] ───► NIC ───► Outbound RTP Packet
                                      │
                         (Only control messages pass up)
                                      ▼
                           [RTPEngine User Daemon]
```

This architecture allows a single quad-core host to sustain over 15,000 concurrent G.711 voice calls with less than 1% CPU utilization.

---

## 8. Troubleshooting & Verification

### Validating RTPEngine Node Availability via RPC
In the **RPC Console**, inspect active media nodes and their responsiveness:
```bash
rtpengine.show all
```
Output confirms socket latency and operational status:
```json
{
  "jsonrpc": "2.0",
  "result": {
    "total_nodes": 2,
    "nodes": [
      {
        "url": "udp:127.0.0.1:2223",
        "weight": 10,
        "recheck_ticks": 0,
        "disabled": 0,
        "in_use": 14
      }
    ]
  },
  "id": 1
}
```

### Inspecting Local RTPEngine Sessions via CLI
Execute from the SBC host operating system:
```bash
rtpengine-ctl list sessions
rtpengine-ctl list totals
```

---

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

The Media Engines subsystem connects with the Model Context Protocol (MCP) to provide autonomous AI diagnostics for media relay availability, real-time MOS telemetry, call stream degradation analysis, and SLA policy management.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_rtpengine_status` | Status Query | `read` | Check connectivity, ping round-trip latency, active media streams, and relay capacity of all RTPEngine nodes. |
| `get_voice_qos_telemetry` | Telemetry Query | `read` | Retrieve real-time Voice QoS telemetry, Mean Opinion Scores (MOS), jitter, and packet loss across media streams. |
| `analyze_call_qos_stream` | Root Cause Analysis | `read` | Deep-dive voice quality diagnosis for a specific Call-ID or endpoint IP address, pinpointing degradation factors. |
| `get_qos_alert_policy` | Policy Inspection | `read` | Inspect active Voice QoS SLA violation policy thresholds (minimum MOS, max jitter, max packet loss). |
| `update_qos_alert_policy` | Configuration Mutation | `operational` | Update Voice QoS SLA threshold policies and automated degradation alerting. |

### Tool Schemas & Payloads

#### 1. `get_rtpengine_status`

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

##### Output Payload Example
```json
{
  "success": true,
  "data": {
    "totalNodes": 2,
    "activeNodes": 2,
    "nodes": [
      {
        "id": 1,
        "name": "rtpe-media-01",
        "socket": "udp:127.0.0.1:2223",
        "weight": 10,
        "status": "ONLINE",
        "activeSessions": 42,
        "pingLatencyMs": 0.8
      },
      {
        "id": 2,
        "name": "rtpe-media-02",
        "socket": "udp:192.168.10.35:2223",
        "weight": 10,
        "status": "ONLINE",
        "activeSessions": 38,
        "pingLatencyMs": 1.2
      }
    ]
  }
}
```

#### 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
{
  "success": true,
  "data": {
    "totalMatches": 1,
    "policyThresholds": {
      "minMos": 3.6,
      "maxJitterMs": "40ms",
      "maxLossPct": "2%"
    },
    "streams": [
      {
        "callId": "8120391-ab12@sbc",
        "from": "sip:2000@sbc.ring2all.com",
        "to": "sip:+14155552671@carrier.net",
        "durationSec": 184,
        "sourceIp": "192.168.1.150",
        "destinationIp": "64.120.10.5",
        "carrier": "Direct Relay",
        "mosScore": 4.38,
        "jitterMs": "6ms",
        "packetLossPct": "0.1%",
        "status": "HEALTHY",
        "detectedIssues": ["None (Optimal Audio Quality)"]
      }
    ]
  }
}
```

### Natural Language AI Prompts

#### English Examples
* *"Check the health and latency of all registered RTPEngine media nodes."*
* *"Analyze voice quality and packet jitter for Call-ID 8120391-ab12@sbc."*
* *"What is the current Voice QoS SLA alert policy threshold on our media engines?"*

#### Spanish Examples (Español)
* *"Verifica el estado y la latencia de todos los nodos de medios RTPEngine registrados."*
* *"Analiza la calidad de voz y el jitter de paquetes para el Call-ID 8120391-ab12@sbc."*
* *"¿Cuál es el umbral de política de alerta SLA de calidad de voz actual en nuestros motores de medios?"*

### Enterprise Safeguards & Access Governance
1. **Non-Disruptive Probes**: RTPEngine health checks send asynchronous ping commands without disrupting existing active RTP sessions.
2. **SLA Guardrails**: Updating QoS alert thresholds is constrained within valid ITU-T MOS boundaries (1.0 to 5.0).
3. **Role Segregation**: Modifying QoS alert policies requires `noc_network_engineer` or `sbc_system_admin` privileges; read-only roles can query telemetry and status.

---

## 10. Glossary

* **RTPEngine**: An enterprise-grade, high-performance media proxy designed for Kamailio and OpenSIPS, developed by Sipwise.
* **NG Protocol**: A high-efficiency, Bencode-serialized control protocol used between Kamailio and RTPEngine over UDP or TCP sockets.
* **DTLS-SRTP**: Datagram Transport Layer Security for Secure Real-time Transport Protocol, mandatory for WebRTC audio/video encryption.
* **Kernel Module (`xt_RTPENGINE`)**: An in-tree Linux kernel module that provides fast-path packet forwarding for active RTP media sessions.