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:
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.
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.
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.
}
}];
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.
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:];
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:
connectionId
— The connection ID of the client subscribing to the streamsubscriberId
— The subscriber ID of the client subscribing to the streamThese 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.
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.