Injects an Online Media Stream to a Live Broadcast
The streamInjectedStatus
callback returns the inject status.If this method is called successfully, the server pulls the voice or video stream and injects it into a live channel.
This is applicable to scenarios where all of the audience members in the channel can watch a live show and interact with each other.
Note:
Contact sales@agora.io to enable the CDN push-stream function.
URL address of the live streaming. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes. Valid protocols are RTMP, HLS, and FLV.
Configuration of the inject stream, see InjectStreamConfig for details.
Configures the CDN Live Streaming
DEPRECATED
Agora recommends using the following methods instead:
This method configures the CDN live streaming before joining a channel.
Note:
Call configPublisher before Client.join.
Width of the output data stream set for CDN Live, 360 is the default value. A positive integer, and the value range is [1,10000].
Height of the output data stream set for CDN Live, 640 is the default value. A positive integer, and the value range is [1,10000].
Frame rate of the output data stream set for CDN Live, 15 fps is the default value. A positive integer, and the value range is [1,10000].
Bitrate of the output data stream set for CDN Live, 500 kbps is the default value. A positive integer, and the value range is [1,10000000].
The push-stream address for the picture-in-picture layouts, null
is the default value.
ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
Disables Dual Streams
This method disables dual streams.
The callback when the method succeeds.
The callback when the method fails.
Enables Volume Indicator
This method enables the SDK to report the active remote users who are speaking and their volume regularly.
If this method is enabled, the SDK triggers the "volume-indicator"
callback to report the volumes every two seconds, regardless of whether there are active speakers.
Note:
Enables Dual Stream
This method enables the dual-stream mode on the publisher side.
Dual streams are a hybrid of a high-video stream and a low-video stream:
We do not recommend using the track methods (addTrack/removeTrack/replaceTrack) on dual streams, which might cause different performance in the high-video and low-video streams.
The callback when the method succeeds.
The callback when the method fails.
Enumerates Video Input Devices
This method enumerates the available video input devices, such as cameras.
If this method succeeds, the SDK returns a list of video input devices in an array of MediaDeviceInfo objects.
Gets the Connection State
This method returns the state of the connection between the SDK and Agora's edge server.
The connection state:
DISCONNECTED
: The SDK is disconnected from Agora's edge server.CONNECTING
: The SDK is connecting to Agora's edge server.
The SDK enters this state when calling Client.join or reconnecting to Agora's edge server automatically after the connection is lost.CONNECTED
: The SDK is connected to Agora's edge server and joins a channel. You can now publish or subscribe to a stream in the channel.DISCONNECTING
: The SDK is disconnecting from Agora's edge server. The SDK enters this state when calling Client.leave.Retrieves the Audio Statistics of the Local Stream
This method retrieves the audio statistics of the published stream, including audio codec type, sampling rate, bitrate, and so on.
Note:
stream-published
event, which may take at most 3 seconds.The callback contains the statistics of the local audio stream.
Retrieves the Video Statistics of the Local Stream
This method retrieves the video statistics of the published stream, including video resolution, bitrate, frame rate, and so on.
Note:
stream-published
event, which may take at most 3 seconds.The callback contains the statistics of the local video stream.
Gets the Statistics of the System Network
DEPRECATED from v2.5.1, use getTransportStats instead.
This method gets the statistics of the browser's local network.
Currently only the network type information is provided, see NetworkType.
Note:
Chrome 61+ is required for this function, and the compatibility is not guaranteed. See Network Information API for details.
The callback contains the statistics of the system network.
Enumerates Audio Output Devices
This method enumerates the available audio output devices, such as speakers.
If this method succeeds, the SDK returns a list of audio output devices in an array of MediaDeviceInfo objects.
Note:
Only Chrome 49+ supports this function.
Enumerates Audio Input Devices
This method enumerates the available audio input devices, such as microphones.
If this method succeeds, the SDK returns a list of audio input devices in an array of MediaDeviceInfo objects.
Retrieves the Audio Statistics of the Remote Stream
This method retrieves the audio statistics of the remote stream, including audio codec type, packet loss rate, bitrate, and so on.
Note:
stream-subscribed
event, which may take at most 3 seconds.The callback contains the statistics of the remote audio stream.
Retrieves the Video Statistics of the Remote Stream
This method retrieves the video statistics of the remote stream, including packet loss rate, video bitrate, frame rate, and so on.
Note:
stream-subscribed
event, which may take at most 3 seconds.The callback contains the statistics of the remote video stream.
Gets the Statistics of the Session
This method gets the statistics of the session connection.
Note:
The callback contains the statistics of the session connection.
Gets the Statistics of the System
This method gets the statistics of the system.
Currently only the battery level information is provided, see BatteryLevel.
Note:
This feature is experimental, see Battery Status API for browser compatibility.
The callback contains the statistics of the system.
Gets the Statistics of the Transmission
This method gets the statistics of the transmission quality to Agora service.
Note:
The callback contains the statistics of the transmission quality.
Initializes a Client Object
This method initializes the client object.
Pass in the App ID for your project. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
The callback when the method succeeds.
The callback when the method fails.
Joins an AgoraRTC Channel
This method joins an AgoraRTC channel.
null
as the parameter value.A string that provides a unique channel name for the Agora session. The length must be within 64 bytes. Supported character scopes:
The user ID, an integer or a string, ASCII characters only. Ensure this ID is unique.
If you set the uid to null
, the server assigns one and returns it in the onSuccess
callback.
Note:
uid
.The callback when the method succeeds. The server returns the uid which represents the identity of the user.
The callback when the method fails.
Leaves an AgoraRTC Channel
This method enables a user to leave a channel.
The callback when the method succeeds.
The callback when the method fails.
Occurs when the local stream is published.
Occurs when the remote stream is added.
Note:
When the local user joins the channel, if other users are already in the channel, the SDK also reports to the app on the existing remote streams.
Occurs when the remote stream is removed; for example, a peer user calls Client.unpublish.
Occurs when a user subscribes to a remote stream.
Occurs when the peer user leaves the channel; for example, the peer user calls Client.leave.
Occurs when the peer user mutes the audio.
Occurs when the peer user unmutes the audio.
Occurs when the peer user turns off the video.
Occurs when the peer user turns on the video.
This callback notifies the peer user that he/she is banned from the channel. Only the banned users receive this callback.
This callback notifies the application who is the active speaker in the channel.
This callback notifies the application of all the speaking remote users and their volumes.
It is disabled by default. You can enable this event by calling enableAudioVolumeIndicator. If enabled, it reports the volumes every two seconds regardless of whether there are users speaking.
The volume is an integer ranging from 0 to 100. Usually a user with volume above five will be counted as a speaking user.
Occurs when the live streaming starts.
Occurs when the live streaming fails.
Occurs when the live streaming stops.
Occurs when the live transcoding setting is updated.
Occurs when the injected online media stream's status is updated.
Occurs when the Token expires in 30 seconds.
You should request a new Token from your server and call Client.renewToken.
Occurs when the Token expires.
You should request a new Token from your server and call Client.renewToken.
Occurs when an error message is reported and requires error handling.
Occurs when the network type changes.
Occurs when an audio input device is added or removed.
Occurs when an audio output device is added or removed.
Occurs when a camera is added or removed.
Occurs when the type of a video stream changes.
It happens when a high-video stream changes to a low-video stream, or vice versa.
The stream type (streamType):
Occurs when the network connection state changes.
The connection between the SDK and Agora's edge server has the following states:
DISCONNECTED
: The SDK is disconnected from Agora's edge server.CONNECTING
: The SDK is connecting to Agora's edge server.
The SDK enters this state when calling Client.join or reconnecting to Agora's edge server automatically after the connection is lost.CONNECTED
: The SDK is connected to Agora's edge server and joins a channel. You can now publish or subscribe to a stream in the channel.
If the connection is lost because, for example, the network is down or switched, the SDK triggers this callback and notifies the app that the state changes from CONNECTED
to CONNECTING
.DISCONNECTING
: The SDK is disconnecting from Agora's edge server. The SDK enters this state when calling Client.leave.The current connection state.
The previous connection state.
Occurs when the SDK starts republishing or re-subscribing to a stream.
The corresponding uid of the stream being republished or re-subscribed to.
Occurs when the SDK finishes republishing or re-subscribing to a stream.
success
is true
.success
is false
.The result of republishing or re-subscribing to the stream.
true
: Success.false
: Failure.The corresponding uid of the stream being republished or re-subscribed to.
Occurs when the user role switches in a live broadcast. For example, from a host to an audience or vice versa.
Role that the user switches to.
Occurs when a remote user or host joins the channel.
ID of the user or host who joins the channel.
Occurs when the SDK starts reconnecting to the server automatically after the connection is lost.
Occurs when the SDK is connected to the server.
Reports the network quality of the local user once every two seconds.
This callback reports on the uplink and downlink network conditions of the local user.
Note:
This is an experimental feature and the network quality rating is for reference only.
The local user's network quality, including the uplink and downlink quality, see NetworkQualityStats for details.
Occurs when the remote video stream falls back to an audio-only stream due to unreliable network conditions or switches back to the video after the network conditions improve.
If you set fallbackType
as 2 in setStreamFallbackOption,
the SDK triggers this callback when the remote media stream falls back to audio only due to unreliable network conditions or switches back to the video after the network condition improves.
Note:
Once the remote media stream is switched to the low stream due to unreliable network conditions,
you can monitor the stream switch between a high stream and low stream in the stream-type-changed
callback.
Whether the remote media stream falls back to audio-only or switches back to the video:
ID of the remote user sending the stream.
Occurs when a remote stream adds or removes a track.
When a remote stream calls the addTrack or removeTrack method, the SDK triggers this callback.
The stream that adds or removes a track:
video
: boolean, marks whether the stream contains a video track.audio
: boolean, marks whether the stream contains an audio track.Reports exception events in the channel.
Exceptions are not errors, but usually mean quality issues.
This callback also reports recovery from an exception.
Each exception event has a corresponding recovery event, see the table below for details:
Note:
This callback supports only the Chrome browser.
Event code.
Event message.
The uid of the user who experiences the exception or recovery event.
Publishes a Local Stream
This method publishes a local stream to the SD-RTN.
Note:
In a live broadcast, whoever calls this API is the host.
Stream object, which represents the local stream.
The callback when the method fails.
Removes the Injected Stream
This method removes the HTTP/HTTPS URL address (added by addInjectStreamUrl) from the live broadcast.
URL address of the live streaming. ASCII characters only, and the string length must be greater that 0 and less than 256 bytes.
Renews the Channel Key
This method renews your channel key.
Once the Channel Key schema is enabled, the key expires after a certain period of time.
When the onFailure callback reports the error DYNAMIC_KEY_TIMEOUT
, the application should renew the Channel Key by calling this method.
Not doing so will result in SDK disconnecting with the server.
Specifies the renewed Channel Key.
The callback when the method succeeds.
The callback when the method fails.
Renews the Token
This method renews your token.
Once the Token schema is enabled, the token expires after a certain period of time.
In case of the onTokenPrivilegeWillExpire
or onTokenPrivilegeDidExpire
callback events, the application should renew the Token by calling this method.
Not doing so will result in SDK disconnecting with the server.
Specifies the renewed Token.
Sets the role of the user.
This method is applicable only to the live mode.
Sets the role of the user such as a host or an audience (default), before joining a channel.
This method can be used to switch the user role after the user joins a channel.
In live mode (mode is set as live
):
Before joining the channel, you can call this method to set the role.
After joining the channel, you can call this method to switch the role:
Note
In communication mode (mode set as rtc
), this method does not take effect. All users are host
by default.
User role in a live broadcast:
"audience"
: Audience, the default role. An audience can only receive streams."host"
: Host. A host can both send and receive streams.Sets the Encryption Mode
Use this method with setEncryptionSecret method to enable the built-in encryption before joining a channel.
All users in a channel must set the same encryption mode.
Note:
The encryption mode:
Enables Built-in Encryption
Use this method with setEncryptionMode method to enable the built-in encryption before joining a channel.
All users in a channel must set the same encryption password.
Note:
The encryption password. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
Sets Live Transcoding
This method sets the video layout and audio for CDN live.
Note:
Transcoding settings, see LiveTranscoding for details.
Sets the Low-video Stream Parameter
If you enabled the dual-stream mode by calling Client.enableDualStream, use this method to set the low-video stream profile.
If you do not set the low-video stream profile, the SDK will assign default values based on your stream video profile.
Note:
Sets the video profile of the low-video stream.
Bitrate of the low-video stream frame in Kbps. A positive integer, and the value range is [1,10000000].
Frame rate of the low-video stream frame in fps. A positive integer, and the value range is [1,10000].
Height of the low-video stream frame. A positive integer, and the value range is [1,10000].
The width and height parameters are bound together, and take effect only when both are set. Otherwise, the SDK assigns default values.
Width of the low-video stream frame. A positive integer, and the value range is [1,10000].
The width and height parameters are bound together, and take effect only when both are set.Otherwise, the SDK assigns default values.
Deploys the Nginx Server
Use this method to deploy the Nginx server.
Note:
Your Nginx server domain name. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
Sets the Remote Video-stream Type
When a remote user sends dual streams, this method decides on which stream to receive on the subscriber side. If this method is not used, the subscriber receives the high-video stream.
The remote video stream object.
Sets the remote video stream type. The following lists the video-stream types:
Sets Stream Fallback Option
Use this method to set stream fallback option on the receiver.
Under poor network conditions, the SDK can choose to subscribe to the low-video stream or only the audio stream.
Note:
This method can only be used when the publisher has enabled the dual-stream mode by enableDualStream.
The remote stream object.
The fallback option:
Deploys the TURN Server
Use this method to deploy the TURN server.
Note:
Ensure that you call this API before Client.join.
The TURN server settings.
Sets whether to force data transfer by TURN Server:
Your TURN Server password. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
The TCP port(s) you want add to TURN Server. Numeric characters only, and the string length must be greater than 0 and less than 256 bytes.
Your TURN Server URL address. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
The UDP port(s) you want to add to TURN Server. Numeric characters only, and the string length must be greater than 0 and less than 256 bytes.
Your TURN Server username. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
Starts a Live Stream
This method starts a live stream.
URL address for the live stream. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
Marks whether to enable live transcoding. If set as true
, setLiveTranscoding must be called before this method.
Stops Live Streaming
This method stops and deletes the live streaming.
URL address of the live streaming. ASCII characters only, and the string length must be greater than 0 and less than 256 bytes.
Subscribes to a Remote Stream
This method enables a user to subscribe to a remote stream.
Stream object, which represents the remote stream.
Sets whether to receive the video or audio data independently by the video
and audio
parameters.
Note:
video
and audio
cannot be set as false
at the same time. If you need to stop subscribing to the stream, call Client.unsubscribe instead.options
as null
for Safari, otherwise theSAFARI_NOT_SUPPORTED_FOR_TRACK_SUBSCRIPTION
error occurs.Marks whether to receive the audio data.
true
: (Default) Receives the audio data.false
: Not receives the audio data.Marks whether to receive the video data.
true
: (Default) Receives the video data.false
: Not receives the video data.The callback when the method fails.
Unpublishes the Local Stream
This method unpublishes the local stream.
Stream object, which represents the local stream.
The callback when the method fails.
Unsubscribes from the Remote Stream
This method enables the user to unsubscribe from the remote stream.
Stream object, which represents the remote stream.
The callback when the method fails.
The Client object returned by the createClient method provides access to much of the core AgoraRTC functionality.