io.agora.rtc.IRtcChannelEventHandler Class Reference

Public Member Functions
void	onChannelWarning (RtcChannel rtcChannel, int warn)
void	onChannelError (RtcChannel rtcChannel, int err)
void	onJoinChannelSuccess (RtcChannel rtcChannel, int uid, int elapsed)
void	onRejoinChannelSuccess (RtcChannel rtcChannel, int uid, int elapsed)
void	onLeaveChannel (RtcChannel rtcChannel, RtcStats stats)
void	onClientRoleChanged (RtcChannel rtcChannel, int oldRole, int newRole)
void	onUserJoined (RtcChannel rtcChannel, int uid, int elapsed)
void	onUserOffline (RtcChannel rtcChannel, int uid, int reason)
void	onConnectionStateChanged (RtcChannel rtcChannel, int state, int reason)
void	onConnectionLost (RtcChannel rtcChannel)
void	onTokenPrivilegeWillExpire (RtcChannel rtcChannel, String token)
void	onRequestToken (RtcChannel rtcChannel)
void	onRtcStats (RtcChannel rtcChannel, RtcStats stats)
void	onNetworkQuality (RtcChannel rtcChannel, int uid, int txQuality, int rxQuality)
void	onRemoteVideoStats (RtcChannel rtcChannel, RemoteVideoStats stats)
void	onRemoteAudioStats (RtcChannel rtcChannel, RemoteAudioStats stats)
void	onRemoteAudioStateChanged (RtcChannel rtcChannel, int uid, int state, int reason, int elapsed)
void	onAudioPublishStateChanged (RtcChannel rtcChannel, int oldState, int newState, int elapseSinceLastState)
void	onVideoPublishStateChanged (RtcChannel rtcChannel, int oldState, int newState, int elapseSinceLastState)
void	onFirstRemoteVideoFrame (RtcChannel rtcChannel, int uid, int width, int height, int elapsed)
void	onAudioSubscribeStateChanged (RtcChannel rtcChannel, int uid, int oldState, int newState, int elapseSinceLastState)
void	onVideoSubscribeStateChanged (RtcChannel rtcChannel, int uid, int oldState, int newState, int elapseSinceLastState)
void	onActiveSpeaker (RtcChannel rtcChannel, int uid)
void	onVideoSizeChanged (RtcChannel rtcChannel, int uid, int width, int height, int rotation)
void	onRemoteVideoStateChanged (RtcChannel rtcChannel, int uid, int state, int reason, int elapsed)
void	onUserSuperResolutionEnabled (RtcChannel rtcChannel, int uid, boolean enabled, int reason)
void	onStreamMessage (RtcChannel rtcChannel, int uid, int streamId, byte[] data)
void	onStreamMessageError (RtcChannel rtcChannel, int uid, int streamId, int error, int missed, int cached)
void	onChannelMediaRelayStateChanged (RtcChannel rtcChannel, int state, int code)
void	onChannelMediaRelayEvent (RtcChannel rtcChannel, int code)
void	onRtmpStreamingStateChanged (RtcChannel rtcChannel, String url, int state, int errCode)
void	onTranscodingUpdated (RtcChannel rtcChannel)
void	onRtmpStreamingEvent (RtcChannel rtcChannel, String url, int errCode)
void	onLocalPublishFallbackToAudioOnly (RtcChannel rtcChannel, boolean isFallbackOrRecover)
void	onRemoteSubscribeFallbackToAudioOnly (RtcChannel rtcChannel, int uid, boolean isFallbackOrRecover)
void	onProxyConnected (RtcChannel rtcChannel, int uid, int proxyType, String localProxyIp, int elapsed)
void	onClientRoleChangeFailed (RtcChannel rtcChannel, int reason, int currentRole)

Detailed Description

The IRtcChannelEventHandler class.

Member Function Documentation

onChannelWarning()

void io.agora.rtc.IRtcChannelEventHandler.onChannelWarning	(	RtcChannel	rtcChannel,
		int	warn
	)

Reports the warning code of the RtcChannel instance.

Parameters

rtcChannel	The current RtcChannel instance.
warn	The warning code: WarnCode.

onChannelError()

void io.agora.rtc.IRtcChannelEventHandler.onChannelError	(	RtcChannel	rtcChannel,
		int	err
	)

Reports the error code of the RtcChannel instance.

Parameters

rtcChannel	The current RtcChannel instance.
err	The error code: ErrorCode

onJoinChannelSuccess()

void io.agora.rtc.IRtcChannelEventHandler.onJoinChannelSuccess	(	RtcChannel	rtcChannel,
		int	uid,
		int	elapsed
	)

Occurs when the local user joins a specified channel.

If the uid is not specified when calling joinChannel, the server automatically assigns a uid.

Parameters

rtcChannel	The current RtcChannel instance.
uid	The user ID.
elapsed	Time elapsed (ms) from the local user calling joinChannel until this callback is triggered.

onRejoinChannelSuccess()

void io.agora.rtc.IRtcChannelEventHandler.onRejoinChannelSuccess	(	RtcChannel	rtcChannel,
		int	uid,
		int	elapsed
	)

Occurs when a user rejoins the channel after being disconnected due to network problems.

When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection.

Parameters

rtcChannel	The current RtcChannel instance.
uid	The user ID.
elapsed	Time elapsed (ms) from the user calling joinChannel until the SDK triggers this callback.

onLeaveChannel()

void io.agora.rtc.IRtcChannelEventHandler.onLeaveChannel	(	RtcChannel	rtcChannel,
		RtcStats	stats
	)

Occurs when a user leaves the channel.

When a user leaves the channel by using the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel.

With this callback, the app gets the channel information, such as the call duration and statistics.

Parameters

rtcChannel	The current RtcChannel instance.
stats	Statistics of the call: RtcStats.

onClientRoleChanged()

void io.agora.rtc.IRtcChannelEventHandler.onClientRoleChanged	(	RtcChannel	rtcChannel,
		int	oldRole,
		int	newRole
	)

Occurs when the user role switches successfully in the interactive live streaming.

In the LIVE_BROADCASTING channel profile, when the local user successfully calls setClientRole to switch their user role after joining the channel, for example, from a host to an audience member or vice versa, the SDK triggers this callback to report the user role before and after the switch.

Parameters

rtcChannel	The current RtcChannel instance.
oldRole	The role that the user switches from. CLIENT_ROLE_BROADCASTER(1): Host. CLIENT_ROLE_AUDIENCE(2): Audience.
newRole	The role that the user switches to. CLIENT_ROLE_BROADCASTER(1): Host. CLIENT_ROLE_AUDIENCE(2): Audience.

onUserJoined()

void io.agora.rtc.IRtcChannelEventHandler.onUserJoined	(	RtcChannel	rtcChannel,
		int	uid,
		int	elapsed
	)

Occurs when a remote user (COMMUNICATION) or a host (LIVE_BROADCASTING) joins the channel.

• COMMUNICATION profile: This callback notifies the app when another user joins the channel. If other users are already in the channel, the SDK also reports to the app on the existing users.
• LIVE_BROADCASTING profile: This callback notifies the app when the host joins the channel. If other hosts are already in the channel, the SDK also reports to the app on the existing hosts. We recommend having at most 17 hosts in a channel.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the user or host who joins the channel.
elapsed	Time delay (ms) from the local user calling joinChannel or setClientRole(BROADCASTER) until this callback is triggered.

Note

In the LIVE_BROADCASTING profile:

• The host receives this callback when another host joins the channel.
• The audience in the channel receives this callback when a new host joins the channel.
• When a web app joins the channel, this callback is triggered as long as the web app publishes streams.

onUserOffline()

void io.agora.rtc.IRtcChannelEventHandler.onUserOffline	(	RtcChannel	rtcChannel,
		int	uid,
		int	reason
	)

Occurs when a remote user (COMMUNICATION) or a host (LIVE_BROADCASTING) leaves the channel.

There are two reasons for users to become offline:

• Leave the channel: When the user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel.
• Go offline: When no data packet of the user or host is received for a certain period of time (around 20 seconds), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections, so we recommend using the signaling system for reliable offline detection.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the user or host who leaves the channel or goes offline.
reason	The reason why the user goes offline: USER_OFFLINE_QUIT(0): The user leaves the current channel. USER_OFFLINE_DROPPED(1): The SDK timed out and the user dropped offline because no data packet was received within a certain period of time. Note: If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline. After the user kills the app with a gesture swipe, the SDK reports USER_OFFLINE_DROPPED(1) instead of USER_OFFLINE_QUIT(0) due to system limitations. USER_OFFLINE_BECOME_AUDIENCE(2): (LIVE_BROADCASTING only.) The client role switched from host to audience.

onConnectionStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onConnectionStateChanged	(	RtcChannel	rtcChannel,
		int	state,
		int	reason
	)

Occurs when the network connection state changes.

The Agora SDK triggers this callback to report on the current network connection state when it changes, and the reason to such change.

Parameters

rtcChannel	The current RtcChannel instance.
state	The current network connection state: CONNECTION_STATE_DISCONNECTED(1): The SDK is disconnected from Agora edge server. CONNECTION_STATE_CONNECTING(2): The SDK is connecting to Agora edge server. CONNECTION_STATE_CONNECTED(3): The SDK joined a channel and is connected to Agora edge server. You can now publish or subscribe to a media stream in the channel. CONNECTION_STATE_RECONNECTING(4): The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues. CONNECTION_STATE_FAILED(5): The SDK fails to join the channel.
reason	The reason causing the change of the connection state: CONNECTION_CHANGED_CONNECTING(0): The SDK is connecting to Agora edge server. CONNECTION_CHANGED_JOIN_SUCCESS(1): The SDK has joined the channel successfully. CONNECTION_CHANGED_INTERRUPTED(2): The connection between the SDK and Agora edge server is interrupted. CONNECTION_CHANGED_BANNED_BY_SERVER(3): The connection is banned by the server. This occurs when the server calls the Banning user privileges API to kick the user out of the channel. You can display a pop-up box in the application that says: "The user has been banned from this channel." CONNECTION_CHANGED_JOIN_FAILED(4): The SDK fails to join the channel. This occurs when the SDK fails to rejoin the channel within 20 minutes after receiving the onConnectionStateChanged(connection_state_reconnecting, connection_changed_interrupted) callback and stops trying. You can display a pop-up box in the application that says: "Failed to join the channel due to network issues. Please try to rejoin the channel after switching to a different network." CONNECTION_CHANGED_LEAVE_CHANNEL(5): The SDK has left the channel. CONNECTION_CHANGED_INVALID_APP_ID(6): The specified App ID is invalid. Check whether the App ID used by the user is the same as the App ID obtained from the Agora Console, and then try to rejoin the channel with a valid App ID. CONNECTION_CHANGED_INVALID_CHANNEL_NAME(7): The specified channel name is invalid. The channel name cannot be empty nor longer than 64 bytes in length. For supported characters, see the channelName parameter in joinChannel. You can display a pop-up box in the application that says: "The channel name is invalid. Please try to rejoin the channel with a valid channel name." CONNECTION_CHANGED_INVALID_TOKEN(8): The token is invalid, probably due to the following reasons: The App Certificate for the project is enabled in the Agora Console, but you do not use a token to authenticate the user when calling joinChannel. When the App Certificate for a project is enabled, you must use tokens to authenticate users. The user ID that you specify in the joinChannel method is different from the user ID that you pass for generating the token. Check whether the token used by the user is the same as the token generated at your app server, and then try to rejoin the channel with a valid token. CONNECTION_CHANGED_TOKEN_EXPIRED(9): The token has expired. The user using the expired token is forced to leave the channel. The app client needs to request a new token from the app server and then try to rejoin the channel with the new token. CONNECTION_CHANGED_REJECTED_BY_SERVER(10): The user is banned by the server. This error usually occurs in the following situations: When the user is already in the channel, and still calls the method to join the channel, for example, joinChannel. When the user tries to join a channel during a call test (startEchoTest). Once you call startEchoTest, you need to call stopEchoTest before joining a channel. CONNECTION_CHANGED_SETTING_PROXY_SERVER(11): The SDK tries to reconnect after setting a proxy server. CONNECTION_CHANGED_RENEW_TOKEN(12): The token renews. CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED(13): Due to a change of the network type, IP address, or network port, the client IP address has changed, and the SDK tries to reconnect. If this state occurs multiple times, you can display a pop-up box in the application that says: "The network connection is not stable. Please switch to another network." CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT(14): Timeout for the keep-alive of the connection between the SDK and Agora edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). CONNECTION_CHANGED_SAME_UID_LOGIN(19): Join the same channel from different devices using the same user ID. CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20): The number of hosts in the channel is already at the upper limit.

onConnectionLost()

void io.agora.rtc.IRtcChannelEventHandler.onConnectionLost

(

RtcChannel

rtcChannel

)

Occurs when the SDK cannot reconnect to Agora edge server 10 seconds after its connection to the server is interrupted.

The SDK also triggers this callback when it cannot connect to the server 10 seconds after calling joinChannel, regardless of whether it is in the channel or not.

If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora edge server, the SDK stops rejoining the channel.

Parameters

rtcChannel

The current RtcChannel instance.

onTokenPrivilegeWillExpire()

void io.agora.rtc.IRtcChannelEventHandler.onTokenPrivilegeWillExpire	(	RtcChannel	rtcChannel,
		String	token
	)

Occurs when the token expires in 30 seconds.

The user becomes offline if the token used when joining the channel expires. This callback is triggered 30 seconds before the token expires, to remind the app to get a new token. Upon receiving this callback, you need to generate a new token on the server and call renewToken to pass the new token to the SDK.

Parameters

rtcChannel	The current RtcChannel instance.
token	The token that will expire in 30 seconds.

onRequestToken()

void io.agora.rtc.IRtcChannelEventHandler.onRequestToken

(

RtcChannel

rtcChannel

)

Occurs when the token has expired.

After a token is specified when joining the channel, the token expires after a certain period of time, and a new token is required to reconnect to the server.

Once you receive this callback, generate a new token on your app server, and call renewToken to pass the new token to the SDK.

Parameters

rtcChannel

The current RtcChannel instance.

onRtcStats()

void io.agora.rtc.IRtcChannelEventHandler.onRtcStats	(	RtcChannel	rtcChannel,
		RtcStats	stats
	)

Reports the statistics of the RtcEngine once every two seconds.

Parameters

rtcChannel	The current RtcChannel instance.
stats	Statistics of the RtcChannel instance: RtcStats.

onNetworkQuality()

void io.agora.rtc.IRtcChannelEventHandler.onNetworkQuality	(	RtcChannel	rtcChannel,
		int	uid,
		int	txQuality,
		int	rxQuality
	)

Reports the last mile network quality of each user in the channel once every two seconds.

Last mile refers to the connection between the local device and Agora edge server. This callback reports once every two seconds the last mile network conditions of each user in the channel. If a channel includes multiple users, then this callback will be triggered as many times.

Parameters

rtcChannel	The current RtcChannel instance.
uid	User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
txQuality	Uplink transmission quality of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time) and jitter of the uplink network. txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. For example, a 1000 Kbps uplink network may be adequate for video frames with a resolution of 680 × 480 and a frame rate of 30 fps, but may be inadequate for resolutions higher than 1280 × 720. QUALITY_UNKNOWN(0): The quality is unknown. QUALITY_EXCELLENT(1): The quality is excellent. QUALITY_GOOD(2): The quality is quite good, but the bitrate may be slightly lower than excellent. QUALITY_POOR(3): Users can feel the communication slightly impaired. QUALITY_BAD(4): Users can communicate not very smoothly. QUALITY_VBAD(5): The quality is so bad that users can barely communicate. QUALITY_DOWN(6): The network is disconnected and users cannot communicate at all. QUALITY_DETECTING(8): The SDK is detecting the network quality.
rxQuality	Downlink network quality rating of the user in terms of packet loss rate, average RTT, and jitter of the downlink network. QUALITY_UNKNOWN(0): The quality is unknown. QUALITY_EXCELLENT(1): The quality is excellent. QUALITY_GOOD(2): The quality is quite good, but the bitrate may be slightly lower than excellent. QUALITY_POOR(3): Users can feel the communication slightly impaired. QUALITY_BAD(4): Users can communicate not very smoothly. QUALITY_VBAD(5): The quality is so bad that users can barely communicate. QUALITY_DOWN(6): The network is disconnected and users cannot communicate at all. QUALITY_DETECTING(8): The SDK is detecting the network quality.

onRemoteVideoStats()

void io.agora.rtc.IRtcChannelEventHandler.onRemoteVideoStats	(	RtcChannel	rtcChannel,
		RemoteVideoStats	stats
	)

Reports the statistics of the video stream from each remote user/host. The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

Parameters

rtcChannel	The current RtcChannel instance.
stats	Statistics of the received remote video streams: RemoteVideoStats.

onRemoteAudioStats()

void io.agora.rtc.IRtcChannelEventHandler.onRemoteAudioStats	(	RtcChannel	rtcChannel,
		RemoteAudioStats	stats
	)

Reports the statistics of the audio stream from each remote user/host.

The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall audio quality acceptable even when the packet loss rate is high.

Parameters

rtcChannel	The current RtcChannel instance.
stats	Statistics of the received remote audio streams: RemoteAudioStats.

onRemoteAudioStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onRemoteAudioStateChanged	(	RtcChannel	rtcChannel,
		int	uid,
		int	state,
		int	reason,
		int	elapsed
	)

Occurs when the remote audio state changes.

This callback indicates the state change of the remote audio stream.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the user whose audio state changes.
state	State of the remote audio: REMOTE_AUDIO_STATE_STOPPED(0): The remote audio is in the default state, probably due to REMOTE_AUDIO_REASON_LOCAL_MUTED(3), REMOTE_AUDIO_REASON_REMOTE_MUTED(5), or REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7). REMOTE_AUDIO_STATE_STARTING(1): The first remote audio packet is received. REMOTE_AUDIO_STATE_DECODING(2): The remote audio stream is decoded and plays normally, probably due to REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2), REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4) or REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6). REMOTE_AUDIO_STATE_FROZEN(3): The remote audio is frozen, probably due to REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1). REMOTE_AUDIO_STATE_FAILED(4): The remote audio fails to start, probably due to REMOTE_AUDIO_REASON_INTERNAL(0).
reason	The reason of the remote audio state change. REMOTE_AUDIO_REASON_INTERNAL(0): The SDK reports this reason when the audio state changes. REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1): The remote user's network is congested. If the network conditions are persistently poor, display a pop-up box in the application that says "The remote user's network conditions are poor". REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2): The remote user's network conditions are restored from congested to normal. You can display a pop-up box in the application that says "The remote user's network conditions have improved". REMOTE_AUDIO_REASON_LOCAL_MUTED(3): The local user stops receiving the remote audio stream or disables the audio module. You can display a pop-up box in the application that says "You have muted the remote user". REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4): The local user resumes receiving the remote audio stream or enables the audio module. You can display a pop-up box in the application that says "You have unmuted the remote user". REMOTE_AUDIO_REASON_REMOTE_MUTED(5): The remote user stops sending the audio stream or disables the audio module. You can use an icon in the list of users in the application user interface to show that the remote user is muted and display a pop-up box in the application that says "The remote user has muted themselves". REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6): The remote user resumes sending the audio stream or enables the audio module. You can use an icon in the list of users in the application user interface to show that the remote user is unmuted and display a pop-up box in the application that says "The remote user has unmuted themselves". REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7): The remote user leaves the channel. You can remove the remote user from the user list in the application user interface.
elapsed	Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

onAudioPublishStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onAudioPublishStateChanged	(	RtcChannel	rtcChannel,
		int	oldState,
		int	newState,
		int	elapseSinceLastState
	)

Occurs when the audio publishing state changes.

Since

v3.1.0.

This callback indicates the publishing state change of the local audio stream.

The publishing states include:

• PUB_STATE_IDLE(0)
• PUB_STATE_NO_PUBLISHED(1)
• PUB_STATE_PUBLISHING(2)
• PUB_STATE_PUBLISHED(3)

Parameters

rtcChannel	The current RtcChannel instance.
oldState	The previous publishing state.
newState	The current publishing state.
elapseSinceLastState	The time elapsed (ms) from the previous state to the current state.

onVideoPublishStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onVideoPublishStateChanged	(	RtcChannel	rtcChannel,
		int	oldState,
		int	newState,
		int	elapseSinceLastState
	)

Occurs when the local video publishing state changes.

Since

v3.1.0.

This callback indicates the publishing state change of the local video stream.

The publishing states include:

• PUB_STATE_IDLE(0)
• PUB_STATE_NO_PUBLISHED(1)
• PUB_STATE_PUBLISHING(2)
• PUB_STATE_PUBLISHED(3)

Parameters

rtcChannel	The current RtcChannel instance.
oldState	The previous publishing state.
newState	The current publishing state.
elapseSinceLastState	The time elapsed (ms) from the previous state to the current state.

onFirstRemoteVideoFrame()

void io.agora.rtc.IRtcChannelEventHandler.onFirstRemoteVideoFrame	(	RtcChannel	rtcChannel,
		int	uid,
		int	width,
		int	height,
		int	elapsed
	)

Occurs when the first remote video frame is rendered.

Since

v3.7.0

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

rtcChannel	The current RtcChannel instance.
uid	User ID of the remote user sending the video streams.
width	Width (px) of the video stream.
height	Height (px) of the video stream.
elapsed	Time elapsed (ms) from the local user calling the joinChannel method until this callback is triggered.

onAudioSubscribeStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onAudioSubscribeStateChanged	(	RtcChannel	rtcChannel,
		int	uid,
		int	oldState,
		int	newState,
		int	elapseSinceLastState
	)

Occurs when the remote audio subscribing state changes.

Since

v3.1.0.

This callback indicates the subscribing state change of the remote audio stream.

The subscribing states include:

• SUB_STATE_IDLE(0)
• SUB_STATE_NO_SUBSCRIBED(1)
• SUB_STATE_SUBSCRIBING(2)
• SUB_STATE_SUBSCRIBED(3)

Parameters

rtcChannel	The current RtcChannel instance.
uid	The ID of the remote user whose audio subscribing state changes.
oldState	The previous subscribing state.
newState	The current subscribing state.
elapseSinceLastState	The time elapsed (ms) from the previous state to the current state.

onVideoSubscribeStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onVideoSubscribeStateChanged	(	RtcChannel	rtcChannel,
		int	uid,
		int	oldState,
		int	newState,
		int	elapseSinceLastState
	)

Occurs when the remote video subscribe state changes.

Since

v3.1.0.

This callback indicates the subscribe state change of the remote video stream.

The subscribing states include:

• SUB_STATE_IDLE(0)
• SUB_STATE_NO_SUBSCRIBED(1)
• SUB_STATE_SUBSCRIBING(2)
• SUB_STATE_SUBSCRIBED(3)

Parameters

rtcChannel	The current RtcChannel instance.
uid	The ID of the remote user whose video subscribe state changes.
oldState	The previous subscribing state.
newState	The current subscribing state.
elapseSinceLastState	The time elapsed (ms) from the previous state to the current state.

onActiveSpeaker()

void io.agora.rtc.IRtcChannelEventHandler.onActiveSpeaker	(	RtcChannel	rtcChannel,
		int	uid
	)

Occurs when the most active remote speaker is detected.

After a successful call of enableAudioVolumeIndication, the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user, who is detected as the loudest for the most times, is the most active user.

When the number of user is no less than two and an active speaker exists, the SDK triggers this callback and reports the uid of the most active speaker.

• If the most active speaker is always the same user, the SDK triggers this callback only once.
• If the most active speaker changes to another user, the SDK triggers this callback again and reports the uid of the new active speaker.

Parameters

rtcChannel	The current RtcChannel instance.
uid	The user ID of the most active remote speaker.

onVideoSizeChanged()

void io.agora.rtc.IRtcChannelEventHandler.onVideoSizeChanged	(	RtcChannel	rtcChannel,
		int	uid,
		int	width,
		int	height,
		int	rotation
	)

Occurs when the video size or rotation information of a remote user changes.

Parameters

rtcChannel	The current RtcChannel instance.
uid	User ID of the remote user or local user (0) whose video size or rotation changes.
width	New width (pixels) of the video.
height	New height (pixels) of the video.
rotation	New rotation of the video [0 to 360].

onRemoteVideoStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onRemoteVideoStateChanged	(	RtcChannel	rtcChannel,
		int	uid,
		int	state,
		int	reason,
		int	elapsed
	)

Occurs when the remote video state changes.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the remote user whose video state changes.
state	State of the remote video: REMOTE_VIDEO_STATE_STOPPED(0): The remote video is in the default state, probably due to REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3), REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5), or REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7). REMOTE_VIDEO_STATE_STARTING(1): The first remote video packet is received. REMOTE_VIDEO_STATE_DECODING(2): The remote video stream is decoded and plays normally, probably due to REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY (2), REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4), REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6), or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9). REMOTE_VIDEO_STATE_FROZEN(3): The remote video is frozen, probably due to REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1) or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8). REMOTE_VIDEO_STATE_FAILED(4): The remote video fails to start, probably due to REMOTE_VIDEO_STATE_REASON_INTERNAL(0).
reason	The reason of the remote video state change: REMOTE_VIDEO_STATE_REASON_INTERNAL(0): The SDK reports this reason when the video state changes. REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1): The remote user's network is congested. If the network conditions are persistently poor, display a pop-up box in the application that says "The remote user's network conditions are poor". REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2): The remote user's network conditions are restored from congested to normal. You can display a pop-up box in the application that says "The remote user's network conditions have improved". REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3): The local user stops receiving the remote video stream or disables the video module. You can close the window to render the remote user's video and display a pop-up box in the application that says "You have stopped receiving video from the remote user". REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4): The local user resumes receiving the remote video stream or enables the video module. You can restore the window to render the remote user's video and display a pop-up box in the application that says "You have resumed receiving video from the remote user". REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5): The remote user stops sending the video stream or disables the video module. You can close the window to render the remote user's video, use an icon in the list of users in the application user interface to show that the remote user has stopped sending video, and display a pop-up box in the application that says "The remote user has disabled the camera". REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6): The remote user resumes sending the video stream or enables the video module. You can restore the window to render the remote user's video, use an icon in the list of users in the application user interface to show that the remote user has resumed sending video, and display a pop-up box in the application that says "The remote user has enabled the camera". REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7): The remote user leaves the channel. You can close the window to render the remote user's video and remove the remote user from the user list in the application user interface. REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8): The remote audio-and-video stream falls back to the audio-only stream due to poor network conditions. You can close the window to render the remote user's video and display a pop-up box in the application that says "The remote user's network conditions are poor". REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9): The remote audio-only stream switches back to the audio-and-video stream after the network conditions improve. You can restore the window to render the remote user's video and display a pop-up box in the application that says "The remote user's network conditions are poor". REMOTE_VIDEO_STATE_REASON_SDK_IN_BACKGROUND(10): The SDK reports this error code to the local user when a remote user is using the iOS app and the app is in the background. In this case, the local user sees the remote user's video stuck.
elapsed	Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

onUserSuperResolutionEnabled()

void io.agora.rtc.IRtcChannelEventHandler.onUserSuperResolutionEnabled	(	RtcChannel	rtcChannel,
		int	uid,
		boolean	enabled,
		int	reason
	)

Reports whether the super resolution feature is successfully enabled. (beta feature)

Since

v3.5.1

After calling enableRemoteSuperResolution, the SDK triggers this callback to report whether super resolution is successfully enabled. If it is not successfully enabled, use reason for troubleshooting.

Parameters

rtcChannel	The current RtcChannel instance.
uid	The user ID of the remote user.
enabled	Whether super resolution is successfully enabled: true: Super resolution is successfully enabled. false: Super resolution is not successfully enabled.
reason	The reason why super resolution is not successfully enabled or the message that confirms success. SR_STATE_REASON_SUCCESS(0): Super resolution is successfully enabled. SR_STATE_REASON_STREAM_OVER_LIMITATION(1): The original resolution of the remote video is beyond the range where super resolution can be applied. SR_STATE_REASON_USER_COUNT_OVER_LIMITATION(2): Super resolution is already being used to boost another remote user's video. SR_STATE_REASON_DEVICE_NOT_SUPPORTED(3): The device does not support using super resolution. SR_STATE_REASON_INSUFFICIENT_PERFORMANCE(4): When the super resolution feature is enabled or is running, the SDK detects that device performance is not qualified. When you receive this reason code, Agora recommends that the user disable virtual background.

onStreamMessage()

void io.agora.rtc.IRtcChannelEventHandler.onStreamMessage	(	RtcChannel	rtcChannel,
		int	uid,
		int	streamId,
		byte[]	data
	)

Occurs when the local user receives a remote data stream.

The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the remote user who sends the data stream.
streamId	Stream ID.
data	Data received by the local user.

onStreamMessageError()

void io.agora.rtc.IRtcChannelEventHandler.onStreamMessageError	(	RtcChannel	rtcChannel,
		int	uid,
		int	streamId,
		int	error,
		int	missed,
		int	cached
	)

Occurs when the local user fails to receive a remote data stream.

The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the sendStreamMessage method.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the remote user who sends the data stream.
streamId	Stream ID.
error	The detailed error informationL ErrorCode.
missed	The number of lost messages.
cached	The number of incoming cached messages when the data stream is interrupted.

onChannelMediaRelayStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onChannelMediaRelayStateChanged	(	RtcChannel	rtcChannel,
		int	state,
		int	code
	)

Occurs when the state of the media stream relay changes.

The SDK reports the state of the current media relay and possible error messages in this callback.

Parameters

rtcChannel	The current RtcChannel instance.
state	The state code: RELAY_STATE_IDLE(0): The SDK is initializing. RELAY_STATE_CONNECTING(1): The SDK tries to relay the media stream to the destination channel. RELAY_STATE_RUNNING(2): The SDK successfully relays the media stream to the destination channel. RELAY_STATE_FAILURE(3): A failure occurs. See the details in code.
code	The error code: RELAY_OK(0): The state is normal. RELAY_ERROR_SERVER_ERROR_RESPONSE(1): An error occurs in the server response. RELAY_ERROR_SERVER_NO_RESPONSE(2): No server response. This error can also occur if the channel media relay service is not enabled in the project. You can contact technical support to enable the service. RELAY_ERROR_NO_RESOURCE_AVAILABLE(3): The SDK fails to access the service, probably due to limited resources of the server. RELAY_ERROR_FAILED_JOIN_SRC(4): The server fails to join the source channel. RELAY_ERROR_FAILED_JOIN_DEST(5): The server fails to join the destination channel. RELAY_ERROR_FAILED_PACKET_RECEIVED_FROM_SRC(6): The server fails to receive the data from the source channel. RELAY_ERROR_FAILED_PACKET_SENT_TO_DEST(7): The source channel fails to transmit data. RELAY_ERROR_SERVER_CONNECTION_LOST(8): The SDK disconnects from the server due to poor network connections. You can call the leaveChannel method to leave the channel. RELAY_ERROR_INTERNAL_ERROR(9): An internal error occurs in the server. RELAY_ERROR_SRC_TOKEN_EXPIRED(10): The token of the source channel has expired. RELAY_ERROR_DEST_TOKEN_EXPIRED(11): The token of the destination channel has expired.

onChannelMediaRelayEvent()

void io.agora.rtc.IRtcChannelEventHandler.onChannelMediaRelayEvent	(	RtcChannel	rtcChannel,
		int	code
	)

Reports events during the media stream relay.

Parameters

rtcChannel

The current RtcChannel instance.

code

The event code for media stream relay: RELAY_EVENT_NETWORK_DISCONNECTED(0): The user disconnects from the server due to poor network connections. RELAY_EVENT_NETWORK_CONNECTED(1): The network reconnects. RELAY_EVENT_PACKET_JOINED_SRC_CHANNEL(2): The user joins the source channel. RELAY_EVENT_PACKET_JOINED_DEST_CHANNEL(3): The user joins the destination channel. RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4): The SDK starts relaying the media stream to the destination channel. RELAY_EVENT_PACKET_RECEIVED_VIDEO_FROM_SRC(5): The server receives the video stream from the source channel. RELAY_EVENT_PACKET_RECEIVED_AUDIO_FROM_SRC(6): The server receives the audio stream from the source channel. RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7): The destination channel is updated. RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED(8): The destination channel update fails due to internal reasons. RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_NOT_CHANGE(9): The destination channel does not change, which means that the destination channel fails to be updated. RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_IS_NULL(10): The destination channel name is NULL. RELAY_EVENT_VIDEO_PROFILE_UPDATE(11): The video profile is sent to the server. RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(12): The SDK successfully pauses relaying the media stream to destination channels. RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED(13): The SDK fails to pause relaying the media stream to destination channels. RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(14): The SDK successfully resumes relaying the media stream to destination channels. RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED(15): The SDK fails to resume relaying the media stream to destination channels.

onRtmpStreamingStateChanged()

void io.agora.rtc.IRtcChannelEventHandler.onRtmpStreamingStateChanged	(	RtcChannel	rtcChannel,
		String	url,
		int	state,
		int	errCode
	)

Occurs when the state of the RTMP or RTMPS streaming changes.

When the CDN live streaming state changes, the SDK triggers this callback to report the current state and the reason why the state has changed.

This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the errCode parameter.

Parameters

rtcChannel	The current RtcChannel instance.
url	The CDN streaming URL.
state	The RTMP or RTMPS streaming state: RTMP_STREAM_PUBLISH_STATE_IDLE(0): The RTMP or RTMPS streaming has not started or has ended. This state is also triggered after you remove an RTMP or RTMPS stream from the CDN by calling removePublishStreamUrl. RTMP_STREAM_PUBLISH_STATE_CONNECTING(1): The SDK is connecting to Agora streaming server and the CDN server. This state is triggered after you call the addPublishStreamUrl method. RTMP_STREAM_PUBLISH_STATE_RUNNING(2): The RTMP or RTMPS streaming publishes. The SDK successfully publishes the RTMP or RTMPS streaming and returns this state. RTMP_STREAM_PUBLISH_STATE_RECOVERING(3): The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK attempts to resume RTMP or RTMPS streaming and returns this state. If the SDK successfully resumes the streaming, RTMP_STREAM_PUBLISH_STATE_RUNNING(2) returns. If the streaming does not resume within 60 seconds or server errors occur, RTMP_STREAM_PUBLISH_STATE_FAILURE(4) returns. You can also reconnect to the server by calling the removePublishStreamUrl and addPublishStreamUrl methods. RTMP_STREAM_PUBLISH_STATE_FAILURE(4): The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the addPublishStreamUrl method to publish the RTMP or RTMPS streaming again. RTMP_STREAM_PUBLISH_STATE_DISCONNECTING(5): The SDK is disconnecting from the Agora streaming server and CDN. When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as DISCONNECTING, IDLE in sequence.
errCode	The detailed error information for streaming: RTMP_STREAM_PUBLISH_ERROR_OK(0): The RTMP or RTMPS streaming publishes successfully. RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMEN(1): Invalid argument used. If, for example, you do not call the setLiveTranscoding method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the setLiveTranscoding method properly. RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED(2): The RTMP or RTMPS streaming is encrypted and cannot be published. RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT(3): Timeout for the RTMP or RTMPS streaming. Call the addPublishStreamUrl method to publish the streaming again. RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR(4): An error occurs in Agora streaming server. Call the addPublishStreamUrl method to publish the streaming again. RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR(5): An error occurs in the CDN server. RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN(6): Reserved. RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT(7): The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED(8): The host manipulates other hosts' URLs. Check your app logic. RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND(9): Agora server fails to find the RTMP or RTMPS streaming. RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED(10): The format of the CDN streaming URL is not supported. Check whether the URL format is correct. RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER(11): The user role is not host, so the user cannot use the CDN live streaming function. Check your application code logic. RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM(13): The updateRtmpTranscoding or setLiveTranscoding method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. Check your application code logic. RTMP_STREAM_PUBLISH_ERROR_NET_DOWN(14): Errors occurred in the host's network. RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID(15): Your App ID does not have permission to use the CDN live streaming function. Refer to Prerequisites to enable the CDN live streaming permission. RTMP_STREAM_UNPUBLISH_ERROR_OK(100): The streaming has been stopped normally.

onTranscodingUpdated()

void io.agora.rtc.IRtcChannelEventHandler.onTranscodingUpdated

(

RtcChannel

rtcChannel

)

Occurs when the publisher's transcoding settings are updated.

When the LiveTranscoding class in the setLiveTranscoding method updates, the SDK triggers this callback to report the update information.

Note

If you call the setLiveTranscoding method to set the LiveTranscoding class for the first time, the SDK does not trigger this callback.

Parameters

rtcChannel

The current RtcChannel instance.

onRtmpStreamingEvent()

void io.agora.rtc.IRtcChannelEventHandler.onRtmpStreamingEvent	(	RtcChannel	rtcChannel,
		String	url,
		int	errCode
	)

Reports events during the RTMP or RTMPS streaming.

Since

v3.1.0

Parameters

rtcChannel	The current RtcChannel instance.
url	The CDN streaming URL.
errCode	The event code. RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE(1): An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE(2): The chosen URL address is already in use for CDN live streaming. RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3): The feature is not supported. RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4): Reserved.

onLocalPublishFallbackToAudioOnly()

void io.agora.rtc.IRtcChannelEventHandler.onLocalPublishFallbackToAudioOnly	(	RtcChannel	rtcChannel,
		boolean	isFallbackOrRecover
	)

Occurs when the published media stream falls back to an audio-only stream due to poor network conditions or switches back to video stream after the network conditions improve.

If you call setLocalPublishFallbackOption and set option as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), this callback is triggered when the local published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves. Once the published stream falls back to audio only, the remote app receives the onRemoteVideoStateChanged callback.

Parameters

rtcChannel	The current RtcChannel instance.
isFallbackOrRecover	Whether the published stream fell back to audio-only or switched back to the video: true: The published stream fell back to audio-only due to poor network conditions. false: The published stream switched back to the video after the network conditions improved.

onRemoteSubscribeFallbackToAudioOnly()

void io.agora.rtc.IRtcChannelEventHandler.onRemoteSubscribeFallbackToAudioOnly	(	RtcChannel	rtcChannel,
		int	uid,
		boolean	isFallbackOrRecover
	)

Occurs when the remote media stream falls back to audio-only stream due to poor network conditions or switches back to video stream after the network conditions improve.

If you call setRemoteSubscribeFallbackOption and set option as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), this callback is triggered when the remote media stream falls back to audio-only mode due to poor downlink conditions, or when the remote media stream switches back to the video after the downlink network condition improves.

Note

Once the remote media stream is switched to the low stream due to poor network conditions, you can monitor the stream switch between a high and low stream in the onRemoteVideoStats callback.

Parameters

rtcChannel	The current RtcChannel instance.
uid	ID of the remote user sending the stream.
isFallbackOrRecover	Whether the remote media stream fell back to audio-only or switched back to the video: true: The remote media stream fell back to audio-only due to poor network conditions. false: The remote media stream switched back to the video stream after the network conditions improved.

onProxyConnected()

void io.agora.rtc.IRtcChannelEventHandler.onProxyConnected	(	RtcChannel	rtcChannel,
		int	uid,
		int	proxyType,
		String	localProxyIp,
		int	elapsed
	)

Reports the proxy connection state.

Since

v3.6.2

You can use this callback to listen for the state of the SDK connecting to a proxy. For example, when a user calls setCloudProxy and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

Parameters

rtcChannel	The current RtcChannel instance.
uid	The user ID.
proxyType	The proxy type connected: PROXY_TYPE_NONE_PROXY(0): Reserved for future use. PROXY_TYPE_UDP_CLOUD_PROXY(1): The cloud proxy for the UDP protocol, that is, the Force UDP cloud proxy mode. In this mode, the SDK always transmits data over UDP. PROXY_TYPE_TCP_CLOUD_PROXY(2): The cloud proxy for the TCP (encryption) protocol, that is, the Force TCP cloud proxy mode. In this mode, the SDK always transmits data over TLS 443. PROXY_TYPE_LOCAL_PROXY(3): Reserved for future use. PROXY_TYPE_TCP_AUTO_FALLBACK(4): The automatic mode. In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TLS 443 if the attempt fails.
localProxyIp	Reserved for future use.
elapsed	The time elapsed (ms) from the user calling joinChannel until this callback is triggered.

onClientRoleChangeFailed()

void io.agora.rtc.IRtcChannelEventHandler.onClientRoleChangeFailed	(	RtcChannel	rtcChannel,
		int	reason,
		int	currentRole
	)

Occurs when the user role switch fails in the interactive live streaming.

Since

v3.7.0

In the LIVE_BROADCASTING channel profile, when the local user calls setClientRole to switch their user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role.

Parameters

rtcChannel	The current RtcChannel instance.
reason	The reason for the user role switch failure: CLIENT_ROLE_CHANGE_FAILED_BY_TOO_MANY_BROADCASTERS(1) CLIENT_ROLE_CHANGE_FAILED_BY_NOT_AUTHORIZED(2) CLIENT_ROLE_CHANGE_FAILED_BY_REQUEST_TIME_OUT(3) CLIENT_ROLE_CHANGE_FAILED_BY_CONNECTION_FAILED(4)
currentRole	The current user role: CLIENT_ROLE_BROADCASTER(1) CLIENT_ROLE_AUDIENCE(2)