Expand description
§moq-wasm (Rust)
The Rust SDK of this repository: connect to a MoQT relay, publish and subscribe to tracks and watch namespaces, in the same shapes as the browser SDK and the Python SDK. Clients offer MoQT draft-18 first, then draft-14. The design is in docs/architecture/moq-wasm/sdk.md.
§Install
Depend on a release tag:
[dependencies]
moq-wasm = { git = "https://github.com/nttcom/moq-wasm", tag = "rust-sdk-v0.0.1" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }The SDK runs on tokio. It builds aws-lc-sys, so a build needs a C
compiler, and a cross build a C toolchain for the target. It is tested on
Linux x86_64, Linux aarch64 and macOS arm64 with Rust 1.100.
§Send and receive a message
Run make relay from the repository root, then run this with the relay’s
certificate, services/relay/keys/cert.pem. It prints hello.
use moq_wasm::{CertificateVerification, ConnectOptions};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let cert = std::env::args_os().nth(1).expect("pass the relay certificate path");
let options = ConnectOptions {
certificate_verification: CertificateVerification::TrustedCertificates(cert.into()),
..Default::default()
};
let url = "moqt://127.0.0.1:4433";
let publisher = moq_wasm::connect(url, options.clone()).await?;
let subscriber = moq_wasm::connect(url, options).await?;
let namespace = ["anon", "room"];
let writer = publisher.publish_track(&namespace, "chat", Default::default()).await?;
publisher.announce(&namespace).await?;
let messages = subscriber.subscribe(&namespace, "chat", Default::default()).await?;
writer.write_group("hello".into()).await?;
let message = messages.next().await?.expect("track ended before the message");
println!("{}", std::str::from_utf8(&message.payload)?);
subscriber.close().await;
publisher.close().await;
Ok(())
}moqt:// connects over raw QUIC, https:// over WebTransport.
§Publish a broadcast
media::create_broadcast registers tracks before it publishes the
namespace, so a SUBSCRIBE the relay forwards at once finds them. A media
source takes frames you encode (H.264, H.265, VP8, VP9, AV1, AAC, Opus) and
publishes them as LOC tracks with the MSF catalog that the browser and
Python SDKs read; the SDK neither encodes nor decodes.
use moq_wasm::{Retention, media::{self, MediaSourceOptions}};
use serde_json::json;
use std::time::Duration;
let builder = media::create_broadcast(session, &["anon", "robot-1"]);
let events = builder
.event_timeline("events", Retention::For(Duration::from_secs(3600)))
.await?;
let broadcast = builder.announce().await?;
let camera = broadcast.add_media_source(MediaSourceOptions::new("camera"));
camera.configure_video("avc1.42e01f")?;
camera.push_video(access_unit, timestamp_micros)?; // Annex B; a keyframe opens a group
events.append(&json!({"T": 0, "data": "started"})).await?;
broadcast.close().await?;§Follow broadcasts
media::watch_broadcasts runs a handler for each broadcast published under
a prefix, skipping this session’s own, and aborts it when the broadcast is
withdrawn. A RemoteBroadcast reads the MSF catalog, follows a track
(subscribing again after it ends) and reads an event timeline from the
records the relay keeps.
use moq_wasm::media::{self, EventTimelineOptions, FollowOptions, TrackQuery, WatchOptions};
media::watch_broadcasts(session, &["anon", "room"], WatchOptions::default(), |remote| async move {
let mut catalogs = remote.catalogs().await?;
if let Some(catalog) = catalogs.next().await? {
let audio = catalog.select(&TrackQuery { role: Some("audio"), ..Default::default() });
println!("{:?} offers {:?}", remote.namespace(), audio.map(|track| &track.name));
}
let mut events = remote.event_timeline("events", EventTimelineOptions::default());
let mut status = remote.follow("status", FollowOptions::default());
loop {
tokio::select! {
record = events.next() => println!("event {record}"),
object = status.next() => println!("status {} bytes", object.payload.len()),
}
}
})
.await?;examples/rust/moq-broadcast
runs both sides against a relay.
§Tokens and the end of a session
A relay that verifies tokens takes a JWT in ConnectOptions::token. Give
refresh_token too, and the session asks it for a later token five minutes
before the current one expires, retrying every 30 s:
use moq_wasm::{ConnectOptions, RefreshToken, SessionEnd};
async fn later_token(current: String) -> anyhow::Result<String> {
// Ask your app server for a new token of the same app.
Ok(current)
}
let session = moq_wasm::connect(
"https://relay.example:4433",
ConnectOptions {
token: Some(jwt),
refresh_token: Some(RefreshToken::new(later_token)),
..Default::default()
},
)
.await?;
tokio::select! {
result = work(&session) => result?,
end = session.closed() => match end {
SessionEnd::ConnectionLost(close) => eprintln!("relay lost: {close}"),
SessionEnd::TokenExpired => eprintln!("token expired"),
_ => {}
},
}The session follows GOAWAY and replaces a lost connection for up to 60 s by
itself, sending its namespaces and subscriptions again. closed() resolves
when it cannot, when the token expired, or after close().
§Logs
The SDK logs through tracing and installs no
subscriber: install your own, such as tracing-subscriber.
Modules§
- media
- Broadcasts: a namespace with its tracks, MSF event timelines and media
sources of encoded frames, published and followed as the browser SDK’s
moq-wasm/mediaand the Python SDK’smoq_wasm.mediado.
Structs§
- Announcement
- A namespace
Session::announcepublished. - Connect
Options - Extension
Headers - Fetch
- The response to one Standalone FETCH (draft-14 §9.16.1).
- Group
- One subgroup stream of a subscription (draft-14 §10.4).
- Group
Start Options - How
Session::subscribe_group_startandSession::subscribe_current_groupsubscribe; their filter is Largest Object and their Forward State 1. - Location
- Namespace
Event - A namespace the peer published (
active) or withdrew (PUBLISH_NAMESPACE / PUBLISH_NAMESPACE_DONE, draft-14 §9.23, §9.26). - Namespace
Watch - The namespaces published and withdrawn under one SUBSCRIBE_NAMESPACE
prefix (draft-14 §9.28), until the session ends or
close. - Publish
Done - The PUBLISH_DONE (draft-14 §9.12) that ended a subscription.
- Publish
Track Options - How
Session::publish_trackregisters a track. - Received
Object - An object of a subscription or a FETCH response.
- Refresh
Token - Gets a later token of the same app, given the current one, typically from the application’s app server.
- Request
Error - A failed request;
codegives the draft’s error code for it. - Session
- A relay session: the requests of
moqt::client::Session, throughDeref, with its token kept fresh. It follows GOAWAY and replaces a lost connection for up to 60 s, sending its namespaces and subscriptions again; when it cannot, the session ends withSessionEnd::ConnectionLost. - Subscribe
Options - How
Session::subscribesubscribes (draft-14 §9.7). - Subscription
- One SUBSCRIBE (draft-14 §9.7). It is read either by object (
next) or by subgroup stream (next_group), whichever is called first. - Track
Follower - A track that peers publish one after another, such as the input track of a browser viewer: each publisher in turn is followed from the start of its next group, whether it announces the namespace (PUBLISH_NAMESPACE, answered with SUBSCRIBE) or publishes the track (PUBLISH). While one is followed, a PUBLISH of another is refused, and one that announced takes over once the followed one leaves.
- Track
Writer - A track
Session::publish_trackregistered with the session’sOrigin, which numbers and caches what is written and answers the track’s SUBSCRIBE, FETCH and TRACK_STATUS. - Transferred
Bytes - Bytes a session carried over all its connections, the closed ones
included; unlike
TransportStats, it keeps counting across a migration. - Transport
Close - How the transport ended:
codeis the peer’s termination code when the connection was closed by the application layer (draft-14 §3.4),Nonefor transport-level failures.
Enums§
- Certificate
Verification Endpoint::create_clientfails onBROWSERfor every variant butNativeRoots.- Fetch
Error - A FETCH that did not succeed: the peer did not accept it (
Request), or its response stream did not arrive (Stream), as when the session ends first. - Filter
Type - Follow
Event - Group
Order - Object
Status - Request
Error Code - Why a request was rejected (draft-ietf-moq-transport-14 §13.1.2 and §13.1.4–§13.1.7).
- Request
Failure - The session stays open after
RejectedandTimeout(draft-14 §12.2). - Request
Kind - The request a
RequestErrorCodeis sent or received for; draft-14 numbers the codes per*_ERRORmessage. - Retention
- Session
End - Version
- A MoQT draft a session can speak; the one both ends offer is chosen when the session is established.
Functions§
- connect
- Connects to
url:moqt://over raw QUIC,https://over WebTransport. Fails when the relay cannot be reached or refuses the session, whenrefresh_tokenis given withouttoken, or whentokenis no JWT with anappIdclaim.