Suggestions

close search

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

Visit the Vonage API Developer Portal

Subscribing to streams — macOS

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:

Detecting streams in a session

The on_stream_received callback function of the otc_session_callbacks struct is called when a stream published by another client is created in a session. (A stream is created when a client publishes a stream to the session or if the stream exists when you connect to the session.) See Instantiating an otc_session instance and session-related callbacks.

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

Subscribing to a stream

The on_stream_received callback function (see the previous section) includes a stream parameter, which is a pointer to an otc_stream struct representing the new stream. To subscribe to the stream, instantiate a otc_subscriber_callbacks instance, set some callback functions for subscriber-related events, and then call the otc_subscriber_new() function passing in the otc_stream and otc_subscriber_callbacks instances

char *user_data = strdup("Session user data");

static void on_subscriber_connected(otc_subscriber *subscriber,
                                    void *user_data,
                                    const otc_stream *stream) {
  // Called when the subscriber connects to the stream.
}

static void on_render_frame(otc_subscriber *subscriber,
                            void *user_data,
                            const otc_video_frame *frame) {
  // Called when the the subscriber is ready to render a new video frame
}

static void on_error(otc_subscriber *subscriber,
                     void *user_data) {
  // Called when there is an error.
}

struct otc_subscriber_callbacks subscriber_callbacks = {0};
subscriber_callbacks.user_data = user_data;
subscriber_callbacks.on_connected = on_subscriber_connected;
subscriber_callbacks.on_render_frame = on_subscriber_render_frame;
subscriber_callbacks.on_error = on_subscriber_error;

otc_subscriber *subscriber = otc_subscriber_new(stream,
                                                &subscriber_callbacks);
if (subscriber == NULL) {
  printf("Could not create OpenTok subscriber successfully");
  return;
}

if (otc_session_subscribe(session, subscriber) != OTC_SUCCESS) {
  printf("Could not subscribe successfully.");
}

Use the user_data member of the otc_subscriber_callbacks structure to set data you may want to reference in the callback functions. In this example, we set it to a pointer to a string object. But it could be a pointer to an instance of some other type that contains meaningful information.

The other members of the otc_subscriber_callbacks structure are each callback functions that are invoked when events related to the subscriber occur:

All callbacks will not be made on the application or main thread but on an internal thread. The application should return the callback as quickly as possible to avoid blocking the internal thread.

See otc_subscriber_callbacks in the OpenTok macOS SDK reference for details on each of the callback functions.

Unsubscribing from a stream

To stop playing a stream you are subscribed to, call the otc_session_unsubscribe() function, passing in the otc_session and otc_subscriber instances:

if (session.unsubscribe(session, subscriber) ==  OTC_SUCCESS) {
  printf("Unsubscribed from the stream successfully.");
  otc_subscriber_delete(subscriber);
} else {
  printf("Could not unsubscribe successfully.");
};

Call the otc_subscriber_delete() function to release the subscriber instance, including all hardware and UI resources bound to it.

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 on_disconnected callback function of the otc_subscriber_callbacks struct for the subscriber is called. When the connection is restored, the on_reconnected callback function of the otc_subscriber_callbacks struct for the subscriber is called. If the client cannot restore the stream, the on_stream_dropped callback function of the otc_session_callbacks struct is called.

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

Detecting when streams leave a session

The on_stream_dropped callback function of the otc_session_callbacks struct is called when another client's stream is dropped from the OpenTok session. The stream parameter passed into this function is a pointer to an otc_stream struct for the stream. Call the otc_stream_get_id() method, passing in the otc_stream struct, to get the stream ID.

Detecting when a stream's video is disabled

The on_stream_has_video_changed callback function of the otc_session_callbacks struct is called when another client's stream is dropped from the OpenTok session. The stream parameter passed into this function is a pointer to an otc_stream struct for the stream. Call the otc_stream_get_id() method, passing in the otc_stream struct, to get the stream ID.

Getting information about a stream

Call the following functions to get information about a stream:

Use the on_audio_stats() and on_video_stats() callback functions of the otc_subscriber_callbacks to monitor the following statistics for a subscriber's stream:

To get more detailed stream statics, use the otc_subscriber_get_rtc_stats_report() function. This provides an RTC stats report for the media stream. This is an asynchronous operation. Create an otc_subscriber_rtc_stats_report_cb struct and pass it into the otc_subscriber_set_rtc_stats_report_cb function prior to calling otc_subscriber_get_rtc_stats_report(). When the stats are available, the otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report callback function is called. This callback function includes a json_array_of_reports 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. Use the otc_subscriber_set_preferred_framerate() and otc_subscriber_set_preferred_resolution functions.