Public Member Functions

void setRtcChannelEventHandler (IRtcChannelEventHandler eventHandler)
 
IRtcChannelEventHandler getEventHandler ()
 
abstract int destroy ()
 
abstract String channelId ()
 
abstract String getCallId ()
 
abstract int getConnectionState ()
 
abstract int joinChannel (String token, String optionalInfo, int optionalUid, ChannelMediaOptions options)
 
abstract int joinChannelWithUserAccount (String token, String userAccount, ChannelMediaOptions options)
 
abstract int leaveChannel ()
 
abstract int publish ()
 
abstract int unpublish ()
 
abstract int renewToken (String token)
 
abstract int setEncryptionSecret (String secret)
 
abstract int setEncryptionMode (String encryptionMode)
 
abstract int registerMediaMetadataObserver (IMetadataObserver observer, int type)
 
abstract int setClientRole (int role)
 
abstract int setRemoteUserPriority (int uid, int userPriority)
 
abstract int setRemoteVoicePosition (int uid, double pan, double gain)
 
abstract int setRemoteRenderMode (int uid, int renderMode, int mirrorMode)
 
abstract int setDefaultMuteAllRemoteAudioStreams (boolean muted)
 
abstract int setDefaultMuteAllRemoteVideoStreams (boolean muted)
 
abstract int muteAllRemoteAudioStreams (boolean muted)
 
abstract int adjustUserPlaybackSignalVolume (int uid, int volume)
 
abstract int muteRemoteAudioStream (int uid, boolean muted)
 
abstract int muteAllRemoteVideoStreams (boolean muted)
 
abstract int muteRemoteVideoStream (int uid, boolean muted)
 
abstract int setRemoteVideoStreamType (int uid, int streamType)
 
abstract int setRemoteDefaultVideoStreamType (int streamType)
 
abstract int createDataStream (boolean reliable, boolean ordered)
 
abstract int sendStreamMessage (int streamId, byte[] message)
 
abstract int addPublishStreamUrl (String url, boolean transcodingEnabled)
 
abstract int removePublishStreamUrl (String url)
 
abstract int setLiveTranscoding (LiveTranscoding transcoding)
 
abstract int addInjectStreamUrl (String url, LiveInjectStreamConfig config)
 
abstract int removeInjectStreamUrl (String url)
 
abstract int startChannelMediaRelay (ChannelMediaRelayConfiguration channelMediaRelayConfiguration)
 
abstract int stopChannelMediaRelay ()
 
abstract int updateChannelMediaRelay (ChannelMediaRelayConfiguration channelMediaRelayConfiguration)
 
abstract int setRemoteVideoRenderer (int uid, IVideoSink render)
 

Detailed Description

The RtcChannel class.

Since
v3.0.0.

Member Function Documentation

◆ setRtcChannelEventHandler()

void io.agora.rtc.RtcChannel.setRtcChannelEventHandler ( IRtcChannelEventHandler  eventHandler)

Sets the channel event handler.

After setting the channel event handler, you can listen for channel events and receive the statistics of the corresponding RtcChannel instance.

Parameters
eventHandlerThe event handler of the RtcChannel instance: IRtcChannelEventHandler.

◆ getEventHandler()

IRtcChannelEventHandler io.agora.rtc.RtcChannel.getEventHandler ( )

Gets the channel event handler.

Returns

◆ destroy()

abstract int io.agora.rtc.RtcChannel.destroy ( )
abstract

Destroys the RtcChannel instance.

Returns
  • 0: Success.
  • < 0: Fail.
    • ERR_NOT_INITIALIZED(-7): The RtcChannel instance is not initialized before calling this method.

◆ channelId()

abstract String io.agora.rtc.RtcChannel.channelId ( )
abstract

Gets the channel ID of the current RtcChannel instance.

Returns
  • The channel ID of the current RtcChannel instance, if the method call succeeds.
  • The empty string "", if the method call fails.

◆ getCallId()

abstract String io.agora.rtc.RtcChannel.getCallId ( )
abstract

Gets the current call ID.

Returns
  • The current call ID, if the method call succeeds.
  • The empty string "", if the method call fails.

◆ getConnectionState()

abstract int io.agora.rtc.RtcChannel.getConnectionState ( )
abstract

Gets the connection state of the SDK.

Returns
The connection state:

◆ joinChannel()

abstract int io.agora.rtc.RtcChannel.joinChannel ( String  token,
String  optionalInfo,
int  optionalUid,
ChannelMediaOptions  options 
)
abstract

Joins the channel with a user ID.

This method differs from the joinChannel method in the RtcEngine class in the following aspects:

RtcChannel::joinChannel RtcEngine::joinChannel
Does not contain the channelId parameter, because channelId is specified when creating the RtcChannel instance. Contains the channelId parameter, which specifies the channel to join.
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. Does not contain the options parameter. By default, users subscribe to all streams when joining the channel.
Users can join multiple channels simultaneously by creating multiple RtcChannel instances and calling the joinChannel method of each instance. Users can join only one channel.
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. By default, the SDK publishes streams once the user joins the channel.
Note
  • If you are already in a channel, you cannot rejoin it with the same uid.
  • We recommend using different UIDs for different channels.
  • If you want to join the same channel from different devices, ensure that the UIDs in all devices are different.
  • Ensure that the app ID you use to generate the token is the same with the app ID used when creating the RtcEngine instance.
Parameters
tokenThe token generated at your server:
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at your server. For details, see Get a token.
optionalInfoAdditional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information.
optionalUidThe user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If uid is not assigned (or set as 0), the SDK assigns a uid and reports it in the onJoinChannelSuccess callback. The app must maintain this user ID.
optionsThe channel media options: ChannelMediaOptions.
Returns

◆ joinChannelWithUserAccount()

abstract int io.agora.rtc.RtcChannel.joinChannelWithUserAccount ( String  token,
String  userAccount,
ChannelMediaOptions  options 
)
abstract

Joins a channel with the user account.

This method differs from the joinChannelWithUserAccount method in the RtcEngine class in the following aspects:

RtcChannel::joinChannelWithUserAccount RtcEngine::joinChannelWithUserAccount
Does not contain the channelId parameter, because channelId is specified when creating the RtcChannel instance. Contains the channelId parameter, which specifies the channel to join.
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. Does not contain the options parameter. By default, users subscribe to all streams when joining the channel.
Users can join multiple channels simultaneously by creating multiple RtcChannel instances and calling the joinChannelWithUserAccount method of each instance. Users can join only one channel.
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. By default, the SDK publishes streams once the user joins the channel.
Note
  • If you are already in a channel, you cannot rejoin it with the same uid.
  • We recommend using different user accounts for different channels.
  • If you want to join the same channel from different devices, ensure that the user accounts in all devices are different.
  • Ensure that the app ID you use to generate the token is the same with the app ID used when creating the RtcEngine instance.
Parameters
tokenThe token generated at your server:
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at your server. For details, see Get a token.
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null.
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: ChannelMediaOptions.
Returns

◆ leaveChannel()

abstract int io.agora.rtc.RtcChannel.leaveChannel ( )
abstract

Leaves the current channel.

A successful leaveChannel method call triggers the following callbacks:

  • The local client: onLeaveChannel.
  • The remote client: onUserOffline, if the user leaving the channel is in a Communication channel, or is a broadcaster in a Live-Broadcast channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ publish()

abstract int io.agora.rtc.RtcChannel.publish ( )
abstract

Publishes the local stream to the channel.

You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the ERR_REFUSED(-5):

  • This method publishes one stream only to the channel corresponding to the current RtcChannel instance.
  • In a Live-Broadcast channel, only a broadcaster can call this method. To switch the client role, call setClientRole of the current RtcChannel instance.
  • You can publish a stream to only one channel at a time. For details, see the advanced guide Join Multiple Channels.
    Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_REFUSED(-5): The method call is refused.

◆ unpublish()

abstract int io.agora.rtc.RtcChannel.unpublish ( )
abstract

Stops publishing a stream to the channel.

If you call this method in a channel where you are not publishing streams, the SDK returns ERR_REFUSED(-5).

Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_REFUSED(-5): The method call is refused.

◆ renewToken()

abstract int io.agora.rtc.RtcChannel.renewToken ( String  token)
abstract

Renews the token when the current token expires.

In the following situations, the SDK decides that the current token has expired:

You should get a new token from your server and call this method to renew it. Failure to do so results in the SDK disconnecting from the Agora server.

Parameters
tokenThe new token.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionSecret()

abstract int io.agora.rtc.RtcChannel.setEncryptionSecret ( String  secret)
abstract

Enables built-in encryption with an encryption password before joining a channel.

All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel. If the encryption password is not specified or set to empty, the encryption functionality is disabled.

Note
  • For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
  • Do not use this method for CDN streaming.
Parameters
secretThe encryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

abstract int io.agora.rtc.RtcChannel.setEncryptionMode ( String  encryptionMode)
abstract

Sets the built-in encryption mode.

The Agora SDK supports built-in encryption, which is set to aes-128-xts mode by default. Call this method to set the encryption mode to use other encryption modes. All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note
  • Do not use this method for CDN streaming.
  • Before calling this method, ensure that you have called setEncryptionSecret to enable encryption.
Parameters
encryptionModeSets the encryption mode:
  • "aes-128-xts": 128-bit AES encryption, XTS mode.
  • "aes-128-ecb": 128-bit AES encryption, ECB mode.
  • "aes-256-xts": 256-bit AES encryption, XTS mode.
  • "": (Default) When encryptionMode is set as the empty string, the encryption is in “aes-128-xts” by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerMediaMetadataObserver()

abstract int io.agora.rtc.RtcChannel.registerMediaMetadataObserver ( IMetadataObserver  observer,
int  type 
)
abstract

Registers the metadata observer.

You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the getMaxMetadataSize callback.

This method enables you to add synchronized metadata in the video stream for more diversified live broadcast interactions, such as sending shopping links, digital coupons, and online quizzes.

Note
  • Call this method before the joinChannel method.
  • This method applies to the Live-Broadcast profile only.
Parameters
observerThe IMetadataObserver class.
typeThe metadata type. Currently, the SDK supports VIDEO_METADATA(0) only.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole()

abstract int io.agora.rtc.RtcChannel.setClientRole ( int  role)
abstract

Sets the role of a user.

This method sets the role of a user, such as a host or an audience. In a Live-Broadcast channel, only a broadcaster can call the publish method in the RtcChannel class.

A successful call of this method triggers the following callbacks:

Parameters
roleThe role of the user:
  • CLIENT_ROLE_BROADCASTER(1): Broadcaster.
  • CLIENT_ROLE_AUDIENCE(2): Audience.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteUserPriority()

abstract int io.agora.rtc.RtcChannel.setRemoteUserPriority ( int  uid,
int  userPriority 
)
abstract

Sets the priority of a remote user's media stream.

Use this method with the setRemoteSubscribeFallbackOption method. If a remote video stream experiences the fallback, the SDK ensures the high-priority user gets the best possible stream quality.

Note
The Agora SDK supports setting userPriority as high for one user only.
Parameters
uidThe ID of the remote user.
userPriorityThe priority of the remote user:
  • USER_PRIORITY_HIGH(50): The user's priority is high.
  • USER_PRIORITY_NORMAL(100): (Default) The user's priority is normal.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVoicePosition()

abstract int io.agora.rtc.RtcChannel.setRemoteVoicePosition ( int  uid,
double  pan,
double  gain 
)
abstract

Sets the sound position 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 stereo headset.
Parameters
uidThe ID of the remote user.
panThe 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.
gainGain 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.
  • -1: Failure.

◆ setRemoteRenderMode()

abstract int io.agora.rtc.RtcChannel.setRemoteRenderMode ( int  uid,
int  renderMode,
int  mirrorMode 
)
abstract

Updates the remote video display mode.

This method can be called multiple times during a call to change the display mode.

Parameters
uidID of the remote user.
renderModeThe remote video render mode:
  • RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
  • RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black.
  • RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode.
mirrorModeThe remote video render mode:
  • VIDEO_MIRROR_MODE_AUTO(0): (Default) The SDK determines the mirror mode. The SDK disables the mirror mode by default.
  • VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode.
  • VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteAudioStreams()

abstract int io.agora.rtc.RtcChannel.setDefaultMuteAllRemoteAudioStreams ( boolean  muted)
abstract

Sets whether to receive all remote audio streams by default.

Parameters
mutedDetermines whether to receive/stop receiving all remote audio streams by default:
  • true: Stop receiving all remote audio streams by default.
  • false: (Default) Receive all remote audio streams by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteVideoStreams()

abstract int io.agora.rtc.RtcChannel.setDefaultMuteAllRemoteVideoStreams ( boolean  muted)
abstract

Sets whether to receive all remote video streams by default.

Parameters
mutedDetermines whether to receive/stop receiving all remote video streams by default:
  • true: Stop receiving all remote video streams by default.
  • false: (Default) Receive all remote video streams by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteAudioStreams()

abstract int io.agora.rtc.RtcChannel.muteAllRemoteAudioStreams ( boolean  muted)
abstract

Stops/Resumes receiving all remote audio streams.

Parameters
mutedDetermines whether to receive/stop receiving all remote audio streams:
  • true: Stop receiving all remote audio streams.
  • false: (Default) Receive all remote audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ adjustUserPlaybackSignalVolume()

abstract int io.agora.rtc.RtcChannel.adjustUserPlaybackSignalVolume ( int  uid,
int  volume 
)
abstract

Adjusts the playback volume of a specified remote user.

You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

Note
  • Call this method after joining a channel.
  • The playback volume here refers to the mixed volume of a specified remote user.
  • This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.
Parameters
uidID of the remote user.
volumeThe playback volume of the specified remote user. The value ranges from 0 to 100:
  • 0: Mute.
  • 100: The original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteAudioStream()

abstract int io.agora.rtc.RtcChannel.muteRemoteAudioStream ( int  uid,
boolean  muted 
)
abstract

Stops/Resumes receiving the audio stream of the specified user.

Parameters
uidID of the remote user whose audio stream you want to mute.
mutedDetermines whether to receive/stop receiving the audio stream of the specified user:
  • true: Stop receiving the audio stream of the user.
  • false: (Default) Receive the audio stream of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteAllRemoteVideoStreams()

abstract int io.agora.rtc.RtcChannel.muteAllRemoteVideoStreams ( boolean  muted)
abstract

Stops/Resumes receiving all remote video streams.

Parameters
mutedDetermines whether to receive/stop receiving all remote video streams:
  • true: Stop receiving all remote video streams.
  • false: (Default) Receive all remote video streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteVideoStream()

abstract int io.agora.rtc.RtcChannel.muteRemoteVideoStream ( int  uid,
boolean  muted 
)
abstract

Stops/Resumes receiving the video stream of the specified user.

Parameters
uidID of the remote user whose video stream you want to mute.
mutedDetermines whether to receive/stop receiving the video stream of the specified user:
  • true: Stop receiving the video stream of the user.
  • false: (Default) Receive the video stream of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoStreamType()

abstract int io.agora.rtc.RtcChannel.setRemoteVideoStreamType ( int  uid,
int  streamType 
)
abstract

Sets the stream type of the remote video.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-quality video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch the remote stream type to reduce the bandwidth and resources.

The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The SDK reports the result of calling this method in the onApiCallExecuted callback.

Parameters
uidID of the remote user sending the video stream.
streamTypeSets the video stream type:
  • VIDEO_STREAM_HIGH(0): High-resolution, high-bitrate video.
  • VIDEO_STREAM_LOW(1): Low-resolution, high-bitrate video.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

abstract int io.agora.rtc.RtcChannel.setRemoteDefaultVideoStreamType ( int  streamType)
abstract

Sets the default video-stream type of the remote video stream when the remote user sends dual streams.

Parameters
streamTypeSets the video stream type:
  • VIDEO_STREAM_HIGH(0): High-resolution, high-bitrate video.
  • VIDEO_STREAM_LOW(1): Low-resolution, high-bitrate video.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream()

abstract int io.agora.rtc.RtcChannel.createDataStream ( boolean  reliable,
boolean  ordered 
)
abstract

Creates a data stream.

Each user can create up to five data streams during the life cycle of the RtcChannel instance.

Parameters
reliableSets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • true: The recipients receive the data from the sender within five seconds. If the recipient does not receive the data within five seconds, the SDK triggers the onStreamMessageError callback and returns an error code.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
orderedDetermines whether or not the recipients receive the data stream in the sent order:
  • true: The recipients receive the data in the sent order.
  • false: The recipients do not receive the data in the sent order.
Note
Set both the reliable and ordered parameters to true or false. Do not set one as true and the other as false.
Returns
  • The stream ID, if the method call succeeds.
  • The negative integer, if the method call fails.

◆ sendStreamMessage()

abstract int io.agora.rtc.RtcChannel.sendStreamMessage ( int  streamId,
byte []  message 
)
abstract

Sends the data stream message.

The SDK has the following restrictions on this method:

  • Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 KB.
  • Each client can send up to 6 KB of data per second.
  • Each user can have up to five data channels simultaneously.

A successful sendStreamMessage method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.

A failed sendStreamMessage method call triggers the onStreamMessageError callback on the remote client.

Parameters
streamIdID of the sent data stream returned by the createDataStream method.
messageThe message data in byte[].
Returns
  • 0: Success.
  • < 0: Failure.

◆ addPublishStreamUrl()

abstract int io.agora.rtc.RtcChannel.addPublishStreamUrl ( String  url,
boolean  transcodingEnabled 
)
abstract

Publishes the local stream to the CDN.

This method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.
transcodingEnabledSets whether transcoding is enabled/disabled. If you set this parameter as true, ensure that you call the setLiveTranscoding method before this method.
  • true: Enable transcoding to transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple broadcasters in CDN live.
  • false: Disable transcoding.
Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
  • Ensure that the user joins a channel before calling this method.
  • This method can only be called by a broadcaster in a Live-Broadcast channel.
  • This method adds only one stream HTTP/HTTPS URL address each time it is called.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT(2): Invalid parameter, usually because the URL address is null or the string length is 0.
    • ERR_NOT_INITIALIZED(7): You have not initialized RtcChannel when publishing the stream.

◆ removePublishStreamUrl()

abstract int io.agora.rtc.RtcChannel.removePublishStreamUrl ( String  url)
abstract

Removes an RTMP stream from the CDN.

This method removes the RTMP URL address (added by addPublishStreamUrl) from a CDN live stream. The SDK reports the result of this method call in the onRtmpStreamingStateChanged callback.

Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
  • This method can only be called by a broadcaster in a Live-Broadcast channel.
  • This method removes only one stream HTTP/HTTPS URL address each time it is called.
Parameters
urlThe RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLiveTranscoding()

abstract int io.agora.rtc.RtcChannel.setLiveTranscoding ( LiveTranscoding  transcoding)
abstract

Sets the video layout and audio settings for CDN live.

The SDK triggers the onTranscodingUpdated callback when you call this method to update the LiveTranscodingclass. If you call this method to set the LiveTranscoding class for the first time, the SDK does not trigger the onTranscodingUpdated callback.

Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
  • Ensure that the user joins a channel before calling this method.
  • This method can only be called by a broadcaster in a Live-Broadcast channel.
  • Ensure that you call this method before calling the addPublishStreamUrl method.
Parameters
transcodingSets the CDN live audio/video transcoding settings: LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addInjectStreamUrl()

abstract int io.agora.rtc.RtcChannel.addInjectStreamUrl ( String  url,
LiveInjectStreamConfig  config 
)
abstract

Injects an online media stream to a Live-Broadcast channel.

If this method call succeeds, the server pulls the voice or video stream and injects it into a live channel. This applies to scenarios where all audience members in the channel can watch a live show and interact with each other.

Note
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
  • This method can only be called by a broadcaster in a Live-Broadcast channel.

Calling this method triggers the following callbacks:

  • The local client:
    • onStreamInjectedStatus, with the state of injecting the media stream.
    • onUserJoined(uid: 666), if the method call succeeds and the online media stream is injected into the channel.
  • The remote client:
    • onUserJoined(uid: 666), if the method call succeeds and the online media stream is injected into the channel.
Parameters
urlThe URL address to be added to the ongoing live broadcast. Valid protocols are RTMP, HLS, and FLV.
  • Supported FLV audio codec type: AAC.
  • Supported FLV video codec type: H264(AVC).
configThe LiveInjectStreamConfig object, which contains the configuration information for the added voice or video stream.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT(2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
    • ERR_NOT_READY(3): The user is not in the channel.
    • ERR_NOT_SUPPORTED(4): The channel profile is not Live-Broadcast.
    • ERR_NOT_INITIALIZED(7): The SDK is not initialized. Ensure that the RtcChannel instance is initialized before using this method.

◆ removeInjectStreamUrl()

abstract int io.agora.rtc.RtcChannel.removeInjectStreamUrl ( String  url)
abstract

Removes the injected online media stream from a Live-Broadcast channel.

This method removes the URL address added by addInjectStreamUrl.

If you successfully remove the URL address from the Live-Broadcast, the SDK triggers the onUserJoined callback, with the stream uid of 666.

Parameters
urlThe URL address to be removed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startChannelMediaRelay()

abstract int io.agora.rtc.RtcChannel.startChannelMediaRelay ( ChannelMediaRelayConfiguration  channelMediaRelayConfiguration)
abstract

Starts to relay media streams across channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks report the state and events of the media stream relay.

  • If the onChannelMediaRelayStateChanged callback reports RELAY_STATE_RUNNING(2) and RELAY_OK(0), and the onChannelMediaRelayEvent callback reports RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4), the SDK starts relaying media streams between the original and the destination channel.
  • If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE(3), an exception occurs during the media stream relay.
Note
  • Contact suppo.nosp@m.rt@a.nosp@m.gora..nosp@m.io before implementing this function.
  • Call this method after joining the channel.
  • This method can only be called by a broadcaster in a Live-Broadcast channel.
  • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
Parameters
channelMediaRelayConfigurationThe configuration of the media stream relay: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopChannelMediaRelay()

abstract int io.agora.rtc.RtcChannel.stopChannelMediaRelay ( )
abstract

Stops the media stream relay.

Once the relay stops, the broadcaster quits all the destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback reports RELAY_STATE_IDLE(0) and RELAY_OK(0), the broadcaster successfully stops the relay.

Note
If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the RELAY_ERROR_SERVER_NO_RESPONSE(2) or RELAY_ERROR_SERVER_CONNECTION_LOST(8) state code. You can leave the channel using leaveChannel, and the media stream relay automatically stops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaRelay()

abstract int io.agora.rtc.RtcChannel.updateChannelMediaRelay ( ChannelMediaRelayConfiguration  channelMediaRelayConfiguration)
abstract

Updates the channels for media relay.

After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method, the SDK triggers the onChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7) state code.

Note
  • Call this method after the startChannelMediaRelay method to update the destination channel.
  • This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the removeDestChannelInfo method in ChannelMediaRelayConfiguration before calling this method.
Parameters
channelMediaRelayConfigurationThe media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVideoRenderer()

abstract int io.agora.rtc.RtcChannel.setRemoteVideoRenderer ( int  uid,
IVideoSink  render 
)
abstract

Customizes the remote video renderer for the RtcChannel object.

Since
3.0.1

During real-time engagements, the Agora SDK enables the default video sink to render the video. In the multi-channel scenario, if you want to customize the video renderer, you can create a customized video sink using the IVideoSink class, and call setRemoteVideoRenderer to add the customized sink into the RtcChannel object.

Parameters
uidThe ID of the remote user.
renderThe customized remote video renderer: IVideoSink.
Returns
  • 0: Success.
  • < 0: Failure.