Agora RTC Objective-C API Reference Refactor

Data Structures | Public Member Functions
ILocalUser Class Referenceabstract

## Data Structures
struct | ANAStats
struct | AudioProcessingStats
struct | LocalAudioDetailedStats

## Public Member Functions
virtual int | setUserRole (rtc::CLIENT_ROLE_TYPE role, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual CLIENT_ROLE_TYPE | getUserRole ()=0
virtual int | setAudienceLatencyLevel (AUDIENCE_LATENCY_LEVEL_TYPE level, int role, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setAudioEncoderConfiguration (const rtc::AudioEncoderConfiguration &config, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setAudioScenario (AUDIO_SCENARIO_TYPE scenario, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setVideoScenario (VIDEO_APPLICATION_SCENARIO_TYPE scenarioType, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setVideoQoEPreference (VIDEO_QOE_PREFERENCE_TYPE qoePreference, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | getLocalAudioStatistics (LocalAudioDetailedStats &stats)=0
virtual int | publishAudio (agora_refptr< ILocalAudioTrack > audioTrack, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unpublishAudio (agora_refptr< ILocalAudioTrack > audioTrack, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | publishVideo (agora_refptr< ILocalVideoTrack > videoTrack, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unpublishVideo (agora_refptr< ILocalVideoTrack > videoTrack, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | subscribeAudio (user_id_t userId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | subscribeAllAudio (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unsubscribeAudio (user_id_t userId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unsubscribeAllAudio (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | adjustPlaybackSignalVolume (int volume, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | getPlaybackSignalVolume (int *volume)=0
virtual int | getUserPlaybackSignalVolume (user_id_t userId, int *volume)=0
virtual int | enableSoundPositionIndication (bool enabled, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setRemoteVoicePosition (user_id_t userId, double pan, double gain, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | enableSpatialAudio (bool enabled, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setPlaybackAudioFrameParameters (size_t numberOfChannels, uint32_t sampleRateHz, RAW_AUDIO_FRAME_OP_MODE_TYPE mode=RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, int samplesPerCall=0, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setRecordingAudioFrameParameters (size_t numberOfChannels, uint32_t sampleRateHz, RAW_AUDIO_FRAME_OP_MODE_TYPE mode=RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, int samplesPerCall=0, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setMixedAudioFrameParameters (size_t numberOfChannels, uint32_t sampleRateHz, int samplesPerCall=0, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setEarMonitoringAudioFrameParameters (bool enabled, size_t numberOfChannels, uint32_t sampleRateHz, RAW_AUDIO_FRAME_OP_MODE_TYPE mode=RAW_AUDIO_FRAME_OP_MODE_READ_ONLY, int samplesPerCall=0, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setPlaybackAudioFrameBeforeMixingParameters (size_t numberOfChannels, uint32_t sampleRateHz, int samplesPerCall=0, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | registerAudioFrameObserver (agora::media::IAudioFrameObserverBase *observer, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterAudioFrameObserver (agora::media::IAudioFrameObserverBase *observer)=0
virtual int | enableAudioSpectrumMonitor (int intervalInMS=100, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | disableAudioSpectrumMonitor (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | registerAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer, void(*safeDeleter)(agora::media::IAudioSpectrumObserver *), aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterAudioSpectrumObserver (agora::media::IAudioSpectrumObserver *observer)=0
virtual int | registerLocalVideoEncodedFrameObserver (agora::media::IVideoEncodedFrameObserver *observer, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterLocalVideoEncodedFrameObserver (agora::media::IVideoEncodedFrameObserver *observer)=0
virtual int | forceNextIntraFrame (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | registerVideoEncodedFrameObserver (agora::media::IVideoEncodedFrameObserver *observer, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterVideoEncodedFrameObserver (agora::media::IVideoEncodedFrameObserver *observer)=0
virtual int | registerVideoFrameObserver (IVideoFrameObserver2 *observer, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterVideoFrameObserver (IVideoFrameObserver2 *observer)=0
virtual int | setSubscribeAudioAllowlist (user_id_t *userList, int userNumber, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setSubscribeVideoAllowlist (user_id_t *userList, int userNumber, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | subscribeVideo (user_id_t userId, const VideoSubscriptionOptions &subscriptionOptions, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | subscribeAllVideo (const VideoSubscriptionOptions &subscriptionOptions, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unsubscribeVideo (user_id_t userId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unsubscribeAllVideo (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setAudioVolumeIndicationParameters (int intervalInMS, int smooth, bool reportVad, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | registerLocalUserObserver (ILocalUserObserver *observer, void(*safeDeleter)(ILocalUserObserver *)=NULL, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterLocalUserObserver (ILocalUserObserver *observer)=0
virtual IMediaControlPacketSender * | getMediaControlPacketSender ()=0
virtual int | registerMediaControlPacketReceiver (IMediaControlPacketReceiver *ctrlPacketReceiver, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterMediaControlPacketReceiver (IMediaControlPacketReceiver *ctrlPacketReceiver)=0
virtual int | sendIntraRequest (user_id_t userId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setAudioFilterable (bool filterable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | enableRemoteAudioTrackFilter (user_id_t userId, const char *id, bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setRemoteAudioTrackFilterProperty (user_id_t userId, const char *id, const char *key, const char *jsonValue, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | getRemoteAudioTrackFilterProperty (user_id_t userId, const char *id, const char *key, char *jsonValue, size_t bufSize)=0
virtual int | publishDataChannel (agora_refptr< ILocalDataChannel > channel, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unpublishDataChannel (agora_refptr< ILocalDataChannel > channel, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | subscribeDataChannel (user_id_t userId, int channelId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unsubscribeDataChannel (user_id_t userId, int channelId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | registerDataChannelObserver (IDataChannelObserver *observer, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterDataChannelObserver (IDataChannelObserver *observer)=0
virtual int | SetAudioNsMode (bool NsEnable, NS_MODE NsMode, NS_LEVEL NsLevel, NS_DELAY NsDelay, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | RegisterLocalMixedAudioTrack (agora_refptr< ILocalAudioTrack > &track, bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | takeDataChannelSnapshot (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | sendAudioMetadata (const char *metadata, size_t length, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setRemoteRenderTargetFps (int targetFps)=0

## Detailed Description

The ILocalUser class defines the behavior and state of a local user.

Each RTC connection has its own local user. Apps can get the local user object by calling IRtcConnection::getLocalUser.

Each local user has two user roles: broadcaster (publisher and subscriber) and audience (subscriber only). A publisher publishes audio and video tracks, while audience receive them.

## Member Enumeration Documentation

## ◆ NS_MODE

enum NS_MODE

Enumerator
ElderNsStatistical |
NsNGStatistical |
NsNG |

## ◆ NS_LEVEL

enum NS_LEVEL

Enumerator
Soft |
Aggressive |

## ◆ NS_DELAY

enum NS_DELAY

Enumerator
HighQuality |
Balance |
LowDelay |

## Constructor & Destructor Documentation

## ◆ ~ILocalUser()

virtual ~ILocalUser | ( |  | ) |
| inline virtual

## Member Function Documentation

## ◆ setUserRole()

virtual int setUserRole | ( | rtc::CLIENT_ROLE_TYPE | role,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the role of the user.

You can call this method either before or after connecting to an Agora channel:

- Before connecting: This method sets the user role as publisher or subscriber (default).
- After connecting: This method allows you to switch the user role between publisher and subscriber. The onChangeRoleSuccess and onChangeRoleFailure callbacks indicate the result of this method call.

Note
  If the token in the connect method does not have the same role as `role`, the connection fails with the onConnectionFailure callback.

Parameters

  role | The role of the user. See CLIENT_ROLE_TYPE.

## ◆ getUserRole()

virtual CLIENT_ROLE_TYPE getUserRole | ( |  | ) |
| pure virtual

Gets the role of the user.

Returns
  The role of the user: Success.

## ◆ setAudienceLatencyLevel()

virtual int setAudienceLatencyLevel | ( | AUDIENCE_LATENCY_LEVEL_TYPE | level,
|  | int | role,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the latency level of an audience member.

Note

Parameters

  level | The latency level of an audience member in interactive live streaming. See AUDIENCE_LATENCY_LEVEL_TYPE.
  role | The user role determined by the config. If it's -1, it means there is no configured role.

## ◆ getAudienceLatencyLevel()

virtual AUDIENCE_LATENCY_LEVEL_TYPE getAudienceLatencyLevel | ( |  | ) |
| pure virtual

## ◆ setAudioEncoderConfiguration()

virtual int setAudioEncoderConfiguration | ( | const rtc::AudioEncoderConfiguration & | config,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Configures the audio encoder.

The SDK applies the configurations to all the sending audio tracks.

Parameters

  config | The reference to the audio encoder configurations.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioScenario()

virtual int setAudioScenario | ( | AUDIO_SCENARIO_TYPE | scenario,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the audio parameters and application scenarios.

Parameters

  scenario | Sets the audio application scenarios: AUDIO_SCENARIO_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVideoScenario()

virtual int setVideoScenario | ( | VIDEO_APPLICATION_SCENARIO_TYPE | scenarioType,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

You can call this method to set the expected video scenario. The SDK will optimize the video experience for each scenario you set.

Parameters

  scenarioType | The video application scenario.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVideoQoEPreference()

virtual int setVideoQoEPreference | ( | VIDEO_QOE_PREFERENCE_TYPE | qoePreference,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the Video qoe preference.

You can call this method to set the expected QoE Preference. The SDK will optimize the video experience for each preference you set.

Parameters

  qoePreference | The qoe preference type. See VIDEO_QOE_PREFERENCE_TYPE.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getLocalAudioStatistics()

virtual bool getLocalAudioStatistics | ( | LocalAudioDetailedStats & | stats | ) |
| pure virtual

Gets the detailed statistics of the local audio.

Parameters

  [out] | stats | The reference to the detailed statistics of the local audio.

Returns
  - `true`: Success.
  - `false`: Failure.

## ◆ publishAudio()

virtual int publishAudio | ( | agora_refptr< ILocalAudioTrack > | audioTrack,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Publishes a local audio track to the channel.

By default, all published audio tracks are mixed.

Parameters

  audioTrack | The local audio track to be published.

Returns
  - 0: Success.
  - < 0: Failure.
    - -5(ERR_REFUSED), if the role of the local user is not broadcaster.

## ◆ unpublishAudio()

virtual int unpublishAudio | ( | agora_refptr< ILocalAudioTrack > | audioTrack,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Stops publishing the local audio track to the channel.

Parameters

  audioTrack | The local audio track that you want to stop publishing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ publishVideo()

virtual int publishVideo | ( | agora_refptr< ILocalVideoTrack > | videoTrack,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Publishes a local video track to the channel.

Parameters

  videoTrack | The local video track to be published.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unpublishVideo()

virtual int unpublishVideo | ( | agora_refptr< ILocalVideoTrack > | videoTrack,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Stops publishing the local video track to the channel.

Parameters

  videoTrack | The local video track that you want to stop publishing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ subscribeAudio()

virtual int subscribeAudio | ( | user_id_t | userId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Subscribes to the audio of a specified remote user in channel.

Parameters

  userId | The ID of the remote user whose audio you want to subscribe to.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT), if no such user exists or `userId` is invalid.

## ◆ subscribeAllAudio()

virtual int subscribeAllAudio | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Subscribes to the audio of all remote users in the channel.

This method also automatically subscribes to the audio of any subsequent user.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unsubscribeAudio()

virtual int unsubscribeAudio | ( | user_id_t | userId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Stops subscribing to the audio of a specified remote user in the channel.

Parameters

  userId | The ID of the user whose audio you want to stop subscribing to.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT), if no such user exists or `userId` is invalid.

## ◆ unsubscribeAllAudio()

virtual int unsubscribeAllAudio | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Stops subscribing to the audio of all remote users in the channel.

This method automatically stops subscribing to the audio of any subsequent user, unless you explicitly call subscribeAudio or subscribeAllAudio.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustPlaybackSignalVolume()

virtual int adjustPlaybackSignalVolume | ( | int | volume,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Adjusts the playback signal volume.

Parameters

  volume | The playback volume. The value ranges between 0 and 400, including the following: 0: Mute. 100: (Default) Original volume. 400: Four times the original volume with signal-clipping protection.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getPlaybackSignalVolume()

virtual int getPlaybackSignalVolume | ( | int * | volume | ) |
| pure virtual

Gets the current playback signal volume.

Parameters

  volume | A pointer to the playback signal volume.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ adjustUserPlaybackSignalVolume()

virtual int adjustUserPlaybackSignalVolume | ( | user_id_t | userId,
|  | int | volume,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

## ◆ getUserPlaybackSignalVolume()

virtual int getUserPlaybackSignalVolume | ( | user_id_t | userId,
|  | int * | volume
| ) |  |
| pure virtual

Gets the current playback signal volume of specified user.

Parameters

  userId | The ID of the Remote user.
  volume | A pointer to the playback signal volume.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableSoundPositionIndication()

virtual int enableSoundPositionIndication | ( | bool | enabled,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enables/Disables stereo panning for remote users.

Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.

Parameters

  enabled | Sets whether or not to enable stereo panning for remote users: true: enables stereo panning. false: disables stereo panning.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteVoicePosition()

virtual int setRemoteVoicePosition | ( | user_id_t | userId,
|  | double | pan,
|  | double | gain,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the sound position and gain of a remote user.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.

Note
  - For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
  - This method requires hardware support. For the best sound positioning, we recommend using a wired headset.
  - Ensure that you call this method after joining a channel.

Parameters

  userId | The ID of the remote user.
  pan | The sound position of the remote user. The value ranges from -1.0 to 1.0: 0.0: the remote sound comes from the front. -1.0: the remote sound comes from the left. 1.0: the remote sound comes from the right.
  gain | Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableSpatialAudio()

virtual int enableSpatialAudio | ( | bool | enabled,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

enable spatial audio

Parameters

  enabled | enable/disable spatial audio: true: enable spatial audio. false: disable spatial audio.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackAudioFrameParameters()

virtual int setPlaybackAudioFrameParameters | ( | size_t | numberOfChannels,
|  | uint32_t | sampleRateHz,
|  | RAW_AUDIO_FRAME_OP_MODE_TYPE | mode = `RAW_AUDIO_FRAME_OP_MODE_READ_ONLY`,
|  | int | samplesPerCall = `0`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the audio frame parameters for the onPlaybackAudioFrame callback.

Parameters

  numberOfChannels | The number of audio channels of the audio frame in the `onPlaybackAudioFrame` callback. 1: Mono. 2: Stereo.
  sampleRateHz | The sample rate (Hz) of the audio frame in the `onPlaybackAudioFrame` callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
  mode | Use mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.
  samplesPerCall | The number of samples of the audio frame. *

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRecordingAudioFrameParameters()

virtual int setRecordingAudioFrameParameters | ( | size_t | numberOfChannels,
|  | uint32_t | sampleRateHz,
|  | RAW_AUDIO_FRAME_OP_MODE_TYPE | mode = `RAW_AUDIO_FRAME_OP_MODE_READ_ONLY`,
|  | int | samplesPerCall = `0`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the audio frame parameters for the onRecordAudioFrame callback.

Parameters

  numberOfChannels | The number of channels of the audio frame in the `onRecordAudioFrame` callback. 1: Mono. 2: Stereo.
  sampleRateHz | The sample rate (Hz) of the audio frame in the `onRecordAudioFrame` callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
  mode | Use mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.
  samplesPerCall | The number of samples of the audio frame.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setMixedAudioFrameParameters()

virtual int setMixedAudioFrameParameters | ( | size_t | numberOfChannels,
|  | uint32_t | sampleRateHz,
|  | int | samplesPerCall = `0`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the audio frame parameters for the onMixedAudioFrame callback.

Parameters

  numberOfChannels | The number of channels of the audio frame in the `onMixedAudioFrame` callback. 1: Mono. 2: Stereo.
  sampleRateHz | The sample rate (Hz) of the audio frame in the `onMixedAudioFrame` callback. You can set it as 8000, 16000, 32000, 44100, or 48000.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setEarMonitoringAudioFrameParameters()

virtual int setEarMonitoringAudioFrameParameters | ( | bool | enabled,
|  | size_t | numberOfChannels,
|  | uint32_t | sampleRateHz,
|  | RAW_AUDIO_FRAME_OP_MODE_TYPE | mode = `RAW_AUDIO_FRAME_OP_MODE_READ_ONLY`,
|  | int | samplesPerCall = `0`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the audio frame parameters for the onEarMonitoringAudioFrame callback.

Parameters

  enabled | Determines whether to enable ear monitoring audio frame observer. true: Enable ear monitoring audio frame observer. false: Disable ear monitoring audio frame observer.
  numberOfChannels | The number of audio channels of the audio frame in the `onEarMonitoringAudioFrame` callback. 1: Mono. 2: Stereo.
  sampleRateHz | The sample rate (Hz) of the audio frame in the `onEarMonitoringAudioFrame` callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
  mode | Use mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.
  samplesPerCall | The number of samples of the audio frame. *

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackAudioFrameBeforeMixingParameters()

virtual int setPlaybackAudioFrameBeforeMixingParameters | ( | size_t | numberOfChannels,
|  | uint32_t | sampleRateHz,
|  | int | samplesPerCall = `0`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the audio frame parameters for the onPlaybackAudioFrameBeforeMixing callback.

Parameters

  numberOfChannels | The number of channels of the audio frame in the `onPlaybackAudioFrameBeforeMixing` callback. 1: Mono. 2: Stereo.
  sampleRateHz | The sample rate (Hz) of the audio frame in the `onPlaybackAudioFrameBeforeMixing` callback. You can set it as 8000, 16000, 32000, 44100, or 48000.
  samplesPerCall | The number of samples of the audio frame.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerAudioFrameObserver()

virtual int registerAudioFrameObserver | ( | agora::media::IAudioFrameObserverBase * | observer,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an audio frame observer.

You need to implement the `IAudioFrameObserverBase` class in this method, and register the following callbacks according to your scenario:

- onRecordAudioFrame: Occurs when the SDK receives the audio data captured by the local recording device.
- onPlaybackAudioFrame: Occurs when the SDK receives the remote audio data for playback.
- onPlaybackAudioFrameBeforeMixing: Occurs when the SDK receives the remote audio data of a specified remote user before mixing.
- onMixedAudioFrame: Occurs when the SDK receives the mixed data of recorded and playback audio.

Parameters

  observer | A pointer to the audio frame observer: IAudioFrameObserverBase.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterAudioFrameObserver()

virtual int unregisterAudioFrameObserver | ( | agora::media::IAudioFrameObserverBase * | observer | ) |
| pure virtual

Releases the audio frame observer.

Parameters

  observer | The pointer to the audio frame observer: IAudioFrameObserverBase.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableAudioSpectrumMonitor()

virtual int enableAudioSpectrumMonitor | ( | int | intervalInMS = `100`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enable the audio spectrum monitor.

Parameters

  intervalInMS | Sets the time interval(ms) between two consecutive audio spectrum callback. The default value is 100. This param should be larger than 10.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ disableAudioSpectrumMonitor()

virtual int disableAudioSpectrumMonitor | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Disalbe the audio spectrum monitor.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerAudioSpectrumObserver()

virtual int registerAudioSpectrumObserver | ( | agora::media::IAudioSpectrumObserver * | observer,
|  | void(*)(agora::media::IAudioSpectrumObserver *) | safeDeleter,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an audio spectrum observer.

You need to implement the `IAudioSpectrumObserver` class in this method, and register the following callbacks according to your scenario:

- onAudioSpectrumComputed: Occurs when the SDK receives the audio data and at set intervals.

Parameters

  observer | A pointer to the audio spectrum observer: IAudioSpectrumObserver.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterAudioSpectrumObserver()

virtual int unregisterAudioSpectrumObserver | ( | agora::media::IAudioSpectrumObserver * | observer | ) |
| pure virtual

Releases the audio spectrum observer.

Parameters

  observer | The pointer to the audio spectrum observer: IAudioSpectrumObserver.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerLocalVideoEncodedFrameObserver()

virtual int registerLocalVideoEncodedFrameObserver | ( | agora::media::IVideoEncodedFrameObserver * | observer,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an IVideoEncodedFrameObserver object.

You need to implement the `IVideoEncodedFrameObserver` class in this method. Once you successfully register the local encoded frame observer, the SDK triggers the onEncodedVideoFrameReceived callback when it receives the encoded video image.

Parameters

  observer | The pointer to the `IVideoEncodedFrameObserver` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterLocalVideoEncodedFrameObserver()

virtual int unregisterLocalVideoEncodedFrameObserver | ( | agora::media::IVideoEncodedFrameObserver * | observer | ) |
| pure virtual

Releases the IVideoEncodedFrameObserver object.

Parameters

  observer | The pointer to the `IVideoEncodedFrameObserver` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ forceNextIntraFrame()

virtual int forceNextIntraFrame | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Force trigger to intra-frame the next frame.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerVideoEncodedFrameObserver()

virtual int registerVideoEncodedFrameObserver | ( | agora::media::IVideoEncodedFrameObserver * | observer,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an IVideoEncodedFrameObserver object.

You need to implement the `IVideoEncodedFrameObserver` class in this method. Once you successfully register the encoded frame observer, the SDK triggers the onEncodedVideoFrameReceived callback when it receives the encoded video image.

Parameters

  observer | The pointer to the `IVideoEncodedFrameObserver` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterVideoEncodedFrameObserver()

virtual int unregisterVideoEncodedFrameObserver | ( | agora::media::IVideoEncodedFrameObserver * | observer | ) |
| pure virtual

Releases the IVideoEncodedFrameObserver object.

Parameters

  observer | The pointer to the `IVideoEncodedFrameObserver` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerVideoFrameObserver()

virtual int registerVideoFrameObserver | ( | IVideoFrameObserver2 * | observer,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an IVideoFrameObserver2 object.

You need to implement the `IVideoFrameObserver2` class in this method. Once you successfully register the video frame observer, the SDK triggers the onFrame callback when it receives the video image.

Parameters

  observer | The pointer to the `IVideoFrameObserver2` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterVideoFrameObserver()

virtual int unregisterVideoFrameObserver | ( | IVideoFrameObserver2 * | observer | ) |
| pure virtual

Releases the IVideoFrameObserver2 object.

Parameters

  observer | The pointer to the `IVideoFrameObserver2` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setVideoSubscriptionOptions()

virtual int setVideoSubscriptionOptions | ( | user_id_t | userId,
|  | const VideoSubscriptionOptions & | options,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

## ◆ setHighPriorityUserList()

virtual int setHighPriorityUserList | ( | uid_t * | vipList,
|  | int | uidNum,
|  | int | option,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

## ◆ getHighPriorityUserList()

virtual int getHighPriorityUserList | ( | std::vector< uid_t > & | vipList,
|  | int & | option
| ) |  |
| pure virtual

## ◆ setRemoteSubscribeFallbackOption()

virtual int setRemoteSubscribeFallbackOption | ( | int | option,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

## ◆ setSubscribeAudioAllowlist()

virtual int setSubscribeAudioAllowlist | ( | user_id_t * | userList,
|  | int | userNumber,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the allowlist of subscribe remote stream audio.

Parameters

  userList | The id list of users who do subscribe to audio.
  userNumber | The number of uid in uidList.

Note
  If uid is in uidList, the remote user's audio will be subscribed, even if unsubscribeAudio(uid) and unsubscribeAllAudio(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to audio.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setSubscribeVideoAllowlist()

virtual int setSubscribeVideoAllowlist | ( | user_id_t * | userList,
|  | int | userNumber,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the allowlist of subscribe remote stream video.

Parameters

  userList | The id list of users who do subscribe to video.
  userNumber | The number of uid in uidList.

Note
  If uid is in uidList, the remote user's video will be subscribed, even if unsubscribeVideo(uid) and unsubscribeAllVideo(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to video.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ subscribeVideo()

virtual int subscribeVideo | ( | user_id_t | userId,
|  | const VideoSubscriptionOptions & | subscriptionOptions,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Subscribes to the video of a specified remote user in the channel.

Parameters

  userId | The ID of the user whose video you want to subscribe to.
  subscriptionOptions | The reference to the video subscription options: VideoSubscriptionOptions. For example, subscribing to encoded video data only or subscribing to low-stream video.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT), if `userId` is invalid.

## ◆ subscribeAllVideo()

virtual int subscribeAllVideo | ( | const VideoSubscriptionOptions & | subscriptionOptions,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Subscribes to the video of all remote users in the channel.

This method also automatically subscribes to the video of any subsequent remote user.

Parameters

  subscriptionOptions | The reference to the video subscription options: VideoSubscriptionOptions.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unsubscribeVideo()

virtual int unsubscribeVideo | ( | user_id_t | userId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Stops subscribing to the video of a specified remote user in the channel.

Parameters

  userId | The ID of the user whose video you want to stop subscribing to.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT), if `userId` is invalid.

## ◆ unsubscribeAllVideo()

virtual int unsubscribeAllVideo | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Stops subscribing to the video of all remote users in the channel.

This method automatically stops subscribing to the video of any subsequent user, unless you explicitly call subscribeVideo or subscribeAllVideo.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioVolumeIndicationParameters()

virtual int setAudioVolumeIndicationParameters | ( | int | intervalInMS,
|  | int | smooth,
|  | bool | reportVad,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the time interval and the volume smoothing factor of the onAudioVolumeIndication callback.

By default, the SDK triggers the `onAudioVolumeIndication` callback once every 500 ms, with a smoothing factor of 3.

Parameters

  intervalInMS | Sets the time interval(ms) between two consecutive volume indications. The default value is 500. ≤ 10: Disables the volume indication. > 10: The time interval (ms) between two consecutive callbacks.
  smooth | The smoothing factor that sets the sensitivity of the audio volume indicator. The value range is [0,10]. The greater the value, the more sensitive the indicator.The default value is 3.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT), if `intervalInMS` or `smooth` is out of range.

## ◆ registerLocalUserObserver()

virtual int registerLocalUserObserver | ( | ILocalUserObserver * | observer,
|  | void(*)(ILocalUserObserver *) | safeDeleter = `NULL`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers a local user observer object.

You need to implement the ILocalUserObserver class in this method. Once registered, the ILocalUserObserver receives events of the ILocalUser object.

Parameters

  observer | The pointer to the `ILocalUserObserver` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterLocalUserObserver()

virtual int unregisterLocalUserObserver | ( | ILocalUserObserver * | observer | ) |
| pure virtual

Releases the ILocalUserObserver object.

Parameters

  observer | The pointer to the `ILocalUserObserver` object that you want to release.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getMediaControlPacketSender()

virtual IMediaControlPacketSender* getMediaControlPacketSender | ( |  | ) |
| pure virtual

Gets the media control packet sender.

Returns
  - The pointer to the media control packet sender IMediaControlPacketSender: Success.
  - A null pointer: Failure.

## ◆ registerMediaControlPacketReceiver()

virtual int registerMediaControlPacketReceiver | ( | IMediaControlPacketReceiver * | ctrlPacketReceiver,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers a media control packet receiver.

You need to implement the `IMediaControlPacketReceiver` class in this method. Once you successfully register the media control packet receiver, the SDK triggers the onMediaControlPacketReceived callback when it receives the media control packet.

Parameters

  ctrlPacketReceiver | The pointer to the IMediaControlPacketReceiver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterMediaControlPacketReceiver()

virtual int unregisterMediaControlPacketReceiver | ( | IMediaControlPacketReceiver * | ctrlPacketReceiver | ) |
| pure virtual

Releases the media control packet receiver.

Parameters

  ctrlPacketReceiver | The pointer to the `IMediaControlPacketReceiver` object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ sendIntraRequest()

virtual int sendIntraRequest | ( | user_id_t | userId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sends intra-frame request to the broadcaster with a specified uid.

The local user receives the `onIntraRequestReceived` callback when the broadcaster receives the request.

Parameters

  userId | The user ID of the target broadcaster .

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioFilterable()

virtual int setAudioFilterable | ( | bool | filterable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Set local audio filterable by topn

The local user receives the `onIntraRequestReceived` callback when the broadcaster receives the request.

Parameters

  userId | The user ID of the target broadcaster .

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableRemoteAudioTrackFilter()

virtual int enableRemoteAudioTrackFilter | ( | user_id_t | userId,
|  | const char * | id,
|  | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enable / Disable specified audio filter

Parameters

  userId | The ID of the remote user
  id | id of the filter
  enable | enable / disable the filter with given id

Returns
  - 0: success
  - <0: failure

## ◆ setRemoteAudioTrackFilterProperty()

virtual int setRemoteAudioTrackFilterProperty | ( | user_id_t | userId,
|  | const char * | id,
|  | const char * | key,
|  | const char * | jsonValue,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

set the properties of the specified audio filter

Parameters

  userId | The ID of the remote user
  id | id of the filter
  key | key of the property
  jsonValue | json str value of the property

Returns
  - 0: success
  - <0: failure

## ◆ getRemoteAudioTrackFilterProperty()

virtual int getRemoteAudioTrackFilterProperty | ( | user_id_t | userId,
|  | const char * | id,
|  | const char * | key,
|  | char * | jsonValue,
|  | size_t | bufSize
| ) |  |
| pure virtual

get the properties of the specified audio filter

Parameters

  userId | The ID of the remote user
  id | id of the filter
  key | key of the property
  jsonValue | json str value of the property
  bufSize | max length of the json value buffer

Returns
  - 0: success
  - <0: failure

## ◆ publishDataChannel()

virtual int publishDataChannel | ( | agora_refptr< ILocalDataChannel > | channel,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Publishes a local data channel to the channel.

Parameters

  channel | The data stream to be published.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unpublishDataChannel()

virtual int unpublishDataChannel | ( | agora_refptr< ILocalDataChannel > | channel,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Stops publishing the data channel to the channel.

Parameters

  channel | The data channel that you want to stop publishing.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ subscribeDataChannel()

virtual int subscribeDataChannel | ( | user_id_t | userId,
|  | int | channelId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Subscribes to a specified data channel of a specified remote user in channel.

Parameters

  userId | The ID of the remote user whose data channel you want to subscribe to.
  channelId | The ID of the data channel that you want to subscribe to.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unsubscribeDataChannel()

virtual int unsubscribeDataChannel | ( | user_id_t | userId,
|  | int | channelId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Stops subscribing to the data channel of a specified remote user in the channel.

Parameters

  userId | The ID of the remote user whose data channel you want to stop subscribing to.
  channelId | The ID of the data channel that you want to stop subscribing to.

Returns
  - 0: Success.
  - < 0: Failure.
    - -2(ERR_INVALID_ARGUMENT), if no such user exists or `userId` is invalid.

## ◆ registerDataChannelObserver()

virtual int registerDataChannelObserver | ( | IDataChannelObserver * | observer,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an data channel observer.

You need to implement the `IDataChannelObserver` class in this method

Parameters

  observer | A pointer to the data channel observer:

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterDataChannelObserver()

virtual int unregisterDataChannelObserver | ( | IDataChannelObserver * | observer | ) |
| pure virtual

Releases the data channel observer.

Parameters

  observer | The pointer to the data channel observer

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ SetAudioNsMode()

virtual int SetAudioNsMode | ( | bool | NsEnable,
|  | NS_MODE | NsMode,
|  | NS_LEVEL | NsLevel,
|  | NS_DELAY | NsDelay,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

set the profile of audio noise suppression module

Parameters

  NsEnable | enable ns or not
  NsMode | type of ns
  NsLevel | level of the suppression
  NsDelay | algorithm delay

Returns
  - 0: success
  - <0: failure

## ◆ RegisterLocalMixedAudioTrack()

virtual int RegisterLocalMixedAudioTrack | ( | agora_refptr< ILocalAudioTrack > & | track,
|  | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

enable the mix track that mix special track

Parameters

  track | The special mixed audio track.
  enalble | Action of start mixing this user's audio.

Returns
  - 0: success
  - <0: failure

## ◆ takeDataChannelSnapshot()

virtual int takeDataChannelSnapshot | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Trigger data channel update callback with all data channel infos.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ sendAudioMetadata()

virtual int sendAudioMetadata | ( | const char * | metadata,
|  | size_t | length,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

send audio metadata

Parameters

  metadata | The pointer of metadata
  length | Size of metadata

Returns
  - 0: success
  - <0: failure @technical preview

## ◆ setRemoteRenderTargetFps()

virtual int setRemoteRenderTargetFps | ( | int | targetFps | ) |
| pure virtual

set remote render target fps

Parameters

  target_fps | The target fps

Returns
  - 0: success
  - <0: failure @technical preview