str0m

A Sans I/O WebRTC implementation in Rust.

This is a Sans I/O implementation meaning the Rtc instance itself is not doing any network talking. Furthermore it has no internal threads or async tasks. All operations are happening from the calls of the public API.

This is deliberately not a standard RTCPeerConnection API since that isn't a great fit for Rust. See more details in below section.

Join us

We are discussing str0m things on Discord. Join us using this invitation link.

Usage

The chat example shows how to connect multiple browsers together and act as an SFU (Selective Forwarding Unit). The example multiplexes all traffic over one server UDP socket and uses two threads (one for the web server, and one for the SFU loop).

TLS

For the browser to do WebRTC, all traffic must be under TLS. The project ships with a self-signed certificate that is used for the examples. The certificate is for hostname str0m.test since TLD .test should never resolve to a real DNS name.

cargo run --example chat

The log should prompt you to connect a browser to https://10.0.0.103:3000 – this will most likely cause a security warning that you must get the browser to accept.

The http-post example roughly illustrates how to receive media data from a browser client. The example is single threaded and is a bit simpler than the chat. It is a good starting point to understand the API.

cargo run --example http-post

Real example

To see how str0m is used in a real project, check out BitWHIP – a CLI WebRTC Agent written in Rust.

Passive

For passive connections, i.e. where the media and initial OFFER is made by a remote peer, we need these steps to open the connection.

// Instantiate a new Rtc instance.
let mut rtc = Rtc::new(Instant::now());

//  Add some ICE candidate such as a locally bound UDP port.
let addr = "1.2.3.4:5000".parse().unwrap();
let candidate = Candidate::host(addr, "udp").unwrap();
rtc.add_local_candidate(candidate);

// Accept an incoming offer from the remote peer
// and get the corresponding answer.
let offer = todo!();
let answer = rtc.sdp_api().accept_offer(offer).unwrap();

// Forward the answer to the remote peer.

// Go to _run loop_

Active

Active connections means we are making the inital OFFER and waiting for a remote ANSWER to start the connection.

// Instantiate a new Rtc instance.
let mut rtc = Rtc::new(Instant::now());

// Add some ICE candidate such as a locally bound UDP port.
let addr = "1.2.3.4:5000".parse().unwrap();
let candidate = Candidate::host(addr, "udp").unwrap();
rtc.add_local_candidate(candidate);

// Create a `SdpApi`. The change lets us make multiple changes
// before sending the offer.
let mut change = rtc.sdp_api();

// Do some change. A valid OFFER needs at least one "m-line" (media).
let mid = change.add_media(MediaKind::Audio, Direction::SendRecv, None, None, None);

// Get the offer.
let (offer, pending) = change.apply().unwrap();

// Forward the offer to the remote peer and await the answer.
// How to transfer this is outside the scope for this library.
let answer = todo!();

// Apply answer.
rtc.sdp_api().accept_answer(pending, answer).unwrap();

// Go to _run loop_

Run loop

The single-mutation invariant

str0m's API has one strict contract that the run loop is built around:

Every mutation of an Rtc instance must be followed by a complete drain of poll_output until it returns Output::Timeout, before the next mutation on the same Rtc.

A "mutation" is anything that takes &mut Rtc (directly or through a handle obtained from it). The common ones are:

• Rtc::handle_input — feeding a network packet or a timeout
• Writer::write / Writer::request_keyframe — sending media
• Channel::write — sending data channel data
• SdpApi::apply / DirectApi::* — negotiation
• Rtc::add_local_candidate / Rtc::add_remote_candidate

Always: mutate → drain to Timeout → mutate → drain to Timeout → …

Doing two mutations back-to-back without draining in between, or waiting on I/O while the engine still has output queued, leaves the engine in an inconsistent state and produces wrong behavior. Mutations issued from inside the drain loop (e.g. calling Writer::write in response to an Output::Event) are fine — the drain loop naturally continues calling poll_output afterward and so the invariant holds.

Canonical shape

Driving an Rtc forward follows the same six-step shape, regardless of sync or async:

1. Wait for one of: the next timeout firing, an incoming network packet, or the application wanting to perform a mutation (e.g. write media).
2. Perform that ONE mutation — feed Input to handle_input, or call into a writer / channel / SDP API.
3. Poll Rtc::poll_output.
4. Handle the output: Output::Transmit is sent on the socket, Output::Event is dispatched to the application, Output::Timeout records the next deadline.
5. Goto 3 until poll_output returns Output::Timeout. Only then is the engine fully drained.
6. The returned timeout is what we wait on next — goto 1.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗