mediasoup_client_ios API

Working Draft

NOTE: Can only be used with mediasoup version 3

Mediasoupclient

The main Objective-C namespace exposed by the mediasoup_client_ios library

#include "mediasoup_client_ios/Mediasoupclient.h"

Swift users will need to include the above in their bridging headers

Functions

Objective-C

[Mediasoupclient version];

Swift

Mediasoupclient.version()

the libmediasoupclient version used by mediasoup_client_ios

@returns NSString

MediasoupDevice

A device represents an endpoint that connects to a mediasoup Router to send and/or receive media.

This is the entry point for iOS client side applications

Constructor

Objective-C

MediasoupDevice device = [[MediasoupDevice alloc] init];

Swift

let device = MediasoupDevice()

Methods

Objective-C

[device getRtpCapabilities];

Swift

device.getRtpCapabilities()

The device RTP capabilities, generated by combining both the underlying WebRTC capabilities and the router RTP capabilities.

@returns NSString @throws NSException if device is not loaded

These RTP capabilities must be given to the mediasoup router in order to consume a remote stream.

Objective-C

[device isLoaded];

Swift

device.isLoaded()

Whether the device has been loaded

@returns bool

Objective-C

[device load:[routerRtpCapabilities]];

Swift

device.load(routerRtpCapabilities)

Loads the device with the RTP capabilities of the mediasoup router. This is how the device knows about the allowed media codecs and other settings.

Argument	Type	Description	Required	Default
routerRtpCapabilities	NSString	The mediasoup router RTP capabilities	Yes

@throws NSException

The router RTP capabilities are exposed via the router.rtpCapabilities getter.

Objective-C

[device canProduce:@"video"];

Swift

device.canProduce("video")

Whether the device can produce media of the given kind. This depends on the media codecs enabled in the mediasoup router and the media capabilities of libwebrtc.

Argument	Type	Description	Required	Default
kind	NSString	"audio" or "video"	Yes

@returns bool @throws NSException, if device is not loaded @throws NSException, if invalid kind

Objective-C

[device createSendTransport:listener id:id iceParameters:iceParameters iceCandidates:iceCandidates dtlsParameters:dtlsParameters];

Swift

device.createSendTransport(listener, id: id, iceParameters: iceParameters, iceCandidates: iceCandidates, dtlsParameters: dtlsParameters)

Creates a new WebRTC transport to send media. The transport must be previously created in the mediasoup router via router.createWebRtcTransport().

Argument	Type	Description	Required
listener	SendTransportListener	The listener of the SendTransport	Yes
id	NSString	The identifier of the server side transport.	Yes
iceParameters	NSString	ICE parameters of the server side transport	Yes
iceCandidates	NSString	ICE candidates of the server side transport	Yes
dtlsParameters	NSString	DTLS parameters of the server side transport	Yes
sctpParameters	NSString	SCTP parameters of the server side transport	No
options	NSString	PeerConnection options	No
appData	NSString	Custom applcation data	No

@returns SendTransport

Objective-C

[device createRecvTransport:listener id:id iceParameters:iceParameters iceCandidates:iceCandidates dtlsParameters:dtlsParameters];

Swift

device.createRecvTransport(listener, id: id, iceParameters: iceParameters, iceCandidates: iceCandidates, dtlsParameters: dtlsParameters)

Creates a new WebRTC transport to receive media. The transport must be previously created in the mediasoup router via router.createWebRtcTransport().

Argument	Type	Description	Required
listener	RecvTransportListener	The listener of the RecvTransport	Yes
id	NSString	The identifier of the server side transport	Yes
iceParameters	NSString	ICE parameters of the server side transport	Yes
iceCandidates	NSString	ICE candidates of the server side transport	Yes
dtlsParameters	NSString	DTLS parameters of the server side transport	Yes
sctpParameters	NSString	SCTP parameters of the server side transport	No
options	NSString	PeerConnection options	No
appData	NSString	Custom application data	No

@returns RecvTransport

Transport

A transport instance in mediasoup_client_ios represents the local side of a WebRtcTransport in mediasoup server. A WebRTC transport connects a mediasoup Device with a mediasoup Router at media level and enables the sending of media (by means of Producer instances) or receiving of media (by means of Consumer instances).

Internally, the transport holds a WebRTC RTCPeerConnection instance.

Methods

Objective-C

[transport getId];

Swift

transport.getId()

Transport identifier. It matches the id of the server side transport.

@returns NSString

Objective-C

[transport getConnectionState];

Swift

transport.getConnectionState()

The current connection state of the local peerconnection

@returns NSString

Objective-C

[transport getStats];

Swift

transport.getStats()

Gets the local transport statistics by calling getStats() in the underlying RTCPeerConnection instance.

@returns NSString

Objective-C

[transport getAppData];

Swift

transport.getAppData()

Custom data object provided by the application in the transport constructor. The app can modify its content at any time.

@returns NSString

Objective-C

[transport isClosed];

Swift

transport.isClosed()

Whether the transport is closed.

@returns bool

Objective-C

[transport close];

Swift

transport.close()

Closes the transport, including all its producers and consumers

This method should be called when the server side transport has been closed (and vice-versa).

Objective-C

[transport restartIce:iceParameters];

Swift

transport.restartIce(iceParameters)

Instructs the underlying peerconnection to restart ICE by providing it with new remote ICE parameters.

Argument	Type	Description	Required	Default
iceParameters	NSString	New ICE parameters of the server side transport	Yes

This method must be called after restarting ICE in the server side via webRtcTransport.restartIce()

Objective-C

[transport updateIceServers:iceServers];

Swift

transport.updateIceServers(iceServers)

Provides the underlying peerconnection with a new list of TURN servers.

Argument	Type	Description	Required	Default
iceServers	NSString	List of TURN servers to provide the local peerconnection with.	No

This method is specially useful if the TURN server credentials have changed.

TransportListener

This is the base class inherited by SendTransportListener and RecvTransportListener

Events

Objective-C

-(void)onConnect:(Transport *)transport dtlsParameters:(NSString *)dtlsParameters

Swift

func onConnect(_ transport: Transport!, dtlsParameters: String!)

Called when the transport is about to establish the ICE+DTLS connection and needs to exchange information with the associated server side transport.

Argument	Type	Description
transport	Transport	Transport instance.
dtlsParameters	NSString	Local DTLS parameters.

In server side, the application should call webRtcTransport.connect().

Objective-C

-(void) onConnectionStateChange:(Transport *)transport connectionState:(NSString *)connectionState

Swift

func onConnectionStateChange(_ transport: Transport!, connectionState: String!)

Emitted when the local transport connection state changes.

Argument	Type	Description
transport	Transport	Transport instance
connectionState	NSString	Transport connecton state.

SendTransport

@inherits Transport

A WebRTC send transport connects a mediasoupclient Device with a mediasoup Router at media level and enables the sending of media (by means of Producer instances).

Internally, the transport holds a WebRTC RTCPeerConnection instance.

Methods

Objective-C

[sendTransport produce listener track:track encodings:encodings codecOptions:codecOptions appData:appData]

Swift

sendTransport.produce(listener, track: track, encodings:encodings, codecOptions:codecOptions, appData: appData)

Instructs the transport to send an audio or video track to the mediasoup router.

Argument	Type	Description
listener	ProducerListener	Producer listener.
track	RTCMediaStreamTrack	An audio or video track.
encodings	NSString	Encoding settings
codecOptions	NSString	Per codec specific options.
appData	NSString	Custom application data.

Due to a current issue with encodings please set encodings to nil

@returns Producer

SendTransportListener

@inherits TransportListener

This is a base class which must be implemented and used according to the API.

Events

Objective-C

-(void)onProduce:(Transport *)transport kind:(NSString *)kind rtpParameters:(NSString *)rtpParameters appData:(NSString *)appData callback:(void (^)(NSString *))callback

Swift

func onProduce(_ transport: Transport!, kind: String!, rtpParameters: String!, appData: String!, callback: ((String?) -> Void)!)

Emitted when the transport needs to transmit information about a new producer to the associated server side transport.

This event occurs before the produce() method completes

Argument	Type	Description
transport	SendTransport	SendTransport instance.
kind	NSString	Producer's media kind("audio" or "video").
rtpParameters	NSString	Producer's RTP parameters.
appData	NSString	Custom application data as given in the transport produce method.

In server side, the application should call transport.produce()

RecvTransport

@inherits Transport

A WebRTC receive transport connects a mediasoupclient Device with a mediasoup Router as media level and enables the reception of media (by means of Consumer instances).

Internally, the transport holds a WebRTC RTCPeerConnection instance.

Methods

Objective-C

[recvTransport consume:listener id:id producerId:producerId kind:kind rtpParameters:rtpParameters appData:appData]

Swift

recvTransport.consume(listener, id: id, producerId: producerId, kind: kind, rtpParameters:rtpParameters, appData: appData)

Instructs the transport to receive an audio or video track in the mediasoup router.

Argument	Type	Description	Required
listener	ConsumerListener	Consumer listener.	Yes
id	NSString	The identifier of the server side consumer.	Yes
producerId	NSString	The identifier of the server side producer being consumed	Yes
kind	NSString	Media kind("audio" or "video").	Yes
rtpParameters	NSString	Receive RTP parameters.	Yes
appData	NSString	Custom application data	No

@returns Consumer

RecvTransportListener

@inherits TransportListener

This is a base class which must be implemented and used according to the API.

Producer

A producer represents an audio or video source that will be transmitted to the mediasoup router through a WebRTC transport.

Methods

Objective-C

[producer getId];

Swift

producer.getId()

Producer identifier

@returns NSString

Objective-C

[producer getKind];

Swift

producer.getKind()

The media kind ("audio" or "video").

@returns NSString

Objective-C

[producer getTrack];

Swift

producer.getTrack()

The audio or video track being transmitted

@returns RTCMediaStreamTrack

Objective-C

[producer getRtpParameters];

Swift

producer.getRtpParameters()

Producer RTP parameters. These parameters are internally build by the library and conform to the syntax and requirements of mediasoup, thus they can be transmitted to the server to invoke transport.produce() with them.

@returns NSString

Objective-C

[producer getMaxSpatialLayer];

Swift

producer.getMaxSpatialLayer()

In case of simulcast, this value determines the highest stream (from 0 to N-1) being transmitted.

@returns int

Objective-C

[producer getStats];

Swift

producer.getStats()

Gets the local RTP sender statistics by calling getStats() in the underlying RTCRtpSender instance.

@returns NSString

Objective-C

[producer getAppData];

Swift

producer.getAppData()

Custom data object provided by the application in the producer factory method. The app can modify its contents at any time.

@returns NSString

Objective-C

[producer isClosed];

Swift

producer.isClosed()

Whether the producer is closed.

@returns bool

Objective-C

[producer isPaused];

Swift

producer.isPaused()

Whether the producer is paused.

@returns bool

Objective-C

[producer close];

Swift

producer.close()

Closes the producer. No more media is transmitted.

This method should be called when the server side producer has been closed (and vice-versa)

Objective-C

[producer pause];

Swift

producer.pause()

Pauses the producer (no RTP is sent to the server)

This method should be called when the server side producer has been paused (and vice-versa)

Objective-C

[producer resume];

Swift

producer.resume()

Paused the producer (RTP is sent again to the server).

This method should be called when the server side producer has been resumed (and vice-versa)

Objective-C

[producer replaceTrack:newTrack]

Swift

producer.replaceTrack(newTrack)

Replaces the audio or video track being transmitted. No negotiation with the server is needed.

Argument	Type	Description	Required
track	RTCMediaStreamTrack	An audio or video track.	Yes

Objective-C

[producer setMaxSpatialLayer:spatialLayer]

Swift

producer.setMaxSpatialLayer(spatialLayer)

In case of simulcast, this method limits the highest RTP stream being transmitted to the server.

Argument	Type	Description	Required
spatialLayer	int	The index of the entry in encodings representing the highest RTP stream that will be transmitted.	Yes

ProducerListener

@abstract

This is an abstract listener which must be implemented and used according to the API.

Events

Objective-C

-(void)onTransportClose(Producer *)producer

Swift

func onTransportClose(_ producer: Producer)

Executed when the transport this producer belongs to is closed for whatever reason. The producer itself is also closed.

Argument	Type	Description	Required
producer	Producer	The producer instance executing this method.	Yes

Consumer

A consumer represents an audio or video remote source being transmitted from the mediasoup router to the client application through a WebRTC transport.

Methods

Objective-C

[consumer getId];

Swift

consumer.getId()

Consumer identifier

@returns NSString

Objective-C

[consumer getProducerId];

Swift

consumer.getProducerId()

The associated producer identifier

@returns NSString

Objective-C

[consumer getKind];

Swift

consumer.getKind()

The media kind ("audio" or "video")

@returns NSString

Objective-C

[consumer getRtpParameters];

Swift

consumer.getRtpParameters()

Consumer RTP parameters

@returns NSString

Objective-C

[consumer getTrack];

Swift

consumer.getTrack()

The remote audio or video track

@returns RTCMediaTrack

Objective-C

[consumer getStats];

Swift

consumer.getStats()

Gets the local RTP receiver statistics by calling getStats() in the underlying RTCRtpReceiver instance.

@returns NSString

Objective-C

[consumer getAppData];

Swift

consumer.getAppData()

Custom data object provided by the application in the consumer factory method. The app can modify its content at any time.

@returns NSString

Objective-C

[consumer isClosed];

Swift

consumer.isClosed()

Whether the consumer is closed.

@returns Bool

Objective-C

[consumer isPaused];

Swift

consumer.isPaused()

Whether the consumer is paused.

@returns Bool

Objective-C

[consumer close];

Swift

consumer.close()

Closes the consumer

This method should be called when the server side consumer has been closed (and vice-versa).

Objective-C

[consumer pause];

Swift

consumer.pause()

Pauses the consumer.

This method should be called when the server side consumer has been paused (and vice-versa).

Objective-C

[consumer resume];

Swift

consumer.resume()

Resumes the consumer.

This method should be called when the server side consumer has been resumed (and vice-versa).

ConsumerListener

@abstract

This is an abstract class which must be implemented and used according to the API.

Events

Objective-C

-(void)onTransportClose(Consumer *)consumer

Swift

func onTransportClose(_ consumer: Consumer!)

Executed when the transport this consumer belongs to is closed for whatever reason. The consumer itself is also closed.

Logger

libmediasoupclient inner Logger.

Enums

LogLevel

Value	Description
TRACE	Logs everything
WARN	Logs warning level and above.
ERROR	Logs error level.
NONE	Logs nothing.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Api.md

Api.md

mediasoup_client_ios API