Suggestions

close search

Searching ...

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:

• Initializing an otc_publisher struct and setting publisher callbacks
• Publishing a stream
• Stopping a publisher from streaming
• Getting statistics about a publisher's stream

Initializing an otc_publisher struct and setting publisher callbacks

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

Publishing a stream

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:

• The pointer to the otc_session structure.
• The 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.

Stopping a publisher from streaming

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.");
}

Getting statistics about a publisher's stream

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:

• The total number of audio or video packets sent
• The total number of audio or video packets lost
• The total number of audio or video bytes sent
• The timestamp for when the stats were gathered
• The audio level (for audio stats)

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 stream
• SubscriberId — The subscriber ID of the client subscribing to the stream

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