otc_publisher_callbacks

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.

Properties

Name	Type	Description
`user_data`	void *	A pointer to data you set related to the publisher.
`reserved`	void *	A void pointer to a memory area holding reserved resources used for the internal implementation.

Callbacks

Name	Description
`on_stream_created(publisher, user_data, stream)`	Called when the publisher's stream is created.
`on_stream_destroyed(publisher, user_data, stream)`	Called when the publisher's stream is destroyed.
`on_render_frame(publisher, user_data, frame)`	Called when there is a new frame ready to be rendered by the publisher.
`on_audio_level_updated(publisher, user_data, audio_level)`	Called periodically to report the audio level of the publisher.
`on_publisher_mute_forced(publisher, user_data)`	Called when a moderator has forced this publisher to mute audio.
`on_audio_stats(publisher, user_data, audio_stats, number_of_stats)`	Called periodically to report audio statistics for the publisher.
`on_video_stats(publisher, user_data, video_stats, number_of_stats)`	Called periodically to report video statistics for the publisher.
`on_error(publisher, user_data, error_string, error_code)`	Called when the publisher fails.
`on_video_disabled(publisher, user_data, reason)`	Called when the publisher's video is disabled.
`on_video_enabled(publisher, user_data, reason)`	Called when the publisher's video is enabled.
`on_video_disable_warning(publisher, 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.
`on_video_disable_warning_lifted(publisher, 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.
`on_network_condition_changed(publisher, user_data, stats, reason)`	This callback is invoked whenever there is a change in the quality state of the publisher's video stream.
`on_media_link_stats(publisher, user_data, media_link_stats, number_of_stats)`	Called periodically to report media link statistics for the publisher.

on_stream_created(publisher, user_data, stream)

Called when the publisher's stream is created.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`stream`	const otc_stream *	A pointer to the stream.

on_stream_destroyed(publisher, user_data, stream)

Called when the publisher's stream is destroyed.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`stream`	const otc_stream *	A pointer to the stream.

on_render_frame(publisher, user_data, 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:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`frame`	const otc_video_frame *	A pointer to the new video frame.

on_audio_level_updated(publisher, user_data, audio_level)

Called periodically to report the audio level of the publisher.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`audio_level`	float	The audio level value, from 0 to 1.0.

on_publisher_mute_forced(publisher, user_data)

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

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.

on_audio_stats(publisher, user_data, audio_stats, number_of_stats)

Called periodically to report audio statistics for the publisher.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`audio_stats`	struct otc_publisher_audio_stats []	An array of publisher audio stats.
`number_of_stats`	size_t	The number of audio stats in the array.

on_video_stats(publisher, user_data, video_stats, number_of_stats)

Called periodically to report video statistics for the publisher.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`video_stats`	struct otc_publisher_video_stats []	An array of publisher video stats.
`number_of_stats`	size_t	The number of video stats in the array.

on_error(publisher, user_data, error_string, 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:

Name	Type	Description
`publisher`	otc_publisher *	A pointer to the publisher.
`user_data`	void *	A pointer to the user_data you set for the publisher.
`error_string`	const char *	A string containing the error message.
`error_code`	enum otc_publisher_error_code	An error code enum value.

on_video_disabled(publisher, user_data, reason)

Called when the publisher's video is disabled.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`reason`	enum otc_video_reason	Gives more details about why the video has been disabled.

on_video_enabled(publisher, user_data, reason)

Called when the publisher's video is enabled.

Parameters:

Name	Type	Description
`publisher`	otc_publisher *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`reason`	enum otc_video_reason	Gives more details about why the video has been enabled.

on_video_disable_warning(publisher, 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:

Name	Type	Description
`publisher`	otc_publisher *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.

on_video_disable_warning_lifted(publisher, 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:

Name	Type	Description
`publisher`	otc_publisher *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.

on_network_condition_changed(publisher, user_data, stats, 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.

/** 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:

Name	Type	Description
`publisher`	otc_publisher *	The publisher instance triggering the event.
`user_data`	void *	Optional user data pointer passed when registering the callback.
`stats`	const struct otc_publisher_media_link_stats *	A pointer to the media link statistics for the publisher.
`reason`	enum otc_network_reason	The reason for the network condition change.

on_media_link_stats(publisher, user_data, media_link_stats, 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:

Name	Type	Description
`publisher`	otc_publisher *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`media_link_stats`	struct otc_publisher_media_link_stats []	A pointer to the media link stats struct.
`number_of_stats`	size_t