Struct Writer

pub struct Writer<'a> { /* private fields */ }

Writer of sample level data.

Obtained via Rtc::writer.

This is the Sample Level API. For RTP level see DirectApi::stream_tx.

Implementations

impl<'a> Writer<'a>

pub fn payload_params(&self) -> impl Iterator<Item = &PayloadParams>

Get the configured payload parameters for the mid this writer is for.

For the Writer::write() call, the pt must be set correctly.

pub fn match_params(&self, params: PayloadParams) -> Option<Pt>

Match the given parameters to the configured parameters for this Media.

In a server scenario, a certain codec configuration might not have the same payload type (PT) for two different peers. We will have incoming data with one PT and need to match that against the PT of the outgoing Media.

This call performs matching and if a match is found, returns the local PT that can be used for sending media.

pub fn rid(self, rid: Rid) -> Self

Add on an Rtp Stream Id. This is typically used to separate simulcast layers.

pub fn audio_level(self, audio_level: i8, voice_activity: bool) -> Self

Add on audio level and voice activity. These values are communicated in the same RTP header extension, hence it makes sense setting both at the same time.

Audio level is measured in negative decibel. 0 is max and a “normal” value might be -30.

pub fn video_orientation(self, o: VideoOrientation) -> Self

Add video orientation. This can be used by a player on the receiver end to decide whether the video requires to be rotated to show correctly.

pub fn user_extension_value<T: Send + Sync + 'static>(self, val: T) -> Self

Set a user extension value.

pub fn write( self, pt: Pt, wallclock: Instant, rtp_time: MediaTime, data: impl Into<Vec<u8>>, ) -> Result<(), RtcError>

Write media.

This operation fails if the PT doesn’t match a negotiated codec, or the RID (None or a value) does not match anything negotiated.

Regarding wallclock and rtp_time, the wallclock is the real world time that corresponds to the MediaTime. For an SFU, this can be hard to know, since RTP packets typically only contain the media time (RTP time). In the simplest SFU setup, the wallclock could simply be the arrival time of the incoming RTP data (see MediaData::network_time). For better synchronization the SFU probably needs to weigh in clock drifts and data provided via the statistics.

If you write media before IceConnectionState is Connected it will be dropped.

Panics if RtcConfig::set_rtp_mode() is true.

pub fn is_request_keyframe_possible(&self, kind: KeyframeRequestKind) -> bool

Test if the kind of keyframe request is possible.

Sending a keyframe request requires the mechanic to be negotiated as a feedback mechanic in the SDP offer/answer dance first.

Specifically these SDP lines would enable FIR and PLI respectively (for payload type 96).

a=rtcp-fb:96 ccm fir
a=rtcp-fb:96 nack pli

pub fn request_keyframe( &mut self, rid: Option<Rid>, kind: KeyframeRequestKind, ) -> Result<(), RtcError>

Request a keyframe from a remote peer sending media data.

For SDP: This can fail if the kind of request (PLI or FIR), as specified by the KeyframeRequestKind, is not negotiated in the SDP answer/offer for this m-line.

To ensure the call will not fail, use Writer::is_request_keyframe_possible() to check whether the feedback mechanism is enabled.

Example

let mut rtc = Rtc::new();

// add candidates, do SDP negotiation
let mid: Mid = todo!(); // obtain mid from Event::MediaAdded.

let writer = rtc.writer(mid).unwrap();

writer.request_keyframe(None, KeyframeRequestKind::Pli).unwrap();