Once you have connected to a session, you can publish a stream that other clients connected to the session can view.
This topic includes the following sections:
Start by creating a structure of type otc_publisher_callbacks
:
char *publisher_user_data = strdup("Publisher user data");
static void on_publisher_stream_created(otc_publisher *publisher,
void *user_data,
const otc_stream *stream) {
// The stream has been created.
}
static void on_publisher_render_frame(otc_publisher *publisher,
void *user_data,
const otc_video_frame *frame) {
// You can render the frame to the UI.
}
static void on_publisher_stream_destroyed(otc_publisher *publisher,
void *user_data,
const otc_stream *stream) {
// The stream has been destroyed.
}
static void on_publisher_error(otc_publisher *publisher,
void *user_data,
const char* error_string,
enum otc_publisher_error_code error_code) {
// Handle the error.
}
struct otc_publisher_callbacks publisher_callbacks = {0};
publisher_callbacks.user_data = publisher_user_data;
publisher_callbacks.on_stream_created = on_publisher_stream_created;
publisher_callbacks.on_render_frame = on_publisher_render_frame;
publisher_callbacks.on_stream_destroyed = on_publisher_stream_destroyed;
publisher_callbacks.on_error = on_publisher_error;
Use the user_data
member of the otc_publisher_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 char array. But it could be a pointer to an instance of some other type
that contains meaningful information.
The other members of the otc_publisher_callbacks
structure are each callback
functions that are invoked when events related to the published stream occur:
on_stream_created
— Called when the publisher starts streaming
to the session.
on_render_frame
— Called each time the publisher is ready to render
a new video frame to the stream.
on_stream_destroyed
— Called when the publisher's stream is destroyed.
on_error
— Called when an error occurs in publishing the stream.
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_publisher_callbacks in the OpenTok macOS SDK reference for details on each of the callback functions.
Call the otc_publisher_new()
to create an otc_publisher
structure,
which represents the OpenTok publisher:
publisher = otc_publisher_new("Bob's video",
NULL, /* Use the system camera. */
&publisher_callbacks);
if (publisher == NULL) {
printf("Could not create OpenTok publisher successfully");
otc_session_delete(session);
otc_destroy();
return EXIT_FAILURE;
}
The otc_publisher_new()
method takes
three arguments:
name
— A name (optional) identifying the publisher of the stream.
capturer
— Use this parameter if you want to provide a custom video capturer.
If it is set to NULL
, the publisher uses the default system camera as the video source.
See Using a custom
video capturer to see how to implement a custom video capturer.)
callbacks
— The otc_publisher_callbacks
publisher callback structure,
described above.
You can create a custom audio driver to be used by all publishers and subscribers.
You can use a custom video capturer to publish a stream with a customized video source — see Using a custom video capturer.
When the application connects to the OpenTok session, the
on_connected()
callback function of the otc_session_callbacks
struct is called (see Joining
a Session). In response to this, you can call the otc_session_publish()
function to publish a stream to the OpenTok session:
if (otc_session_publish(session, publisher) != OTC_SUCCESS) {
printf("Could not publish successfully.");
}
The otc_session_publish()
function takes two arguments:
otc_session
structure.
otc_publisher
structure.
It returns OTC_SUCCESS
when it successfully starts publishing
a stream to the session. Or it returns an error, and the
otc_error
callback is called.
To stop a publisher's stream, call the otc_session_unpublish()
function, passing in the otc_session
and otc_publisher
structs:
otc_status status = otc_session_unpublish(session, publisher);
if (status == OTC_SUCCESS) {
printf("Unpublished successfully.");
} else {
printf("Could not unpublish.");
}
To register callbacks methods for periodic reports of audio and video statistics
for a publisher, set the
on_audio_stats()
and
on_video_stats()
callback functions
when you initialize the otc_publisher_callbacks
struct to be
used by the publisher. See Initializing an otc_publisher
struct and setting publisher callbacks.
These callback functions are called periodically to report audio and video statistics
for the publisher. Each function is passed in the following: A pointer to the publisher
struct,
A pointer to the user_data
you set for the publisher,
an array of stats, and the number of stats in the array. The stats parameter
is defined by the
otc_publisher_audio_stats
and
otc_publisher_video_stats
structs. For a publisher in
a routed session (one that uses the
OpenTok
Media Router), the array includes one object, defining the statistics for
the single audio or video media stream that is sent to the OpenTok Media Router.
In a relayed session, the array includes an object for each subscriber to
the published stream. The struct passed in as the stats parameter includes
the following properties:
Additionally, for a publisher in a relayed session, each object in the array contains the following two properties:
ConnectionId
— The connection ID of the client subscribing to the streamSubscriberId
— The subscriber ID of the client subscribing to the streamThese two properties are undefined for a publisher in a routed session.
To get more detailed stream statics, use the
otc_publisher_get_rtc_stats_report()
function. This provides
RTC stats reports for the media stream.
This is an asynchronous operation. Create an
otc_publisher_rtc_stats_report_cb struct
and pass it into the
otc_publisher_set_rtc_stats_report_cb
function prior to calling otc_publisher_get_rtc_stats_report()
. When the stats are available,
the otc_publisher_rtc_stats_report_cb.on_rtc_stats_report()
callback function is called.
This function includes a stats
parameter, which is a pointer to an array of
otc_publisher_rtc_stats
structs. This struct includes a
json_array_of_reports
property. 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.