pub struct Media<'a> { /* private fields */ }
Expand description
Audio or video media. An m-line in the SDP.
Instances of Media
are obtained via Rtc::media()
. The instance
only exists for m-lines that have passed the offer/answer SDP negotiation.
This is mainly a handle to send outgoing media, but also contains information about the media.
let mut rtc = Rtc::new();
// add candidates, do SDP negotation
let mid: Mid = todo!(); // obtain mid from Event::MediaAdded.
let media = rtc.media(mid).unwrap();
Implementations§
source§impl Media<'_>
impl Media<'_>
sourcepub fn index(&self) -> usize
pub fn index(&self) -> usize
The index of the line in the SDP. Once negotiated this cannot change.
sourcepub fn direction(&self) -> Direction
pub fn direction(&self) -> Direction
Current direction. This can be changed using
ChangeSet::set_direction()
followed by an SDP negotiation.
To test whether it’s possible to send media with the current direction, use
let media: Media = todo!(); // Get hold of media row.
if media.direction().is_sending() {
// media.write(...);
}
sourcepub fn payload_params(&self) -> &[PayloadParams]
pub fn payload_params(&self) -> &[PayloadParams]
The negotiated payload parameters for this m-line.
sourcepub fn match_params(&self, params: PayloadParams) -> Option<Pt>
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
/m-line.
This call performs matching and if a match is found, returns the local PT that can be used for sending media.
sourcepub fn writer(&mut self, pt: Pt, now: Instant) -> Writer<'_>
pub fn writer(&mut self, pt: Pt, now: Instant) -> Writer<'_>
Send outgoing media data via this m-line.
The pt
is the payload type for sending and must match the codec of the media data.
This is typically done using Media::match_params()
to compare an incoming set of
parameters with the configured ones in this Media
instance. It’s also possible to
manually match the codec using Media::payload_params()
.
The now
parameter is required to know the exact time the data is enqueued. This has a
side effect of driving the time of the Rtc
instance forward. I.e. passing the now
here
is the same driving time forward with handle_input()
.
rid
is Rtp Stream Identifier. In classic RTP, individual RTP packets are identified
via an RTP header value SSRC
(Synchronization Source). However it’s been proposed to send
the RID in a header extension as an alternative way, making SSRC less important. Currently
this is only used in Chrome when doing Simulcast.
This operation fails if the current Media::direction()
does not allow sending, the
PT doesn’t match a negotiated codec, or the RID (None
or a value) does not match
anything negotiated.
let mut rtc = Rtc::new();
// add candidates, do SDP negotation
let mid: Mid = todo!(); // obtain mid from Event::MediaAdded.
let media = rtc.media(mid).unwrap();
// Get incoming media data from another peer
let data: MediaData = todo!();
// Match incoming PT to an outgoing PT.
let pt = media.match_params(data.params).unwrap();
media.writer(pt, Instant::now()).write(data.network_time, data.time, &data.data).unwrap();
sourcepub fn is_request_keyframe_possible(&self, kind: KeyframeRequestKind) -> bool
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
sourcepub fn request_keyframe(
&mut self,
rid: Option<Rid>,
kind: KeyframeRequestKind
) -> Result<(), RtcError>
pub fn request_keyframe(
&mut self,
rid: Option<Rid>,
kind: KeyframeRequestKind
) -> Result<(), RtcError>
Request a keyframe from a remote peer sending media data.
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 Media::is_request_keyframe_possible()
to
check whether the feedback mechanism is enabled.
Example
let mut rtc = Rtc::new();
// add candidates, do SDP negotation
let mid: Mid = todo!(); // obtain mid from Event::MediaAdded.
let media = rtc.media(mid).unwrap();
media.request_keyframe(None, KeyframeRequestKind::Pli).unwrap();