OpenTok Publisher. More...

#include "base.h"
#include "config.h"
#include "stream.h"
#include "video_frame.h"
#include "camera_capture_resolution.h"
#include "media_transformer.h"
#include "video_capturer.h"
#include "media_utils.h"

Data Structures
struct	otc_publisher_video_layer_stats
struct	otc_publisher_audio_stats
struct	otc_publisher_video_stats
struct	otc_publisher_media_link_stats
struct	otc_publisher_callbacks
struct	otc_publisher_rtc_stats
struct	otc_publisher_rtc_stats_report_cb

Macros
#define	OTC_MAX_VIDEO_LAYERS 3

Typedefs
typedef struct otc_publisher	otc_publisher
typedef struct otc_publisher_settings	otc_publisher_settings

Enumerations
enum	otc_publisher_error_code { OTC_PUBLISHER_INTERNAL_ERROR = 2000 , OTC_PUBLISHER_SESSION_DISCONNECTED , OTC_PUBLISHER_TIMED_OUT = 1541 , OTC_PUBLISHER_UNABLE_TO_PUBLISH = 1500 , OTC_PUBLISHER_WEBRTC_ERROR = 1610 , OTC_PUBLISHER_CAPTIONS_CHANGE_RATE_LIMIT_ERROR = 5010 , OTC_PUBLISHER_ENCRYPTION_INTERNAL_ERROR , OTC_PUBLISHER_ENCRYPTION_UNSUPPORTED_CODEC = 6005 , OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED }
enum	otc_publisher_video_type { OTC_PUBLISHER_VIDEO_TYPE_CAMERA = 1 , OTC_PUBLISHER_VIDEO_TYPE_SCREEN = 2 }
enum	otc_media_type { OTC_MEDIA_TYPE_VIDEO = 0 , OTC_MEDIA_TYPE_AUDIO }
	Media type.
enum	otc_video_bitrate_preset { OTC_VIDEO_BITRATE_PRESET_DEFAULT , OTC_VIDEO_BITRATE_PRESET_BW_SAVER , OTC_VIDEO_BITRATE_PRESET_EXTRA_BW_SAVER , OTC_VIDEO_BITRATE_PRESET_CUSTOM }
	Preset strategies for controlling video bitrate in a publisher's stream. More...
enum	otc_degradation_preference { OTC_DEGRADATION_PREFERENCE_NOT_SET = -1 , OTC_DEGRADATION_PREFERENCE_MAINTAIN_FRAMERATE_AND_RESOLUTION = 0 , OTC_DEGRADATION_PREFERENCE_MAINTAIN_FRAMERATE = 1 , OTC_DEGRADATION_PREFERENCE_MAINTAIN_RESOLUTION = 2 , OTC_DEGRADATION_PREFERENCE_BALANCED = 3 }
	Describes the policy that the video engine will try to follow when adapting frame rate and resolution to limited bandwidth and CPU. This is a best effort policy. There are no guarantees on the frame rate and some frames can still be skipped for other reasons. More...

Functions
otc_publisher *	otc_publisher_new (const char name, const struct otc_video_capturer_callbacks capturer, const struct otc_publisher_callbacks *callbacks)
otc_publisher_settings *	otc_publisher_settings_new ()
otc_status	otc_publisher_settings_delete (otc_publisher_settings *settings)
otc_status	otc_publisher_settings_set_name (otc_publisher_settings settings, const char name)
otc_status	otc_publisher_settings_set_video_capturer (otc_publisher_settings settings, const struct otc_video_capturer_callbacks capturer)
otc_status	otc_publisher_settings_set_audio_track (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_video_track (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_sender_stats_track (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_stereo (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_opus_dtx (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_auto_gain_control (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_noise_suppression (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_echo_cancellation (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_disable_audio_processing (otc_publisher_settings *settings, otc_bool disabled)
otc_status	otc_publisher_settings_set_default_camera_capture_resolution (otc_publisher_settings *settings, const enum otc_camera_capture_resolution camera_capture_resolution)
otc_status	otc_publisher_settings_set_scalable_screenshare (otc_publisher_settings *settings, const otc_bool enabled)
otc_status	otc_publisher_settings_set_allow_audio_capture_while_muted (otc_publisher_settings *settings, const otc_bool enabled)
otc_publisher *	otc_publisher_new_with_settings (const struct otc_publisher_callbacks callbacks, otc_publisher_settings settings)
	otc_statusotc_publisher_delete (otc_publisher *publisher)
otc_stream *	otc_publisher_get_stream (otc_publisher *publisher)
otc_status	otc_publisher_set_publish_video (otc_publisher *publisher, otc_bool publish_video)
otc_status	otc_publisher_set_publish_audio (otc_publisher *publisher, otc_bool publish_audio)
otc_status	otc_publisher_set_publish_captions (otc_publisher *publisher, otc_bool publish_captions)
otc_bool	otc_publisher_get_publish_video (const otc_publisher *publisher)
otc_bool	otc_publisher_get_publish_audio (const otc_publisher *publisher)
otc_bool	otc_publisher_get_publish_captions (const otc_publisher *publisher)
otc_status	otc_publisher_set_captions_input_language (otc_publisher publisher, const char language)
const char *	otc_publisher_get_captions_input_language (const otc_publisher *publisher)
otc_session *	otc_publisher_get_session (const otc_publisher *publisher)
otc_status	otc_publisher_set_max_audio_bitrate (otc_publisher *publisher, uint32_t bitrate)
	otc_statusotc_publisher_set_rtc_stats_report_cb (otc_publisher *publisher, const struct otc_publisher_rtc_stats_report_cb cb)
	otc_statusotc_publisher_get_rtc_stats_report (otc_publisher *publisher)
const char *	otc_publisher_get_publisher_id (const otc_publisher *publisher)
otc_status	otc_publisher_set_video_type (struct otc_publisher *publisher, enum otc_publisher_video_type video_type)
enum otc_publisher_video_type	otc_publisher_get_video_type (const struct otc_publisher *publisher)
void *	otc_publisher_get_user_data (const struct otc_publisher *publisher)
const char *	otc_publisher_get_name (const struct otc_publisher *publisher)
otc_status	otc_publisher_set_video_transformers (otc_publisher publisher, otc_video_transformer *transformers, uint8_t size)
	Sets an array of video transformers to this publisher's video stream. If null resets transformers.
otc_status	otc_publisher_set_audio_transformers (otc_publisher publisher, otc_audio_transformer *transformers, uint8_t size)
	Sets an array of audio transformers to this publisher's audio stream. If null resets transformers.
otc_status	otc_publisher_set_target_scalability_mode (otc_publisher publisher, const char scalability_mode)
	Sets the target scalability mode (SVC - Scalable Video Coding) for this publisher. The scalability mode controls the number of spatial (resolution) and temporal (frame rate) layers that WebRTC encodes. The mode is applied to the routed (publisher ↔ SFU) peer connection only, regardless of which leg is currently active.
const char *	otc_publisher_get_target_scalability_mode (otc_publisher *publisher)
	Gets the target scalability mode that was explicitly set via `otc_publisher_set_target_scalability_mode`. Returns the last value passed to the setter, or NULL if the setter has never been called. This reflects the user's intent, not the mode actually applied (which may differ due to codec-dependent fallback).
otc_status	otc_publisher_set_max_video_bitrate (otc_publisher *publisher, int bitrate_bps)
	Gets the maximum video bitrate set for this publisher's video stream.
int	otc_publisher_get_max_video_bitrate (const otc_publisher *publisher)
	Gets the maximum video bitrate set for this publisher's video stream.
otc_status	otc_publisher_set_video_bitrate_preset (otc_publisher *publisher, enum otc_video_bitrate_preset preset)
	Sets a video bitrate preset for this publisher's video stream.
enum otc_video_bitrate_preset	otc_publisher_get_video_bitrate_preset (const otc_publisher *publisher)
	Gets the currently active video bitrate preset for this publisher's stream.
otc_status	otc_publisher_set_degradation_preference (otc_publisher *publisher, enum otc_degradation_preference degradation_preference)
	Sets the preferred policy that the video engine will follow when adjusting frame rate and resolution to limited bandwidth and CPU conditions. See otc_degradation_preference for a description of the possible values.
enum otc_degradation_preference	otc_publisher_get_degradation_preference (const otc_publisher *publisher)
	Gets the preferred policy that the video engine will follow when adjusting frame rate and resolution to limited bandwidth and CPU conditions. See otc_degradation_preference for a description of the possible values.
otc_status	otc_publisher_settings_set_subscriber_audio_fallback_enabled (otc_publisher_settings *settings, const otc_bool enabled)
otc_status	otc_publisher_settings_set_publisher_audio_fallback_enabled (otc_publisher_settings *settings, const otc_bool enabled)
otc_status	otc_publisher_settings_set_preferred_video_codecs (otc_publisher_settings settings, const otc_video_codec_type codecs, size_t num_codecs)
	Sets the preferred video codecs to use for this publisher's stream.
otc_status	otc_publisher_settings_set_preferred_video_codecs_automatic (otc_publisher_settings *settings)
	Enables automatic codec prioritization for this publisher's stream.

Detailed Description

OpenTok Publisher.

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

Typedef Documentation

◆ otc_publisher

typedef struct otc_publisher otc_publisher

OpenTok publisher type definition.

A type representing a publisher of an audio-video stream to an OpenTok session.

◆ otc_publisher_settings

typedef struct otc_publisher_settings otc_publisher_settings

OpenTok publisher settings type definition.

Enumeration Type Documentation

◆ otc_degradation_preference

enum otc_degradation_preference

Describes the policy that the video engine will try to follow when adapting frame rate and resolution to limited bandwidth and CPU. This is a best effort policy. There are no guarantees on the frame rate and some frames can still be skipped for other reasons.

For details, see Degradation Preference.

Enumerator
OTC_DEGRADATION_PREFERENCE_NOT_SET	Default value. The video engine will decide the optimal degradation preference.
OTC_DEGRADATION_PREFERENCE_MAINTAIN_FRAMERATE_AND_RESOLUTION	The video engine will not reduce the resolution and will try to keep the frame rate steady. In some versions of the standard this option is referred to as "DISABLED", meaning that no degradation will be applied at all when under limited resources.
OTC_DEGRADATION_PREFERENCE_MAINTAIN_FRAMERATE	The video engine will try to keep the frame rate steady but might reduce resolution if necessary.
OTC_DEGRADATION_PREFERENCE_MAINTAIN_RESOLUTION	The video engine will not reduce the resolution but might reduce the frame rate if necessary.
OTC_DEGRADATION_PREFERENCE_BALANCED	The video engine will try to reach a balance between reducing resolution and frame rate when necessary.

◆ otc_publisher_error_code

enum otc_publisher_error_code

Error code enumeration for OpenTok publishers.

This enumeration represents several error codes associated with a publisher.

Enumerator
OTC_PUBLISHER_INTERNAL_ERROR	Internal error.
OTC_PUBLISHER_SESSION_DISCONNECTED	The session to which the publisher was publishing has disconnected.
OTC_PUBLISHER_TIMED_OUT	Time-out attempting to publish.
OTC_PUBLISHER_UNABLE_TO_PUBLISH	Unable to publish error.
OTC_PUBLISHER_WEBRTC_ERROR	WebRTC error.
OTC_PUBLISHER_CAPTIONS_CHANGE_RATE_LIMIT_ERROR	The server rejected a captions change request for the publisher because too many were made in a short period of time. Operation can be retried after a few seconds
OTC_PUBLISHER_ENCRYPTION_INTERNAL_ERROR	Internal error while encrypting a packet
OTC_PUBLISHER_ENCRYPTION_UNSUPPORTED_CODEC	Unsupported media codec for encryption
OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED	An encryption secret was set, but the session was not configured as end-to-end encrypted.

◆ otc_publisher_video_type

enum otc_publisher_video_type

Publisher video type enumeration.

This enumeration represents the different video types supported.

Enumerator
OTC_PUBLISHER_VIDEO_TYPE_CAMERA	Camera video stream.
OTC_PUBLISHER_VIDEO_TYPE_SCREEN	Screen capture video stream.

◆ otc_video_bitrate_preset

enum otc_video_bitrate_preset

Preset strategies for controlling video bitrate in a publisher's stream.

These presets allow developers to apply bandwidth strategies without manually specifying bitrates. Presets are mutually exclusive with manual bitrate configuration.

For details, see Publisher Max Bitrate.

Enumerator
OTC_VIDEO_BITRATE_PRESET_DEFAULT	Default preset. No extra restrictions are applied. This is the default mode.
OTC_VIDEO_BITRATE_PRESET_BW_SAVER	Bandwidth saver preset. Applies moderate constraints to reduce bandwidth usage while maintaining reasonable video quality.
OTC_VIDEO_BITRATE_PRESET_EXTRA_BW_SAVER	Extra bandwidth saver preset. Applies aggressive constraints to minimize bandwidth usage.
OTC_VIDEO_BITRATE_PRESET_CUSTOM	Custom bitrate. Represents a manually configured bitrate using otc_publisher_set_max_video_bitrate(). This value is returned by the preset getter only for internal tracking and cannot be passed to the preset setter.

Function Documentation

◆ otc_publisher_get_captions_input_language()

const char * otc_publisher_get_captions_input_language ( const otc_publisher * publisher )

extern

Gets the configured captions input language for a given publisher.

Parameters

publisher The publisher instance.

Returns: The configured input language. It can be NULL if it isn't set.

◆ otc_publisher_get_degradation_preference()

enum otc_degradation_preference otc_publisher_get_degradation_preference ( const otc_publisher * publisher )

extern

Gets the preferred policy that the video engine will follow when adjusting frame rate and resolution to limited bandwidth and CPU conditions. See otc_degradation_preference for a description of the possible values.

Parameters

[in] publisher The publisher instance.

Returns: The current degradation preference.

◆ otc_publisher_get_max_video_bitrate()

int otc_publisher_get_max_video_bitrate ( const otc_publisher * publisher )

extern

Gets the maximum video bitrate set for this publisher's video stream.

Returns the currently configured maximum video bitrate in bits per second (bps). If no manual bitrate has been set via otc_publisher_set_max_video_bitrate(), or if a preset is active (including the default), this function returns 0.

Note: A return value of 0 indicates that no explicit bitrate limit is applied and the stream is using preset-based behavior instead.

Parameters

[in] publisher The publisher instance.

Returns: The current maximum video bitrate in bits per second, or 0 if not manually set.

◆ otc_publisher_get_name()

const char * otc_publisher_get_name ( const struct otc_publisher * publisher )

extern

Gets the name for a given publisher.

Parameters

publisher The publisher instance.

Returns: The name.

◆ otc_publisher_get_publish_audio()

otc_bool otc_publisher_get_publish_audio ( const otc_publisher * publisher )

extern

Returns whether the Publisher is publishing audio or not.

Parameters

publisher The publisher instance.

Returns: Whether the publisher is publishing audio or not.

◆ otc_publisher_get_publish_captions()

otc_bool otc_publisher_get_publish_captions ( const otc_publisher * publisher )

extern

Returns whether the Publisher has captions active.

Parameters

publisher The publisher instance.

Returns: Whether the publisher has captions active or not.

◆ otc_publisher_get_publish_video()

otc_bool otc_publisher_get_publish_video ( const otc_publisher * publisher )

extern

Returns whether the publisher is publishing video or not.

Parameters

publisher The publisher instance.

Returns: Whether the publisher is publishing video or not.

◆ otc_publisher_get_publisher_id()

const char * otc_publisher_get_publisher_id ( const otc_publisher * publisher )

extern

Gets a unique identifier for a publisher.

Parameters

publisher The publisher instance.

Returns: A unique identifier for the publisher. If there is an error, this is null.

◆ otc_publisher_get_session()

otc_session * otc_publisher_get_session ( const otc_publisher * publisher )

extern

Returns the otc_session associated this publisher instance.

Parameters

publisher The publisher instance.

Returns: The otc_session associated this instance. If there is an error, this is null.

◆ otc_publisher_get_stream()

otc_stream * otc_publisher_get_stream ( otc_publisher * publisher )

extern

Returns the stream associated with the publisher. No callbacks in otc_publisher_callbacks will be invoked as a result of invoking this method (or afterwards).

Parameters

publisher The publisher instance to get the stream from.

Returns: The stream associated with the publisher. If there is an error, this is null.

◆ otc_publisher_get_target_scalability_mode()

const char * otc_publisher_get_target_scalability_mode ( otc_publisher * publisher )

extern

Gets the target scalability mode that was explicitly set via otc_publisher_set_target_scalability_mode. Returns the last value passed to the setter, or NULL if the setter has never been called. This reflects the user's intent, not the mode actually applied (which may differ due to codec-dependent fallback).

This is a beta feature.

Parameters

publisher The publisher instance.

Returns: The target scalability mode set by the caller, or NULL if not explicitly set.

◆ otc_publisher_get_user_data()

void * otc_publisher_get_user_data ( const struct otc_publisher * publisher )

extern

Gets user data for a given publisher.

Parameters

publisher The publisher instance.

Returns: A pointer to the user data in memory.

◆ otc_publisher_get_video_bitrate_preset()

enum otc_video_bitrate_preset otc_publisher_get_video_bitrate_preset ( const otc_publisher * publisher )

extern

Gets the currently active video bitrate preset for this publisher's stream.

If a custom bitrate was previously set using otc_publisher_set_max_video_bitrate(), this method returns OTC_VIDEO_BITRATE_PRESET_CUSTOM.

Parameters

[in] publisher The publisher instance.

Returns: The active bitrate preset.

◆ otc_publisher_get_video_type()

enum otc_publisher_video_type otc_publisher_get_video_type ( const struct otc_publisher * publisher )

extern

Gets the publisher video type. See the otc_publisher_set_video_type function.

Parameters

publisher The publisher instance.

Returns: The publisher video type.

◆ otc_publisher_new()

otc_publisher * otc_publisher_new	(	const char *	name,
		const struct otc_video_capturer_callbacks *	capturer,
		const struct otc_publisher_callbacks *	callbacks )

extern

Creates a new otc_publisher instance.

Parameters

name	The name of the publisher. Other clients can get the names for streams in the session.
capturer	Use this parameter if you want to provide a custom video capturer. If it is set to null, the publisher uses a default video capturer using the system's camera.
callbacks	A pointer to the structure with the publisher callback function pointers.

Returns: A new otc_publisher instance. If there is an error, this is null.

◆ otc_publisher_new_with_settings()

otc_publisher * otc_publisher_new_with_settings	(	const struct otc_publisher_callbacks *	callbacks,
		otc_publisher_settings *	settings )

extern

Creates a new otc_publisher instance.

Parameters

callbacks	A pointer to the struct with publisher callback function pointers.
settings	The settings struct containing the desired settings for the publisher.

Returns: A new otc_publisher instance. If there is an error, this is null.

◆ otc_publisher_set_audio_transformers()

otc_status otc_publisher_set_audio_transformers	(	otc_publisher *	publisher,
		otc_audio_transformer **	transformers,
		uint8_t	size )

extern

Sets an array of audio transformers to this publisher's audio stream. If null resets transformers.

The array can be composed by vonage audio transformers provided by ml-library and/or custom transfomers. Transformers contain a pointer to callback invoked on each audio frame.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

[in]	publisher	The publisher instance.
[in]	transformers	Array of opaque pointers otc_audio_transformer in the order to be applied to the stream.
[in]	size	size of the array.

Returns: an error in the event of an error otherwise OTC_SUCCESS.

◆ otc_publisher_set_captions_input_language()

otc_status otc_publisher_set_captions_input_language	(	otc_publisher *	publisher,
		const char *	language )

extern

Sets the preferred captions input language for a given publisher.

Parameters

publisher	The publisher instance.
language	A supported language code or NULL to leave default selection.

Returns: Return value indicating either error or success.

◆ otc_publisher_set_degradation_preference()

otc_status otc_publisher_set_degradation_preference	(	otc_publisher *	publisher,
		enum otc_degradation_preference	degradation_preference )

extern

Sets the preferred policy that the video engine will follow when adjusting frame rate and resolution to limited bandwidth and CPU conditions. See otc_degradation_preference for a description of the possible values.

Parameters

[in]	publisher	The publisher instance.
[in]	degradation_preference	The degradation preference.

Returns: OTC_SUCCESS or an error.

◆ otc_publisher_set_max_audio_bitrate()

otc_status otc_publisher_set_max_audio_bitrate	(	otc_publisher *	publisher,
		uint32_t	bitrate )

extern

Sets the max audio bitrate for the publisher.

Parameters

publisher	The publisher to be affected.
bitrate	The desired bitrate in kbps.

Returns: Return value indicating either error or success.

◆ otc_publisher_set_max_video_bitrate()

otc_status otc_publisher_set_max_video_bitrate	(	otc_publisher *	publisher,
		int	bitrate_bps )

extern

Gets the maximum video bitrate set for this publisher's video stream.

Returns the current maximum video bitrate in bits per second (bps). If no bitrate has been explicitly set via otc_publisher_set_max_video_bitrate(), or if a bitrate preset is active (including the default preset), this function returns 0.

Note: A return value of 0 indicates that no manual bitrate cap is in effect, and the stream is operating under a preset configuration.

Parameters

[in] publisher The publisher instance.

Returns: The current maximum video bitrate in bits per second, or 0 if unset or preset is used.

◆ otc_publisher_set_publish_audio()

otc_status otc_publisher_set_publish_audio	(	otc_publisher *	publisher,
		otc_bool	publish_audio )

extern

Whether to publish audio or not. By default, streams publish both audio and video.

Parameters

publisher	The publisher to be affected.
publish_audio	Whether to publish audio or not.

Returns: Return value indicating either error or success.

◆ otc_publisher_set_publish_captions()

otc_status otc_publisher_set_publish_captions	(	otc_publisher *	publisher,
		otc_bool	publish_captions )

extern

Whether to make captions active or not. By default, it is off.

Parameters

publisher	The publisher to be affected.
publish_captions	Whether to enable captioning or not.

Returns: Return value indicating either error or success.

◆ otc_publisher_set_publish_video()

otc_status otc_publisher_set_publish_video	(	otc_publisher *	publisher,
		otc_bool	publish_video )

extern

Whether to publish video or not. By default, streams publish both audio and video.

Parameters

publisher	The publisher to be affected.
publish_video	Whether to publish video or not.

Returns: Return value indicating either error or success.

◆ otc_publisher_set_target_scalability_mode()

otc_status otc_publisher_set_target_scalability_mode	(	otc_publisher *	publisher,
		const char *	scalability_mode )

extern

Sets the target scalability mode (SVC - Scalable Video Coding) for this publisher. The scalability mode controls the number of spatial (resolution) and temporal (frame rate) layers that WebRTC encodes. The mode is applied to the routed (publisher ↔ SFU) peer connection only, regardless of which leg is currently active.

This method may be called at any time — it does not require the routed-leg negotiation to have completed. The mode will be applied once the routed leg is established.

If a non-SVC codec (VP8, H.264) is negotiated on the routed leg, the closest applicable mode is used: spatial layers are forced to 1, preserving the temporal dimension (e.g. L2T2 → L1T2 when VP8 is negotiated).

This is a beta feature.

Errors:

Returns OTC_ERROR if the requested mode is not a valid scalability mode (i.e. not one of L1T1, L1T2, L1T3, L2T1, L2T2, L2T3, L3T1, L3T2, L3T3).

Parameters

publisher	The publisher instance.
scalability_mode	The target scalability mode.

Returns: OTC_SUCCESS if the operation succeeds; an error code otherwise.

◆ otc_publisher_set_video_bitrate_preset()

otc_status otc_publisher_set_video_bitrate_preset	(	otc_publisher *	publisher,
		enum otc_video_bitrate_preset	preset )

extern

Sets a video bitrate preset for this publisher's video stream.

Applies a predefined video bitrate strategy to control encoder behavior. These presets are intended to balance video quality with bandwidth usage, depending on the needs of the application.

Note: The preset OTC_VIDEO_BITRATE_PRESET_CUSTOM cannot be set directly. Calling otc_publisher_set_max_video_bitrate() will override the preset and cause the preset getter to return OTC_VIDEO_BITRATE_PRESET_CUSTOM.

Parameters

[in]	publisher	The publisher instance.
[in]	preset	A value from otc_video_bitrate_preset to apply.

Returns: an error in the event of an error otherwise OTC_SUCCESS.

◆ otc_publisher_set_video_transformers()

otc_status otc_publisher_set_video_transformers	(	otc_publisher *	publisher,
		otc_video_transformer **	transformers,
		uint8_t	size )

extern

Sets an array of video transformers to this publisher's video stream. If null resets transformers.

The array can be composed by vonage video transformers provided by ml-library and/or custom transfomers. Transformers contain a pointer to callback invoked on each video frame.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

[in]	publisher	The publisher instance.
[in]	transformers	Array of opaque pointers otc_video_transformer in the order to be applied to the stream.
[in]	size	size of the array.

Returns: an error in the event of an error otherwise OTC_SUCCESS.

◆ otc_publisher_set_video_type()

otc_status otc_publisher_set_video_type	(	struct otc_publisher *	publisher,
		enum otc_publisher_video_type	video_type )

extern

Sets the publisher video type. By default, videos have the video type set to OTC_PUBLISHER_VIDEO_TYPE_CAMERA (indicating the source of the video is a camera). Set this to OTC_PUBLISHER_VIDEO_TYPE_SCREEN to indicate that the video source is screen sharing. Other clients can detect the video type for streams in the session (to determine the video source type).

Parameters

publisher	The publisher to be affected.
video_type	The video type for the publisher.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_delete()

otc_status otc_publisher_settings_delete ( otc_publisher_settings * settings )

extern

Deletes an otc_publisher_settings instance.

Parameters

settings The otc_publisher_settings instance to be deleted.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_new()

otc_publisher_settings * otc_publisher_settings_new ( )

extern

Creates a new otc_publisher_settings instance.

Returns: A new otc_publisher_settings instance

◆ otc_publisher_settings_set_allow_audio_capture_while_muted()

otc_status otc_publisher_settings_set_allow_audio_capture_while_muted	(	otc_publisher_settings *	settings,
		const otc_bool	enabled )

extern

When otc_publisher_settings_set_allow_audio_capture_while_muted is set to false, the microphone will be automatically switched off when all publishers have muted their audio. Mic will be automatically switched on again when at least one publisher unmutes their audio. If set to true, mic will always remain switched on even when all publishers have muted their audio. Be aware that when the mic is switched off, callbacks like audio_level or audio_data will no longer be invoked for the publishers. The default value is true. See otc_session_new_with_settings.

Parameters

settings	Pointer to the session settings object.
enable	Boolean flag to disable (OTC_FALSE, the default value) or enable (OTC_TRUE) this flag.

Returns: otc_status Returns the status of the operation.

◆ otc_publisher_settings_set_audio_track()

otc_status otc_publisher_settings_set_audio_track	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables an audio track for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the existence of an audio track for a publisher to be constructed with `otc_publisher_new_with_settings`.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_auto_gain_control()

otc_status otc_publisher_settings_set_auto_gain_control	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables audio automatic gain control for a publisher to be constructed with otc_publisher_new_with_settings.

It does not work in the Vonage Video API Linux SDK.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true, the default) or disable (false) automatic gain control.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_default_camera_capture_resolution()

otc_status otc_publisher_settings_set_default_camera_capture_resolution	(	otc_publisher_settings *	settings,
		const enum otc_camera_capture_resolution	camera_capture_resolution )

extern

Sets a camera capture resolution for default video capturers.

Custom video capturers should not honor the capturing resolution set by otc_publisher_settings_set_default_camera_capture_resolution, the use of this is only for default video capturers.

Parameters

camera_capture_resolution	The camera capture resolution for default video capturers.
settings	The otc_publisher_settings instance to be affected.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_disable_audio_processing()

otc_status otc_publisher_settings_set_disable_audio_processing	(	otc_publisher_settings *	settings,
		otc_bool	disabled )

extern

When otc_publisher_settings_set_disable_audio_processing is set to true, the individual settings for acoustic echo cancellation, automatic gain control, and noise-suppression will be ignored and audio will not be processed at all. The default value is false. See otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true) or disable (false, the default) audio processing support.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_echo_cancellation()

otc_status otc_publisher_settings_set_echo_cancellation	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables acoustic echo cancellation for a publisher to be constructed with otc_publisher_new_with_settings.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true, the default) or disable (false) acoustic echo cancellation support.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_name()

otc_status otc_publisher_settings_set_name	(	otc_publisher_settings *	settings,
		const char *	name )

extern

Sets the desired name for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
name	The name for the publisher. Other clients can get the names for streams in the session.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_noise_suppression()

otc_status otc_publisher_settings_set_noise_suppression	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables noise suppression for a publisher to be constructed with otc_publisher_new_with_settings.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true, the default) or disable (false) noise suppression.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_opus_dtx()

otc_status otc_publisher_settings_set_opus_dtx	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables Opus DTX for a publisher to be constructed with otc_publisher_new_with_settings. Enabling Opus DTX can reduce bandwidth usage in streams that have long periods of silence.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true) or disable (false, the default) Opus DTX support.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_preferred_video_codecs()

otc_status otc_publisher_settings_set_preferred_video_codecs	(	otc_publisher_settings *	settings,
		const otc_video_codec_type *	codecs,
		size_t	num_codecs )

extern

Sets the preferred video codecs to use for this publisher's stream.

This function allows specifying an explicit, ordered list of video codecs to prioritize during negotiation. The codecs provided will be placed first in the SDP offer (in the given order), but other supported codecs may still be included with lower priority.

This does not restrict negotiation to only these codecs.

Passing an empty list will result in an OT_INVALID_PARAMETER error. If this function is not called, the SDK falls back to the default behavior defined in the Dashboard project settings.

Parameters

[in,out]	settings	The publisher settings instance to modify.
[in]	codecs	An array of video codecs to prioritize (must be non-empty).
[in]	num_codecs	The number of elements in the codecs array.

Returns: OTC_SUCCESS if the operation succeeds; OT_INVALID_PARAMETER if the list is empty or invalid.

◆ otc_publisher_settings_set_preferred_video_codecs_automatic()

otc_status otc_publisher_settings_set_preferred_video_codecs_automatic ( otc_publisher_settings * settings )

extern

Enables automatic codec prioritization for this publisher's stream.

In automatic mode, the SDK determines the most appropriate codec priority order, overriding the default project settings configured in the Dashboard.

This provides a simple way to delegate codec preference to the SDK without specifying a manual list.

Parameters

[in,out] settings The publisher settings instance to modify.

Returns: OTC_SUCCESS if the operation succeeds; an error code otherwise.

◆ otc_publisher_settings_set_publisher_audio_fallback_enabled()

otc_status otc_publisher_settings_set_publisher_audio_fallback_enabled	(	otc_publisher_settings *	settings,
		const otc_bool	enabled )

extern

Enables or disables the publisher audio-fallback feature.

With the publisher audio-fallback feature enabled, when the Publisher determines that a stream's quality has degraded significantly, it disables the video stream in order to preserve audio quality and continues to send the audio stream. The capturer corresponding to this publisher will not be disabled, and the captured frames will still be seen on the publisher side.

The default setting is OTC_FALSE (the audio-fallback feature is disabled). When using the screen video type in a session that uses the OpenTok Media Server, the publisher audio-fallback setting is set to OTC_FALSE by default, so that the video does not drop out in subscribers.

Parameters

settings	The publisher settings to be affected.
enabled	Whether we want to enable the audio-fallback feature or not.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_scalable_screenshare()

otc_status otc_publisher_settings_set_scalable_screenshare	(	otc_publisher_settings *	settings,
		const otc_bool	enabled )

extern

Allow use of scalable video scalable video for a publisher that has the otc_publisher_video_type set to OTC_PUBLISHER_VIDEO_TYPE_SCREEN with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the use of scalable video for screen-sharing streams.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_sender_stats_track()

otc_status otc_publisher_settings_set_sender_stats_track	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables a sender statistics channel for a publisher to be constructed with otc_publisher_new_with_settings. Currently, this feature only supports calls with more than two participants. By default the sender statistics channel is disabled.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the existence of a sender statistics channel for a publisher to be constructed with `otc_publisher_new_with_settings`.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_stereo()

otc_status otc_publisher_settings_set_stereo	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables stereo audio for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable stereo audio support for a publisher to be constructed with `otc_publisher_new_with_settings`.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_subscriber_audio_fallback_enabled()

otc_status otc_publisher_settings_set_subscriber_audio_fallback_enabled	(	otc_publisher_settings *	settings,
		const otc_bool	enabled )

extern

Enables or disables the subscriber audio-fallback feature (for subscribers to the published stream)

The subscriber audio-fallback feature is available in sessions that use the Vonage Video Media Router. With the audio-fallback feature enabled (the default), when the Vonage Video Media Router determines that a stream's quality has degraded significantly for a specific subscriber to the stream, it disables the video in that subscriber in order to preserve audio quality.

The default setting is OTC_TRUE (the audio-fallback feature is enabled). When using the screen video type, the subscriber audio-fallback setting is set to OTC_FALSE by default, so that the video does not drop out in subscribers.

Parameters

settings	The publisher settings to be affected.
enabled	Whether we want to enable the audio-fallback feature or not.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_video_capturer()

otc_status otc_publisher_settings_set_video_capturer	(	otc_publisher_settings *	settings,
		const struct otc_video_capturer_callbacks *	capturer )

extern

Sets the video capturer for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
capturer	The video capturer.

Returns: Return value indicating either error or success.

◆ otc_publisher_settings_set_video_track()

otc_status otc_publisher_settings_set_video_track	(	otc_publisher_settings *	settings,
		otc_bool	enabled )

extern

Enables a video track for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the existence of an video track for a publisher to be constructed with `otc_publisher_new_with_settings`.

Returns: Return value indicating either error or success.

◆ otc_statusotc_publisher_delete()

otc_statusotc_publisher_delete ( otc_publisher * publisher )

extern

Releases a publisher instance, including all hardware resources bound to it.

Parameters

publisher The publisher instance to be deleted.

Returns: Return value indicating either error or success.

◆ otc_statusotc_publisher_get_rtc_stats_report()

otc_statusotc_publisher_get_rtc_stats_report ( otc_publisher * publisher )

extern

Gets the RTC stats report for the publisher. 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 this function. When the stats are available, the otc_publisher_set_rtc_stats_report_cb callback function is called.

Also see otc_publisher_callbacks.on_audio_stats, otc_publisher_callbacks.on_video_stats, and otc_subscriber_get_rtc_stats_report.

Parameters

publisher The publisher.

◆ otc_statusotc_publisher_set_rtc_stats_report_cb()

otc_statusotc_publisher_set_rtc_stats_report_cb	(	otc_publisher *	publisher,
		const struct otc_publisher_rtc_stats_report_cb	cb )

extern

Sets the RTC stats report callback the publisher.

Parameters

publisher	The publisher instance.
cb	The otc_publisher_rtc_stats_report_cb struct that includes the callback function for the RTC stats report.

See also: otc_publisher_get_rtc_stats_report.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ otc_publisher

◆ otc_publisher_settings

Enumeration Type Documentation

◆ otc_degradation_preference

◆ otc_publisher_error_code

◆ otc_publisher_video_type

◆ otc_video_bitrate_preset

Function Documentation

◆ otc_publisher_get_captions_input_language()

◆ otc_publisher_get_degradation_preference()

◆ otc_publisher_get_max_video_bitrate()

◆ otc_publisher_get_name()

◆ otc_publisher_get_publish_audio()

◆ otc_publisher_get_publish_captions()

◆ otc_publisher_get_publish_video()

◆ otc_publisher_get_publisher_id()

◆ otc_publisher_get_session()

◆ otc_publisher_get_stream()

◆ otc_publisher_get_target_scalability_mode()

◆ otc_publisher_get_user_data()

◆ otc_publisher_get_video_bitrate_preset()

◆ otc_publisher_get_video_type()

◆ otc_publisher_new()

◆ otc_publisher_new_with_settings()

◆ otc_publisher_set_audio_transformers()

◆ otc_publisher_set_captions_input_language()

◆ otc_publisher_set_degradation_preference()

◆ otc_publisher_set_max_audio_bitrate()

◆ otc_publisher_set_max_video_bitrate()

◆ otc_publisher_set_publish_audio()

◆ otc_publisher_set_publish_captions()

◆ otc_publisher_set_publish_video()

◆ otc_publisher_set_target_scalability_mode()

◆ otc_publisher_set_video_bitrate_preset()

◆ otc_publisher_set_video_transformers()

◆ otc_publisher_set_video_type()

◆ otc_publisher_settings_delete()

◆ otc_publisher_settings_new()

◆ otc_publisher_settings_set_allow_audio_capture_while_muted()

◆ otc_publisher_settings_set_audio_track()

◆ otc_publisher_settings_set_auto_gain_control()

◆ otc_publisher_settings_set_default_camera_capture_resolution()

◆ otc_publisher_settings_set_disable_audio_processing()

◆ otc_publisher_settings_set_echo_cancellation()

◆ otc_publisher_settings_set_name()

◆ otc_publisher_settings_set_noise_suppression()

◆ otc_publisher_settings_set_opus_dtx()

◆ otc_publisher_settings_set_preferred_video_codecs()

◆ otc_publisher_settings_set_preferred_video_codecs_automatic()

◆ otc_publisher_settings_set_publisher_audio_fallback_enabled()

◆ otc_publisher_settings_set_scalable_screenshare()

◆ otc_publisher_settings_set_sender_stats_track()

◆ otc_publisher_settings_set_stereo()

◆ otc_publisher_settings_set_subscriber_audio_fallback_enabled()

◆ otc_publisher_settings_set_video_capturer()

◆ otc_publisher_settings_set_video_track()

◆ otc_statusotc_publisher_delete()

◆ otc_statusotc_publisher_get_rtc_stats_report()

◆ otc_statusotc_publisher_set_rtc_stats_report_cb()