streamplace
Star
Fork
Watch
streamplace docs moq.md
10 kB · 164 lines
Markdown
at opus55/obs-plugin

Media over QUIC #

Streamplace nodes hand live streams to each other over Media over QUIC, using the official implementation: moq.dev/moq, the Go wrapper over the Rust moq-ffi that Meson builds from source into the node (see rust/streamplace-native). pkg/moq holds only what Streamplace adds, the listener's certificate handling. The listener and both directions of transfer live in the websocketrep replicator (pkg/replication/websocketrep/moq.go). A node pulls a stream from its origin, preferring the origin's MoQ URL over its websocket when one is advertised, and pushes its own streams to the nodes named in --peers.

Wire convention #

Every byte a broadcast carries is signed MUXL, laid out the way the rest of the MoQ ecosystem reads media: a hang catalog and one CMAF track per media track. The MoQ tools (moq export, moq play) and the @moq/watch player can play a Streamplace broadcast, and a Streamplace node reassembles the exact signed segments and verifies them as before.

MoQ Streamplace
broadcast path the streamer's DID (did:plc:...)
catalog.json, catalog.json.z, catalog the hang and MSF catalogs, one CMAF rendition per track
track one MUXL track, named by its MUXL rendition (video1, audio2, audio3; renditions video100 up)
group that track's canonical segment for one GoP
frame one moof+mdat, the first also carrying the segment's leading uuid boxes (C2PA manifest, MUXL catalog)
timestamp the fragment's first presentation time, on the track's timescale

A group's frames concatenate back to the track's canonical segment, byte for byte. Each catalog rendition's CMAF init is the track's own init segment, synthesized from its MUXL catalog (muxl wrap --init-only); the hang codec fields are derived from that init by moq-mux. The catalog is unsigned: a node uses it only to find the tracks, and verifies the bytes.

The source segment's tracks (MUXL track ids below media.RenditionTrackID(0)) share one group sequence per segment. A subscriber reads each in sequence order, concatenates one segment's groups in track-id order, and validates the result with MediaManager.ValidateReplicatedMP4: the websocket path's validation, plus a check that the segment's signed creator is the streamer it asked for. A source track with no group at a segment's sequence has no part in that segment. Each rendition track's group is a single-track addendum, verified with muxl verify and folded into the live window on its own. Anything that is not MUXL ends the session.

A node's listener advertises one route covering every path and serves a broadcast when a peer requests it: a request for a stream that is not live on its segment bus is refused, and a served broadcast ends with the stream's session, or when a track's codec config changes (its MUXL catalog box differs), since the catalog entry describes the old one; the next request starts afresh. The transport shares one served broadcast among all its subscribers. A track is published the first time a segment carries it, and a new subscriber starts from the newest segment, like place.stream.live.subscribeSegments's priming. The source tracks have the higher subscriber priority, and a subscriber that falls behind skips ahead.

To watch or dump a broadcast with the MoQ CLI (pin a self-signed node's certificate with the certhash from its MoQ URL):

moq --connect moqt://host:38443 --connect-tls-fingerprint <certhash> \
    --broadcast did:plc:... export fmp4 > stream.mp4

Bindings #

One UDP port serves raw QUIC (moqt://host:port) and WebTransport, which is the binding a browser uses. The transport negotiates the protocol version by ALPN.

Configuration #

Flag Env Default Meaning
--moq-addr SP_MOQ_ADDR :38443 UDP listen address; empty disables the listener.
--moq-url SP_MOQ_URL Override for the advertised moqt:// URL (default: --server-host on --moq-addr's port).
--peers SP_PEERS Nodes to push this node's live streams to: each an https:// node origin or a moqt:// URL, comma-separated.

The listener terminates TLS itself, even on a node behind an HTTPS proxy, reading its certificate from files (the data directory's moq-tls) that Go keeps current:

  • with --secure, it serves the node's certificate (ACME, rewritten as it renews, or --tls-cert/--tls-key as given);
  • otherwise it mints a self-signed ECDSA certificate, valid for two weeks and rotated weekly (the limits a browser puts on a pinned certificate), and advertises its SHA-256 as the certhash query parameter of the MoQ URL. A subscriber pins exactly that certificate.

Discovery #

The advertised URL travels two ways, like the websocket URL:

  • the moqURL field of the streamer's place.stream.broadcast.origin record on the firehose;
  • the moq_url column of the station's shared broadcast_origins table, written by the ingest node on every local segment, so nodes sharing a statedb find each other without a relay.

Push #

A node that cannot be reached, one beside a streamer's encoder behind NAT, pushes instead of waiting to be pulled from. For each --peers entry it keeps one session open for as long as it runs, publishing the streams it is ingesting: each is announced, one broadcast per streamer DID, once its first published segment's tracks are in the catalog, until the stream session times out, its tracks served from the bus exactly as the listener serves them. The peer gives every incoming session its own origin, so a pushed announcement never becomes a route it serves; it pulls each announced stream's source tracks from that session and validates them exactly as it would a pull, and ignores announcements past 32 streams or that are not DIDs. It takes no renditions from a pusher, whose signer could be anyone: as the stream's origin it mints its own. A pushed stream is a replicated stream on the peer (Local: false); while it flows the peer writes itself into the station's broadcast_origins table for it, so the nodes sharing its statedb pull the stream from the peer. The pusher hands its streams' origin duties to its peers: it writes no broadcast_origins row of its own and does not contend for transcoding (below), so a pusher on the same statedb as its peer, out of the other nodes' reach, is never chosen over it.

An https:// peer is asked for its current MoQ URL on every dial, through place.stream.broadcast.getBroadcaster's moqURL: a node behind an HTTPS proxy serves MoQ with a self-signed certificate it rotates, so a fixed moqt://…?certhash= entry would go stale. A moqt:// entry is dialled as given. A listener accepts any pushed stream its --allowed-streams would accept over RTMP; a frame that fails validation ends the session. Validation refuses a replicated segment whose start time is more than ten minutes from the node's clock, so a pusher cannot replay a public streamer's old signed segments to make them appear live (the same window applies to every replicated segment, /api/segment included).

Who records, multistreams and transcodes #

Recording a stream to S3, driving its multistream targets and transcoding its renditions must each happen on exactly one node, however many carry the stream. The nodes that can do a job contend for it through a lease in the station's shared statedb (leases; pkg/director/roles.go). The holder renews the lease every 2 seconds; a node that dies stops, and the next contender takes the job over once the 6 second TTL has lapsed. A node that ends a session cleanly releases its leases, so a peer takes over at once. A node that wins a job but cannot take it up (a failed lookup before recording) releases the lease at once and asks again after 10 seconds; one that will not do it for this stream (the streamer turned recording off) releases it and stops asking. A node on its own statedb simply holds every lease.

Any node with a session for a stream contends for its multistream targets. Recording (S3 configured) and transcoding (a Livepeer gateway) are contended for only by a node that is an origin for the stream, one that ingests it without pushing it to --peers or that a peer pushes it to: both want the stream at its live edge. Peers take a stream's renditions from its origin, so renditions minted anywhere else would reach nobody but that node's own viewers; and a pull replica, seconds behind, that took the recording over would record again segments its predecessor had saved. A recorder completes its current object when the stream stops being published, so the recording can be finalized at once: an ingest node on its first unpublished segment, a push receiver, which is pushed no unpublished segments, on seeing the streamer's livestream record end.

A pusher whose --peers names two nodes of one station gives that station two origins, of which one transcodes. The other gets the renditions only by pulling the stream from it, so such a station needs --syndicate.