Suggestions

close search

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

Visit the Vonage API Developer Portal

Customizing the UI — iOS

These are the adjustments you can make to customize the user interface of OpenTok videos:

Adding a name for a published stream

To specify the name property of the published stream, set the name property of the OTPublisherSettings object you use when initializing a Publisher: 

OTPublisherSettings *_publisherSettings = [[OTPublisherSettings alloc] init];
_publisherSettings.name = @"Juan";
_publisher = [[OTPublisher alloc]
              initWithDelegate:self
              settings:_publisherSettings];

The OTStream class has a name property. When you subscribe to a stream, you can display this name in a user interface element. (Also, this name is displayed when the video in a web page that uses the OpenTok.js library.)

Adding a mute button for a publisher

There is no default user interface element to mute the publisher's microphone. However, you can add an element, such as a button, that sets the publishAudio property of the OTPublisher object when the user clicks it. Set the publishAudio property to NO to mute the publisher: 

publisher.publishAudio = NO;

Set the publishAudio property to YES to publish audio. 

publisher.publishAudio = YES;

For an example, see the "Project 4: Overlay Graphics" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

Adding a mute button for a subscriber

There is no default user interface element to mute the subscriber's audio. However, you can add an element, such as a button, that sets the subscribeToAudio of the OTSubscriber object when the user clicks it. Set the subscribeToAudio property to NO to mute the subscriber 

subscriber.subscribeToAudio = NO;

Set the subscribeToAudio property to YES to subscribe to audio (if there is an audio stream): 

subscriber.subscribeToAudio = YES;

For an example, see the "Project 4: Overlay Graphics" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

Adding a button to toggle the publisher's camera

There is no default user interface element to toggle the camera used by the publisher. However, you can add an element, such as a button, that sets the cameraPosition property the OTPublisher object. Set the property to a value defined in the AVCaptureDevicePosition enum. For example, the following code sets the publisher to use the back camera: 

publisher.cameraPosition = AVCaptureDevicePositionBack;

Note that the cameraPosition property is not available in the OTPublisherKit class. If you are using the OTPublisherKit class to implement a custom video capturer, you can define the camera used in the custom video capturing code.

For an example, see the "Project 4: Overlay Graphics" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

Adjusting user interface when video is enabled or disabled

When a subscriber's video is disabled, the [OTSubscriberKitDelegate subscriberVideoDisabled:reason:] message is sent. When this occurs, you can add a user interface element (such as an icon) to indicate that the video was disabled: 

- (void)subscriberVideoDisabled:(OTSubscriberKit*)subscriber
                         reason:(OTSubscriberVideoEventReason)reason
{
    // Display the video disabled indicator
}

When a subscriber's video is reenabled, the [OTSubscriberKitDelegate subscriberVideoEnabled:reason:] message is sent. When this occurs, you may remove a user interface element (such as an icon) that indicate that the video is reenabled: 

- (void)subscriberVideoEnabled:(OTSubscriberKit*)subscriber
                        reason:(OTSubscriberVideoEventReason)reason
{
    // Remove the video disabled indicator
}

In sessions that use the OpenTok Media Router (sessions with the media mode set to routed), the following messages can also be sent:

You may also want to display and remove a user interface notification (such as an icon) when these messages are sent.

For an example, see the "Project 4: Overlay Graphics" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

Note that when you publish a stream, you enable or disable publisher and subscriber audio fallback. The audio fallback feature disables video (in publishers and subscribers) when network or CPU conditions do not support video. See Audio fallback (iOS).

If you enable publisher audio fallback, the PublisherKitDelegate object will send the following messages pertaining to publisher audio fallback-related events:

You can display UI indicators in response to these events.

Displaying an indicator element when a session is being archived

When a archive of a session starts recording (or if you connect to a session that is being recorded), the [OTSessionDelegate session:archiveStartedWithId:name:] message is sent. When the recording stops the [OTSessionDelegate session:archiveStoppedWithId:] message is sent. You can add a user interface element, such as an icon displayed in a OTPublisher view, to indicate that a video is being recorded: 

- (void)     session:(OTSession*)session
archiveStartedWithId:(NSString*)archiveId
                name:(NSString*)name
{
    // Display the archive indicator
}

- (void)     session:(OTSession*)session
archiveStoppedWithId:(NSString*)archiveId
{
    // Hide the archive indicator
}

For an example, see the "Project 5: Multi-Party-Call" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

Getting a snapshot image of a video

The following code captures and display a static image of the Publisher video, adds it to the main view, and sets a UIImage object for the image: 

UIView* screenCapture = [publisher.view
    snapshotViewAfterScreenUpdates:YES];
[self.view addSubview:screenCapture];

UIGraphicsBeginImageContextWithOptions(publisher.view.bounds.size,
    NO, [UIScreen mainScreen].scale);
[view drawViewHierarchyInRect:publisher.view.bounds
    afterScreenUpdates:YES];
UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();

The following code captures and display a static image of the subscriber video, adds it to the main view, and sets a UIImage object for the image: 

UIView* screenCapture = [subscriber.view
    snapshotViewAfterScreenUpdates:YES];
[self.view addSubview:screenCapture];

UIGraphicsBeginImageContextWithOptions(subscriber.view.bounds.size,
    NO, [UIScreen mainScreen].scale);
[view drawViewHierarchyInRect:subscriber.view.bounds
    afterScreenUpdates:YES];
UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();

For an example of obtaining a high-resolution image of a publisher, see the "Live Photo Capture" sample in the OpenTok iOS Samples repo. This sample is also in the samples directory of the OpenTok iOS SDK.

Adjusting user interface based on audio levels

The [OTPublisherKitAudioLevelDelegate publisher:audioLevelUpdated:] and [OTSubscriberKitAudioLevelDelegate subscriber:audioLevelUpdated:] messages are sent on a regular interval with the audio level of the subscriber and publisher. You can use the audioLevel value to update the display in an audio level meter.

For an example, see the "Project 6: Audio Levels" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

Note: A publisher's audio level is not available until its stream is published to a session. To get a preview of the audio before the publisher starts streaming to the session, use a custom audio driver.

Using a custom video renderer

The OTPublisher and OTSubscriber classes provide a default UIView instance that renders the publisher or subscriber video. You can use the custom video stream API to define a custom video renderer, using OTPublisherKit, OTSubscriberKit, and OTVideoRender classes. For an example, see the "Project 2: Let's Build OTPublisher" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on github).

You can also set up a publisher to use a custom video capturer.