otc_subscriber_callbacks

Subscriber callback functions.

This struct is a set of function pointers to functions that can be invoked for events related to an OpenTok subscriber.

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.

Properties

Name	Type	Description
`user_data`	void *	This struct member can point to data related to the subscriber which the developer might need.
`reserved`	void *	A void pointer to a memory area holding reserved resources used for the internal implementation.

Callbacks

Name	Description
`on_connected(subscriber, user_data, stream)`	Called when the instance has successfully connected to the stream and begins playing media.
`on_disconnected(subscriber, user_data)`	Called when the subscriber's stream has been interrupted.
`on_reconnected(subscriber, user_data)`	Called when the subscriber's stream has resumed.
`on_render_frame(subscriber, user_data, frame)`	Called when a new video frame for the subscriber is ready to be rendered.
`on_video_disabled(subscriber, user_data, reason)`	Called when the subscriber's video is disabled.
`on_video_enabled(subscriber, user_data, reason)`	Called when the subscriber's video is enabled.
`on_audio_disabled(subscriber, user_data)`	Called when the subscribe's audio is disabled.
`on_audio_enabled(subscriber, user_data)`	Called when the subscriber's audio is enabled.
`on_video_data_received(subscriber, user_data)`	Called when an subscriber initially receives video data.
`on_video_disable_warning(subscriber, user_data)`	Called when the OpenTok Media Router determines that the stream quality has degraded and the video will be disabled if the quality degrades further.
`on_caption_text(subscriber, user_data, text, is_final)`	Called when caption text for the subscriber's stream is available.
`on_video_disable_warning_lifted(subscriber, user_data)`	Called when the OpenTok Media Router determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk.
`on_audio_stats(subscriber, user_data, audio_stats)`	Called periodically to report audio statistics for the subscriber.
`on_video_stats(subscriber, user_data, video_stats)`	Called periodically to report video statistics for the subscriber.
`on_audio_level_updated(subscriber, user_data, audio_level)`	Called periodically to report the audio level of the subscriber.
`on_error(subscriber, user_data, error_string, error)`	Called when the subscriber fails.
`on_audio_data(subscriber, user_data, audio_data)`	Called periodically to report the audio data of the subscriber.
`on_network_condition_changed(subscriber, user_data, media_link_stats, reason)`	This callback is invoked when a quality-related event is detected on the subscriber side.
`on_media_link_stats(subscriber, user_data, media_link_stats)`	Called periodically to report media link statistics for the subscriber.

on_connected(subscriber, user_data, stream)

Called when the instance has successfully connected to the stream and begins playing media.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`stream`	const otc_stream *	The subscriber's stream. The instance does not outlive the callback function execution. Make sure you make a copy if this instance is used later.

on_disconnected(subscriber, user_data)

Called when the subscriber's stream has been interrupted. This callback is only invoked if reconnection feature is enabled, followed by on_reconnected if the reconnection succeeds. Regular interruptions when reconnection is not enabled are notified via on_error callback.

Parameters:

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

on_reconnected(subscriber, user_data)

Called when the subscriber's stream has resumed.

Parameters:

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

on_render_frame(subscriber, user_data, frame)

Called when a new video frame for the subscriber is ready to be rendered. 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
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`frame`	const otc_video_frame *	The video frame.

on_video_disabled(subscriber, user_data, reason)

Called when the subscriber's video is disabled.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	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(subscriber, user_data, reason)

Called when the subscriber's video is enabled.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	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_audio_disabled(subscriber, user_data)

Called when the subscribe's audio is disabled.

Parameters:

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

on_audio_enabled(subscriber, user_data)

Called when the subscriber's audio is enabled.

Parameters:

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

on_video_data_received(subscriber, user_data)

Called when an subscriber initially receives video data.

Parameters:

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

on_video_disable_warning(subscriber, user_data)

Called when the OpenTok Media Router determines that the stream quality has degraded and the video will be disabled if the quality degrades further.

Parameters:

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

on_caption_text(subscriber, user_data, text, is_final)

Called when caption text for the subscriber's stream is available.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance.
`user_data`	void *	Pointer to user custom data bound to this struct.
`text`	const char *	Pointer to the caption text.
`is_final`	otc_bool	Indicates whether a caption is finished.

on_video_disable_warning_lifted(subscriber, user_data)

Called when the OpenTok Media Router determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk.

Parameters:

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

on_audio_stats(subscriber, user_data, audio_stats)

Called periodically to report audio statistics for the subscriber.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`audio_stats`	struct otc_subscriber_audio_stats	A pointer to the audio stats struct.

on_video_stats(subscriber, user_data, video_stats)

Called periodically to report video statistics for the subscriber.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`video_stats`	struct otc_subscriber_video_stats	A pointer to the video stats struct.

on_audio_level_updated(subscriber, user_data, audio_level)

Called periodically to report the audio level of the subscriber.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`audio_level`	float	The audio level value, from 0 to 1.0.

on_error(subscriber, user_data, error_string, error)

Called when the subscriber fails.

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

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`error_string`	const char *	A string containing the error message.
`error`	enum otc_subscriber_error_code	Error code enum value.

on_audio_data(subscriber, user_data, audio_data)

Called periodically to report the audio data of the subscriber. Received audio properties can change dynamically. Causes for these changes are audio codec negotiation, network conditions, etc. Consumers of the audio data are responsible for handling these changes according to the use case implemented (e.g. audio resampling).

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`audio_data`	const struct otc_audio_data *	The audio data.

on_network_condition_changed(subscriber, user_data, media_link_stats, reason)

This callback is invoked when a quality-related event is detected on the subscriber side.

The current implementation only triggers it in the event of a video interruption (pause), a codec change or a resolution change. Freezes are tracked internally and exposed via statistics, but no callback is triggered for each freeze due to their short duration and high potential frequency. A callback is triggered only when a pause is detected (e.g., no frame rendered for 5+ seconds), as it represents a more significant disruption in media playback.

The reason parameter indicates the cause of the event and is considered with the following priority order: OTC_VIDEO_REASON_VIDEO_INTERRUPT, OTC_VIDEO_REASON_CODEC_CHANGE, OTC_VIDEO_REASON_RESOLUTION_CHANGE.

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 freezes, pause counts, and updated statistics.

This callback considers all types of video interruptions lasting 5 seconds or longer. This means that, in the particular case of audio fallback or stream property changes (such as video being disabled), besides triggering the on_video_disabled and on_video_enabled callbacks, the interruption is also recorded as a pause in the video statistics, and a corresponding video interruption quality

Applications can use this callback to respond to quality issues, such as updating the UI, logging telemetry, or notifying the user.

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

The current implementation triggers this callback only when the network condition has changed for either side.

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 subscriber’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
`subscriber`	otc_subscriber *	The subscriber instance triggering the event.
`user_data`	void *	Optional user data pointer passed when registering the callback.
`media_link_stats`	const struct otc_subscriber_media_link_stats *	The media link statistics.
`reason`	enum otc_network_reason	The reason for the network condition change.

on_media_link_stats(subscriber, user_data, media_link_stats)

Called periodically to report media link statistics for the subscriber.

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

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The instance invoking this call.
`user_data`	void *	Pointer to user custom data bound to this struct.
`media_link_stats`	const struct otc_subscriber_media_link_stats *	A pointer to the media link stats struct.