Struct RtcConfig

pub struct RtcConfig { /* private fields */ }

Customized config for creating an Rtc instance.

use str0m::RtcConfig;

let rtc = RtcConfig::new()
    .set_ice_lite(true)
    .build();

Configs implement Clone to help create multiple Rtc instances.

Implementations

impl RtcConfig

pub fn new() -> Self

Creates a new default config.

pub fn local_ice_credentials(&self) -> &Option<IceCreds>

Get the local ICE credentials, if set.

If not specified, local credentials will be randomly generated when building the Rtc instance.

pub fn set_local_ice_credentials(self, local_ice_credentials: IceCreds) -> Self

Explicitly sets local ICE credentials.

pub fn dtls_cert(&self) -> Option<&DtlsCert>

Get the configured DTLS certificate, if set.

Returns None if no DTLS certificate is set. In such cases, the certificate will be created on build and you can use the direct API on an Rtc instance to obtain the local DTLS fingerprint.

let fingerprint = RtcConfig::default()
    .build()
    .direct_api()
    .local_dtls_fingerprint();

pub fn set_dtls_cert(self, dtls_cert: DtlsCert) -> Self

Set the DTLS certificate for secure communication.

Generating a certificate can be a time-consuming process. Use this API to reuse a previously created DtlsCert if available.

let dtls_cert = DtlsCert::new_openssl();

let rtc_config = RtcConfig::default()
    .set_dtls_cert(dtls_cert);

pub fn set_ice_lite(self, enabled: bool) -> Self

Toggle ice lite. Ice lite is a mode for WebRTC servers with public IP address. An Rtc instance in ice lite mode will not make STUN binding requests, but only answer to requests from the remote peer.

See ICE RFC

pub fn fingerprint_verification(&self) -> bool

Get fingerprint verification mode.

let config = Rtc::builder();

// Defaults to true.
assert!(config.fingerprint_verification());

pub fn set_fingerprint_verification(self, enabled: bool) -> Self

Toggle certificate fingerprint verification.

By default the certificate fingerprint is verified.

pub fn ice_lite(&self) -> bool

Tells whether ice lite is enabled.

let config = Rtc::builder();

// Defaults to false.
assert_eq!(config.ice_lite(), false);

pub fn codec_config(&mut self) -> &mut CodecConfig

Lower level access to precise configuration of codecs (payload types).

pub fn clear_codecs(self) -> Self

Clear all configured codecs.

// For the session to use only OPUS and VP8.
let mut rtc = RtcConfig::default()
    .clear_codecs()
    .enable_opus(true)
    .enable_vp8(true)
    .build();

pub fn enable_opus(self, enabled: bool) -> Self

Enable opus audio codec.

Enabled by default.

pub fn enable_vp8(self, enabled: bool) -> Self

Enable VP8 video codec.

Enabled by default.

pub fn enable_h264(self, enabled: bool) -> Self

Enable H264 video codec.

Enabled by default.

pub fn enable_vp9(self, enabled: bool) -> Self

Enable VP9 video codec.

Enabled by default.

pub fn extension_map(&mut self) -> &mut ExtensionMap

Configure the RTP extension mappings.

The default extension map is

let exts = ExtensionMap::standard();

assert_eq!(exts.id_of(Extension::AudioLevel), Some(1));
assert_eq!(exts.id_of(Extension::AbsoluteSendTime), Some(2));
assert_eq!(exts.id_of(Extension::TransportSequenceNumber), Some(3));
assert_eq!(exts.id_of(Extension::RtpMid), Some(4));
assert_eq!(exts.id_of(Extension::RtpStreamId), Some(10));
assert_eq!(exts.id_of(Extension::RepairedRtpStreamId), Some(11));
assert_eq!(exts.id_of(Extension::VideoOrientation), Some(13));

pub fn set_extension_map(self, exts: ExtensionMap) -> Self

Set the extension map replacing the existing.

pub fn clear_extension_map(self) -> Self

Clear out the standard extension mappings.

pub fn set_extension(self, id: u8, ext: Extension) -> Self

Set an extension mapping on session level.

The media level will be capped by the extension enabled on session level.

The id must be 1-14 inclusive (1-indexed).

pub fn set_stats_interval(self, interval: Option<Duration>) -> Self

Set the interval between statistics events.

None turns off the stats events.

This includes MediaEgressStats, MediaIngressStats, MediaEgressStats

pub fn stats_interval(&self) -> Option<Duration>

The configured statistics interval.

None means statistics are disabled.

let config = Rtc::builder();

// Defaults to None.
assert_eq!(config.stats_interval(), None);

pub fn enable_bwe(self, initial_estimate: Option<Bitrate>) -> Self

Enables estimation of available bandwidth (BWE).

None disables the BWE. This is an estimation of the send bandwidth, not receive.

This includes setting the initial estimate to start with.

pub fn enable_experimental_loss_based_bwe(self, enabled: bool) -> Self

Enable the experimental loss based BWE subsystem. Defaults to disabled for now, will be enabled by default in the future.

pub fn bwe_initial_bitrate(&self) -> Option<Bitrate>

The initial bitrate as set by Self::enable_bwe().

let config = Rtc::builder();

// Defaults to None - BWE off.
assert_eq!(config.bwe_initial_bitrate(), None);

pub fn set_reordering_size_audio(self, size: usize) -> Self

Sets the number of packets held back for reordering audio packets.

Str0m tries to deliver the samples in order. This number determines how many packets to “wait” before releasing media contiguous: false.

This setting is ignored in RTP mode where RTP packets can arrive out of order.

pub fn reordering_size_audio(&self) -> usize

Returns the setting for audio reordering size.

let config = Rtc::builder();

// Defaults to 15.
assert_eq!(config.reordering_size_audio(), 15);

This setting is ignored in RTP mode where RTP packets can arrive out of order.

pub fn set_reordering_size_video(self, size: usize) -> Self

Sets the number of packets held back for reordering video packets.

Str0m tries to deliver the samples in order. This number determines how many packets to “wait” before releasing media with gaps.

This must be at least as big as the number of packets the biggest keyframe can be split over.

WARNING: video is very different to audio. Setting this value too low will result in missing video data. The 0 (as described for audio) is not relevant for video.

Default: 30

This setting is ignored in RTP mode where RTP packets can arrive out of order.

pub fn reordering_size_video(&self) -> usize

Returns the setting for video reordering size.

let config = Rtc::builder();

// Defaults to 30.
assert_eq!(config.reordering_size_video(), 30);

This setting is ignored in RTP mode where RTP packets can arrive out of order.

pub fn set_send_buffer_audio(self, size: usize) -> Self

Sets the buffer size for outgoing audio packets.

This must be larger than 0. The value configures an internal ring buffer used as a temporary holding space between calling Writer::write and Rtc::poll_output.

For audio one call to write() typically results in one RTP packet since the entire payload fits in one. If you can guarantee that every write() is a single RTP packet, and is always followed by a poll_output(), it might be possible to set this value to 1. But that would give no margins for unexpected patterns.

panics if set to 0.

pub fn send_buffer_audio(&self) -> usize

Returns the setting for audio resend size.

let config = Rtc::builder();

// Defaults to 50.
assert_eq!(config.send_buffer_audio(), 50);

pub fn set_send_buffer_video(self, size: usize) -> Self

Sets the buffer size for outgoing video packets and resends.

This must be larger than 0. The value configures an internal ring buffer that is both used as a temporary holding space between calling Writer::write and Rtc::poll_output as well as for fulfilling resends.

For video, this buffer is used for more than for audio. First, a call to write() often results in multiple RTP packets since large frames don’t fit in one payload. That means the buffer must be at least as large to hold all those packets. Second, when the remote requests resends (NACK), those are fulfilled from this buffer. Third, for Bandwidth Estimation (BWE), when probing for available bandwidth, packets from this buffer are used to do “spurious resends”, i.e. we do resends for packets that were not asked for.

pub fn send_buffer_video(&self) -> usize

Returns the setting for video resend size.

let config = Rtc::builder();

// Defaults to 1000.
assert_eq!(config.send_buffer_video(), 1000);

pub fn set_rtp_mode(self, enabled: bool) -> Self

Make the entire Rtc be in RTP mode.

This means all media, read from RtpPacket and written to StreamTx::write_rtp are RTP packetized. It bypasses all internal packetization/depacketization inside str0m.

WARNING: This is a low level API and is not str0m’s primary use case.

pub fn rtp_mode(&self) -> bool

Checks if RTP mode is set.

let config = Rtc::builder();

// Defaults to false.
assert_eq!(config.rtp_mode(), false);

pub fn enable_raw_packets(self, enabled: bool) -> Self

Enable the Event::RawPacket event.

This clones data, and is therefore expensive. Should not be enabled outside of tests and troubleshooting.

pub fn build(self) -> Rtc

Create a Rtc from the configuration.

Trait Implementations

impl Clone for RtcConfig

fn clone(&self) -> RtcConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RtcConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RtcConfig

fn default() -> Self

Returns the “default value” for a type.