subscriber.h

This file includes the type definition for an OpenTok subscriber along with several function declarations.

Data structures: otc_subscriber_audio_stats, otc_subscriber_video_stats, otc_subscriber_media_link_stats, otc_subscriber_rtc_stats_report_cb, otc_subscriber_callbacks

Includes: audio_data.h, base.h, config.h, error.h, media_utils.h, stream.h, video_frame.h

typedef otc_subscriber

OpenTok subscriber type definition.

A type representing the consumer of audio and video from a stream in the OpenTok session.

typedef struct otc_subscriber otc_subscriber;

enum otc_subscriber_error_code

Error code enumeration for OpenTok subscribers. This enumeration represents several error codes associated with a subscriber.

Name	Value	Description
`OTC_SUBSCRIBER_INTERNAL_ERROR`	`2000`	Internal error when subscribing.
`OTC_SUBSCRIBER_SESSION_DISCONNECTED`	`1010`	Attempting to subscribe to a stream in a session that you have disconnected from.
`OTC_SUBSCRIBER_SERVER_CANNOT_FIND_STREAM`	`1604`	The subscriber failed because the stream is missing. This can happen if the subscriber is created at the same time the stream is removed from the session.
`OTC_SUBSCRIBER_STREAM_LIMIT_EXCEEDED`	`1605`	The client tried to subscribe to a stream in a session that has exceeded the limit for simultaneous streams.
`OTC_SUBSCRIBER_TIMED_OUT`	`1542`	Timeout while attempting to subscribe.
`OTC_SUBSCRIBER_WEBRTC_ERROR`	`1600`	Subscriber WebRTC failure.
`OTC_SUBSCRIBER_PEER_CONNECTION_NOT_CONNECTED`	`1606`	The peer connection is not yet created or connected.
`OTC_SUBSCRIBER_CAPTIONS_CHANGE_RATE_LIMIT_ERROR`	`5010`	The server rejected a captions change request for the subscriber because too many were made in a short period of time. Operation can be retried in a few seconds.
`OTC_SUBSCRIBER_DECRYPTION_INTERNAL_ERROR`	`6002`	Internal error while decrypting a packet
`OTC_SUBSCRIBER_ENCRYPTION_SECRET_MISMATCH`	`6003`	Secret mismatch while decrypting a packet
`OTC_SUBSCRIBER_DECRYPTION_UNSUPPORTED_CODEC`	`6006`	Unsupported media codec for decryption
`OTC_SUBSCRIBER_ENCRYPTION_NOT_ENABLED`	`6007`	An encryption secret was set, but the session was not configured as end-to-end encrypted.

Functions

Name	Description
`otc_subscriber_new(stream, callbacks) → {otc_subscriber *}`	Creates a new Subscriber for a given Stream.
`otc_subscriber_delete(subscriber) → {otc_status}`	Releases a subscriber instance, including all hardware and UI resources bound to it.
`otc_subscriber_get_stream(subscriber) → {otc_stream *}`	Returns the stream associated with the subscriber.
`otc_subscriber_set_subscribe_to_video(subscriber, subscribe_to_video) → {otc_status}`	Subscribes to the stream's video.
`otc_subscriber_set_subscribe_to_audio(subscriber, subscribe_to_audio) → {otc_status}`	Subscribes to the stream's audio.
`otc_subscriber_set_subscribe_to_captions(subscriber, subscribe_to_captions) → {otc_status}`	Subscribes to captions for the stream.
`otc_subscriber_set_captions_translation_language(subscriber, language) → {otc_status}`	Sets the preferred caption translation language for a given subscriber.
`otc_subscriber_get_captions_translation_language(subscriber) → {const char *}`	Gets the configured caption translation language for a given subscriber.
`otc_subscriber_get_subscribe_to_video(subscriber) → {otc_bool}`	Returns whether the subscriber is subscribed to the stream's video or not.
`otc_subscriber_get_subscribe_to_audio(subscriber) → {otc_bool}`	Returns whether the subscriber is subscribed to the stream's audio or not.
`otc_subscriber_get_subscribe_to_captions(subscriber) → {otc_bool}`	Returns whether the subscriber is subscribed to the stream's captions or not.
`otc_subscriber_get_session(subscriber) → {otc_session *}`	Returns the `otc_session` associated this instance.
`otc_subscriber_set_preferred_resolution(subscriber, preferred_width, preferred_height) → {otc_status}`	Sets the preferred resolution for the subscriber's stream.
`otc_subscriber_get_preferred_resolution(subscriber, preferred_width, preferred_height) → {otc_status}`	Returns the preferred resolution for the subscriber's stream.
`otc_subscriber_set_audio_volume(subscriber, volume) → {otc_status}`	Sets the audio volume, between 0 and 100, of the subscriber.
`otc_subscriber_get_audio_volume(subscriber, volume) → {otc_status}`	Returns the audio volume, between 0 and 100, of the subscriber.
`otc_subscriber_set_preferred_framerate(subscriber, preferred_framerate) → {otc_status}`	Sets the preferred frame rate for the subscriber's stream.
`otc_subscriber_get_preferred_framerate(subscriber, preferred_framerate) → {otc_status}`	Returns the preferred frame rate for the subscriber's stream.
`otc_subscriber_get_subscriber_id(subscriber) → {const char *}`	Gets a unique identifier for a given subscriber.
`otc_subscriber_get_user_data(subscriber) → {void *}`	Gets user data for a given subscriber.
`otc_subscriber_get_rtc_stats_report(subscriber) → {otc_status}`	Gets the RTC stats report for the subscriber.
`otc_subscriber_set_rtc_stats_report_cb(subscriber, cb) → {otc_status}`	Sets the RTC stats report callback the subscriber.

otc_subscriber_new(stream, callbacks) → {otc_subscriber *}

Creates a new Subscriber for a given Stream.

Parameters:

Name	Type	Description
`stream`	const otc_stream *	The Stream object corresponding to the stream you will subscribe to.
`callbacks`	const struct otc_subscriber_callbacks *	Struct with function pointers of the subscriber's callbacks.

Returns:

The new Subscriber instance. This can be null if there is an error.

otc_subscriber_delete(subscriber) → {otc_status}

Releases a subscriber instance, including all hardware and UI resources bound to it. No callbacks in otc_subscriber_callbacks will be invoked as a result of invoking this method (or afterwards).

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subcriber to be deleted.

Returns:

Return value indicating either error or success.

otc_subscriber_get_stream(subscriber) → {otc_stream *}

Returns the stream associated with the subscriber.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance to get the stream from.

Returns:

The stream associated with the subscriber. This can be null if there is an error.

otc_subscriber_set_subscribe_to_video(subscriber, subscribe_to_video) → {otc_status}

Subscribes to the stream's video.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance which will be affected.
`subscribe_to_video`	otc_bool	Whether to subscribe to video or not.

Returns:

Return value indicating either error or success.

otc_subscriber_set_subscribe_to_audio(subscriber, subscribe_to_audio) → {otc_status}

Subscribes to the stream's audio.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance which will be affected.
`subscribe_to_audio`	otc_bool	Whether to subscribe to audio or not.

Returns:

Return value indicating either error or success.

otc_subscriber_set_subscribe_to_captions(subscriber, subscribe_to_captions) → {otc_status}

Subscribes to captions for the stream.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance which will be affected.
`subscribe_to_captions`	otc_bool	Whether to subscribe to captions or not.

Returns:

Return value indicating either error or success.

otc_subscriber_set_captions_translation_language(subscriber, language) → {otc_status}

Sets the preferred caption translation language for a given subscriber.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance which will be affected.
`language`	const char *	A supported language code or null to disable translation.

Returns:

Return value indicating either error or success.

otc_subscriber_get_captions_translation_language(subscriber) → {const char *}

Gets the configured caption translation language for a given subscriber.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

The configured language for translation. It can be null if it isn't set.

otc_subscriber_get_subscribe_to_video(subscriber) → {otc_bool}

Returns whether the subscriber is subscribed to the stream's video or not.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

Whether the subscriber is subscribed to the stream's video or not.

otc_subscriber_get_subscribe_to_audio(subscriber) → {otc_bool}

Returns whether the subscriber is subscribed to the stream's audio or not.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

Whether the subscriber is subscribed to the stream's audio or not.

otc_subscriber_get_subscribe_to_captions(subscriber) → {otc_bool}

Returns whether the subscriber is subscribed to the stream's captions or not.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

Whether the subscriber is subscribed to the stream's captions or not. The default value is the captions value of the stream's publisher otc_publisher_get_publish_captions

otc_subscriber_get_session(subscriber) → {otc_session *}

Returns the otc_session associated this instance.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

The otc_session associated this instance. This can be null if there is an error.

otc_subscriber_set_preferred_resolution(subscriber, preferred_width, preferred_height) → {otc_status}

Sets the preferred resolution for the subscriber's stream.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance which will be affected.
`preferred_width`	uint32_t	The preferred width of the subscriber.
`preferred_height`	uint32_t	The preferred height of the subscriber.

See: : - otc_error_code

Returns:

Return value indicating either error or success.

otc_subscriber_get_preferred_resolution(subscriber, preferred_width, preferred_height) → {otc_status}

Returns the preferred resolution for the subscriber's stream.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.
`preferred_width`	uint32_t *	The preferred width of the subscriber.
`preferred_height`	uint32_t *	The preferred height of the subscriber.

See: : - otc_error_code

Returns:

Return value indicating either error or success.

otc_subscriber_set_audio_volume(subscriber, volume) → {otc_status}

Sets the audio volume, between 0 and 100, of the subscriber. If the value is not in this range, it will be clamped to it.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance.
`volume`	double	The volume of the subscriber.

See: : - otc_error_code

Returns:

Return value indicating either error or success.

otc_subscriber_get_audio_volume(subscriber, volume) → {otc_status}

Returns the audio volume, between 0 and 100, of the subscriber.

The default value is 100.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.
`volume`	double *	The volume of the subscriber.

See: : - otc_error_code

Returns:

Return value indicating either error or success.

otc_subscriber_set_preferred_framerate(subscriber, preferred_framerate) → {otc_status}

Sets the preferred frame rate for the subscriber's stream.

The default value is 100.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance which will be affected.
`preferred_framerate`	float	The preferred framerate of the subscriber.

See: : - otc_error_code

Returns:

Return value indicating either error or success.

otc_subscriber_get_preferred_framerate(subscriber, preferred_framerate) → {otc_status}

Returns the preferred frame rate for the subscriber's stream.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.
`preferred_framerate`	float *	The preferred framerate associated with the subscriber.

See: : - otc_error_code

Returns:

Return value indicating either error or success.

otc_subscriber_get_subscriber_id(subscriber) → {const char *}

Gets a unique identifier for a given subscriber.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

A unique identifier for the subscriber. This can be null if there is an error.

otc_subscriber_get_user_data(subscriber) → {void *}

Gets user data for a given subscriber.

Parameters:

Name	Type	Description
`subscriber`	const otc_subscriber *	The subscriber instance.

Returns:

A pointer to the user data in memory.

otc_subscriber_get_rtc_stats_report(subscriber) → {otc_status}

Gets the RTC stats report for the subscriber. This is an asynchronous operation. create an otc_subscriber_rtc_stats_report_cb struct and pass it into the otc_subscriber_set_rtc_stats_report_cb function prior to calling this function. When the stats are available, the otc_subscriber_set_rtc_stats_report_cb callback function is called.

Also see otc_subscriber_callbacks.on_audio_stats, otc_subscriber_callbacks.on_video_stats, and otc_publisher_get_rtc_stats_report.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber.

Returns:

otc_status

otc_subscriber_set_rtc_stats_report_cb(subscriber, cb) → {otc_status}

Sets the RTC stats report callback the subscriber. See otc_subscriber_get_rtc_stats_report.

Parameters:

Name	Type	Description
`subscriber`	otc_subscriber *	The subscriber instance.
`cb`	struct otc_subscriber_rtc_stats_report_cb	The otc_subscriber_rtc_stats_report_cb struct that includes the callback function for the RTC stats report.

Returns:

otc_status