Suggestions

close search

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

Visit the Vonage API Developer Portal

Subscribing to streams — iOS

Once you have connected to a session, you can subscribe to streams in the session. When you subscribe to a stream, you can put its video view in the app.

This topic includes the following sections:

Automatic reconnection

If a client drops a connection to a subscribed stream (for example, due to a drop in network connectivity in either client), it will attempt to automatically reconnect to the stream. When the stream is dropped and the client tries to reconnect, the [OTSubscriberKitDelegate subscriberDidDisconnectFromStream:] message is sent to the OTSubscriberKit object's delegate. When the connection is restored, the [OTSubscriberKitDelegate subscriberDidReconnectToStream:] message is sent. If the client cannot restore the connection, the [OTSessionDelegate session:streamDestroyed:] message is sent.

In response to these events, your application can (optionally) display user interface notifications indicating the temporary disconnection, reconnection, and disconnection states. 

// OTSubscriber delegate callbacks:
- (void)subscriberDidDisconnectFromStream:(OTStream*)stream
{
  // Display a user interface notification.
}

- (void)subscriberDidReconnectToStream:(OTStream*)stream
{
  // Adjust user interface.
}

// OTSession delegate callback:
- (void)session:(OTSession*)session session:streamDestroyed:(OTStream*)stream
{
  // Adjust user interface.
}

Detecting streams in a session

The [OTSessionDelegate session:streamCreated:] message is sent when a new stream is created in a session. (A stream is created when a client publishes a stream to the session.) The OTStream object has properties that define the stream. Compare the connection property of the OTStream object with the connection property of the OTSession object to determine whether the stream is one that your client published: 

- (void)session:(OTSession*)session streamCreated:(OTStream*)stream
{
    NSLog(@"session streamCreated (%@)", stream.streamId);

    // See the declaration of subscribeToSelf above.
    if ([stream.connection.connectionId isEqualToString: session.connection.connectionId]) {
        // This is my own stream
    } else {
        // This is a stream from another client.
    }
}

You can subscribe to a stream to display it in your app. See the next section.

Subscribing to a stream

To subscribe to a stream, call the [OTSubscriber initWithStream:] method, passing in an OTStream object and a delegate object to receive subscriber-related messages. Then call the[OTSession subscribe:error] method to start subscribing to the stream: 

- (void)session:(OTSession*)session streamCreated:(OTStream*)stream
{
    subscriber = [[OTSubscriber alloc] initWithStream:stream delegate:self];
    OTError* error = nil;
    [session subscribe:subscriber error:&error]
    if (error) {
      NSLog(@"subscribe failed with error: (%@)", error);
    }
}

The [OTSubscriberDelegate subscriberDidConnectToStream:] message is sent when the app starts receiving the subscriber's stream. At this point, you can add the subscriber's view (represented by the OTSubscriber.view property) to the app: 

	- (void)subscriberDidConnectToStream:(OTSubscriber*)subscriber
	{
	    [subscriber.view setFrame:CGRectMake(0, 300, 400, 300)];
	    [self.view addSubview:subscriber.view];
	}

Unsubscribing from a stream

To stop playing a stream you are subscribed to, call the [OTSession unsubscribe:error:] method:

    OTError* error = nil;
    [session unsubscribe:_subscriber error:&error]
    if (error) {
      NSLog(@"unsubscribe failed with error: (%@)", error);
    }

The Subscriber is disconnected. Next, remove its view from its superview:

    [subscriber.view removeFromSuperview:];

Detecting when streams leave a session

When streams leave a session, the [OTSession session: streamDestroyed:] message is sent. When a stream is dropped, the view for any OTSubscriber object for the stream is removed from its superview. Check if the stream is not published by your own client, and remove its view from its superview. 

- (void)session:(OTSession*)session streamDestroyed:(OTStream *)stream
{
    NSLog(@"session streamDestroyed (%@)", stream.streamId);

    if ([subscriber.stream.streamId isEqualToString:stream.streamId])
    {
        [_subscriber.view removeFromSuperview];
        _subscriber = nil;
    }
}

Detecting when a subscriber's video is disabled

The subscriber's delegate sends the [OTSubscriberDelegate subscriberVideoDisabled:reason:] message when the subscriber's video is disabled: 

- (void)subscriberVideoDisabled:(OTSubscriber *)subscriber
                         reason:(OTSubscriberVideoEventReason)reason
{
    NSLog(@"subscriber video disabled.");
}

The reason parameter can be set to one of the following constants defined in the OTSubscriberVideoEventReason enum:

If the video stream resumes, the [OTSubscriberKit subscriberVideoEnabled:reason:] message is sent.

When you publish a stream, you can prevent it from having its video disabled due to stream quality. Before calling the [OTSession publish:error:] method, set the audioFallbackEnabled property of the Publisher object (or PublisherKit object) to NO.

Getting information about a stream

The OTStream object has the following properties that define the stream:

You can set a OTSubscriberKitNetworkStatsDelegate object for the OTSubscriberKit object to monitor the following statistics for a subscriber's stream:

See the SubscriberKit.networkStatsDelegate property.

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).

To get more detailed stream statics, use the [OTSubscriberKit getRtcStatsReport:] method. This provides an RTC stats report for the media stream. This is an asynchronous operation. Set the [OTSubscriberKit rtcStatsReportDelegate]> property and implement the >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> method prior to calling [OTSubscriberKit getRtcStatsReport:]. When the stats are available, the implementation of the >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> message is sent. The message includes an a jsonArrayOfReports parameter. 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.

Setting the preferred frame rate and resolution

When subscribing to a stream that uses the scalable video feature, you can set the preferred frame rate and resolution for the stream the subscribing client receives from the OpenTok Media Router. For details, see SubscriberKit.preferredFrameRate and SubscriberKit.preferredResolution.