Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalYou can make audio and video adjustments to published and subscribed streams:
You can toggle audio and video on or off, by setting the publishAudio and publishVideo
properties. For example, the following code turns audio off:
publisher.publishAudio = NO;
To set up a voice-only session, set the
videoTrack property of the OTPublisherSettings object to NO
when you initialize
each OTPublisher object in the session. For example, the following code
creates a publisher for a voice-only session:
OTPublisherSettings *_publisherSettings = [[OTPublisherSettings alloc] init];
_publisherSettings.videoTrack = NO;
_publisher = [[OTPublisher alloc]
initWithDelegate:self
settings:_publisherSettings];
You can specify (or change) the camera used to publish a stream:
publisher.cameraPosition = AVCaptureDevicePositionFront; // front camera
publisher.cameraPosition = AVCaptureDevicePositionBack; // back camera
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.
When the camera used to publish a stream changes, the publisher delegate
sends an [OTPublisher publisher:didChangeCameraPosition:] message:
- (void)publisher:(OTPublisher *)publisher didChangeCameraPosition:(AVCaptureDevicePosition)position
{
if (position == AVCaptureDevicePositionFront) {
// front camera
} else {
// back camera
}
}
You can set the resolution and frame rate for a publisher's stream by setting the
cameraResolution and cameraFrameRate properties of the
OTPublisherSettings object you pass into the [OTPublisher initWithDelegate:settings:]
method:
OTPublisherSettings *_publisherSettings = [[OTPublisherSettings alloc] init];
_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.
Note: See the 1080p developer guide for considerations about using 1080p resolution.
The OTPublisher class captures video from a camera on the iOS device. You can use the custom video stream API to define a custom video capturer, using the OTPublisherKit and OTVideoCapture 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 use a custom video renderer for videos.
By default, the OpenTok iOS SDK uses the device microphone to capture audio to transmit to a
published stream. And it uses the speakers (or headphones) to play back audio from a subscribed
stream. Call the [OTAudioDeviceManager setAudioDevice:] method to set up a custom audio
driver for capturing and rendering audio samples:
myAudioDevice = [[MyAudioDevice alloc] init];
[OTAudioDeviceManager setAudioDevice:_myAudioDevice];
Call [OTAudioDeviceManager setAudioDevice:] before you initialize an OTSession object.
Call the [OTAudioDevice setAudioBus:] method to set an audio bus object. This object,
defined by the OTAudioBus protocol, has a [OTAudioBus writeCaptureData:numberOfSamples:]
method and a [OTAudioBus readRenderData:numberOfSamples:] method. These methods are
called when audio samples are made available for writing to the publisher's audio stream or for
reading from the subscribed streams.
For an example, see the "Project 7: External Audio Device" sample in the samples directory of the OpenTok iOS SDK (or at the opentok-ios-sdk-samples repo on GitHub).
You can use pre-built transformers from the Vonage Media Processor library or create your own custom audio or video transformer to apply to published video. See this topic.
To fine tune audio quality for a publisher stream the following approaches can be used:
Audio bitrate as a publisher settings
@property (nonatomic) int audioBitrate
The desired bitrate for the published audio, in bits per second.
The supported range of values is 6,000 - 510,000. (Invalid values are
ignored.) Set this value to enable high-quality audio (or to reduce bandwidth usage with
lower-quality audio). If you do not set this option, OpenTok automatically assigns an audio bitrate for the
stream.
The following are recommended settings:
enableOpusDtx property of the
OTPublisherKitSettings
object you pass into the [OTPublisherKit initWithDelegate:settings:]
method (when creating
a Publisher).
For more information, see this Vonage Video API knowledge base article.
You can individually set the audio volume for each subscriber by setting the
OTSubscriberKit.audioVolume property.
By default, a Subscriber object is initialized to subscribe to audio and video, if they are available.
When you subscribe to a stream, you can specify whether to initially subscribe to audio or video (if they are available). For example, the following code subscribes to the audio stream only:
_subscriber = [[OTSubscriber alloc]
initWithStream:stream delegate:self];
_subscriber.subscribeToAudio = NO;
After you create a Subscriber object, you toggle audio on or off by calling the subscribeToAudio()
method of the Subscriber object:
_subscriber.subscribeToAudio = NO; // audio off
_subscriber.subscribeToAudio = YES; // audio on
You toggle video on or off by calling the subscribeToVideo() method of the Subscriber object:
subscriber.subscribeToVideo = NO; // video off
subscriber.subscribeToVideo = YES; // video on
Note however that you can only subscribe to audio or video if the client publishing the stream includes audio or
video. For example, calling subscribeToVideo(false) will have no effect if the client publishing the
stream is publishing audio only.
By default, a Subscriber object plays back both audio and video (if they are available). You can check if a stream has
audio or video (if the publisher of the stream is streaming audio or video) by checking the hasAudio and
hasVideo properties of the Stream object:
if (!stream.hasAudio) {
// You may want to adjust the user interface
}
if (!stream.hasVideo) {
// You may want to adjust the user interface
}
For example, when you subscribe to a stream, you may want to adjust the user interface based on whether the stream has audio or video. For example, you may want to indicate to the user whether a stream has audio or not; or you may not want to display a subscriber's view if a stream does not have video.