Struct Router

pub struct Router { /* private fields */ }

A router enables injection, selection and forwarding of media streams through Transport instances created on it.

Developers may think of a mediasoup router as if it were a “multi-party conference room”, although mediasoup is much more low level than that and doesn’t constrain itself to specific high level use cases (for instance, a “multi-party conference room” could involve various mediasoup routers, even in different physicals hosts).

Implementations

impl Router

pub fn id(&self) -> RouterId

Router id.

pub fn worker(&self) -> &Worker

Worker to which router belongs.

pub fn app_data(&self) -> &AppData

Custom application data.

pub fn closed(&self) -> bool

Whether router is closed.

pub fn rtp_capabilities(&self) -> &RtpCapabilitiesFinalized

RTP capabilities of the router. These capabilities are typically needed by mediasoup clients to compute their sending RTP parameters.

Notes on usage

• Check the RTP Parameters and Capabilities section for more details.
• See also how to filter these RTP capabilities before using them into a client.

pub async fn create_direct_transport( &self, direct_transport_options: DirectTransportOptions, ) -> Result<DirectTransport, RequestError>

Create a DirectTransport.

Router will be kept alive as long as at least one transport instance is alive.

Example

use mediasoup::prelude::*;

let transport = router.create_direct_transport(DirectTransportOptions::default()).await?;

pub async fn create_webrtc_transport( &self, webrtc_transport_options: WebRtcTransportOptions, ) -> Result<WebRtcTransport, RequestError>

Create a WebRtcTransport.

Router will be kept alive as long as at least one transport instance is alive.

Example

use mediasoup::prelude::*;
use std::net::{IpAddr, Ipv4Addr};

let transport = router
    .create_webrtc_transport(WebRtcTransportOptions::new(WebRtcTransportListenInfos::new(
        ListenInfo {
            protocol: Protocol::Udp,
            ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
            announced_address: Some("9.9.9.1".to_string()),
            port: None,
            port_range: None,
            flags: None,
            send_buffer_size: None,
            recv_buffer_size: None,
        },
    )))
    .await?;

pub async fn create_pipe_transport( &self, pipe_transport_options: PipeTransportOptions, ) -> Result<PipeTransport, RequestError>

Create a PipeTransport.

Router will be kept alive as long as at least one transport instance is alive.

Example

use mediasoup::prelude::*;
use std::net::{IpAddr, Ipv4Addr};

let transport = router
    .create_pipe_transport(PipeTransportOptions::new(ListenInfo {
        protocol: Protocol::Udp,
        ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
        announced_address: Some("9.9.9.1".to_string()),
        port: None,
        port_range: None,
        flags: None,
        send_buffer_size: None,
        recv_buffer_size: None,
    }))
    .await?;

pub async fn create_plain_transport( &self, plain_transport_options: PlainTransportOptions, ) -> Result<PlainTransport, RequestError>

Create a PlainTransport.

Router will be kept alive as long as at least one transport instance is alive.

Example

use mediasoup::prelude::*;
use std::net::{IpAddr, Ipv4Addr};

let transport = router
    .create_plain_transport(PlainTransportOptions::new(ListenInfo {
        protocol: Protocol::Udp,
        ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
        announced_address: Some("9.9.9.1".to_string()),
        port: None,
        port_range: None,
        flags: None,
        send_buffer_size: None,
        recv_buffer_size: None,
    }))
    .await?;

pub async fn create_audio_level_observer( &self, audio_level_observer_options: AudioLevelObserverOptions, ) -> Result<AudioLevelObserver, RequestError>

Create an AudioLevelObserver.

Router will be kept alive as long as at least one observer instance is alive.

Example

use mediasoup::prelude::*;
use std::num::NonZeroU16;

let observer = router
    .create_audio_level_observer({
        let mut options = AudioLevelObserverOptions::default();
        options.max_entries = NonZeroU16::new(1).unwrap();
        options.threshold = -70;
        options.interval = 2000;
        options
    })
    .await?;

pub async fn create_active_speaker_observer( &self, active_speaker_observer_options: ActiveSpeakerObserverOptions, ) -> Result<ActiveSpeakerObserver, RequestError>

Create an ActiveSpeakerObserver.

Router will be kept alive as long as at least one observer instance is alive.

Example

use mediasoup::active_speaker_observer::ActiveSpeakerObserverOptions;

let observer = router
    .create_active_speaker_observer({
        let mut options = ActiveSpeakerObserverOptions::default();
        options.interval = 300;
        options
    })
    .await?;

pub async fn pipe_producer_to_router( &self, producer_id: ProducerId, pipe_to_router_options: PipeToRouterOptions, ) -> Result<PipeProducerToRouterPair, PipeProducerToRouterError>

Pipes Producer with the given producer_id into another Router on same host.

Example

use mediasoup::prelude::*;
use mediasoup::rtp_parameters::RtpCodecParameters;
use std::net::{IpAddr, Ipv4Addr};
use std::num::{NonZeroU32, NonZeroU8};

// Have two workers.
let worker1 = worker_manager.create_worker(WorkerSettings::default()).await?;
let worker2 = worker_manager.create_worker(WorkerSettings::default()).await?;

// Create a router in each worker.
let media_codecs = vec![
    RtpCodecCapability::Audio {
        mime_type: MimeTypeAudio::Opus,
        preferred_payload_type: None,
        clock_rate: NonZeroU32::new(48000).unwrap(),
        channels: NonZeroU8::new(2).unwrap(),
        parameters: RtpCodecParametersParameters::from([
            ("useinbandfec", 1_u32.into()),
        ]),
        rtcp_feedback: vec![],
    },
];
let router1 = worker1.create_router(RouterOptions::new(media_codecs.clone())).await?;
let router2 = worker2.create_router(RouterOptions::new(media_codecs)).await?;

// Produce in router1.
let transport1 = router1
    .create_webrtc_transport(WebRtcTransportOptions::new(WebRtcTransportListenInfos::new(
        ListenInfo {
            protocol: Protocol::Udp,
            ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
            announced_address: Some("9.9.9.1".to_string()),
            port: None,
            port_range: None,
            flags: None,
            send_buffer_size: None,
            recv_buffer_size: None,
        },
    )))
    .await?;
let producer1 = transport1
    .produce(ProducerOptions::new(
        MediaKind::Audio,
        RtpParameters {
            mid: Some("AUDIO".to_string()),
            codecs: vec![RtpCodecParameters::Audio {
                mime_type: MimeTypeAudio::Opus,
                payload_type: 0,
                clock_rate: NonZeroU32::new(48000).unwrap(),
                channels: NonZeroU8::new(2).unwrap(),
                parameters: RtpCodecParametersParameters::from([
                    ("useinbandfec", 1_u32.into()),
                    ("usedtx", 1_u32.into()),
                ]),
                rtcp_feedback: vec![],
            }],
            ..RtpParameters::default()
        },
    ))
    .await?;

// Pipe producer1 into router2.
router1
    .pipe_producer_to_router(
        producer1.id(),
        PipeToRouterOptions::new(router2.clone())
    )
    .await?;

// Consume producer1 from router2.
let transport2 = router2
    .create_webrtc_transport(WebRtcTransportOptions::new(WebRtcTransportListenInfos::new(
        ListenInfo {
            protocol: Protocol::Udp,
            ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
            announced_address: Some("9.9.9.1".to_string()),
            port: None,
            port_range: None,
            flags: None,
            send_buffer_size: None,
            recv_buffer_size: None,
        },
    )))
    .await?;
let consumer2 = transport2
    .consume(ConsumerOptions::new(
        producer1.id(),
        RtpCapabilities {
           codecs: vec![
               RtpCodecCapability::Audio {
                   mime_type: MimeTypeAudio::Opus,
                   preferred_payload_type: Some(100),
                   clock_rate: NonZeroU32::new(48000).unwrap(),
                   channels: NonZeroU8::new(2).unwrap(),
                   parameters: RtpCodecParametersParameters::default(),
                   rtcp_feedback: vec![],
               },
           ],
           header_extensions: vec![],
       }
    ))
    .await?;

pub async fn pipe_data_producer_to_router( &self, data_producer_id: DataProducerId, pipe_to_router_options: PipeToRouterOptions, ) -> Result<PipeDataProducerToRouterPair, PipeDataProducerToRouterError>

Pipes DataProducer with the given data_producer_id into another Router on same host.

Example

use mediasoup::prelude::*;
use std::net::{IpAddr, Ipv4Addr};

// Have two workers.
let worker1 = worker_manager.create_worker(WorkerSettings::default()).await?;
let worker2 = worker_manager.create_worker(WorkerSettings::default()).await?;

// Create a router in each worker.
let router1 = worker1.create_router(RouterOptions::default()).await?;
let router2 = worker2.create_router(RouterOptions::default()).await?;

// Produce in router1.
let transport1 = router1
    .create_webrtc_transport({
        let mut options = WebRtcTransportOptions::new(WebRtcTransportListenInfos::new(
            ListenInfo {
                protocol: Protocol::Udp,
                ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
                announced_address: Some("9.9.9.1".to_string()),
                port: None,
                port_range: None,
                flags: None,
                send_buffer_size: None,
                recv_buffer_size: None,
            },
        ));
        options.enable_sctp = true;
        options
    })
    .await?;
let data_producer1 = transport1
    .produce_data(DataProducerOptions::new_sctp(
        SctpStreamParameters::new_unordered_with_life_time(666, 5000),
    ))
    .await?;

// Pipe data_producer1 into router2.
router1
    .pipe_data_producer_to_router(
        data_producer1.id(),
        PipeToRouterOptions::new(router2.clone())
    )
    .await?;

// Consume data_producer1 from router2.
let transport2 = router2
    .create_webrtc_transport({
        let mut options = WebRtcTransportOptions::new(WebRtcTransportListenInfos::new(
            ListenInfo {
                protocol: Protocol::Udp,
                ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
                announced_address: Some("9.9.9.1".to_string()),
                port: None,
                port_range: None,
                flags: None,
                send_buffer_size: None,
                recv_buffer_size: None,
            },
        ));
        options.enable_sctp = true;
        options
    })
    .await?;
let data_consumer2 = transport2
    .consume_data(DataConsumerOptions::new_sctp(data_producer1.id()))
    .await?;

pub fn can_consume( &self, producer_id: &ProducerId, rtp_capabilities: &RtpCapabilities, ) -> bool

Check whether the given RTP capabilities are valid to consume the given producer.

pub fn on_new_transport<F: Fn(NewTransport<'_>) + Send + Sync + 'static>( &self, callback: F, ) -> HandlerId

Callback is called when a new transport is created.

pub fn on_new_rtp_observer<F: Fn(NewRtpObserver<'_>) + Send + Sync + 'static>( &self, callback: F, ) -> HandlerId

Callback is called when a new RTP observer is created.

pub fn on_worker_close<F: FnOnce() + Send + 'static>( &self, callback: F, ) -> HandlerId

Callback is called when the worker this router belongs to is closed for whatever reason. The router itself is also closed. A on_router_close callbacks are triggered in all its transports all RTP observers.

pub fn on_close<F: FnOnce() + Send + 'static>(&self, callback: F) -> HandlerId

Callback is called when the router is closed for whatever reason.

NOTE: Callback will be called in place if router is already closed.

Trait Implementations

impl Clone for Router

fn clone(&self) -> Router

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Router

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

Formats the value using the given formatter.