Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Publishing streams — iOS

Once you have connected to a session, you can publish a stream that other clients connected to the session can view.

This topic includes the following sections:

Initializing an OTPublisher object

The OTPublisher object is used to capture an audio-video stream from the device's microphone and camera for use in an OpenTok session. The view property of the object contains the view of the video you publish: 

OTPublisher publisher = [[OTPublisher alloc]
                      initWithDelegate:self
                      settings:[[OTPublisherSettings alloc] init]];
[self.view addSubview:publisher.view];
[publisher.view setFrame:CGRectMake(0, 0, 200, 150)];

Implement the methods of the OTPublisherDelegate protocol in the object you specify as the delegate object. These methods are called when publisher-related events occur.

Pass the Publisher object into the [OTSession publish:error] method to publish a stream to a session. See Publishing a stream.

You can set other properties of the OTPublisherSettings object to define custom settings for the publisher: 

OTPublisherSettings *_publisherSettings = [[OTPublisherSettings alloc] init];
_publisherSettings.name = @"Bob's video";
_publisherSettings.audioTrack = NO;
_publisherSettings.videoTrack = YES;
_publisherSettings.cameraResolution = OTCameraCaptureResolutionHigh;
_publisherSettings.cameraFrameRate = OTCameraCaptureFrameRate30FPS;
_publisher = [[OTPublisher alloc]
              initWithDelegate:self
              settings:_publisherSettings];

Note that in sessions that use the OpenTok Media Router (sessions with the media mode set to routed), lowering the frame rate proportionally reduces the bandwidth the stream uses. However, in sessions that have the media mode set to relayed, lowering the frame rate does not reduce the stream's bandwidth.

You can use a custom video capturer to publish a stream with a customized video source — see Using a custom video capturer. You can also use the custom video capturer to publish a screen-sharing stream — see Screen-sharing.

You can also use a customized audio source for the published stream — see Using a custom audio driver.

Checking whether a client has publish capabilities

Once you have connected to a session, you can check if the client can publish. Check the value of the [OTSession.capablilites.canPublish:] property. If it is set to `YES`, the client can publish:

if (session.capabilities.canPublish) {
    // The client can publish.
} else {
    // The client cannot publish.
    // You may want to notify the user.
}

To publish, the client must connect to the session with a token that is assigned a role that supports publishing. See the Token Creation Overview.

Checking for camera access

We recommend that you check for camera access app permissions prior to publishing and, if access is denied, give feedback to the end-user about setting app access permissions. (An end-user can enable access to the camera via the iOS Settings: Privacy > Camera.)

The end-user is prompted to grant access to the camera for any app requesting it. You may control when this prompt is shown by calling [AVCaptureDevice requestAccessForMediaType:completionHandler:] with AVMediaTypeVideo, which will give the prompt on first run. Subsequent calls will execute the completion handler with the user's stored preference. 

[AVCaptureDevice requestAccessForMediaType:AVMediaTypeVideo completionHandler:^(BOOL granted) {
        if(granted){
            // Access to the camera is granted. You can publish.
        } else {
           // Access to the camera is not granted.
        }
    }];

Publishing a stream

Once you create a Publisher object (See Initializing an OTPublisher object), you can pass it into the [OTSession publish:error] method of an OTSession object to publish the stream to the session: 

OTError* error = nil;
[session publish:publisher error:&error];
if (error) {
  NSLog(@"publishing failed with error: (%@)", error);
}

This code assumes that session is a Session object, and that the client has connected to the session. For more information, see Joining a Session.

The [OTPublisherDelegate publisher:streamCreated:] message is sent when the publisher starts streaming to the session.

Stopping a publisher from streaming

You can stop publisher from streaming to the session by calling the [OTSession unpublish:error:] method of the OTSession object: 

OTError* error = nil;
[session unpublish:publisher error:&error];
if (error) {
  NSLog(@"publishing failed with error: (%@)", error);
}

The [OTPublisherDelegate publisher:streamDestroyed:] message is sent when the publisher stops streaming to the session. When this message is sent, remove the publisher's view from its superview: 

[publisher.view removeFromSuperview:];

Getting statistics about a publisher's stream

Set the networkStatsDelegate property of an OTPublisherKit to an object implements the OTPublisherKitNetworkStatsDelegate protocol. This protocol includes an [OTPublisherKitNetworkStatsDelegate publisher: audioNetworkStatsUpdated:] message and an [OTPublisherKitNetworkStatsDelegate publisher: videoNetworkStatsUpdated:] message, which are periodically sent to report publisher audio and video quality statistics. The second parameter of each of these — audioNetworkStatsUpdated and videoNetworkStatsUpdated — is an array of stats objects that include properties defining the network statistics (audio and video).

For a publisher in a routed session (one that uses the OpenTok Media Router), the stats array includes one object, defining the statistics for the single audio or video media stream that is sent to the OpenTok Media Router. In a relayed session, the stats array includes an object for each subscriber to the published stream. The object includes the following properties:

Additionally, for a publisher in a relayed session, each stats object in the array contains the following two properties:

These two properties are undefined for a publisher in a routed session.

To get more detailed stream statics, use the [OTPublisherKit getRtcStatsReport:] method. This provides RTC stats reports for the media stream. This is an asynchronous operation. Set the >[OTPublisherKit rtcStatsReportDelegate]> property and implement the >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> method prior to calling [OTPublisherKit getRtcStatsReport:]. When the stats are available, the implementation of the >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> message is sent. The message includes an array of OTPublisherRtcStats objects, which includes a jsonArrayOfReports property. This is a JSON array of RTC stats reports, which are similar to the format the RtcStatsReport object implemented in web browsers (see these Mozilla docs). Also see this W3C documentation.

Testing a publisher's stream

You can publish a test stream and check its audio and video statistics to determine the type of stream (such as high-resolution or audio-only) supported by your connection.

To get statistics for a stream published by the local client, you must use a session that uses the OpenTok Media Router (sessions with the media mode set to routed). You can then use the networkStatsDelegate method of the OTSubscriberKit object to get audio and video statistics for the stream you publish. See this topic for more information.

The opentok-network-test repo includes sample code for showing how to use statistics of a test stream before publishing to a session.