Skip to main content

Crate moq_wasm

Crate moq_wasm 

Source
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/media and the Python SDK’s moq_wasm.media do.

Structs§

Announcement
A namespace Session::announce published.
ConnectOptions
ExtensionHeaders
Fetch
The response to one Standalone FETCH (draft-14 §9.16.1).
Group
One subgroup stream of a subscription (draft-14 §10.4).
GroupStartOptions
How Session::subscribe_group_start and Session::subscribe_current_group subscribe; their filter is Largest Object and their Forward State 1.
Location
NamespaceEvent
A namespace the peer published (active) or withdrew (PUBLISH_NAMESPACE / PUBLISH_NAMESPACE_DONE, draft-14 §9.23, §9.26).
NamespaceWatch
The namespaces published and withdrawn under one SUBSCRIBE_NAMESPACE prefix (draft-14 §9.28), until the session ends or close.
PublishDone
The PUBLISH_DONE (draft-14 §9.12) that ended a subscription.
PublishTrackOptions
How Session::publish_track registers a track.
ReceivedObject
An object of a subscription or a FETCH response.
RefreshToken
Gets a later token of the same app, given the current one, typically from the application’s app server.
RequestError
A failed request; code gives the draft’s error code for it.
Session
A relay session: the requests of moqt::client::Session, through Deref, 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 with SessionEnd::ConnectionLost.
SubscribeOptions
How Session::subscribe subscribes (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.
TrackFollower
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.
TrackWriter
A track Session::publish_track registered with the session’s Origin, which numbers and caches what is written and answers the track’s SUBSCRIBE, FETCH and TRACK_STATUS.
TransferredBytes
Bytes a session carried over all its connections, the closed ones included; unlike TransportStats, it keeps counting across a migration.
TransportClose
How the transport ended: code is the peer’s termination code when the connection was closed by the application layer (draft-14 §3.4), None for transport-level failures.

Enums§

CertificateVerification
Endpoint::create_client fails on BROWSER for every variant but NativeRoots.
FetchError
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.
FilterType
FollowEvent
GroupOrder
ObjectStatus
RequestErrorCode
Why a request was rejected (draft-ietf-moq-transport-14 §13.1.2 and §13.1.4–§13.1.7).
RequestFailure
The session stays open after Rejected and Timeout (draft-14 §12.2).
RequestKind
The request a RequestErrorCode is sent or received for; draft-14 numbers the codes per *_ERROR message.
Retention
SessionEnd
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, when refresh_token is given without token, or when token is no JWT with an appId claim.