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.

Setting the maximum bitrate for a stream

You can set the maximum bitrate for a published stream. Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. See this documentation.

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.

To get low-level peer connection statistics, use the [OTPublisherKit getRtcStatsReport:] method. This provides RTC stats reports for the media stream.

Refer to the client observability developer guide for detailed information.

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.