publisher.h
This file includes the type definition for an OpenTok publisher along with several function declarations.
Data structures: otc_publisher_video_layer_stats, otc_publisher_audio_stats, otc_publisher_video_stats, otc_publisher_media_link_stats, otc_publisher_callbacks, otc_publisher_rtc_stats, otc_publisher_rtc_stats_report_cb
Includes: base.h, config.h, stream.h, video_frame.h, camera_capture_resolution.h, media_transformer.h, video_capturer.h, media_utils.h
#define OTC_MAX_VIDEO_LAYERS
#define OTC_MAX_VIDEO_LAYERS 3
typedef otc_publisher
OpenTok publisher type definition.
A type representing a publisher of an audio-video stream to an OpenTok session.
typedef struct otc_publisher otc_publisher;
typedef otc_publisher_settings
OpenTok publisher settings type definition.
typedef struct otc_publisher_settings otc_publisher_settings;
enum otc_publisher_error_code
Error code enumeration for OpenTok publishers.
This enumeration represents several error codes associated with a publisher.
| Name | Value | Description |
|---|---|---|
OTC_PUBLISHER_INTERNAL_ERROR |
2000 |
Internal error. |
OTC_PUBLISHER_SESSION_DISCONNECTED |
1010 |
The session to which the publisher was publishing has disconnected. |
OTC_PUBLISHER_TIMED_OUT |
1541 |
Time-out attempting to publish. |
OTC_PUBLISHER_UNABLE_TO_PUBLISH |
1500 |
Unable to publish error. |
OTC_PUBLISHER_WEBRTC_ERROR |
1610 |
WebRTC error. |
OTC_PUBLISHER_CAPTIONS_CHANGE_RATE_LIMIT_ERROR |
5010 |
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 |
6001 |
Internal error while encrypting a packet |
OTC_PUBLISHER_ENCRYPTION_UNSUPPORTED_CODEC |
6005 |
Unsupported media codec for encryption |
OTC_PUBLISHER_ENCRYPTION_NOT_ENABLED |
6007 |
An encryption secret was set, but the session was not configured as end-to-end encrypted. |
enum otc_publisher_video_type
Publisher video type enumeration.
This enumeration represents the different video types supported.
| Name | Value | Description |
|---|---|---|
OTC_PUBLISHER_VIDEO_TYPE_CAMERA |
1 |
Camera video stream. |
OTC_PUBLISHER_VIDEO_TYPE_SCREEN |
2 |
Screen capture video stream. |
enum otc_media_type
Media type.
| Name | Value | Description |
|---|---|---|
OTC_MEDIA_TYPE_VIDEO |
0 |
|
OTC_MEDIA_TYPE_AUDIO |
enum otc_video_bitrate_preset
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.
| Name | Description |
|---|---|
OTC_VIDEO_BITRATE_PRESET_DEFAULT |
This is the default mode. |
OTC_VIDEO_BITRATE_PRESET_BW_SAVER |
Applies moderate constraints to reduce bandwidth usage while maintaining reasonable video quality. |
OTC_VIDEO_BITRATE_PRESET_EXTRA_BW_SAVER |
Applies aggressive constraints to minimize bandwidth usage. |
OTC_VIDEO_BITRATE_PRESET_CUSTOM |
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. |
enum otc_degradation_preference
For details, see Degradation Preference.
| Name | Value | Description |
|---|---|---|
OTC_DEGRADATION_PREFERENCE_NOT_SET |
-1 |
Default value. The video engine will decide the optimal degradation preference. |
OTC_DEGRADATION_PREFERENCE_MAINTAIN_FRAMERATE_AND_RESOLUTION |
0 |
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 |
1 |
The video engine will try to keep the frame rate steady but might reduce resolution if necessary. |
OTC_DEGRADATION_PREFERENCE_MAINTAIN_RESOLUTION |
2 |
The video engine will not reduce the resolution but might reduce the frame rate if necessary. |
OTC_DEGRADATION_PREFERENCE_BALANCED |
3 |
The video engine will try to reach a balance between reducing resolution and frame rate when necessary. |
Functions
| Name | Description |
|---|---|
otc_publisher_new(name, capturer, callbacks) → {otc_publisher *} |
Creates a new otc_publisher instance. |
otc_publisher_settings_new() → {otc_publisher_settings *} |
Creates a new otc_publisher_settings instance. |
otc_publisher_settings_delete(settings) → {otc_status} |
Deletes an otc_publisher_settings instance. |
otc_publisher_settings_set_name(settings, name) → {otc_status} |
Sets the desired name for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_video_capturer(settings, capturer) → {otc_status} |
Sets the video capturer for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_audio_track(settings, enabled) → {otc_status} |
Enables an audio track for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_video_track(settings, enabled) → {otc_status} |
Enables a video track for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_sender_stats_track(settings, enabled) → {otc_status} |
Enables a sender statistics channel for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_stereo(settings, enabled) → {otc_status} |
Enables stereo audio for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_opus_dtx(settings, enabled) → {otc_status} |
Enables Opus DTX for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_auto_gain_control(settings, enabled) → {otc_status} |
Enables audio automatic gain control for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_noise_suppression(settings, enabled) → {otc_status} |
Enables noise suppression for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_echo_cancellation(settings, enabled) → {otc_status} |
Enables acoustic echo cancellation for a publisher to be constructed with otc_publisher_new_with_settings. |
otc_publisher_settings_set_disable_audio_processing(settings, disabled) → {otc_status} |
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. |
otc_publisher_settings_set_default_camera_capture_resolution(settings, camera_capture_resolution) → {otc_status} |
Sets a camera capture resolution for default video capturers. |
otc_publisher_settings_set_scalable_screenshare(settings, enabled) → {otc_status} |
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. |
otc_publisher_settings_set_allow_audio_capture_while_muted(settings, enabled) → {otc_status} |
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. |
otc_publisher_new_with_settings(callbacks, settings) → {otc_publisher *} |
Creates a new otc_publisher instance. |
otc_publisher_delete(publisher) → {otc_status} |
Releases a publisher instance, including all hardware resources bound to it. |
otc_publisher_get_stream(publisher) → {otc_stream *} |
Returns the stream associated with the publisher. |
otc_publisher_set_publish_video(publisher, publish_video) → {otc_status} |
Whether to publish video or not. |
otc_publisher_set_publish_audio(publisher, publish_audio) → {otc_status} |
Whether to publish audio or not. |
otc_publisher_set_publish_captions(publisher, publish_captions) → {otc_status} |
Whether to make captions active or not. |
otc_publisher_get_publish_video(publisher) → {otc_bool} |
Returns whether the publisher is publishing video or not. |
otc_publisher_get_publish_audio(publisher) → {otc_bool} |
Returns whether the Publisher is publishing audio or not. |
otc_publisher_get_publish_captions(publisher) → {otc_bool} |
Returns whether the Publisher has captions active. |
otc_publisher_set_captions_input_language(publisher, language) → {otc_status} |
Sets the preferred captions input language for a given publisher. |
otc_publisher_get_captions_input_language(publisher) → {const char *} |
Gets the configured captions input language for a given publisher. |
otc_publisher_get_session(publisher) → {otc_session *} |
Returns the otc_session associated this publisher instance. |
otc_publisher_set_max_audio_bitrate(publisher, bitrate) → {otc_status} |
Sets the max audio bitrate for the publisher. |
otc_publisher_set_rtc_stats_report_cb(publisher, cb) → {otc_status} |
Sets the RTC stats report callback the publisher. |
otc_publisher_get_rtc_stats_report(publisher) → {otc_status} |
Gets the RTC stats report for the publisher. |
otc_publisher_get_publisher_id(publisher) → {const char *} |
Gets a unique identifier for a publisher. |
otc_publisher_set_video_type(publisher, video_type) → {otc_status} |
Sets the publisher video type. |
otc_publisher_get_video_type(publisher) → {enum otc_publisher_video_type} |
Gets the publisher video type. |
otc_publisher_get_user_data(publisher) → {void *} |
Gets user data for a given publisher. |
otc_publisher_get_name(publisher) → {const char *} |
Gets the name for a given publisher. |
otc_publisher_set_video_transformers(publisher, transformers, size) → {otc_status} |
The array can be composed by vonage video transformers provided by ml-library and/or custom transfomers. |
otc_publisher_set_audio_transformers(publisher, transformers, size) → {otc_status} |
The array can be composed by vonage audio transformers provided by ml-library and/or custom transfomers. |
otc_publisher_set_target_scalability_mode(publisher, scalability_mode) → {otc_status} |
This method may be called at any time — it does not require the routed-leg negotiation to have completed. |
otc_publisher_get_target_scalability_mode(publisher) → {const char *} |
This is a beta feature. |
otc_publisher_set_max_video_bitrate(publisher, bitrate_bps) → {otc_status} |
Returns the current maximum video bitrate in bits per second (bps). |
otc_publisher_get_max_video_bitrate(publisher) → {int} |
Returns the currently configured maximum video bitrate in bits per second (bps). |
otc_publisher_set_video_bitrate_preset(publisher, preset) → {otc_status} |
Applies a predefined video bitrate strategy to control encoder behavior. |
otc_publisher_get_video_bitrate_preset(publisher) → {enum otc_video_bitrate_preset} |
If a custom bitrate was previously set using otc_publisher_set_max_video_bitrate(), this method returns OTC_VIDEO_BITRATE_PRESET_CUSTOM. |
otc_publisher_set_degradation_preference(publisher, degradation_preference) → {otc_status} |
|
otc_publisher_get_degradation_preference(publisher) → {enum otc_degradation_preference} |
|
otc_publisher_settings_set_subscriber_audio_fallback_enabled(settings, enabled) → {otc_status} |
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. |
otc_publisher_settings_set_publisher_audio_fallback_enabled(settings, enabled) → {otc_status} |
Enables or disables the publisher audio-fallback feature. |
otc_publisher_settings_set_preferred_video_codecs(settings, codecs, num_codecs) → {otc_status} |
This function allows specifying an explicit, ordered list of video codecs to prioritize during negotiation. |
otc_publisher_settings_set_preferred_video_codecs_automatic(settings) → {otc_status} |
In automatic mode, the SDK determines the most appropriate codec priority order, overriding the default project settings configured in the Dashboard. |
otc_publisher_new(name, capturer, callbacks) → {otc_publisher *}
Creates a new otc_publisher instance.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
const char * | The name of the publisher. Other clients can get the names for streams in the session. |
capturer |
const struct otc_video_capturer_callbacks * | 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 |
const struct otc_publisher_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_settings_new() → {otc_publisher_settings *}
Creates a new otc_publisher_settings instance.
Returns:
A new otc_publisher_settings instance
otc_publisher_settings_delete(settings) → {otc_status}
Deletes an otc_publisher_settings instance.
Parameters:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be deleted. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_name(settings, name) → {otc_status}
Sets the desired name for a publisher to be constructed with otc_publisher_new_with_settings.
Parameters:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
name |
const char * | 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_video_capturer(settings, capturer) → {otc_status}
Sets the video capturer for a publisher to be constructed with otc_publisher_new_with_settings.
Parameters:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
capturer |
const struct otc_video_capturer_callbacks * | The video capturer. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_audio_track(settings, enabled) → {otc_status}
Enables an audio track for a publisher to be constructed with otc_publisher_new_with_settings.
Parameters:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | 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_video_track(settings, enabled) → {otc_status}
Enables a video track for a publisher to be constructed with otc_publisher_new_with_settings.
Parameters:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | 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_publisher_settings_set_sender_stats_track(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | 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(settings, enabled) → {otc_status}
Enables stereo audio for a publisher to be constructed with otc_publisher_new_with_settings.
Parameters:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | 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_opus_dtx(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | Whether to enable (true) or disable (false, the default) Opus DTX support. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_auto_gain_control(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | Whether to enable (true, the default) or disable (false) automatic gain control. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_noise_suppression(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | Whether to enable (true, the default) or disable (false) noise suppression. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_echo_cancellation(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
otc_bool | 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_disable_audio_processing(settings, disabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
disabled |
otc_bool |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_default_camera_capture_resolution(settings, camera_capture_resolution) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
camera_capture_resolution |
const enum otc_camera_capture_resolution | The camera capture resolution for default video capturers. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_scalable_screenshare(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The otc_publisher_settings instance to be affected. |
enabled |
const otc_bool | Enable/disable the use of scalable video for screen-sharing streams. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_allow_audio_capture_while_muted(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | Pointer to the session settings object. |
enabled |
const otc_bool |
Returns:
otc_status Returns the status of the operation.
otc_publisher_new_with_settings(callbacks, settings) → {otc_publisher *}
Creates a new otc_publisher instance.
Parameters:
| Name | Type | Description |
|---|---|---|
callbacks |
const struct otc_publisher_callbacks * | A pointer to the struct with publisher callback function pointers. |
settings |
otc_publisher_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_delete(publisher) → {otc_status}
Releases a publisher instance, including all hardware resources bound to it.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance to be deleted. |
Returns:
Return value indicating either error or success.
otc_publisher_get_stream(publisher) → {otc_stream *}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_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_set_publish_video(publisher, publish_video) → {otc_status}
Whether to publish video or not. By default, streams publish both audio and video.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher to be affected. |
publish_video |
otc_bool | Whether to publish video or not. |
Returns:
Return value indicating either error or success.
otc_publisher_set_publish_audio(publisher, publish_audio) → {otc_status}
Whether to publish audio or not. By default, streams publish both audio and video.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher to be affected. |
publish_audio |
otc_bool | Whether to publish audio or not. |
Returns:
Return value indicating either error or success.
otc_publisher_set_publish_captions(publisher, publish_captions) → {otc_status}
Whether to make captions active or not. By default, it is off.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher to be affected. |
publish_captions |
otc_bool | Whether to enable captioning or not. |
Returns:
Return value indicating either error or success.
otc_publisher_get_publish_video(publisher) → {otc_bool}
Returns whether the publisher is publishing video or not.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
Whether the publisher is publishing video or not.
otc_publisher_get_publish_audio(publisher) → {otc_bool}
Returns whether the Publisher is publishing audio or not.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
Whether the publisher is publishing audio or not.
otc_publisher_get_publish_captions(publisher) → {otc_bool}
Returns whether the Publisher has captions active.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
Whether the publisher has captions active or not.
otc_publisher_set_captions_input_language(publisher, language) → {otc_status}
Sets the preferred captions input language for a given publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
language |
const char * | A supported language code or NULL to leave default selection. |
Returns:
Return value indicating either error or success.
otc_publisher_get_captions_input_language(publisher) → {const char *}
Gets the configured captions input language for a given publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
The configured input language. It can be NULL if it isn't set.
otc_publisher_get_session(publisher) → {otc_session *}
Returns the otc_session associated this publisher instance.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
The otc_session associated this instance. If there is an error, this is null.
otc_publisher_set_max_audio_bitrate(publisher, bitrate) → {otc_status}
Sets the max audio bitrate for the publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher to be affected. |
bitrate |
uint32_t | The desired bitrate in kbps. |
Returns:
Return value indicating either error or success.
otc_publisher_set_rtc_stats_report_cb(publisher, cb) → {otc_status}
Sets the RTC stats report callback the publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
cb |
const struct otc_publisher_rtc_stats_report_cb | The otc_publisher_rtc_stats_report_cb struct that includes the callback function for the RTC stats report. |
See: : - otc_publisher_get_rtc_stats_report.
Returns:
otc_status
otc_publisher_get_rtc_stats_report(publisher) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher. |
Returns:
otc_status
otc_publisher_get_publisher_id(publisher) → {const char *}
Gets a unique identifier for a publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
A unique identifier for the publisher. If there is an error, this is null.
otc_publisher_set_video_type(publisher, video_type) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
struct otc_publisher * | The publisher to be affected. |
video_type |
enum otc_publisher_video_type | The video type for the publisher. |
Returns:
Return value indicating either error or success.
otc_publisher_get_video_type(publisher) → {enum otc_publisher_video_type}
Gets the publisher video type. See the otc_publisher_set_video_type function.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const struct otc_publisher * | The publisher instance. |
Returns:
The publisher video type.
otc_publisher_get_user_data(publisher) → {void *}
Gets user data for a given publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const struct otc_publisher * | The publisher instance. |
Returns:
A pointer to the user data in memory.
otc_publisher_get_name(publisher) → {const char *}
Gets the name for a given publisher.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const struct otc_publisher * | The publisher instance. |
Returns:
The name.
otc_publisher_set_video_transformers(publisher, transformers, size) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
transformers |
otc_video_transformer * * | Array of opaque pointers otc_video_transformer in the order to be applied to the stream. |
size |
uint8_t | size of the array. |
Returns:
an error in the event of an error otherwise OTC_SUCCESS.
otc_publisher_set_audio_transformers(publisher, transformers, size) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
transformers |
otc_audio_transformer * * | Array of opaque pointers otc_audio_transformer in the order to be applied to the stream. |
size |
uint8_t | size of the array. |
Returns:
an error in the event of an error otherwise OTC_SUCCESS.
otc_publisher_set_target_scalability_mode(publisher, scalability_mode) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
scalability_mode |
const char * | The target scalability mode. |
Returns:
OTC_SUCCESS if the operation succeeds; an error code otherwise.
otc_publisher_get_target_scalability_mode(publisher) → {const char *}
This is a beta feature.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
Returns:
The target scalability mode set by the caller, or NULL if not explicitly set.
otc_publisher_set_max_video_bitrate(publisher, bitrate_bps) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
bitrate_bps |
int |
Returns:
The current maximum video bitrate in bits per second, or 0 if unset or preset is used.
otc_publisher_get_max_video_bitrate(publisher) → {int}
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:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
The current maximum video bitrate in bits per second, or 0 if not manually set.
otc_publisher_set_video_bitrate_preset(publisher, preset) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
preset |
enum otc_video_bitrate_preset | A value from otc_video_bitrate_preset to apply. |
Returns:
an error in the event of an error otherwise OTC_SUCCESS.
otc_publisher_get_video_bitrate_preset(publisher) → {enum otc_video_bitrate_preset}
If a custom bitrate was previously set using otc_publisher_set_max_video_bitrate(), this method returns OTC_VIDEO_BITRATE_PRESET_CUSTOM.
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
The active bitrate preset.
otc_publisher_set_degradation_preference(publisher, degradation_preference) → {otc_status}
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
otc_publisher * | The publisher instance. |
degradation_preference |
enum otc_degradation_preference | The degradation preference. |
Returns:
OTC_SUCCESS or an error.
otc_publisher_get_degradation_preference(publisher) → {enum otc_degradation_preference}
Parameters:
| Name | Type | Description |
|---|---|---|
publisher |
const otc_publisher * | The publisher instance. |
Returns:
The current degradation preference.
otc_publisher_settings_set_subscriber_audio_fallback_enabled(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The publisher settings to be affected. |
enabled |
const otc_bool | Whether we want to enable the audio-fallback feature or not. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_publisher_audio_fallback_enabled(settings, enabled) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The publisher settings to be affected. |
enabled |
const otc_bool | Whether we want to enable the audio-fallback feature or not. |
Returns:
Return value indicating either error or success.
otc_publisher_settings_set_preferred_video_codecs(settings, codecs, num_codecs) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The publisher settings instance to modify. |
codecs |
const otc_video_codec_type * | An array of video codecs to prioritize (must be non-empty). |
num_codecs |
size_t | 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(settings) → {otc_status}
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:
| Name | Type | Description |
|---|---|---|
settings |
otc_publisher_settings * | The publisher settings instance to modify. |
Returns:
OTC_SUCCESS if the operation succeeds; an error code otherwise.