Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalOnce 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:
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.
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:
on_connected — Called when the subscriber connects to the
audio-video stream.
on_render_frame — Called each time the subscriber is ready to render
a new video frame.
on_error — Called when a subscriber error occurs.
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.
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.
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:
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.
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.
Call the following functions to get information about a stream:
otc_stream_get_connection()— Returns the otc_connection
instance corresponding to the connection that is publishing the stream. You can compare
the connection ID for this to the connection ID for the otc_connection
instance returned by the otc_session_get_connection() function to see
if the stream is being published by your client.
otc_stream_get_creation_time()— Returns the timestamp for
the creation time of the stream.
otc_stream_has_audio()— Whether the stream is currently publishing audio.
otc_stream_has_video()— Whether the stream is currently publishing video.
otc_stream_has_audio_track()— Whether the stream has an audio track.
otc_stream_has_video_track()— Whether the stream has a video track.
otc_stream_get_name()— Returns the name of the stream. This is set
when you initialize the Publisher of the stream (see
Initializing
an otc_publisher struct and setting publisher callbacks).
otc_stream_get_id()— Returns the unique ID for the stream.
otc_stream_get_video_height()— The height of the stream, in pixels.
otc_stream_get_video_type()— Whether the stream uses a camera video
source (OTC_STREAM_VIDEO_TYPE_CAMERA) or a screen-sharing video source
(OTC_STREAM_VIDEO_TYPE_SCREEN).
otc_stream_get_video_width()— The width of the stream, in pixels.
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.
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.