otc_publisher_callbacks Struct Reference

#include <publisher.h>

Data Fields
void(*	on_stream_created )(otc_publisher *publisher, void *user_data, const otc_stream *stream)
void(*	on_stream_destroyed )(otc_publisher *publisher, void *user_data, const otc_stream *stream)
void(*	on_render_frame )(otc_publisher *publisher, void *user_data, const otc_video_frame *frame)
void(*	on_audio_level_updated )(otc_publisher *publisher, void *user_data, float audio_level)
void(*	on_publisher_mute_forced )(otc_publisher *publisher, void *user_data)
void(*	on_audio_stats )(otc_publisher *publisher, void *user_data, struct otc_publisher_audio_stats audio_stats[], size_t number_of_stats)
void(*	on_video_stats )(otc_publisher *publisher, void *user_data, struct otc_publisher_video_stats video_stats[], size_t number_of_stats)
void(*	on_error )(otc_publisher *publisher, void *user_data, const char *error_string, enum otc_publisher_error_code error_code)
void(*	on_video_disabled )(otc_publisher *publisher, void *user_data, enum otc_video_reason reason)
void(*	on_video_enabled )(otc_publisher *publisher, void *user_data, enum otc_video_reason reason)
void(*	on_video_disable_warning )(otc_publisher *publisher, void *user_data)
void(*	on_video_disable_warning_lifted )(otc_publisher *publisher, void *user_data)
void(*	on_network_condition_changed )(otc_publisher *publisher, void *user_data, const struct otc_publisher_media_link_stats *stats, enum otc_network_reason reason)
void(*	on_media_link_stats )(otc_publisher *publisher, void *user_data, struct otc_publisher_media_link_stats media_link_stats[], size_t number_of_stats)
void *	user_data
void *	reserved

Detailed Description

Publisher callback functions.

This structure is a set of function pointers to callback functions that can be called in response to events related to an OpenTok publisher.

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.

Data passed into a callback function (other than publisher and user_data) will be released after the callback is called. Make a copy of the data if you need to retain it.

Field Documentation

on_audio_level_updated

void(* on_audio_level_updated) (otc_publisher *publisher, void *user_data, float audio_level)

Called periodically to report the audio level of the publisher.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
audio_level	The audio level value, from 0 to 1.0.

on_audio_stats

void(* on_audio_stats) (otc_publisher *publisher, void *user_data, struct otc_publisher_audio_stats audio_stats[], size_t number_of_stats)

Called periodically to report audio statistics for the publisher.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
audio_stats	An array of publisher audio stats.
number_of_stats	The number of audio stats in the array.

on_error

void(* on_error) (otc_publisher *publisher, void *user_data, const char *error_string, enum otc_publisher_error_code error_code)

Called when the publisher fails.

Most errors are fatal: the publisher is automatically dropped and can no longer be used. Some errors are continuable and leave the publisher usable; when an error is non-fatal it is stated in the error description.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
error_string	A string containing the error message.
error_code	An error code enum value.

on_media_link_stats

void(* on_media_link_stats) (otc_publisher *publisher, void *user_data, struct otc_publisher_media_link_stats media_link_stats[], size_t number_of_stats)

Called periodically to report media link statistics for the publisher.

Media link statistics provide a unified view of the transport-level network conditions.

Parameters

publisher	The instance invoking this call.
user_data	Pointer to user custom data bound to this struct.
media_link_stats	A pointer to the media link stats struct.

on_network_condition_changed

void(* on_network_condition_changed) (otc_publisher *publisher, void *user_data, const struct otc_publisher_media_link_stats *stats, enum otc_network_reason reason)

This callback is invoked whenever there is a change in the quality state of the publisher's video stream. It provides information about the event, updated statistics and a reason code indicating why the event occurred.

The reason parameter indicates the cause of the event and is considered with the following priority order: bandwidth degradation, CPU degradation, other quality degradation reasons, codec changes, resolution or layer changes.

This event differs from on_video_disabled and on_video_enabled callbacks in that it reports video quality relevant changes. on_video_disabled and `on_video_enabled only indicate that the subscriber’s video track has been turned on or off (for example, due to a stream property update or audio-fallback). In contrast, this event provides diagnostic information about quality degradation causes—such as CPU or bandwidth limitations—and is also triggered when the video remains enabled.

Applications can use this callback to monitor quality changes and react accordingly, such as adjusting UI elements or triggering alerts.

Parameters

publisher	The instance invoking this call.
stats	Updated statistics including details about resolution or video layers change
user_data	Optional user data pointer passed when registering the callback.
reason	The reason code for the quality event, based on otc_video_reason enum. */ void (on_video_quality_changed)(struct otc_publisher publisher, void* user_data, const struct otc_publisher_video_stats* stats, enum otc_video_reason reason);

/** This callback is invoked when a network condition change is detected for the publisher.

The reason parameter indicates the cause of the event and is currently always OTC_NETWORK_REASON_NETWORK_CONDITION_CHANGE.

This event differs from on_video_disabled and on_video_enabled callbacks in that it reports network health changes rather than changes in the publisher’s video track state. Applications can use this callback to respond to network issues, such as updating UI, logging telemetry, or triggering adaptive behavior.

Parameters

publisher	The publisher instance triggering the event.
user_data	Optional user data pointer passed when registering the callback.
stats	A pointer to the media link statistics for the publisher.
reason	The reason for the network condition change.

on_publisher_mute_forced

void(* on_publisher_mute_forced) (otc_publisher *publisher, void *user_data)

Called when a moderator has forced this publisher to mute audio.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.

on_render_frame

void(* on_render_frame) (otc_publisher *publisher, void *user_data, const otc_video_frame *frame)

Called when there is a new frame ready to be rendered by the publisher. Do not call any OpenTok API functions (except those in video_frame.h) on the same thread that invokes this callback. If you need to call an OpenTok API function (for example, functions in publisher.h or subscriber.h), reschedule its execution to a different thread.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
frame	A pointer to the new video frame.

on_stream_created

void(* on_stream_created) (otc_publisher *publisher, void *user_data, const otc_stream *stream)

Called when the publisher's stream is created.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
stream	A pointer to the stream.

on_stream_destroyed

void(* on_stream_destroyed) (otc_publisher *publisher, void *user_data, const otc_stream *stream)

Called when the publisher's stream is destroyed.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
stream	A pointer to the stream.

on_video_disable_warning

void(* on_video_disable_warning) (otc_publisher *publisher, void *user_data)

Called when the publisher determines that the network congestion level has degraded and the video will be disabled if the quality degrades further.

Parameters

publisher	The instance invoking this call.
user_data	Pointer to user custom data bound to this struct.

on_video_disable_warning_lifted

void(* on_video_disable_warning_lifted) (otc_publisher *publisher, void *user_data)

Called when the publisher determines that the network congestion level has improved to the point at which the video being disabled is not an immediate risk.

Parameters

publisher	The instance invoking this call.
user_data	Pointer to user custom data bound to this struct.

on_video_disabled

void(* on_video_disabled) (otc_publisher *publisher, void *user_data, enum otc_video_reason reason)

Called when the publisher's video is disabled.

Parameters

publisher	The instance invoking this call.
user_data	Pointer to user custom data bound to this struct.
reason	Gives more details about why the video has been disabled.

on_video_enabled

void(* on_video_enabled) (otc_publisher *publisher, void *user_data, enum otc_video_reason reason)

Called when the publisher's video is enabled.

Parameters

publisher	The instance invoking this call.
user_data	Pointer to user custom data bound to this struct.
reason	Gives more details about why the video has been enabled.

on_video_stats

void(* on_video_stats) (otc_publisher *publisher, void *user_data, struct otc_publisher_video_stats video_stats[], size_t number_of_stats)

Called periodically to report video statistics for the publisher.

Parameters

publisher	A pointer to the publisher.
user_data	A pointer to the user_data you set for the publisher.
video_stats	An array of publisher video stats.
number_of_stats	The number of video stats in the array.

reserved

void* reserved

A void pointer to a memory area holding reserved resources used for the internal implementation.

user_data

void* user_data

A pointer to data you set related to the publisher.

---

The documentation for this struct was generated from the following file:

• src/otkit/include/opentok/publisher.h