Suggestions

close search

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

Visit the Vonage API Developer Portal

Subscribing to streams — Linux

Once 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 Linux 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:

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.