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 (Swift)

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 OTSubscriberDelegate subscriberDidDisconnect(fromStream:) message is sent to the OTSubscriber object's delegate. When the connection is restored, the OTSubscriberDelegate subscriberDidReconnect(toStream:) 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:
func subscriberDidDisconnect(fromStream subscriber: OTSubscriberKit) {
  // Display a user interface notification.
}

func subscriberDidReconnect(toStream subscriber: OTSubscriberKit) {
  // Adjust user interface.
}

// OTSession delegate callback:
func session(_ session: OTSession, streamDestroyed stream: OTStream) {
  // Adjust user interface.
}

Detecting streams in a session

The OTSessionDelegate session(_ 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: 

func session(_ session: OTSession, streamCreated stream: OTStream) {
    print("Session streamCreated: \(stream.streamId)")

    // See the declaration of subscribeToSelf above.
    if stream.connection.connectionId == 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 init(stream:delegate:) method, passing in an OTStream object and a delegate object to receive subscriber-related messages. Then call theOTSession subscribe(_:error:) method to start subscribing to the stream: 

func session(_ session: OTSession, streamCreated stream: OTStream) {
    subscriber = OTSubscriber(stream: stream, delegate: self)
    var error: OTError?
	session.subscribe(subscriber!, error: &error)
	
    if error {
      print("subscribe failed with error: \(error)")
    }
}

The OTSubscriberDelegate subscriberDidConnect(toStream:) 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: 

func subscriberDidConnect(toStream subscriber: OTSubscriberKit) {
	if let subscriberView = self.subscriber?.view {
		subscriberView.frame = CGRect(x: 0, y: 300, width: 400, height: 300)
		self.view.addSubview(subscriberView)
	}
}

Unsubscribing from a stream

To stop playing a stream you are subscribed to, call the OTSession unsubscribe(_:error:) method:

var error: OTError?
session.unsubscribe(subscriber, error: &error)
if (error) {
    print("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. 

func session(_ session: OTSession, streamDestroyed stream: OTStream) {
    print("Session streamDestroyed: \(stream.streamId)")

    if subscriber?.stream?.streamId == 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: 

func subscriberVideoDisabled(_ subscriber: OTSubscriberKit, reason: OTSubscriberVideoEventReason) {
    print("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 OTSubscriberDelegate subscriberVideoEnabled(_:reason:) message is sent.

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

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

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.