1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
//! # moqros
//!
//! Stream ROS 2 topics over [Media over QUIC](https://moq.dev).
//!
//! Images are converted to I420, encoded (VP8 via libvpx by default, AV1 via libaom with the
//! `av1` feature, or H.264 via Cisco's OpenH264 binary with the `h264` feature; on a GPU through
//! GStreamer with the `hw` feature) and published as
//! [hang](https://docs.rs/hang) broadcasts, the format played by the `@moq/watch`
//! web component. The reverse direction (MoQ -> decoded images) is also provided.
//!
//! Messages of any other type travel as JSON or CDR payloads in a hang data track
//! ([`Publisher::create_data_broadcast`], [`Subscriber::subscribe_data`]).
//!
//! The core API is ROS-independent:
//!
//! ```no_run
//! # async fn run(rgb_bytes: Vec<u8>, capture_time: std::time::Duration) -> moqros::Result<()> {
//! let config = moqros::ClientConfig::new("http://localhost:4443/anon".parse().unwrap());
//!
//! let publisher = moqros::Publisher::connect(&config)?;
//! let mut camera = publisher.create_image_broadcast("camera", moqros::EncoderSettings::default())?;
//! camera.publish(&moqros::Image::new(640, 480, moqros::PixelFormat::Rgb8, rgb_bytes, capture_time)?)?;
//!
//! let subscriber = moqros::Subscriber::connect(&config)?;
//! let mut images = subscriber.subscribe_images("camera").await?;
//! while let Some(decoded) = images.next_image().await? {
//! // decoded.image is rgb8, captured at decoded.capture_time
//! }
//! # Ok(()) }
//! ```
//!
//! Data broadcasts carry opaque payloads:
//!
//! ```no_run
//! # async fn run(publisher: moqros::Publisher, subscriber: moqros::Subscriber) -> moqros::Result<()> {
//! let settings = moqros::DataSettings::new(moqros::DataFormat::Json);
//! let mut status = publisher.create_data_broadcast("status", settings)?;
//! status.publish(r#"{"battery": 0.82}"#)?;
//!
//! let mut messages = subscriber.subscribe_data("status").await?;
//! while let Some(message) = messages.next_message().await? {
//! // message.payload is one JSON document
//! }
//! # Ok(()) }
//! ```
//!
//! [`Subscriber::subscribe`] returns either kind, depending on what the broadcast's catalog
//! offers. Enable the `ros` feature for [`ros`] bridges built on r2r.
//!
//! ## Features
//!
//! | Feature | What |
//! | --- | --- |
//! | `vp8` (default) | VP8 through the system libvpx, real-time CBR. Needs libvpx, pkg-config, and libclang at build time. |
//! | `av1` | AV1 (Main profile, 8-bit) through the system libaom in real-time mode. Needs libaom, pkg-config, and libclang at build time. |
//! | `h264` | H.264 (Constrained Baseline, `avc3`) through Cisco's prebuilt OpenH264 binary, loaded at runtime. |
//! | `hw` | Hardware encoders (VA-API, NVENC) through GStreamer, falling back to software. Needs the GStreamer development files at build time. |
//! | `compressed` (default) | Decode JPEG and PNG images ([`Image::from_compressed`], `sensor_msgs/CompressedImage`) with pure-Rust decoders. |
//! | `ros` | ROS 2 bridges built on r2r. Needs a sourced ROS 2 environment and libclang at build time. |
//!
//! Pick the codec with [`EncoderSettings::codec`]. A subscriber picks the best rendition in
//! the catalog that this build can decode.
//!
//! With the `hw` feature, [`EncoderSettings::hardware`] ([`Hardware::Auto`] by default) encodes
//! on the first hardware encoder GStreamer can start for the codec: VA-API (`va` plugin, or the
//! older `vaapi` plugin) on Intel/AMD GPUs, or NVENC (`nvcodec` plugin) on NVIDIA GPUs. When
//! none works, it logs a warning and encodes in software, so the codec's own feature is still
//! required. Decoding always runs in software.
//!
//! The `h264` feature never compiles OpenH264: Cisco only covers the MPEG LA royalties for
//! binaries downloaded from Cisco. Give the binary's path in `OPENH264_LIBRARY` or with
//! `set_openh264_library`; its SHA-256 must match a known Cisco release.
//! `scripts/fetch_openh264.sh` in the repository downloads the right one for the platform.
//!
//! ## Wire format
//!
//! - **Video broadcasts:** the catalog (`catalog.json`) lists one video track, [`VIDEO_TRACK`],
//! and is republished whenever the resolution changes. Each frame goes in the hang "legacy"
//! container (a timestamp plus the codec payload). Each keyframe starts a new MoQ group, so
//! [`EncoderSettings::keyframe_interval`] bounds how long a new viewer waits for the first
//! picture. Subscribers always jump to the newest group. With
//! [`ImageBroadcastSettings::renditions`], smaller renditions go into tracks of their own
//! (`video_<height>p`), all listed in the same catalog; [`SubscribeOptions`] picks one.
//! - **Pixel formats:** see [`PixelFormat`]. An odd trailing row or column is cropped,
//! because 4:2:0 video needs even dimensions.
//! - **Timestamps:** capture times become a µs timeline that starts at 0 for each broadcast.
//! - **Data broadcasts:** the catalog lists one track, [`DATA_TRACK`], in its `json` section
//! ([`DataFormat::Json`]) or its `binary` section ([`DataFormat::Cdr`], MIME type
//! [`CDR_MIME`]), with the [`DataMode`] and the ROS message type (`rosType`). Each MoQ frame
//! is one message payload, without a container.
//! - **Capture times:** a root `moqros` section of the catalog can carry `captureOrigin`, the
//! capture time in µs that frame timestamp 0 maps to, in the publisher's clock (e.g. ROS time,
//! which may be sim time). It is republished whenever the timeline re-anchors. When the
//! capture times are wall-clock times since 2020, hang's `clock` carries the same origin.
//! Data broadcasts published with [`DataPublisher::publish_at`] use it.
//! - **Version:** the `moqros` section carries `version` (1 now; a section without one is
//! version 1). It only goes up when a field changes meaning, and a subscriber ignores a section
//! newer than it understands.
// On docs.rs, label feature-gated items with the feature they need.
pub use ;
pub use ;
pub use set_openh264_library;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Url;