Injects the online media stream to a live streaming.
If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. And all audience members in the channel can watch a live show and interact with each other.
This method call triggers the following callbacks:
streamInjectedStatus, reports the injecting status.userJoined(uid:666), reports the stream is injected
successfully and the UID of this stream is 666.
userJoined(uid:666), reports the stream is injected
successfully and the UID of this stream is 666.
The URL address to be added to the ongoing live streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.
The configuration of the injected stream. See InjectStreamConfig
AgoraRtcChannel object is initialized before calling this
method.
Publishes the local stream to a specified CDN URL address.
In the 1 (live streaming) profile, the host can call this method
to publish the local stream to a specified CDN URL address, which is called
"Media Push."
During Media Push, the SDK triggers the
rtmpStreamingStateChanged callback is any streaming state
changes.
The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters.
Sets whether transcoding is enabled/disabled:
true, ensure that you call
the
setLiveTranscoding
method before this method.
ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has
a string length of 0.
ERR_NOT_INITIALIZED (7): You have not initialized
AgoraRtcChannel when publishing the stream.
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.
The ID of the remote user.
The playback volume of the specified remote user. The value ranges from 0 to 100:
Gets the channel ID of the current AgoraRtcChannel object.
AgoraRtcChannel object, if the
method call succeeds.
Creates a data stream.
Each user can create up to five data streams during the lifecycle of the AgoraRtcChannel.
Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
Sets whether or not the recipients receive the data stream in the sent order:
Creates a data stream.
The configurations for the data stream.
Enables/Disables the built-in encryption.
Whether to enable the built-in encryption:
Configurations of built-in encryption schemas. See EncryptionConfig.
Retrieves the current call ID.
When a user joins a channel on a client, a callId is generated to
identify the call from the client. Feedback methods, such as {@link
AgoraRtcChannel.rate rate} and {@link AgoraRtcChannel.complain complain}, must
be called after the call ends to submit feedback to the SDK.
The rate and complain methods require the
callId parameter retrieved from the getCallId method
during a call.
Gets the connection state of the SDK.
Connect states. See {@link ConnectionState}.
Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams.
Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.
You must call the leaveChannel method to exit the current call before entering another channel.
A successful joinChannel method call triggers the following
callbacks:
joinChannelSuccess.userJoined, if the user joining the channel
is in the 0 (communication) profile, or is a host in the
1 (live stream ing) profile.
When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server.
When the local client successfully rejoins the channel, the SDK triggers the
rejoinChannelSuccess callback on the local client.
The token generated at your server. For details, see Generate a token.
(Optional) Reserved for future use.
(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1
to 232-1. The @p uid must be unique. If a @p uid is not
assigned (or set to 0), the SDK assigns and returns a @p uid in the
joinChannelSuccess callback. Your application must record and
maintain the returned uid, because the SDK does not do so.
Note: The ID of each user in the channel should be
unique. If you want to join the same channel from different devices,
ensure that the user IDs in all devices are different.
The channel media options. See ChannelMediaOptions.
-2: The parameter is invalid.-3: The SDK fails to be initialized. You can try
re-initializing the SDK.
AgoraRtcChannel object with the same
channel name.
AgoraRtcChannel object. When you join a channel created
by the AgoraRtcEngine object, the SDK publishes the local
audio and video streams to that channel by default. Because the SDK
does not support publishing a local stream to more than one channel
simultaneously, an error occurs in this occasion.
-7: The SDK is not initialized before calling this method.
Joins the channel with a user account.
After the user successfully joins the channel, the SDK triggers the following callbacks:
localUserRegistered and
joinChannelSuccess.
userJoined and userInfoUpdated,
if the user joining the channel is in the communication(0)
profile, or is a host in the 1 (live streaming) profile.
The token generated at your server. For details, see Generate a token.
The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
The channel media options. See ChannelMediaOptions.
-2-3-5-7Allows a user to leave a channel.
Allows a user to leave a channel, such as hanging up or exiting a call. The user must call the method to end the call before joining another channel after call the joinChannel method. This method returns 0 if the user leaves the channel and releases all resources related to the call. This method call is asynchronous, and the user has not left the channel when the method call returns.
Once the user leaves the channel, the SDK triggers the leavechannel callback.
A successful leavechannel method call triggers the removeStream callback for the remote client when the user leaving the channel is in the Communication channel, or is a host in the Live streaming profile.
Stops or resumes subscribing to the audio streams of all remote users.
As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.
Sets whether to stop subscribing to the audio streams of all remote users.
Stops or resumes subscribing to the video streams of all remote users.
As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.
Sets whether to stop subscribing to the video streams of all remote users.
Stops or resumes publishing the local audio stream.
Sets whether to stop publishing the local audio stream.
-5 (ERR_REFUSED): The request is rejected.Stops or resumes publishing the local video stream.
Sets whether to stop publishing the local video stream.
-5 (ERR_REFUSED): The request is rejected.Stops or resumes subscribing to the audio stream of a specified user.
Sets whether to stop subscribing to the audio stream of a specified user.
Stops or resumes subscribing to the video stream of a specified user.
Sets whether to stop subscribing to the video stream of a specified user.
Occurs when a user joins a specified channel.
The User ID.
Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.
Reports a warning during SDK runtime.
Warning code.
The warning message.
Reports an error during SDK runtime.
Error code.
The error message.
Occurs when a user rejoins the channel after disconnection 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.
User ID of the user joining the channel.
Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.
Occurs when the user leaves the channel.
When the app calls the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel.
Occurs when the user role switches in a live streaming.
For example, from a host to an audience or vice versa.
This callback notifies the application of a user role switch when the application calls the setClientRole method.
The old role, see {@link ClientRoleType}
The new role, see {@link ClientRoleType}
Occurs when a user or host joins the channel.
The SDK triggers this callback under one of the following circumstances:
User ID of the user or host joining the channel.
Time delay (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when a remote user (Communication)/host (Live streaming) leaves the channel.
There are two reasons for users to become offline:
ID of the user or host who leaves the channel or goes offline.
Reason why the user goes offline:
Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.
The SDK triggers this callback when it cannot connect to the server 10 seconds after calling the joinChannel method, whether or not it is in the channel.
Occurs when the token expires.
After a token(channel key) is specified by calling the joinChannel method, if the SDK losses connection with the Agora server due to network issues, the token may expire after a certain period of time and a new token may be required to reconnect to the server.
This callback notifies the application to generate a new token and call joinChannel to rejoin the channel with the new token.
Occurs when the token expires in 30 seconds.
The user becomes offline if the token used in the joinChannel method expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call the renewToken method to pass the new token to the SDK.
The token that expires in 30 seconds.
Reports the statistics of the AgoraRtcChannel once every two seconds.
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's edge server.
User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. See AgoraNetworkQuality.
Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See AgoraNetworkQuality.
Reports the statistics of the video stream from each remote user/host.
Statistics of the received remote video streams. See RemoteVideoState.
Reports the statistics of the audio stream from each remote user/host.
Statistics of the received remote audio streams. See RemoteAudioStats.
Occurs when the remote audio state changes.
This callback indicates the state change of the remote audio stream.
ID of the remote user whose audio state changes.
State of the remote audio: RemoteAudioState.
The reason of the remote audio state change: RemoteAudioStateReason.
Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Reports which user is the loudest speaker.
This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.
User ID of the active speaker. A uid of 0 represents the local user. If the user enables the audio volume indication by calling the enableAudioVolumeIndication method, this callback returns the uid of the active speaker detected by the audio volume detection module of the SDK.
User ID of the remote user sending the audio stream.
The time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when the video size or rotation of a specified user changes.
User ID of the remote user or local user (0) whose video size or rotation changes.
New width (pixels) of the video.
New height (pixels) of the video.
Occurs when the remote video state changes.
ID of the user whose video state changes.
State of the remote video. See RemoteVideoState.
The reason of the remote video state change. See RemoteVideoStateReason
Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when the local user receives the data stream from the remote user within five seconds.
The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.
User ID of the remote user sending the message.
Stream ID.
The data received bt the local user.
Reports the result of an audio device test.
The volume type. See AudioDeviceTestVolumeType.
The volume, in the range of [0,255].
Occurs when the local user does not receive the data stream from the remote user within five seconds.
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.
User ID of the remote user sending the message.
Stream ID.
Number of the lost messages.
Number of incoming cached messages when the data stream is interrupted.
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.
The state code. See ChannelMediaRelayState.
The error code. See ChannelMediaRelayError.
Reports events during the media stream relay.
The event code. See ChannelMediaRelayEvent.
User ID of the remote user.
Time elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback.
Occurs when the state of the RTMP or RTMPS streaming changes.
The SDK triggers this callback to report the result of the local user calling the addPublishStreamUrl and removePublishStreamUrl method.
This callback indicates the state of Media Push. When exceptions occur, you
can troubleshoot issues by referring to the detailed error descriptions in the
code parameter.
The RTMP URL address.
Media Push state:
0: Media Push has not started or has ended.
This state is also triggered after you remove an RTMP
address from the CDN by calling
removePublishStreamUrl.
1: The SDK is connecting to Agora's
streaming server and the RTMP server. This state is
triggered after you call the
addPublishStreamUrl
method.
2: Media Push publishes. The SDK successfully
publishes the Media Push stream and returns this state.
3: Media Push is recovering. When exceptions
occur to the CDN, or the streaming is interrupted, the SDK
tries to resume Media Push and returns this state.
2 returns.
4 returns. You can
also reconnect to the server by calling the
removePublishStreamUrl
and then
addPublishStreamUrl
method.
4: Media Push fails. See the
code parameter for the detailed error
information. You can also call the
addPublishStreamUrl
method to publish Media Push again.
The detailed error information:
0: Media Push publishes successfully.1: Invalid argument used.2: The RTMP streams is encrypted and cannot be
published.
3: Timeout for Media Push. Call the
addPublishStreamUrl
to publish the stream again.
4: An error occurs in Agora's streaming
server. Call the
addPublishStreamUrl
to publish the stream again.
5: An error occurs in the RTMP server.6: Media Push publishes too frequently.7: The host publishes more than 10 URLs. Delete
the unnecessary URLs before adding new ones.
8: The host manipulates other hosts' URLs.
Check your app logic.
9: Agora's server fails to find the RTMP
stream.
10: The format of the stream's URL address
is not supported. Check whether the URL format is correct.
100: The streaming has been stopped normally.
After you call
removePublishStreamUrl
to stop streaming, the SDK returns this value.
Occurs when the publisher's transcoding is updated.
Occurs when a voice or video stream URL address is added to a live broadcast.
The URL address of the externally injected stream.
User ID.
State of the externally injected stream:
Occurs when the remote media stream falls back to audio-only stream due to poor network conditions or switches back to the video stream after the network conditions improve.
If you call setRemoteSubscribeFallbackOption and set option as AUDIO_ONLY(2), the SDK triggers this callback when the remotely subscribed media stream falls back to audio-only mode due to poor uplink conditions, or when the remotely subscribed media stream switches back to the video after the uplink network condition improves.
ID of the remote user sending the stream.
Whether the remote media stream falls back to audio-only or switches back to the video:
true: The remote media stream falls back to
audio-only due to poor network conditions.
false: The remote media stream switches back to
the video stream after the network conditions improved.
Occurs when the connection state between the SDK and the server changes.
The connection state, see {@link ConnectionState}.
The connection reason, see {@link ConnectionState}.
Occurs when the audio publishing state changes.
The previous publishing state.
The current publishing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the video publishing state changes.
The previous publishing state.
The current publishing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the audio subscribing state changes.
The ID of the remote user.
The previous subscribing state.
The current subscribing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the video subscribing state changes.
The ID of the remote user.
The previous subscribing state.
The current subscribing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the first remote video frame is rendered.
User ID of the remote user sending the video stream.
Width (px) of the video frame.
Height (px) of the video stream.
Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Publishes the local stream to the channel.
Registers a media metadata observer.
Releases all AgoraRtcChannel resource
ERR_NOT_INITIALIZED (7): The SDK is not initialized before
calling this method.
Removes the injected the online media stream in a live streaming.
This method removes the URL address (added by the addInjectStreamUrl method) in a live streaming.
If this method call is successful, the SDK triggers the
userOffline (uid:666) callback and report the UID of the removed
stream is 666.
The URL address of the injected stream to be removed.
Removes the RTMP stream from the CDN.
This method removes the RTMP URL address (added by addPublishStreamUrl) and stops Media Push.
This method call triggers the rtmpStreamingStateChanged callback
to report the state of removing the URL address.
The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters.
Gets a new token when the current token expires after a period of time.
The token expires after a period of time once the token schema is
enabled when the SDK triggers the
onTokenPrivilegeWillExpire callback or
CONNECTION_CHANGED_TOKEN_EXPIRED(9) of
onConnectionStateChanged callback.
You should call this method to renew token, or the SDK
disconnects from Agora' server.
The new Token.
Sends the media metadata.
After calling the
registerMediaMetadataObserver
method, you can call the setMetadata method to send the media
metadata.
If it is a successful sending, the sender receives the
sendMetadataSuccess callback, and the receiver receives the
receiveMetadata callback.
The media metadata.
Sends data stream messages to all users in the channel.
The SDK has the following restrictions on this method:
Ensure that you have created the data stream using createDataStream before calling this method.
If the method call succeeds, the remote user receives the
streamMessage
callback; If the method call fails, the remote user receives the
streamMessageError callback.
he ID of the sent data stream, returned in the createDataStream method.
The data stream messages.
Sets the role of the user.
In the 1 (live streaming) profile, when a user calls this method
to switch user roles after joining a channel, SDK triggers the follwoing
callbacks:
clientRoleChanged in the
AgoraRtcChannel interface.
userjoined or userOffline.
Sets the role of the user. See {@link AgoraRtcChannel.role role}
Sets the role of a user in interactive live streaming.
The role of a user in interactive live streaming.
The detailed options of a user, including user level.
Stops or resumes subscribing to the audio streams of all remote users by default.
Sets whether to stop subscribing to the audio streams of all remote users by default.
Stops or resumes subscribing to the video streams of all remote users by default.
Sets whether to stop subscribing to the video streams of all remote users by default.
Sets the built-in encryption mode.
The set encryption mode:
The encryption password.
Sets the video layout and audio settings for CDN live.
The SDK triggers the transcodingUpdated callback when you call
this method to update the transcoding setting. If you call
this method for the first time to set the transcoding
setting, the SDK does not trigger the
transcodingUpdated callback.
The transcoding setting for the audio and video streams during Media Push. See {@link LiveTranscoding}
Sets the maximum size of the media metadata.
After calling the
registerMediaMetadataObserver
method, you can call the setMaxMetadataSize method to set the
maximum size.
The maximum size of your metadata.
Sets the default type of receiving video stream.
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-video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream) by default.
By default, users receive the high-video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.
The aspect ratio of the low-video stream is the same as the high-video stream. Once the resolution of the high-video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.
The video-stream type. See StreamType
Prioritizes a remote user's stream.
Use this method with the setRemoteSubscribeFallbackOption method.
If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.
The ID of the remote user.
The priority of the remote user. See Priority.
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-video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).
By default, users receive the high-video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.
The aspect ratio of the low-video stream is the same as the high-video stream.
Once the resolution of the high-video stream is set, the system automatically
sets the resolution, frame rate, and bitrate of the low-video stream. The SDK
reports the result of calling this method in the
apiCallExecuted callback.
The ID of the remote user sending the video stream.
The video-stream type. See StreamType
Sets the sound position and gain of a remote user.
When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.
The ID of the remote user.
The sound position of the remote user. The value ranges from -1.0 to 1.0:
Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
Starts to relay media streams across channels.
After a successful method call, the SDK triggers the
channelMediaRelayState and
channelMediaRelayEvent callbacks, which returns the state and
event of the media stream relay.
channelMediaRelayState returns the state code
2 and the error code0, and
channelMediaRelayEvent returns the event code 4,
the host starts sending data to the destination channel.
channelMediaRelayState returns the state code
3, an exception occurs during the media stream relay.
The configuration of the media stream relay. See ChannelMediaRelayConfiguration
Stops the media stream relay.
Once the relay stops, the host quits all the destination channels.
After a successful method call, the SDK triggers the
channelMediaRelayState callback. If the callback returns the
state code 0 and the error code 1, the host
successfully stops the relay.
Unregisters a media metadata observer.
Stops publishing a stream to the channel.
Updates the channels for media stream relay.
After a successful
startChannelMediaRelay
method call, 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 call, the SDK triggers the
channelMediaRelayEvent callback with the event code
7.
The configuration of the media stream relay. See ChannelMediaRelayConfiguration
v3.0.0
The AgoraRtcChannel class.