Interactive Broadcast API Scene-Optimized

Interactive Broadcast API Scene-Optimized

The scene-optimized APIs are specialized for the interactive broadcast scenario, especially for CDN publishing. These APIs have packaged the basic interactive broadcast APIs and added several new APIs, allowing you to:

  • Publish or unpublish a stream.
  • Add or remove a stream URL without interrupting publishing.
  • Keep updated on the publishing status, such as a success or failure.

Note

The RtcEngine class is still available for the time being. It is available for Agora’s long-term partners or senior-level developers who want to use or set:

  • Fullband
  • Audio mixing effects
  • Video capture
  • Audio profiles

You can use the getRtcEngine() method to get an object of the RtcEngine class. For more information about APIs in the RtcEngine class, see broadcast_video_android.

A document on the relationship between the basic interactive broadcast APIs and the scene-optimized APIs will be available soon. For now, please treat them separately.

The structure of the scene-optimized APIs on Android is as follows:

Java Interface Class Description
LiveEngine Class The base class for managing a live broadcast: Manages actions apart from publishing and subscribing.
LiveSubscriber Class A class for managing actions related to live subscribing.
LivePublisher Class A class for managing actions related to live publishing.
LiveEngineHandler Class An abstract class providing callbacks to the LiveEngine class.
LiveSubscriberHandler Class An abstract class providing callbacks to the audience, informing them of occurred events.
LivePublisherHandler Class An abstract class providing callbacks to the host, informing the host of occurred events.
LiveChannelConfig Class A public static class for disabling or enabling live video broadcasting.
LiveStats Class A public static class providing a callback, which returns the statistics of the live broadcasting.
LiveTranscoding Class

A public class managing CDN transcoding:

LiveEngine Class

This class is the base class for managing live broadcast. It manages actions apart from publishing and subscribing, and includes the following methods:

  • getSdkVersion()
  • getMediaEngineVersion()
  • createLiveEngine()
  • destroy()
  • getRtcEngine()
  • getLiveChannelConfig()
  • setPublisher()
  • setSubscriber()
  • joinChannel()
  • leaveChannel()
  • renewChannelKey()
  • startPreview()
  • stopPreview()

Get the SDK Version (getSdkVersion)

public static String getSdkVersion()

This method gets the SDK version.

Get the MediaEngine Version (getMediaEngineVersion)

public static String getMediaEngineVersion()

This method gets the MediaEngine version.

Create a LiveEngine (createLiveEngine)

public static LiveEngine createLiveEngine(Context context, String appId, LiveEngineHandler handler)

This method creates a LiveEngine object.

Parameter Description
context Context of Android activities.
appId App ID issued to the application developers by Agora. Apply for a new one from Agora if it is not in your kit.
handler LiveEngineHandler is an abstract class that provides callbacks to the LiveEngine class.

Destroy the Live Broadcast Object (destroy)

public abstract void destroy();

This method destroys the live broadcast object.

Get the RTC Engine (getRtcEngine)

public abstract RtcEngine getRtcEngine();

This method gets the RtcEngine object.

Note

The RtcEngine class is still available at the moment. It is available for Agora’s old partners or senior-level developers who want to use or call:

  • Fullband
  • Audio mixing effects
  • Video capture
  • Agora’s proprietary APIs through the setParameters() method.

For more information about the RtcEngine class, see broadcast_video_android.

Get a LiveChannelConfig Instance (getLiveChannelConfig)

public abstract LiveChannelConfig getLiveChannelConfig();

This method gets a LiveChannelConfig instance.

Set a Publisher (setPublisher)

public abstract void setPublisher(LivePublisher publisher);

This method sets a publisher.

Parameters Description
publisher A LivePublisher object.

Set a Subscriber (setSubscriber)

public abstract void setSubscriber(LiveSubscriber subscriber);

This method sets a subscriber.

Parameter Description
subscriber A LiveSubscriber object.

Join a Channel (joinChannel)

public abstract int joinChannel(String channelId, String channelKey, LiveChannelConfig channelConfig, int uid);

This method allows a user to join a channel.

Parameter Description
channelId Channel ID. Joining a channel with the same channel ID means that users are joining the same room.
channelKey Channel key generated by the App through signature certification.
channelConfig Configuration to the channel.
uid ID of each user in the channel, that is unique.

Leave a Channel (leaveChannel)

public abstract int leaveChannel();

This method allows a user to leave a channel, such as hang up or exit a call.

Start a Local Video Preview (startPreview)

public abstract int startPreview(SurfaceView view, int renderMode);

This method starts a local video preview without sending any data to the server.

Parameter Description
view View to render
renderMode Rendering mode (For more information, see the following table.)
Name Value Description
RENDER_MODE_HIDDEN 1 If the video size is different from that of the display window, crop the video (if it is bigger) or stretch the video (if it is smaller) to fit it into the window.
RENDER_MODE_FIT 2 If the video size is different from that of the display window, resize the video proportionally to fit the window.
RENDER_MODE_ADAPTIVE 3
  • If both callers use the same screen mode, such as both use landscape or both use portrait, the RENDER_MODE_HIDDEN mode applies.
  • If both callers use different screen modes, such as one landscape and one portrait, the RENDER_MODE_FIT mode applies.

Renew the Channel Key (renewChannelKey)

public abstract int renewChannelKey(String channelKey);

This method renews the channel key and stores it in the SDK. The application should call this API when the SDK reports ERR_CHANNEL_KEY_EXPIRED.

Parameter Description
ChannelKey Channel key. Type: String

Renew the Channel Key (renewChannelKey)

public abstract int renewChannelKey(String channelKey);

This method updates the channel key and stores it in the SDK. The application needs to call this API when the SDK reports ERR_CHANNEL_KEY_EXPIRED.

Parameter Description
ChannelKey Channel key. Type: String

Stop the Local Video Preview (stopPreview)

public abstract int stopPreview();

This method stops the local video preview.

LiveSubscriber Class

This class manages actions related to live subscribing. It includes the following methods:

  • LiveSubscriber()
  • getLiveSubscriberHandler()
  • subscribe()
  • unsubscribe()

Construct a Live Subscriber Object (LiveSubscriber)

public LiveSubscriber(LiveEngine engine, LiveSubscriberHandler handler)

This method constructs a LiveSubscriber object.

Parameter Description
engine The LiveEngine class is the base class for managing live broadcasting. It manages actions apart from publishing and subscribing.
handler The LiveSubscriberHandlerHandler class is an abstract class providing callbacks to the LiveEngine class.

Get a LiveSubscriberHandler Object (getLiveSubscriberHandler)

public LiveSubscriberHandler getLiveSubscriberHandler()

This method gets a LiveSubscriberHandler object.

Subscribe to a Host (subscribe)

public void subscribe(int uid, int mediaType, Object view, int renderMode, int videoType)

This method is used for subscribing to a host.

Parameter Description
uid User id.
mediaType
  • 1: Voice only.
  • 2: Video only.
  • 3: Voice and Video.
  • 0: None.
view View to render.
renderMode Rendering mode. (For more information, see the following table.)
videoType
  • VIDEO_STREAM_HIGH = 0: High-resolution video stream at a high-frame rate.
  • VIDEO_STREAM_LOW = 1: Low-resolution video stream at a low-frame rate.
Name Value Description
RENDER_MODE_HIDDEN 1 If the video size is different from that of the display window, crop the video (if it is bigger) or stretch the video (if it is smaller) to fit it into the window.
RENDER_MODE_FIT 2 If the video size is different from that of the display window, resize the video proportionally to fit the window.
RENDER_MODE_ADAPTIVE 3
  • If both callers use the same screen mode, such as both use landscape or both use portrait, the RENDER_MODE_HIDDEN mode applies.
  • If both callers use different screen modes, such as one landscape and one portrait, the RENDER_MODE_FIT mode applies.

Unsubscribe from a Host (unsubscribe)

public void unsubscribe(int uid)

This method allows a user to unsubscribe from a host.

Parameter Description
uid User ID of the host

LivePublisher Class

This class manages actions related to live publishing. It includes the following methods:

  • LivePublisher()
  • getLivePublisherHandler()
  • setLiveTranscoding()
  • setMediaType()
  • publishWithPermissionKey()
  • setVideoProfile()
  • addStreamUrl()
  • removeStreamUrl()
  • unpublish()
  • switchCamera()

Construct a Live Publisher Object (LivePublisher)

public LivePublisher(LiveEngine engine, LivePublisherHandler handler)

This method constructs a LivePublisher object.

Parameter Description
engine The LiveEngine class is the base class for managing live broadcasting. It manages actions apart from publishing and subscribing.
handler The LivePublisherHandler is an abstract class providing callbacks to the host and informing the host of occurred events.

Get a LivePublisherHandler Object (getLivePublisherHandler)

public LivePublisherHandler getLivePublisherHandler()

This method gets a handler of the LivePublisher class.

Set as Live Transcoding (setLiveTranscoding)

public void setLiveTranscoding(LiveTranscoding transcoding)

This method is used for CDN publishing. In general, it sets the video layout, as well as audio, for CDN publishing.

Parameter Description
transcoding Configuration to live transcoding.

Set the Media Type (setMediaType)

public void setMediaType(int mediaType)

This method sets the media type.

Parameter Description
mediaType
  • 1: Voice only.
  • 2: Video only.
  • 3: Voice and Video.
  • 0: None.

Publish with a Permission Key (publishWithPermissionKey)

public void publishWithPermissionKey(String permissionKey)

This method allows publishing a stream with a permission key.

Parameter Description
permissionKey Default value is NULL. Contact Agora if you need more information about publishing with a permission key.

Set the Video Resolution, Frame Rate, and Bitrate (setVideoProfile)

public int setVideoProfile(int width, int height, int frameRate, int bitrate)

This method sets the video resolution, frame rate, and bitrate.

Parameter Description
width Width of the video.
height Height of the video.
frameRate Frame rate of the video.
bitrate Bitrate of the video.

Note

See the following two tables for the video configurations in portrait and lanscape modes.

Portrait Mode Video Configurations

Height Width fps kbps Description
160 120 15 65  
120 120 15 50 For iPhone only.
320 180 15 140 For iPhone only.
180 180 15 100 For iPhone only.
240 180 15 120 For iPhone only.
320 240 15 200  
240 240 15 140 For iPhone only.
424 240 15 220 For iPhone only.
640 360 15 400 The default and recommended configuration.
360 360 15 260 For iPhone only.
640 360 30 600  
360 360 30 400  
480 360 15 320  
480 360 30 490  
640 360 15 800  
640 360 24 800  
640 360 24 1000  
640 480 15 500  
480 480 15 400 For iPhone only.
640 480 30 750  
480 480 30 600  
848 480 15 610  
848 480 30 930  
640 480 10 400  
1280 720 15 1130  
1280 720 30 1710  
960 720 15 910  
960 720 30 1380  

Landscape Mode Video Resolutions

Height Width fps kbps Description
120 160 15 65  
120 120 15 50 For iPhone only.
180 320 15 140 For iPhone only.
180 180 15 100 For iPhone only.
180 240 15 120 For iPhone only.
240 320 15 200  
240 240 15 140 For iPhone only.
240 424 15 220 For iPhone only.
360 640 15 400  
360 360 15 260 For iPhone only.
360 640 30 600  
360 360 30 400  
360 480 15 320  
360 480 30 490  
360 640 15 800  
360 640 24 800  
360 640 24 1000  
480 640 15 500  
480 480 15 400 For iPhone only.
480 640 30 750  
480 480 30 600  
480 848 15 610  
480 848 30 930  
480 640 10 400  
720 1280 15 1130  
720 1280 30 1710  
720 960 15 910  
720 960 30 1380  

Add a Stream URL (addStreamUrl)

public void addStreamUrl(String url, boolean isTranscodingEnabled)

This method is used in CDN publishing. It adds the URL to which the host publishes the stream.

Parameter Description
url URL to which the host publishes the stream.
isTranscodingEnabled Whether to enable transcoding or not.

Note

This method only adds one URL each time it is called.

Remove a Stream URL (removeStreamUrl)

public void removeStreamUrl(String url)

This method is used in CDN publishing. It removes the URL to which the host publishes the stream.

Parameter Description
url URL to which the host publishes the stream.

Note

This method only removes one URL each time it is called.

Unpublish (Unpublish)

public void unpublish()

This method stops stream publishing.

Add an Inject Stream URL (addInjectStreamUrl)

public int addInjectStreamUrl(String url, LiveInjectStreamConfig config)

This method adds a voice or video stream into an ongoing broadcast.

Name Description
url URL address to be added into the ongoing live broadcast
config Definition of the added voice or video stream

Definition of LiveInjectStreamConfig

public int width;
public int height;
public int videoGop;
public int videoFramerate;
public int videoBitrate;
public AudioSampleRateType audioSampleRate;
public int audioBitrate;
public int audioChannels;

public LiveInjectStreamConfig() {
    width = 0;
    height = 0;
    videoGop = 30;
    videoFramerate = 15;
    videoBitrate = 400;
    audioSampleRate = AudioSampleRateType.TYPE_44100;
    audioBitrate = 48;
    audioChannels = 1;
}
Name Description
width Width of the stream to be added into the broadcast. The default value is 0; same width as the original stream.
height Height of the stream to be added into the broadcast. The default value is 0; same height as the original stream.
videoGop Video GOP of the stream to be added into the broadcast. The default value is 30.
videoFramerate Video frame rate of the stream to be added into the broadcast. The default value is 15 fps.
videoBitrate Video bitrate of the stream to be added into the broadcast. The defaule value is 400 kbps.
audioSampleRate Audio sample rate of the stream to be added into the broadcast. The default value is 44100.
audioBitrate Audio bitrate of the stream to be added into the broadcast. The default value is 48.
audioChannels Audio channels to be added into the broadcast. The default value is 1.

Remove an Inject Stream URL (removeInjectStreamUrl)

public int removeInjectStreamUrl(String url)

This method removes an injected stream URL.

Name Description
url URL address of the added stream to be removed.

Stream Injected Status Callback (onStreamInjectedStatus)

public void onStreamInjectedStatus(String url, int uid, int status)

This callback indicates the status of the injected stream.

Name Description
url URL address added into the broadcast.
uid User ID.
status

Status of the injected stream:

  • public final static int INJECT_STREAM_STATUS_START_SUCCESS = 0
  • public final static int INJECT_STREAM_STATUS_START_ALREADY_EXIST = 1
  • public final static int INJECT_STREAM_STATUS_START_UNAUTHORIZED = 2
  • public final static int INJECT_STREAM_STATUS_START_TIMEDOUT = 3
  • public final static int INJECT_STREAM_STATUS_START_FAILED = 4
  • public final static int INJECT_STREAM_STATUS_STOP_SUCCESS = 5
  • public final static int INJECT_STREAM_STATUS_STOP_NOT_FOUND = 6
  • public final static int INJECT_STREAM_STATUS_STOP_UNAUTHORIZED = 7
  • public final static int INJECT_STREAM_STATUS_STOP_TIMEDOUT = 8
  • public final static int INJECT_STREAM_STATUS_STOP_FAILED = 9
  • public final static int INJECT_STREAM_STATUS_BROKEN = 10

Switch the Camera (switchCamera)

public void switchCamera()

This method switches between front and back cameras.

LiveEngineHandler Class

This abstract class provides callbacks to the LiveEngine class. It includes the following callbacks:

  • onWarning()
  • onError()
  • onLeaveChannel()
  • onJoinChannel()
  • onRejoinChannel()
  • onReportLiveStats()
  • onConnectionInterrupted()
  • onConnectionLost()
  • onNetworkQuality()

Warning Occurred Callback (onWarning)

public void onWarning(int warningCode)

This callback indicates that some warning occurred during SDK runtime.

Parameter Description
warningCode

Warning codes:

  • WARN_INVALID_VIEW = 8
  • WARN_INIT_VIDEO = 16
  • WARN_PENDING = 20
  • WARN_NO_AVAILABLE_CHANNEL = 103
  • WARN_LOOKUP_CHANNEL_TIMEOUT = 104
  • WARN_LOOKUP_CHANNEL_REJECTED = 105
  • WARN_OPEN_CHANNEL_TIMEOUT = 106
  • WARN_OPEN_CHANNEL_REJECTED = 107
  • WARN_SWITCH_LIVE_VIDEO_TIMEOUT = 111
  • WARN_SET_CLIENT_ROLE_TIMEOUT = 118
  • WARN_SET_CLIENT_ROLE_NOT_AUTHORIZED = 119
  • WARN_AUDIO_MIXING_OPEN_ERROR = 701
  • WARN_ADM_RUNTIME_PLAYOUT_WARNING = 1014
  • WARN_ADM_RUNTIME_RECORDING_WARNING = 1016
  • WARN_ADM_RECORD_AUDIO_SILENCE = 1019
  • WARN_ADM_PLAYOUT_MALFUNCTION = 1020
  • WARN_ADM_RECORD_MALFUNCTION = 1021
  • WARN_APM_HOWLING = 1051

Error Occurred Callback (onError)

public void onError(int errorCode)

This callback indicates that a network or media error occurred during SDK runtime.

Parameter Description
errorCode

Error codes:

  • ERR_OK = 0
  • ERR_FAILED = 1
  • ERR_INVALID_ARGUMENT = 2
  • ERR_NOT_READY = 3
  • ERR_NOT_SUPPORTED = 4
  • ERR_REFUSED = 5
  • ERR_BUFFER_TOO_SMALL = 6
  • ERR_NOT_INITIALIZED = 7
  • ERR_NO_PERMISSION = 9
  • ERR_TIMEDOUT = 10
  • ERR_CANCELED = 11
  • ERR_TOO_OFTEN = 12
  • ERR_BIND_SOCKET = 13
  • ERR_NET_DOWN = 14
  • ERR_NET_NOBUFS = 15
  • ERR_JOIN_CHANNEL_REJECTED = 17
  • ERR_LEAVE_CHANNEL_REJECTED = 18
  • ERR_ALREADY_IN_USE = 19
  • ERR_INVALID_APP_ID = 101
  • ERR_INVALID_CHANNEL_NAME = 102
  • ERR_CHANNEL_KEY_EXPIRED = 109
  • ERR_INVALID_CHANNEL_KEY = 110
  • ERR_CONNECTION_INTERRUPTED = 111
  • ERR_CONNECTION_LOST = 112
  • ERR_NOT_IN_CHANNEL = 113
  • ERR_SIZE_TOO_LARGE = 114
  • ERR_BITRATE_LIMIT = 115
  • ERR_TOO_MANY_DATA_STREAMS = 116
  • ERR_DECRYPTION_FAILED = 120
  • ERR_LOAD_MEDIA_ENGINE = 1001
  • ERR_START_CALL = 1002
  • ERR_START_CAMERA = 1003
  • ERR_START_VIDEO_RENDER = 1004
  • ERR_ADM_GENERAL_ERROR = 1005
  • ERR_ADM_JAVA_RESOURCE = 1006
  • ERR_ADM_SAMPLE_RATE = 1007
  • ERR_ADM_INIT_PLAYOUT = 1008
  • ERR_ADM_START_PLAYOUT = 1009
  • ERR_ADM_STOP_PLAYOUT = 1010
  • ERR_ADM_INIT_RECORDING = 1011
  • ERR_ADM_START_RECORDING = 1012
  • ERR_ADM_STOP_RECORDING = 1013
  • ERR_ADM_RUNTIME_PLAYOUT_ERROR = 1015
  • ERR_ADM_RUNTIME_RECORDING_ERROR = 1017
  • ERR_ADM_RECORD_AUDIO_FAILED = 1018
  • ERR_ADM_INIT_LOOPBACK = 1022
  • ERR_ADM_START_LOOPBACK = 1023
  • ERR_AUDIO_BT_SCO_FAILED = 1030
  • ERR_VDM_CAMERA_NOT_AUTHORIZED = 1501; VDM error codes start from 1500.
  • ERR_VCM_UNKNOWN_ERROR = 1600; VCM error codes start from 1600.
  • ERR_VCM_ENCODER_INIT_ERROR = 1601
  • ERR_VCM_ENCODER_ENCODE_ERROR = 1602
  • ERR_VCM_ENCODER_SET_ERROR = 1603

Leave a Channel Callback (onLeaveChannel)

public void onLeaveChannel()

This callback notifies the application that the user has successfully left the channel.

Join a Channel Callback (onJoinChannel)

public void onJoinChannel(String channel, int uid, int elapsed)

This callback indicates that the user has successfully joined the specified channel with a channel ID and user ID assigned.

Parameter Description
channel Channel name.
uid

User ID:

  • If the uid is specified in the joinChannel method, it returns the specified ID.
  • Otherwise, it returns an ID that is automatically assigned by the Agora server.
elapsed
  • Time elapsed (ms) from calling joinChannel() until this event occurs.

Rejoin a Channel Callback (onRejoinChannel)

public void onRejoinChannel(String channel, int uid, int elapsed)

When the client loses connection with the server due to network problems, the SDK automatically tries to reconnect. This callback is triggered when the SDK reconnects to the client.

Parameter Description
channel Channel name.
uid User ID.
elapsed Time elapsed (ms) from calling joinChannel() until this event occurs.

Live Statistics Callback (onReportLiveStats)

public void onReportLiveStats(LiveEngine.LiveStats stats)

This callback returns the statistics of the live broadcast.

Parameter Description
stats
  • duration
  • txBytes
  • rxBytes
  • txAudioKBitrate
  • rxAudioKBitrate
  • txVideoKBitrate
  • rxVideoKBitrate
  • userCount
  • cpuAppUsage
  • cpuTotalUsage
Property Name Description
duration Call duration (s)
txBytes Total number of bytes transmitted
rxBytes Total number of bytes received
txAudioKBitrate Bitrate of the transmitted audio at the time
rxAudioKBitrate Bitrate of the received audio at the time
txVideoKBitrate Bitrate of the transmitted video at the time
rxVideoKBitrate Bitrate of the received video at the time
userCount Total user count of the live broadcast
cpuAppUsage CPU usage contributed by the app (%)
cpuTotalUsage Total CPU usage (%)

Connection Interrupted Callback (onConnectionInterrupted)

public void onConnectionInterrupted()

This callback indicates that the SDK has lost connection with the server. It is triggered immediately when the connection is lost. In the meantime the SDK automatically reconnects to the server until the App calls leaveChannel().

Connection Lost Callback (onConnectionLost)

public void onConnectionLost()

This callback indicates that the SDK has disconnected from the network. It is triggered when the connection is lost for more than the default retry time period (10 s).

Network Quality Callback (onNetworkQuality)

public void onNetworkQuality(int uid, int txQuality, int rxQuality)

This callback is triggered regularly to update the application on the current network quality in a communication or live broadcast channel.

Parameter Description
uid User ID.
txQuality

Uplink network quality of the user:

  • 0: QUALITY_UNKNOWN
  • 1: QUALITY_EXCELLENT
  • 2: QUALITY_GOOD
  • 3: QUALITY_POOR
  • 4: QUALITY_BAD
  • 5: QUALITY_VBAD
  • 6: QUALITY_DOWN
rxQuality

Downlink network quality of the user:

  • 0: QUALITY_UNKNOWN
  • 1: QUALITY_EXCELLENT
  • 2: QUALITY_GOOD
  • 3: QUALITY_POOR
  • 4: QUALITY_BAD
  • 5: QUALITY_VBAD
  • 6: QUALITY_DOWN

LiveSubscriberHandler Class

This abstract class provides callbacks to the audience, informing the audience of occurred events.

  • publishedByHost()
  • unpublishedByHost()
  • onStreamTypeChanged()
  • onFirstRemoteVideoDecoded()
  • onVideoSizeChanged()

Host Published Callback (publishedByHost)

public void publishedByHost(int uid, int streamType)

This callback indicates that a host has started publishing a stream.

Parameter Description
uid User ID of the host.
streamType

Stream type:

  • High-resolution video stream at high-frame rate
  • Low-resolution video stream at low-frame rate

Host Unpublished Callback (unpublishedByHost)

public void unpublishedByHost(int uid)

This method indicates that a host has unpublished a stream.

Parameter Description
uid User ID of the host.

Stream Type Changed Callback (onStreamTypeChanged)

public void onStreamTypeChanged(int streamType, int uid)

This callback indicates that the stream type has changed.

Parameter Description
streamType

Stream type:

  • High-resolution video stream at high-frame rate
  • Low-resolution video stream at low-frame rate
uid User ID.

First Remote Video Decoded Callback (onFirstRemoteVideoDecoded)

public void onFirstRemoteVideoDecoded(int uid, int width, int height, int elapsed)

This callback indicates that the first remote video frame has been decoded.

Parameter Description
uid User ID.
width Width (pixels) of the first video frame.
height Height (pixels) of the first video frame.
elapsed Time elapsed (ms) from the beginning of the session.

Video Size Changed Callback (onVideoSizeChanged)

public void onVideoSizeChanged(int uid, int width, int height, int rotation)

This callback indicates that the size of the video frame has changed.

Parameter Description
uid User ID.
width Width (pixels) of the video frame.
height Height (pixels) of the video frame.
rotation New rotational angle of the video. Can be 0, 90, 180, or 270. It is set as 0 by default.

LivePublisherHandler Class

This abstract class provides callbacks to the host, informing the host of occurred events. It includes:

  • onstreamUrlPublished()
  • onPublishStreamUrlFailed()
  • onStreamUrlUnpublished()
  • onPublisherTranscodingUpdated()

Publishing Succeeded Callback (onstreamUrlPublished)

public void onPublishSuccess(String url)

This callback notifies the host that publishing to a specific URL has succeeded.

Parameter Description
url URL to which the host publishes the stream.

Publishing Failed Callback (onPublishStreamUrlFailed)

public void onPublishStreamUrlFailed(String url, int errorCode)

This callback notifies the publisher that publishing to a specific URL has failed.

Parameter Description
url URL to which the host publishes the stream.
errorCode

Error code:

  • ERR_OK = 0
  • ERR_FAILED = 1
  • ERR_INVALID_ARGUMENT = 2
  • ERR_NOT_READY = 3
  • ERR_NOT_SUPPORTED = 4
  • ERR_REFUSED = 5
  • ERR_BUFFER_TOO_SMALL = 6
  • ERR_NOT_INITIALIZED = 7
  • ERR_NO_PERMISSION = 9
  • ERR_TIMEDOUT = 10
  • ERR_CANCELED = 11
  • ERR_TOO_OFTEN = 12
  • ERR_BIND_SOCKET = 13
  • ERR_NET_DOWN = 14
  • ERR_NET_NOBUFS = 15
  • ERR_JOIN_CHANNEL_REJECTED = 17
  • ERR_LEAVE_CHANNEL_REJECTED = 18
  • ERR_ALREADY_IN_USE = 19
  • ERR_INVALID_APP_ID = 101
  • ERR_INVALID_CHANNEL_NAME = 102
  • ERR_CHANNEL_KEY_EXPIRED = 109
  • ERR_INVALID_CHANNEL_KEY = 110
  • ERR_CONNECTION_INTERRUPTED = 111
  • ERR_CONNECTION_LOST = 112
  • ERR_NOT_IN_CHANNEL = 113
  • ERR_SIZE_TOO_LARGE = 114
  • ERR_BITRATE_LIMIT = 115
  • ERR_TOO_MANY_DATA_STREAMS = 116
  • ERR_DECRYPTION_FAILED = 120
  • ERR_LOAD_MEDIA_ENGINE = 1001
  • ERR_START_CALL = 1002
  • ERR_START_CAMERA = 1003
  • ERR_START_VIDEO_RENDER = 1004
  • ERR_ADM_GENERAL_ERROR = 1005
  • ERR_ADM_JAVA_RESOURCE = 1006
  • ERR_ADM_SAMPLE_RATE = 1007
  • ERR_ADM_INIT_PLAYOUT = 1008
  • ERR_ADM_START_PLAYOUT = 1009
  • ERR_ADM_STOP_PLAYOUT = 1010
  • ERR_ADM_INIT_RECORDING = 1011
  • ERR_ADM_START_RECORDING = 1012
  • ERR_ADM_STOP_RECORDING = 1013
  • ERR_ADM_RUNTIME_PLAYOUT_ERROR = 1015
  • ERR_ADM_RUNTIME_RECORDING_ERROR = 1017
  • ERR_ADM_RECORD_AUDIO_FAILED = 1018
  • ERR_ADM_INIT_LOOPBACK = 1022
  • ERR_ADM_START_LOOPBACK = 1023
  • ERR_AUDIO_BT_SCO_FAILED = 1030
  • ERR_VDM_CAMERA_NOT_AUTHORIZED = 1501; Note that the VDM error code starts off from 1500.
  • ERR_VCM_UNKNOWN_ERROR = 1600; Note that the VCM error code starts off from 1600.
  • ERR_VCM_ENCODER_INIT_ERROR = 1601
  • ERR_VCM_ENCODER_ENCODE_ERROR = 1602
  • ERR_VCM_ENCODER_SET_ERROR = 1603

Unpublished Callback (onStreamUrlUnpublished)

public void onUnpublished(String url)

This callback notifies the publisher that the unpublish action has succeeded.

Parameter Description
url URL to which the host publishes the stream.

Publisher Transcoding was Updated (onPublisherTranscodingUpdated)

public void onPublisherTranscodingUpdated(LivePublisher publisher)

This callback notifies the LiveTranscoding class that the transcoding has been successfully updated.

Parameter Description
publisher The LivePublisher class manages actions related to live publishing

LiveChannelConfig Class

The LiveChannelConfig class is a public static class. It is used to enable or disable the video of a live broadcast. It includes the LiveChannelConfig() method.

public boolean videoEnabled;
Parameter Description
videoEnabled
  • TRUE: Enable video
  • FALSE: Disable video

Construct a LiveChannelConfig Object (LiveChannelConfig)

public LiveChannelConfig()

This method constructs a LiveChannelConfig object.

LiveStats Class

The LiveStats class is a public static class. It provides a callback, which returns the statistics of the live broadcast.

public int duration;
public int txBytes;
public int txAudioKBitrate;
public int rxAudioKBitrate;
public int txVideoKBitrate;
public int rxVideoKBitrate;
public int userCount;
public double cpuAppUsage;
public double cpuTotalUsage;
public LiveStats(IRtcEngineEventHandler.RtcStats rtcStats)
Property Name Description
duration Call duration (s)
txBytes Total number of bytes transmitted
rxBytes Total number of bytes received
txAudioKBitrate Bitrate of the transmitted audio at the time
rxAudioKBitrate Bitrate of the received audio at the time
txVideoKBitrate Bitrate of the transmitted video at the time
rxVideoKBitrate Bitrate of the received video at the time
userCount Total user count of the live broadcast
cpuAppUsage CPU usage contributed by the app (%)
cpuTotalUsage Total CPU usage (%)

LiveTranscoding Class

This class manages CDN transcoding. It includes the following methods and classes:

  • LiveTranscoding()
  • getUsers()
  • setUsers()
  • addUser(TranscodingUser user)
  • addUser(int index, TranscodingUser user)
  • setUser()
  • getRed()
  • getGreen()
  • getBlue()
  • setRed()
  • setGreen()
  • setBlue()
  • setBackgroundColor(int color)
  • setBackgroundColor(int red, int green, int blue)
  • TranscodingUser
  • AudioChannelType Enum Class
  • AudioSampleRateType Enum Class
  • videoCodecProfileType Enum Class
public int width;
public int height;
public int videoBitrate;
public int videoFramerate;
public boolean lowLatency;
public int videoGop;
public int audioSampleRate;
public int audioBitrate;
public int audioChannel;
public int videoCodecProfile;
public int userCount;
public String userConfigExtraInfo;
public int backgroundColor;
Parameter Description
width Width of the canvas.
height Height of the canvas.
videoBitrate Bitrate of the output video stream set for the CDN live broadcast. Default value is 400 kbps.
videoFramerate Frame rate of the output video stream set for the bypass live broadcast. Default value is 15 fps.
lowLatency
  • TRUE: Low latency with unassured quality.
  • FALSE: (default)High latency with assured quality.
videoGop Interval between the I frames. Default value is 2 (s).
audioSampleRate

Audio sample rates:

  • AUDIO_SAMPLE_RATE_TYPE_32000
  • AUDIO_SAMPLE_RATE_TYPE_44100
  • AUDIO_SAMPLE_RATE_TYPE_48000 (Default)
audioBitrate Bitrate of the audio output stream.
audioChannel

Agora’s self-defined audio channel types:

  • AgoraAudioChannelTypeMono = 1,
  • AgoraAudioChannelTypeStereo = 2,
videoCodecProfile

Self-defined codec profiles:

  • AgoraVideoCodecProfileTypeBaseLine = 66, lowest video codec rate
  • AgoraVideoCodecProfileTypeMain = 77,
  • AgoraVideoCodecProfileTypeHigh = 100, highest video codec rate (default)
userCount Number of the users involved in transcoding.
userConfigExtraInfo Reserved: Extra user-defined information to send to the CDN client.
backgroundColor Background color.

Construct a LiveTranscoding Object (LiveTranscoding)

public LiveTranscoding()

This method constructs a LiveTranscoding object.

Get the Users (getUsers)

public ArrayList<TranscodingUser> getUsers()

This method gets all the users involved in transcoding.

Set the Users in Batches (setUsers)

public void setUsers(ArrayList<TranscodingUser> users)

This method sets all the users involved in transcoding.

Parameter Description
users All the users involved in transcoding: ArrayList<TranscodingUser>

Add a User to a Queue (addUser)

public void addUser(int index, TranscodingUser user)

This method adds a user and sets his/her position in the queue.

Parameter Description
index Index of the user to add.
user Transcoding user object.

Add a User (addUser)

public void addUser(TranscodingUser user)

This method adds a user to the existing users.

Parameter Description
user Transcoding user object.

Get the Red Component (getRed)

public int getRed()

This method gets the red component from the background color.

Get the Green Component (getGreen)

public int getGreen()

This method gets the green component from the background color.

Get the Blue Component (getBlue)

public int getBlue()

This method gets the blue component from the background color.

Set the Red Component (setRed)

public void setRed(int red)

This method sets the red component of the background color while keeping the other two components unchanged.

Set the Green Component (setGreen)

public void setGreen(int green)

This method sets the green component of the background color while keeping the other two components unchanged.

Set the Blue Component (setBlue)

public void setBlue(int blue)

This method sets the blue component of the background color while keeping the other two components unchanged.

Set the Background Color (setBackgroundColor)

public void setBackgroundColor(int color)

This method sets the background color to either red, green, or blue.

Parameter Description
color Desired background color

Set the Background RGB (setBackgroundColor)

public void setBackgroundColor(int red, int green, int blue)

This method sets the background color to different variations of red, green, or blue.

Parameter Description
red Red color
green Green color
blue Blue color

Transcoding User Class

This class is a public static class within the LiveTranscoding class. It defines the user-specific transcoding settings for voice and video.

public int uid;
public int x;
public int y;
public int width;
public int height;
public int zOrder;
public float alpha;
public int renderMode;
Parameter Description
uid User ID of the CDN publisher.
x Horizontal position of the top left corner of the video frame
y Vertical position of the top left corner of the video frame
width Width of the video frame
height Height of the video frame
zOrder Layer of the video frame
alpha Transparency of the video frame
renderMode

Render mode of the video frame.

  • RENDER_MODE_HIDDEN: 1
  • RENDER_MODE_FIT: 2
  • RENDER_MODE_ADAPTIVE: 3

AudioChannelType Enum Class

MONO(1),
STEREO(2);

This public class is within the LiveTranscoding class. It sets the audio channel types.

Parameter Description
MONO mono
STEREO stereo

Get the Audio Channel Type(getValue)

public static int getValue(AudioChannelType type)

This method gets the audio channel type. It returns the corresponding enumeration value.

AudioSampleRateType Enum Class

TYPE_32000(32000),
TYPE_44100(44100),
TYPE_48000(48000);

This public class is in the LiveTranscoding class. It sets the audio sample rates.

Parameter Description
TYPE_32000(32000) 32000
TYPE_44100(44100) 44100
TYPE_48000(48000) 48000

Get the Audio Sample Rate(getValue)

public static int getValue(AudioSampleRateType type)

This method gets the audio sample rate. It returns the corresponding enumeration value.

VideoCodecProfileType Enum Class

BASELINE(66),
MAIN(77),
HIGH(100);

This public class is in the LiveTranscoding class. It sets the video codec profiles.

Parameter Description
BASELINE 66
MAIN 77
HIGH 100

Get the Video Codec Profile(getValue)

public static int getValue(VideoCodecProfileType type)

This method gets the video codec profile. It returns the corresponding enumeration value.