WebRTC

WebRTC creates direct peer-to-peer links for MAGPIE streams, RPC, and media. One WebRTCConnection can manage a separate link to each remote peer. MQTT, ZeroMQ, or HTTP is used only to exchange signaling messages; application data leaves the signaling path after negotiation.

Choose a topology

The role setting controls which participants connect:

mesh (default): every participant connects to every other participant.
host: accepts links from clients, typically for a robot, service, or media source.
client: connects to hosts but not to other clients, typically for callers or viewers.

Use one host and multiple clients when several applications consume the same service. connect() returns when the first peer is ready; additional peers may join later. Stream writers publish to all connected peers, while RPC acknowledgements and replies return only to the requester. Connected remote IDs are available through peer_ids in Python, peerIds() in C++, and peerIds in TypeScript.

Choose signaling

Signaling	Use it when
ZeroMQ	Both Python/C++ peers are on localhost or a controlled LAN
MQTT	Peers already reach a broker or sit behind NAT
HTTP	You have a web application backend or want a minimal opaque relay

Signaling does not carry the steady-state media or RPC traffic.

Connect peers

Python
C++
TypeScript / browser

from luxai.magpie.transport.webrtc import WebRTCConnection, WebRTCOptions

options = WebRTCOptions(
    video_topics=["robot/camera/color"],
    audio_topics=["robot/microphone"],
    stun_servers=["stun:stun.l.google.com:19302"],
)

connection = WebRTCConnection.with_mqtt(
    "mqtts://broker.example.com:8883",
    session_id="robot-01",
    role="host",
    options=options,
    reconnect=True,
)
connection.connect(timeout=30)

#include <magpie/transport/webrtc_connection.hpp>
#include <magpie/transport/webrtc_http_signaler.hpp>

auto signaler = std::make_shared<magpie::HttpSignaler>(
    "https://signal.example.com/webrtc", "robot-01");

magpie::WebRtcOptions options;
options.useMediaChannels = false;
options.role = "host";

auto connection = std::make_shared<magpie::WebRtcConnection>(
    signaler, options);
connection->connect();

import {WebRtcConnection} from '@luxai-qtrobot/magpie'

const connection = await WebRtcConnection.withHttp(
  'https://signal.example.com/webrtc',
  'robot-01',
  {
    role: 'client',
    reconnect: true,
    webrtcOptions: {videoTopics: ['robot/camera/color']},
  },
)
await connection.connect(30)

MAGPIE.js WebRTC uses browser APIs and is not available in Node.js.

Create WebRtcStreamWriter/WebRtcStreamReader and WebRTCRpcRequester/WebRTCRpcResponder from the connected peer just as you create components from a shared MQTT connection.

For multi-peer ZeroMQ signaling, enable multiplex mode on the bound signaler and every connecting participant. The legacy PAIR mode supports two-peer setups.

Data channels and media tracks

Ordinary values, frames, and RPC messages travel through the WebRTC data channel. Python and browser peers can route declared video or audio topics over native RTP tracks. Both peers must agree on topic names and compatible media configuration.

:::note C++ media interoperability MAGPIE C++ currently sends image and audio frames over the data channel. When it communicates with a Python peer, set use_media_channels=False in Python and useMediaChannels=false in C++ so both sides use the same path. :::

In a browser, local camera and microphone tracks can be attached directly:

const media = await navigator.mediaDevices.getUserMedia({video: true, audio: true})
connection.sendVideoTrack(media.getVideoTracks()[0], 'robot/camera/color')
connection.sendAudioTrack(media.getAudioTracks()[0], 'robot/microphone')

NAT traversal

STUN helps peers discover reachable addresses. TURN relays traffic when direct connectivity is impossible. Production internet deployments should provide controlled STUN/TURN configuration and test restrictive enterprise, mobile, and carrier-grade NAT networks.

from luxai.magpie.transport.webrtc import WebRTCTurnServer

options = WebRTCOptions(
    stun_servers=["stun:stun.example.com:3478"],
    turn_servers=[
        WebRTCTurnServer(
            url="turn:turn.example.com:3478",
            username="robot-01",
            credential="short-lived-secret",
        )
    ],
)

HTTP signaling relay

The included relay protocol treats signaling messages as opaque bytes and supports join, send, long-poll receive, and leave operations. The example in the Python repository is intentionally in-memory and single-process. A scaled service needs shared storage, authentication, authorization, TLS termination, rate limits, and participant expiry.

Read the HTTP signaling contract or browse the WebRTC examples.

Choose a topology​

Choose signaling​

Connect peers​

Data channels and media tracks​

NAT traversal​

HTTP signaling relay​