Agora RTC Objective-C API Reference Refactor

Public Types | Public Member Functions
ILocalUserObserver Class Referenceabstract

## Public Types
enum | USER_MEDIA_INFO { USER_MEDIA_INFO_MUTE_AUDIO = 0, USER_MEDIA_INFO_MUTE_VIDEO = 1, USER_MEDIA_INFO_ENABLE_VIDEO = 4, USER_MEDIA_INFO_ENABLE_LOCAL_VIDEO = 8 }

## Public Member Functions
virtual void | onAudioTrackPublishSuccess (agora_refptr< ILocalAudioTrack > audioTrack)=0
virtual void | onAudioTrackPublicationFailure (agora_refptr< ILocalAudioTrack > audioTrack, ERROR_CODE_TYPE error)=0
virtual void | onLocalAudioTrackStatistics (const LocalAudioStats &stats)=0
virtual void | onRemoteAudioTrackStatistics (agora_refptr< rtc::IRemoteAudioTrack > audioTrack, const RemoteAudioTrackStats &stats)=0
virtual void | onUserAudioTrackSubscribed (user_id_t userId, agora_refptr< rtc::IRemoteAudioTrack > audioTrack)=0
virtual void | onUserAudioTrackStateChanged (user_id_t userId, agora_refptr< rtc::IRemoteAudioTrack > audioTrack, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed)=0
virtual void | onVideoTrackPublishSuccess (agora_refptr< ILocalVideoTrack > videoTrack)=0
virtual void | onVideoTrackPublicationFailure (agora_refptr< ILocalVideoTrack > videoTrack, ERROR_CODE_TYPE error)=0
virtual void | onLocalVideoTrackStateChanged (agora_refptr< rtc::ILocalVideoTrack > videoTrack, LOCAL_VIDEO_STREAM_STATE state, LOCAL_VIDEO_STREAM_REASON reason)=0
virtual void | onLocalVideoTrackStatistics (agora_refptr< rtc::ILocalVideoTrack > videoTrack, const LocalVideoTrackStats &stats)=0
virtual void | onUserVideoTrackSubscribed (user_id_t userId, const VideoTrackInfo &trackInfo, agora_refptr< rtc::IRemoteVideoTrack > videoTrack)=0
virtual void | onUserVideoTrackStateChanged (user_id_t userId, agora_refptr< rtc::IRemoteVideoTrack > videoTrack, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed)=0
virtual void | onFirstRemoteVideoFrameRendered (user_id_t userId, int width, int height, int elapsed)=0
virtual void | onRemoteVideoTrackStatistics (agora_refptr< rtc::IRemoteVideoTrack > videoTrack, const RemoteVideoTrackStats &stats)=0
virtual void | onAudioVolumeIndication (const AudioVolumeInformation *speakers, unsigned int speakerNumber, int totalVolume)=0
virtual void | onActiveSpeaker (user_id_t userId)=0
virtual void | onAudioSubscribeStateChanged (const char *channel, user_id_t userId, STREAM_SUBSCRIBE_STATE oldState, STREAM_SUBSCRIBE_STATE newState, int elapseSinceLastState)=0
virtual void | onVideoSubscribeStateChanged (const char *channel, user_id_t userId, STREAM_SUBSCRIBE_STATE oldState, STREAM_SUBSCRIBE_STATE newState, int elapseSinceLastState)=0
virtual void | onAudioPublishStateChanged (const char *channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState)=0
virtual void | onVideoPublishStateChanged (const char *channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState)=0
virtual void | onRemoteSubscribeFallbackToAudioOnly (user_id_t userId, bool isFallbackOrRecover)
virtual void | onFirstRemoteAudioFrame (user_id_t userId, int elapsed)=0
virtual void | onFirstRemoteAudioDecoded (user_id_t userId, int elapsed)=0
virtual void | onFirstRemoteVideoFrame (user_id_t userId, int width, int height, int elapsed)=0
virtual void | onFirstRemoteVideoDecoded (user_id_t userId, int width, int height, int elapsed)=0
virtual void | onVideoSizeChanged (user_id_t userId, int width, int height, int rotation)=0
virtual void | onAudioMetadataReceived (user_id_t userId, const char *metadata, size_t length)
virtual void | onUserInfoUpdated (user_id_t userId, USER_MEDIA_INFO msg, bool val)
virtual void | onIntraRequestReceived ()
virtual void | onStreamMessage (user_id_t userId, int streamId, const char *data, size_t length, uint64_t sendTs=0)
virtual void | onUserStateChanged (user_id_t userId, uint32_t state)
virtual void | onRdtMessage (user_id_t userId, RdtStreamType type, const char *data, size_t length)
virtual void | onRdtStateChanged (user_id_t userId, RdtState state)

## Detailed Description

The `ILocalUserObserver` class.

## Member Enumeration Documentation

## ◆ USER_MEDIA_INFO

enum USER_MEDIA_INFO

The media information of a specified user.

Enumerator
USER_MEDIA_INFO_MUTE_AUDIO | 0: The user has muted the audio.
USER_MEDIA_INFO_MUTE_VIDEO | 1: The user has muted the video.
USER_MEDIA_INFO_ENABLE_VIDEO | 4: The user has enabled the video, which includes video capturing and encoding.
USER_MEDIA_INFO_ENABLE_LOCAL_VIDEO | 8: The user has enabled the local video capturing.

## Constructor & Destructor Documentation

## ◆ ~ILocalUserObserver()

virtual ~ILocalUserObserver | ( |  | ) |
| inline virtual

## Member Function Documentation

## ◆ onAudioTrackPublishStart()

virtual void onAudioTrackPublishStart | ( | agora_refptr< ILocalAudioTrack > | audioTrack | ) |
| pure virtual

## ◆ onAudioTrackPublishSuccess()

virtual void onAudioTrackPublishSuccess | ( | agora_refptr< ILocalAudioTrack > | audioTrack | ) |
| pure virtual

Occurs when the first packet of the local audio track is sent, indicating that the local audio track is successfully published.

Parameters

  audioTrack | The pointer to ILocalAudioTrack.

## ◆ onAudioTrackUnpublished()

virtual void onAudioTrackUnpublished | ( | agora_refptr< ILocalAudioTrack > | audioTrack | ) |
| pure virtual

## ◆ onAudioTrackPublicationFailure()

virtual void onAudioTrackPublicationFailure | ( | agora_refptr< ILocalAudioTrack > | audioTrack,
|  | ERROR_CODE_TYPE | error
| ) |  |
| pure virtual

Occurs when a local audio track fails to be published.

Parameters

  audioTrack | The pointer to `ILocalAudioTrack`.
  error | The error information: ERROR_CODE_TYPE.

## ◆ onLocalAudioTrackStatistics()

virtual void onLocalAudioTrackStatistics | ( | const LocalAudioStats & | stats | ) |
| pure virtual

Reports the statistics of a local audio track.

Parameters

  stats | The reference to the statistics of the local audio track.

## ◆ onRemoteAudioTrackStatistics()

virtual void onRemoteAudioTrackStatistics | ( | agora_refptr< rtc::IRemoteAudioTrack > | audioTrack,
|  | const RemoteAudioTrackStats & | stats
| ) |  |
| pure virtual

Reports the statistics of a remote audio track.

Parameters

  audioTrack | The pointer to `IRemoteAudioTrack`.
  stats | The statistics of the remote audio track.

## ◆ onUserAudioTrackSubscribed()

virtual void onUserAudioTrackSubscribed | ( | user_id_t | userId,
|  | agora_refptr< rtc::IRemoteAudioTrack > | audioTrack
| ) |  |
| pure virtual

Occurs when the first remote audio frame is received.

This callback indicates that the local user has subscribed to a specified remote audio track, and the first frame of this audio track has been received.

Parameters

  userId | The ID of the remote user whose audio frame is received.
  audioTrack | The pointer to `IRemoteAudioTrack`.

## ◆ onUserAudioTrackStateChanged()

virtual void onUserAudioTrackStateChanged | ( | user_id_t | userId,
|  | agora_refptr< rtc::IRemoteAudioTrack > | audioTrack,
|  | REMOTE_AUDIO_STATE | state,
|  | REMOTE_AUDIO_STATE_REASON | reason,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the state of a remote audio track changes.

Parameters

  userId | The ID of the remote user whose audio track state has changed.
  audioTrack | The pointer to `IRemoteAudioTrack`.
  state | The current state of the audio track.
  reason | The reason for the state change.
  elapsed | The time (ms) since the user connects to an Agora channel.

## ◆ onVideoTrackPublishStart()

virtual void onVideoTrackPublishStart | ( | agora_refptr< ILocalVideoTrack > | videoTrack | ) |
| pure virtual

## ◆ onVideoTrackPublishSuccess()

virtual void onVideoTrackPublishSuccess | ( | agora_refptr< ILocalVideoTrack > | videoTrack | ) |
| pure virtual

Occurs when the first packet of a local video track is sent, indicating that the local video track is successfully published.

Parameters

  videoTrack | The pointer to `ILocalVideoTrack`.

## ◆ onVideoTrackPublicationFailure()

virtual void onVideoTrackPublicationFailure | ( | agora_refptr< ILocalVideoTrack > | videoTrack,
|  | ERROR_CODE_TYPE | error
| ) |  |
| pure virtual

Occurs when a local video track fails to be published.

Parameters

  videoTrack | The pointer to `ILocalVideoTrack`.
  error | The error information: ERROR_CODE_TYPE.

## ◆ onVideoTrackUnpublished()

virtual void onVideoTrackUnpublished | ( | agora_refptr< ILocalVideoTrack > | videoTrack | ) |
| pure virtual

## ◆ onLocalVideoTrackStateChanged()

virtual void onLocalVideoTrackStateChanged | ( | agora_refptr< rtc::ILocalVideoTrack > | videoTrack,
|  | LOCAL_VIDEO_STREAM_STATE | state,
|  | LOCAL_VIDEO_STREAM_REASON | reason
| ) |  |
| pure virtual

Occurs when the state of a local video track changes.

Note
  When you receive error from this callback, the corresponding track is in error state. To make the track recover from error state, we highly recommend that you disable the track and try re-enabling it again.

Parameters

  videoTrack | The pointer to `ILocalVideoTrack`.
  state | The state of the local video track.
  reason | The error information.

## ◆ onLocalVideoTrackStatistics()

virtual void onLocalVideoTrackStatistics | ( | agora_refptr< rtc::ILocalVideoTrack > | videoTrack,
|  | const LocalVideoTrackStats & | stats
| ) |  |
| pure virtual

Reports the statistics of a local video track.

Parameters

  videoTrack | The pointer to `ILocalVideoTrack`.
  stats | The statistics of the local video track.

## ◆ onUserVideoTrackSubscribed()

virtual void onUserVideoTrackSubscribed | ( | user_id_t | userId,
|  | const VideoTrackInfo & | trackInfo,
|  | agora_refptr< rtc::IRemoteVideoTrack > | videoTrack
| ) |  |
| pure virtual

Occurs when the first remote video frame is received.

This callback indicates that the local user has subscribed to a specified remote video track, and the first frame of this video track has been received.

Parameters

  userId | The ID of the remote user whose video frame is received.
  trackInfo | The information of the remote video track.
  videoTrack | The pointer to `IRemoteVideoTrack`.

## ◆ onUserVideoTrackStateChanged()

virtual void onUserVideoTrackStateChanged | ( | user_id_t | userId,
|  | agora_refptr< rtc::IRemoteVideoTrack > | videoTrack,
|  | REMOTE_VIDEO_STATE | state,
|  | REMOTE_VIDEO_STATE_REASON | reason,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the state of a remote video track changes.

Parameters

  userId | the ID of the remote user whose video track state has changed.
  videoTrack | The pointer to `IRemoteVideoTrack`.
  state | The current state of the video track.
  reason | The reason for the state change.
  elapsed | The time (ms) since the user connects to an Agora channel.

## ◆ onFirstRemoteVideoFrameRendered()

virtual void onFirstRemoteVideoFrameRendered | ( | user_id_t | userId,
|  | int | width,
|  | int | height,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the first remote video frame is rendered.

Parameters

  userId | the ID of the remote user.
  width | Width (px) of the video frame.
  height | Height (px) of the video stream.
  elapsed | The time (ms) since the user connects to an Agora channel.

## ◆ onRemoteVideoTrackStatistics()

virtual void onRemoteVideoTrackStatistics | ( | agora_refptr< rtc::IRemoteVideoTrack > | videoTrack,
|  | const RemoteVideoTrackStats & | stats
| ) |  |
| pure virtual

Reports the statistics of a remote video track.

Parameters

  videoTrack | The pointer to `IRemoteVideoTrack`.
  stats | The statistics of the remote video track.

## ◆ onAudioVolumeIndication()

virtual void onAudioVolumeIndication | ( | const AudioVolumeInformation * | speakers,
|  | unsigned int | speakerNumber,
|  | int | totalVolume
| ) |  |
| pure virtual

Reports which users are speaking, the speakers' volumes, and whether the local user is speaking.

This callback reports the IDs and volumes of the loudest speakers at the moment in the channel, and whether the local user is speaking.

You can set the time interval of this callback using setAudioVolumeIndicationParameters.

The SDK triggers two `onAudioVolumeIndication` callbacks at one time, one reporting the volume information of the local user and the other reporting the volume information of all remote users.

Note
  - To detect whether the local user is speaking, set `report_vad` in `enableAudioVolumeIndication` to `true`.

Parameters

  speakers | The pointer to AudioVolumeInformation, which is an array containing the user ID and volume information for each speaker. In the local user's callback, this array contains the following members: `uid`, which is always `0` `volume`, which reports the sum of the voice volume and the audio-mixing volume of the local user `vad`, which reports whether the local user is speaking In the remote users' callback, this array contains the following members: `uid`, which is the UID of each remote speaker `volume`, which reports the sum of the voice volume and the audio-mixing volume of each remote speaker. `vad`, which is always `0` An empty `speakers` array in the callback indicates that no remote user is speaking at the moment.
  speakerNumber | The total number of the speakers.
  totalVolume | The total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). In the local user's callback, `totalVolume` is the sum of the voice volume and the audio-mixing volume of the local user. In the remote speakers' callback, `totalVolume` is the sum of the voice volume and the audio-mixing volume of all remote speakers.

## ◆ onActiveSpeaker()

virtual void onActiveSpeaker | ( | user_id_t | userId | ) |
| pure virtual

Occurs when an active speaker is detected.

You can add relative functions on your app, for example, the active speaker, once detected, will have the portrait zoomed in.

Note
  - The active speaker means the user ID of the speaker who speaks at the highest volume during a certain period of time.

Parameters

  userId | The ID of the active speaker. A `userId` of `0` means the local user.

## ◆ onAudioSubscribeStateChanged()

virtual void onAudioSubscribeStateChanged | ( | const char * | channel,
|  | user_id_t | userId,
|  | STREAM_SUBSCRIBE_STATE | oldState,
|  | STREAM_SUBSCRIBE_STATE | newState,
|  | int | elapseSinceLastState
| ) |  |
| pure virtual

Occurs when the audio subscribe state changed.

Parameters

  channel | The channel name of user joined.
  userId | The remote string user ID that is subscribed to.
  oldState | The old state of the audio stream subscribe : STREAM_SUBSCRIBE_STATE.
  newState | The new state of the audio stream subscribe : STREAM_SUBSCRIBE_STATE.
  elapseSinceLastState | The time elapsed (ms) from the old state to the new state.

## ◆ onVideoSubscribeStateChanged()

virtual void onVideoSubscribeStateChanged | ( | const char * | channel,
|  | user_id_t | userId,
|  | STREAM_SUBSCRIBE_STATE | oldState,
|  | STREAM_SUBSCRIBE_STATE | newState,
|  | int | elapseSinceLastState
| ) |  |
| pure virtual

Occurs when the video subscribe state changed.

Parameters

  channel | The channel name of user joined.
  userId | The remote string user ID that is subscribed to.
  oldState | The old state of the video stream subscribe : STREAM_SUBSCRIBE_STATE.
  newState | The new state of the video stream subscribe : STREAM_SUBSCRIBE_STATE.
  elapseSinceLastState | The time elapsed (ms) from the old state to the new state.

## ◆ onAudioPublishStateChanged()

virtual void onAudioPublishStateChanged | ( | const char * | channel,
|  | STREAM_PUBLISH_STATE | oldState,
|  | STREAM_PUBLISH_STATE | newState,
|  | int | elapseSinceLastState
| ) |  |
| pure virtual

Occurs when the audio publish state changed.

Parameters

  channel | The channel name of user joined.
  oldState | The old state of the audio stream publish : STREAM_PUBLISH_STATE.
  newState | The new state of the audio stream publish : STREAM_PUBLISH_STATE.
  elapseSinceLastState | The time elapsed (ms) from the old state to the new state.

## ◆ onVideoPublishStateChanged()

virtual void onVideoPublishStateChanged | ( | const char * | channel,
|  | STREAM_PUBLISH_STATE | oldState,
|  | STREAM_PUBLISH_STATE | newState,
|  | int | elapseSinceLastState
| ) |  |
| pure virtual

Occurs when the video publish state changed.

Parameters

  channel | The channel name of user joined.
  oldState | The old state of the video stream publish : STREAM_PUBLISH_STATE.
  newState | The new state of the video stream publish : STREAM_PUBLISH_STATE.
  elapseSinceLastState | The time elapsed (ms) from the old state to the new state.

## ◆ onRemoteSubscribeFallbackToAudioOnly()

virtual void onRemoteSubscribeFallbackToAudioOnly | ( | user_id_t | userId,
|  | bool | isFallbackOrRecover
| ) |  |
| inline virtual

Occurs when the first remote audio frame is received.

Parameters

  userId | ID of the remote user.
  isFallbackOrRecover | Whether the remotely subscribed media stream falls back to audio-only or switches back to the video: true: The remotely subscribed media stream falls back to audio-only due to poor network conditions. false: The remotely subscribed media stream switches back to the video stream after the network conditions improved.

## ◆ onFirstRemoteAudioFrame()

virtual void onFirstRemoteAudioFrame | ( | user_id_t | userId,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the first remote audio frame is received.

Parameters

  userId | ID of the remote user.
  elapsed | The time (ms) since the user connects to an Agora channel.

## ◆ onFirstRemoteAudioDecoded()

virtual void onFirstRemoteAudioDecoded | ( | user_id_t | userId,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the SDK decodes the first remote audio frame for playback.

Parameters

  uid | User ID of the remote user sending the audio stream.
  elapsed | The time (ms) since the user connects to an Agora channel.

## ◆ onFirstRemoteVideoFrame()

virtual void onFirstRemoteVideoFrame | ( | user_id_t | userId,
|  | int | width,
|  | int | height,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the first remote video frame is rendered. The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window. The application can get the time elapsed from a user joining the channel until the first video frame is displayed.

Parameters

  userId | ID of the remote user.
  width | Width (px) of the video frame.
  height | Height (px) of the video stream.
  elapsed | Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

## ◆ onFirstRemoteVideoDecoded()

virtual void onFirstRemoteVideoDecoded | ( | user_id_t | userId,
|  | int | width,
|  | int | height,
|  | int | elapsed
| ) |  |
| pure virtual

Occurs when the SDK decodes the first remote video frame for playback.

Parameters

  userId | ID of the remote user.
  width | Width (px) of the video stream.
  height | Height (px) of the video stream.
  elapsed | The time (ms) since the user connects to an Agora channel.

## ◆ onVideoSizeChanged()

virtual void onVideoSizeChanged | ( | user_id_t | userId,
|  | int | width,
|  | int | height,
|  | int | rotation
| ) |  |
| pure virtual

The local or remote video size or rotation changed.

Parameters

  uid | User ID of the user whose video size or rotation has changed.
  width | Width (pixels) of the video stream.
  height | Height (pixels) of the video stream.
  rotation | Rotation [0 to 360).

## ◆ onAudioMetadataReceived()

virtual void onAudioMetadataReceived | ( | user_id_t | userId,
|  | const char * | metadata,
|  | size_t | length
| ) |  |
| inline virtual

The audio metadata received.

Parameters

  userId | ID of the remote user.
  metadata | The pointer of metadata
  length | Size of metadata @technical preview

## ◆ onUserInfoUpdated()

virtual void onUserInfoUpdated | ( | user_id_t | userId,
|  | USER_MEDIA_INFO | msg,
|  | bool | val
| ) |  |
| inline virtual

Occurs when the user media information is updated.

Parameters

  userId | The ID of the user.
  msg | The media information of the user. See USER_MEDIA_INFO.
  val | Whether the user is muted.

## ◆ onIntraRequestReceived()

virtual void onIntraRequestReceived | ( |  | ) |
| inline virtual

Occurs when the intra request is received from a remote user.

The method notifies the local user to encode a key frame.

## ◆ onStreamMessage()

virtual void onStreamMessage | ( | user_id_t | userId,
|  | int | streamId,
|  | const char * | data,
|  | size_t | length,
|  | uint64_t | sendTs = `0`
| ) |  |
| inline virtual

datastream from this connection.

## ◆ onUserStateChanged()

virtual void onUserStateChanged | ( | user_id_t | userId,
|  | uint32_t | state
| ) |  |
| inline virtual

Occurs when the remote user state is updated.

Parameters

  uid | The uid of the remote user.
  state | The remote user state.Just & REMOTE_USER_STATE

## ◆ onVideoRenderingTracingResult()

virtual void onVideoRenderingTracingResult | ( | user_id_t | user_id,
|  | MEDIA_TRACE_EVENT | currentState,
|  | VideoRenderingTracingInfo | tracingInfo
| ) |  |
| inline virtual

## ◆ onRdtMessage()

virtual void onRdtMessage | ( | user_id_t | userId,
|  | RdtStreamType | type,
|  | const char * | data,
|  | size_t | length
| ) |  |
| inline virtual

Occurs when receive rdt message.

Parameters

  userId | Remote uid.
  type | Rdt stream type.
  data | data The pointer to the sent data.
  length | length The length of the sent data.

## ◆ onRdtStateChanged()

virtual void onRdtStateChanged | ( | user_id_t | userId,
|  | RdtState | state
| ) |  |
| inline virtual

Occurs when rdt state changed with userId.

Parameters

  userId | Remote uid.
  state | rdt state.