Suggestions

close search

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:

publisher = [[OTPublisher alloc] initWithDelegate:self];
[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 also call the [OTPublisher initWithDelegate:name:] method to identify the published stream:

publisher = [[OTPublisher alloc] initWithDelegate:self name:"Bob's video"];

You can also (optionally) publish only audio or video for the stream by calling the [OTPublisher initWithDelegate:name:audioTrack:videoTrack:] method. For example, the following code publishes an audio-only stream (see Voice-Only):

publisher = [[OTPublisher alloc] initWithDelegate:self
                                             name:"Bob's video"
                                       audioTrack:YES
                                       videoTrack:NO];

You can also (optionally) set the resolution and frame rate for a publisher by calling the [OTPublisher initWithDelegate:name:cameraResolution:cameraFrameRate:]) method:

publisher = [[OTPublisher alloc] initWithDelegate:self
                                             name:"Bob's video"
                                 cameraResolution:OTCameraCaptureResolutionHigh
                                  cameraFrameRate:OTCameraCaptureFrameRate30FPS];

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:];

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.