Struct mediasoup::router::Router

pub struct Router { /* fields omitted */ }

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 app_data(&self) -> &AppData

Custom application data.

pub fn closed(&self) -> bool

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::direct_transport::DirectTransportOptions;

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::data_structures::TransportListenIp;
use mediasoup::webrtc_transport::{TransportListenIps, WebRtcTransportOptions};

let transport = router
    .create_webrtc_transport(WebRtcTransportOptions::new(TransportListenIps::new(
        TransportListenIp {
            ip: "127.0.0.1".parse().unwrap(),
            announced_ip: Some("9.9.9.1".parse().unwrap()),
        },
    )))
    .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::data_structures::TransportListenIp;
use mediasoup::pipe_transport::PipeTransportOptions;

let transport = router
    .create_pipe_transport(PipeTransportOptions::new(TransportListenIp {
        ip: "127.0.0.1".parse().unwrap(),
        announced_ip: Some("9.9.9.1".parse().unwrap()),
    }))
    .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::data_structures::TransportListenIp;
use mediasoup::plain_transport::PlainTransportOptions;

let transport = router
    .create_plain_transport(PlainTransportOptions::new(TransportListenIp {
        ip: "127.0.0.1".parse().unwrap(),
        announced_ip: Some("9.9.9.1".parse().unwrap()),
    }))
    .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::audio_level_observer::AudioLevelObserverOptions;
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 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::consumer::ConsumerOptions;
use mediasoup::data_structures::TransportListenIp;
use mediasoup::producer::ProducerOptions;
use mediasoup::router::{PipeToRouterOptions, RouterOptions};
use mediasoup::rtp_parameters::{
   MediaKind, MimeTypeAudio, RtcpParameters, RtpCapabilities, RtpCodecCapability,
   RtpCodecParameters, RtpCodecParametersParameters, RtpParameters,
};
use mediasoup::transport::Transport;
use mediasoup::webrtc_transport::{TransportListenIps, WebRtcTransportOptions};
use mediasoup::worker::WorkerSettings;
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", 1u32.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(TransportListenIps::new(
        TransportListenIp {
            ip: "127.0.0.1".parse().unwrap(),
            announced_ip: Some("9.9.9.1".parse().unwrap()),
        },
    )))
    .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", 1u32.into()),
                    ("usedtx", 1u32.into()),
                ]),
                rtcp_feedback: vec![],
            }],
            header_extensions: vec![],
            encodings: vec![],
            rtcp: RtcpParameters::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(TransportListenIps::new(
        TransportListenIp {
            ip: "127.0.0.1".parse().unwrap(),
            announced_ip: Some("9.9.9.1".parse().unwrap()),
        },
    )))
    .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::new(),
                   rtcp_feedback: vec![],
               },
           ],
           header_extensions: vec![],
           fec_mechanisms: 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::data_consumer::DataConsumerOptions;
use mediasoup::data_structures::TransportListenIp;
use mediasoup::data_producer::DataProducerOptions;
use mediasoup::router::{PipeToRouterOptions, RouterOptions};
use mediasoup::sctp_parameters::SctpStreamParameters;
use mediasoup::transport::Transport;
use mediasoup::webrtc_transport::{TransportListenIps, WebRtcTransportOptions};
use mediasoup::worker::WorkerSettings;

// 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::new(vec![])).await?;
let router2 = worker2.create_router(RouterOptions::new(vec![])).await?;

// Produce in router1.
let transport1 = router1
    .create_webrtc_transport({
        let mut options = WebRtcTransportOptions::new(TransportListenIps::new(
            TransportListenIp {
                ip: "127.0.0.1".parse().unwrap(),
                announced_ip: Some("9.9.9.1".parse().unwrap()),
            },
        ));
        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(TransportListenIps::new(
            TransportListenIp {
                ip: "127.0.0.1".parse().unwrap(),
                announced_ip: Some("9.9.9.1".parse().unwrap()),
            },
        ));
        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.

Trait Implementations

impl Clone for Router

pub fn clone(&self) -> Router

Returns a copy of the value.

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

Performs copy-assignment from source.