Crate reactor_webrtc

Expand description

reactor-webrtc — a safe, idiomatic Rust API over an owned build of Google’s WebRTC engine (see the reactor-webrtc-sys crate and ../../webrtc-build).

§Shape

PeerConnectionFactory → PeerConnection (with a closure-based PeerConnectionObserver) → SDP offer/answer, ICE, Tracks (audio + video send/receive) and DataChannels. RAII throughout: dropping a handle releases the native object.

ICE credentials are libwebrtc’s to generate, and it exposes no setter. When an application needs to choose its ufrag — so that a fronting layer can route on it — SessionDescription::with_ice_credentials substitutes them in the description before it is set locally, which is where libwebrtc reads the transport’s ICE parameters from.

Per-frame metadata (metadata) rides in a trailer appended to the encoded payload, which only works if the peer strips it again. That is negotiated for you: every PeerConnection::create_offer advertises the capability as a session-level a=x-reactor-frame-metadata, PeerConnection::create_answer mirrors an offer that asked for it, and PeerConnection::set_remote_description arms a FrameMetadataGate from what the remote declared, and installs the metadata steps on the video transceivers. Callers pass user_data when it is meaningful and never have to ask what the far end supports — a trailer reaches the wire only when the peer said it strips them. Set RtcConfiguration::frame_metadata to false to keep the whole thing out of a connection.

A FrameTransform of your own composes with that rather than displacing it: the crate owns libwebrtc’s single transformer slot per sender/receiver and runs both, so encoded-frame access and per-frame metadata work on one transceiver.

Building a real binary or test requires a native libwebrtc; set REACTOR_WEBRTC_LIB_DIR or REACTOR_WEBRTC_PREBUILT_URL. cargo check works without one.

Re-exports§

pub use metadata::FrameMetadata;
pub use metadata::FrameMetadataGate;
pub use metadata::FRAME_METADATA_ATTRIBUTE;
pub use metadata::FRAME_METADATA_VERSION;

Modules§

metadata: Frame metadata — protobuf-encoded trailer appended to encoded video payloads.
platform: Platform bootstrap. On Android, libwebrtc needs the JavaVM (and, for the platform ADM, the application Context) before a peer connection is built.

Structs§

ApmConfig: Audio Processing Module configuration passed to PeerConnectionFactory.
AudioFrame: A chunk of decoded audio, borrowed for the duration of the callback: interleaved signed 16-bit PCM (frames * channels samples).
AudioTrack: An audio Track — local or remote. on_frame receives decoded PCM; push_frame family feeds a local AudioTrackSource::LocalPush track (Err on a remote track; no-op semantics on ADM-backed locals match the native ADM).
AudioTrackOptions: Options for [PeerConnectionFactory::create_audio_track_with_options].
ChunkingStats: Running totals of a chunked channel’s messages, since it opened.
DataChannel: A data channel — either locally created or handed to on_data_channel by the remote peer. Dropping releases the native handle.
DataChannelStats: One data channel’s counters (RTCDataChannelStats).
DcChunking: Settings for chunked data channels, set on a factory with PeerConnectionFactoryBuilder::with_dc_chunking.
DcChunkingParams: What a peer declares in a=x-reactor-dc-chunking (see SessionDescription::with_dc_chunking). What one side declares.
EncodedFrame: A borrowed encoded media frame. data and mime_type are valid only for the duration of the callback — copy them to retain.
EncodedVideoFrame: An encoded video frame, produced by an inline encoder callback or pushed to an EncodedVideoTrack.
EncodedVideoTrack: A video track that accepts pre-encoded frames directly, bypassing the libwebrtc software encoder pipeline entirely.
FrameTransform: A callback over encoded frames, to be attached to a transceiver’s sender/receiver; see the module docs.
IceCandidate: A trickled ICE candidate.
IceCandidatePairStats: RTCIceCandidatePairStats subset.
IceServer: A single ICE (STUN/TURN) server.
InboundRtpStats: RTCInboundRtpStreamStats subset.
OutboundRtpStats: RTCOutboundRtpStreamStats subset.
PeerConnection: An RTCPeerConnection.
PeerConnectionFactory: Entry point: creates peer connections and tracks, and owns the audio device module (synthetic by default, or the platform device). Construct it with PeerConnectionFactory::builder.
PeerConnectionFactoryBuilder: Builds a PeerConnectionFactory knob by knob — the single entry point that replaced the old mutually-exclusive constructors (they could not compose: custom encode used to force the synthetic ADM, OpenH264 could not share a factory with a custom encoder, and so on).
PeerConnectionObserver: Builder for the closures invoked over a peer connection’s lifetime. Unset callbacks are simply not delivered.
PlayoutDelay: Bounds on how long a video receiver holds a frame before rendering it — the playout-delay RTP header extension (http://www.webrtc.org/experiments/rtp-hdrext/playout-delay).
PreEncodedOptions: Geometry for a pre-encoded video track (TrackVideoEncoder::PreEncoded).
RawVideoFrame: Raw I420 video frame delivered to an inline encoder callback (TrackVideoEncoder::Inline).
RtcConfiguration: Configuration passed to crate::PeerConnectionFactory::create_peer_connection.
SctpStats: The SCTP association that carries a connection’s data channels, as dcsctp tracks it.
SessionDescription: A session description (offer/answer).
StatsReport: A snapshot of the stats delivered by PeerConnection::get_stats.
TimingFrameInfo: One frame libwebrtc stamped at each stage of its trip, as reported by the receiver (goog_timing_frame_info).
TimingFrameReceiverTimestamps: The timestamps the receiver (this side) took for a TimingFrameInfo.
TimingFrameSenderTimestamps: The timestamps the sender took for a TimingFrameInfo.
Track: A media track (local or remote). Dropping it detaches any sink and releases the native track.
Transceiver: A transceiver: one bidirectional media “slot” in the peer connection. Its mid (available after set_local_description) maps it to an SDP m-section.
VideoFrame: A decoded video frame, borrowed for the duration of the callback. The buffer is BGRA (width*height*4, B-G-R-A); copy it if you need to keep it.
VideoSinkTimings: How long a remote video track’s sink took to hand its decoded frames on, added up since the sink was attached (VideoTrack::sink_timings).
VideoTrack: A video Track — local (raw) or remote. on_frame receives decoded video; push_frame family feeds a local track (Err on a remote track).
VideoTrackOptions: Options for [PeerConnectionFactory::create_video_track_with_options].

Enums§

AdmMode: Which audio device module a PeerConnectionFactory uses.
AudioTrackSource: Where an audio track’s samples come from (create_audio_track_with_options).
BundlePolicy: How m-sections are bundled onto a single transport.
ContinualGatheringPolicy: When ICE candidates are gathered.
DataChannelState: Data channel readiness state.
DcSendError: Why a chunked data channel refused a message (Error::DataChannel). Why push refused a message. Nothing of it was queued.
EncoderFeedback: Feedback from the BWE / rate-control machinery for a custom-encoded (TrackVideoEncoder) track’s encoder instance. The builtin encoder pipeline consumes the same signals internally; custom encoders hear them here through [VideoTrack::on_encoder_feedback] / EncodedVideoTrack::on_encoder_feedback.
Error: Errors surfaced by the WebRTC engine.
FrameAction: What to do with a frame after the callback returns.
FrameDirection: Which side of the pipeline an EncodedFrame came from.
H264Backend: Which H.264 backend a raw video track encodes with.
IceCandidatePairState: State of an ICE candidate pair (RTCIceCandidatePairStats::state).
IceCandidateType: Type of an ICE candidate (RTCIceCandidateStats::candidate_type).
IceGatheringState: ICE gathering state (delivered to PeerConnectionObserver::on_ice_gathering_change).
IceTransportsType: Which ICE candidate types are allowed.
LocalVideoTrack: One video track created by [PeerConnectionFactory::create_video_track_with_options].
MediaKind: Audio vs. video.
PeerConnectionState: Aggregate connection state.
RelayProtocol: Transport a relayed candidate uses to reach its TURN server (RTCIceCandidateStats::relay_protocol).
RemoteTrack: A track delivered by [PeerConnectionObserver::on_track] — media-typed, so RemoteTrack::Video(v).on_frame(...) and RemoteTrack::Audio(a) .on_frame(...) each take the matching frame type and nothing else.
SdpType: SDP description kind.
StreamKind: Media kind of an RTP stream (RTCRtpStreamStats::kind).
TcpCandidatePolicy: Whether libwebrtc may gather TCP ICE candidates.
TrackVideoEncoder: How a video track produces its encoded bitstream, replacing libwebrtc’s builtin encoder for that track only.
TransceiverDirection: Direction of a transceiver / track.
VideoCodec: Which video codec was negotiated for the session.

Functions§

native_abi_version: The ABI version of the linked native build. Used to assert that the safe crate and the prebuilt libwebrtc agree.
time_micros: The engine’s monotonic clock, in microseconds.

Type Aliases§

InlineEncoderCallback: The boxed encoder callback a TrackVideoEncoder::Inline track hands the factory — called synchronously with every raw I420 frame on the encoder thread; return Some(encoded) to forward, None to drop.
Result