MoQROS

Stream ROS 2 topics over Media over QUIC (MoQ), in Rust: images as video, and any other message type as JSON or CDR data.
moqros converts each image to I420, encodes it (VP8 or H.264), and publishes it to a MoQ relay as a
hang broadcast. That's the WebCodecs-friendly format played by the official
@moq/watch web component. Topics of any other type go into a
hang data track instead (see Other message types). It can also go the other way:
subscribe to a broadcast, decode it, and republish it as a ROS topic.
ROS 2 topic ──► moqros-pub ──► moq-relay ──► browser (examples/web: videos + data)
Image / any msg hang QUIC/WebTransport └──► moqros-sub ──► ROS 2 topic
Layout
| Path | What |
|---|---|
crates/moqros |
The library (crates.io, docs.rs). The core (conversion, codec, MoQ publish/subscribe) is ROS-independent; the ros feature adds r2r bridges. |
crates/moqros-cli |
Bridge nodes (crates.io): moqros-pub (ROS → MoQ) and moqros-sub (MoQ → ROS). Also a colcon (ament_cargo) package. |
examples/image_source |
Sample node that plays a video file (via ffmpeg) or a PNG/JPEG directory as an Image topic. |
examples/web |
Browser viewer (React, TypeScript, @moq/watch) for several video and data broadcasts. See Web viewer. |
docker/ |
Dockerfile (ROS 2 Jazzy + Rust, moq-relay) and the end-to-end compose.yml. |
End-to-end sample (Docker)
You only need Docker:
On first start, the one-shot samples service generates a test video (samples/sample.mp4) and a PNG
sequence (samples/frames/) with ffmpeg inside the container. Files that already exist are kept. To stream
your own footage, put a video file or a directory of PNG/JPEG frames in samples/ and pass SAMPLE=<name>.
Open http://localhost:8080 in a Chromium-based browser or Firefox. Both support WebTransport. The page
connects to http://localhost:4443/anon and shows a panel for every broadcast the relay announces: the two
videos sample/image_raw and sample/frames/image_raw, and the latest messages of the data broadcasts
chatter and sample/pose. See Web viewer for picking broadcasts.

The compose file runs these services:
samples: creates the sample inputs if they're missing, then exits.relay:moq-relaywith a self-signed certificate. It allows anonymous access underanon/.source:image_sourcepublishes/sample/image_rawat 30 fps asbgr8(1280x720; setWIDTH=640to scale down).source-frames: a secondimage_sourcepublishes the PNG sequence (640x480) on/sample/frames/image_rawat 15 fps.chatter:ros2 topic pubpublishes astd_msgs/msg/Headerstamped with the publish time on/chatterat 10 Hz. It logs every 100th message.pose:ros2 topic pubpublishes a stampedgeometry_msgs/msg/PoseStampedon/sample/poseat 5 Hz.moqros-pub: publishes both image topics as the video broadcastssample/image_rawandsample/frames/image_raw, and/chatterand/sample/poseas the JSON data broadcastschatterandsample/pose.moqros-sub: subscribes to all four broadcasts. It republishes decodedrgb8images on/moqros/imageand/moqros/frames, and the data on/moqros/chatterand/moqros/pose.web: the viewer inexamples/web, built with Node and served by nginx.
To play the PNG sequence instead of the video, run SAMPLE=frames docker compose -f docker/compose.yml up.
The relay allows anyone who can reach it to watch and publish. Read Security before you run the sample on a machine others can reach.
The ROS services share one network and IPC namespace, as processes on one robot would. This lets Fast DDS
use shared memory for the 2.7 MB frames. The source publishes with reliable QoS, and moqros-pub runs with
--reliable. With best-effort QoS, large images are split into many UDP fragments, and losing any one of them
drops the whole frame. In testing that cut 30 fps down to 10–20 fps. On a real robot, match the camera
driver's QoS. Both bridges log their message rate every 10 s (message rate).
To check the round trip on the ROS side:
If UDP port forwarding doesn't work in your Docker setup, run the relay on the host instead
(cargo install moq-relay && moq-relay docker/relay.toml).
Installing the bridge nodes
moqros-pub and moqros-sub need a ROS 2 environment, libvpx, pkg-config, and libclang at build time
(see Development).
With cargo, from crates.io:
IDL_PACKAGE_FILTER="std_msgs;sensor_msgs;geometry_msgs;nav_msgs;rosgraph_msgs"
As a ROS 2 package with colcon (crates/moqros-cli has an ament_cargo package.xml):
&&
ROS arguments and parameters
Both bridges accept the standard --ros-args: remap the node name (-r __node:=…) and namespace
(-r __ns:=…), and set ROS parameters with -p or --params-file. Each command-line flag can also be
set as a parameter of the same name in snake_case (--keyframe-interval-ms becomes keyframe_interval_ms).
A flag on the command line wins over a parameter, and a parameter wins over environment variables and
defaults. Bool flags also take a value (--reliable=false). Parameters are read once at startup, and
parameters that match no flag are ignored with a warning. In a parameter file, key a namespaced node by
its fully qualified name (/front/moqros_pub); the bare node name only matches in the root namespace.
A repeatable flag (--topic, --broadcast) takes a string array parameter, one element per occurrence
(-p "topic:=[/a, /b]"). If the flag is also on the command line, the command line replaces the whole
array.
The colcon package installs a launch file (moqros.launch.py) and a sample parameter file
(config/moqros.yaml):
The launch file uses $MOQROS_URL when url isn't given, and publishes the broadcast
<namespace>/image_raw (namespace:=/front gives front/image_raw). For a client certificate (see
Authentication), add tls_cert:=… tls_key:=…, or set $MOQROS_TLS_CERT and
$MOQROS_TLS_KEY.
Several topics
One moqros-pub can publish several topics, and one moqros-sub can republish several broadcasts. Repeat
--topic or --broadcast, and add options after the name, separated by commas:
| Bridge | Options | Defaults |
|---|---|---|
moqros-pub --topic TOPIC,… |
format, type, mode, broadcast |
--format and --mode for every topic. The broadcast name is the topic without its leading slash. |
moqros-sub --broadcast NAME,… |
topic, type, frame_id |
--frame-id for every broadcast. The topic is /moqros/<broadcast> (/moqros/image for a lone broadcast). |
Each topic becomes a broadcast of its own. --type and --broadcast of moqros-pub, and --topic and
--type of moqros-sub, name a single topic, so they only work with one --topic or --broadcast. Video
topics start at once. A data topic without a type starts when it appears in the ROS graph. moqros-sub
waits for all its broadcasts at once, and starts each one when it's announced. It skips a broadcast whose
topic it can't create (e.g. a message type this build has no bindings for), and goes on with the rest.
Otherwise, each bridge exits when any of its topics fails.
Other message types
moqros-pub --format json|cdr publishes a topic of any message type. The default, --format video, is for
sensor_msgs/msg/Image.
json: each message is one JSON document, in r2r's mapping of the message fields. Any hang consumer can read it, including a browser; the web viewer shows the latest message. Large arrays (point clouds, images) get big and slow as JSON, so usecdrfor those.cdr: each message is its ROS serialization, passed through untouched. It's compact and lossless, but only ROS-aware consumers can decode it. Images sent ascdrarrive uncompressed and bit-exact.--mode snapshot(default): each message is a MoQ group of its own, and subscribers skip to the newest one when they fall behind. Suits sensor data and state.--mode stream: all messages go into one group and are delivered in order, none skipped. Suits logs and commands. The group never closes, so the publisher and the relay keep its messages for as long as the broadcast runs, and a subscriber that joins late gets them all from the start. Avoid it for long-running, high-rate topics; usesnapshotthere.- Type: without
--type,moqros-pubwaits for the topic to appear and asks the ROS graph for its type. Relative topic names resolve against the node's namespace, but remappings aren't applied. The type goes into the catalog, somoqros-subrepublishes with the same type (--typeoverrides it). - Supported types: r2r generates message bindings at build time, and the data bridges only handle types
it generated. With
IDL_PACKAGE_FILTERset, list every package you need (the Docker image includesstd_msgs,sensor_msgs,geometry_msgs,nav_msgs, androsgraph_msgs).
moqros-sub handles both kinds of broadcast: it republishes video as rgb8 images, and data tracks as their
message type. It fails if a broadcast comes back carrying something different from before.
Web viewer
examples/web is a React and TypeScript app built on @moq/watch.
It opens one connection to the relay and shows any number of broadcasts side by side: a video panel for each
image broadcast, and a data panel with the latest message for each data broadcast. It tells them apart by the
broadcast's catalog.
-
Picking broadcasts: the sidebar lists every broadcast the relay announces. With Show all announced on (the default), each one gets a panel; the filter narrows that to names containing some text, and unticking a broadcast hides it. Add shows a broadcast by name, even one the relay doesn't announce, as
auto(decided by the catalog),video, ordata. -
Query parameters: the view is kept in the URL, so it can be bookmarked or shared:
url(relay URL),auto=0,filter,show,videoanddata(comma-separated broadcasts to always show, by catalog or as that kind), andhide. Thenameparameter of the old viewer still works asvideo. -
Data renderers: JSON messages show as a tree or as text, and CDR messages as their size and a hex dump (the browser can't decode CDR). Messages with a header (
std_msgs/msg/Headerand*Stampedtypes) can also show their stamp and age on arrival. Add a view for a message type of your own by registering a React component insrc/panels/renderers/index.ts:register({ rosType: "sensor_msgs/msg/Imu", format: "json", label: "IMU", component: ImuView });The component gets the broadcast name, the track (ROS type, format, mode), the raw payload, and the parsed JSON message. Each panel lets you switch between the renderers that match its type.
To develop it, run the relay and the bridges (e.g. the Docker sample, without its web service), then:
Library usage
The library is published on crates.io as moqros; API docs are on
docs.rs.
[]
= { = "0.1", = ["ros"] } # omit `ros` for the ROS-independent core
ROS → MoQ
use ;
let ctx = create?;
let mut node = create?;
let publisher = connect?;
let broadcast = publisher.create_image_broadcast?;
let bridge = spawn_ros_to_moq?;
spawn_blocking;
bridge.await??;
Any other message type goes through a data broadcast:
use ;
let settings = DataSettings ;
let broadcast = publisher.create_data_broadcast?;
let bridge = spawn_ros_to_moq_data?;
spawn_moq_to_ros goes the other way for both kinds of broadcast.
Without ROS
let publisher = connect?;
let mut camera = publisher.create_image_broadcast?;
camera.publish?;
let subscriber = connect?;
let mut images = subscriber.subscribe_images.await?;
while let Some = images.next_image.await?
Data broadcasts carry opaque payloads:
let mut status = publisher.create_data_broadcast?;
status.publish?;
let mut messages = subscriber.subscribe_data.await?;
while let Some = messages.next_message.await?
Subscriber::subscribe returns either kind, depending on what the broadcast's catalog offers.
Codecs
| Codec | Feature | Backend | Notes |
|---|---|---|---|
| VP8 | vp8 (default) |
system libvpx, real-time CBR | |
| H.264 | h264 |
Cisco's OpenH264 binary, loaded at runtime | Constrained Baseline, avc3. |
Pick the codec with EncoderSettings::codec (moqros-pub --codec vp8|h264). The subscriber picks the best
rendition in the catalog that this build can decode.
The h264 feature loads Cisco's prebuilt OpenH264 binary at runtime and checks its SHA-256 against known
Cisco releases:
# downloads from ciscobinary.openh264.org
You can also set the path in code with moqros::set_openh264_library.
Behavior
- Encodings:
rgb8,bgr8,rgba8,bgra8,mono8,yuv422(UYVY), andyuv422_yuy2(YUYV). An odd trailing row or column is cropped, because 4:2:0 video needs even dimensions. - Format on the wire: each frame goes in the hang "legacy" container (a timestamp plus the codec payload). The catalog
(
catalog.json) has one video track namedvideo. It's republished whenever the resolution changes. - Groups: each keyframe starts a new MoQ group. The keyframe interval (default 2 s) bounds how long a new viewer waits for the first picture.
- Latency: if the encoder falls behind, the bridge drops all but the newest pending image. The subscriber always jumps to the newest group.
- Timestamps:
header.stampbecomes a µs timeline that starts at 0 for each broadcast.moqros-substamps the republished images with the local receive time. - Reconnects: the relay connection redials automatically.
moqros-subresubscribes when the broadcast comes back. - QoS: both bridges default to the best-effort
sensor_dataprofile. Pass--reliableto match a reliable publisher, which is recommended for large uncompressed images. - Data broadcasts: the catalog lists one track named
data, in itsjsonsection (JSON) or itsbinarysection (CDR, MIME typeapplication/x-ros2-cdr), with the mode and the ROS type (rosType). Each MoQ frame is one message payload, without a container.
Security
The Docker sample is meant for one machine. Before you expose a relay beyond localhost, keep these in mind:
- Anyone who reaches the relay can watch, and publish.
docker/relay.tomlgrants anonymous publish and subscribe underanon/([auth] public = "anon/**"). With port 4443 reachable, anyone who knows the address can watch every broadcast, and can publish broadcasts of their own. Broadcast names aren't secret: subscribers can list what's announced under a path. - Published broadcasts can reach ROS.
moqros-subrepublishes whatever arrives on its broadcasts as ROS messages. On an open relay, someone else can publish under the same name and inject messages into your ROS graph, e.g.geometry_msgs/msg/Twiston a command topic. - The compose file listens on all interfaces. Its
ports:entries bind 4443 (relay) and 8080 (viewer) on every host interface, and on Linux Docker's port publishing bypasses firewalls such as ufw. To keep the sample local, bind to loopback ("127.0.0.1:4443:4443/udp","127.0.0.1:4443:4443/tcp","127.0.0.1:8080:80"). http://relay URLs trust the network. QUIC always encrypts the stream, but with anhttp://URL the client fetches the certificate fingerprint it trusts over plain HTTP, so anyone on the path can swap it and read or alter the stream.--insecureskips verification entirely. Outside development, give the relay a real certificate ([listen] tls.cert/tls.key) and usehttps://URLs.
Authentication
Replace public in the relay's [auth] section with url, pointing at an auth server: the relay asks it
about every session. moq auth serve from the moq project is the reference
one. It admits a session by a client certificate (mTLS) or a JWT, and grants publish and subscribe patterns.
See the upstream authentication documentation
for its flags. Give each client only what it needs: the robot publishes, viewers subscribe.
Bridges: client certificates. For a device that runs unattended, issue it a certificate from your own CA.
Point the relay's [listen] tls.root at the CA, and pass the certificate and its key to the bridge:
--tls-cert and --tls-key also come from MOQROS_TLS_CERT and MOQROS_TLS_KEY, or the tls_cert and
tls_key ROS parameters; in the library, use ClientConfig::with_client_cert. Nothing secret goes into the
URL, and you revoke a device by its certificate. moq auth serve grants every certificate its CA signed the
same patterns. To scope each device to its own path, run an auth server of your own that decides by the
certificate's name or fingerprint, which the relay passes along with each session.
Viewers: JWTs. Browsers present a JWT in the jwt query parameter of the relay URL. Issue it from your
own backend once the viewer has signed in, signed with the key moq auth serve verifies, and add it to the
viewer's relay URL (the Relay URL field or the url query parameter of examples/web). A token's root is
the path it's valid under, and its publish and subscribe patterns say what it may do there.
The bridges accept a token too (--url "https://relay.example.com/robot?jwt=…"), but prefer certificates:
a URL ends up in shell history and process lists, and the bridges reuse it on every reconnect without asking
for a new token, so once it expires they can't reconnect. They do hide the token (jwt=REDACTED) when they
log the URL.
Development
The core library builds and tests natively on any OS. ROS isn't required for it, but the default vp8
feature needs libvpx, pkg-config, and libclang (bindgen generates the libvpx bindings):
# Debian/Ubuntu
# or macOS (libclang comes with the Xcode CLI tools)
# brew install libvpx pkgconf
# H.264 tests (skipped unless OPENH264_LIBRARY is set):
# OPENH264_LIBRARY=$(./scripts/fetch_openh264.sh) cargo test -p moqros --features h264
# Integration test through a real relay:
MOQROS_RELAY_BIN=
The ros feature, moqros-cli, and examples/image_source need a sourced ROS 2 environment and libclang,
because r2r generates its bindings at build time. Use the Docker build stage, or on a ROS machine:
IDL_PACKAGE_FILTER="std_msgs;sensor_msgs;geometry_msgs;rosgraph_msgs"
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Dependencies have their own licenses. libvpx is BSD-3-Clause, and the env-libvpx-sys bindings are MPL-2.0.
Cisco's OpenH264 binary is covered by Cisco's binary license.