All Products
Search

This Product

    ApsaraVideo Live:Handle errors, exceptions, and special cases

    Document Center

    ApsaraVideo Live:Handle errors, exceptions, and special cases

    Last Updated:Feb 29, 2024

    This topic describes the exceptions and special cases that you may encounter when you use Push SDK for Android. This topic also describes how to handle such exceptions and special cases.

    Handle errors and exceptions

    Push SDK provides the following types of callbacks.

    Callback type

    Class

    Stream ingest callbacks

    AlivcLivePushInfoListener

    Network callbacks

    AlivcLivePushNetworkListener

    Error callbacks

    AlivcLivePushErrorListener

    Background music callbacks

    AlivcLivePushBGMListener

    Stream ingest callbacks

    Stream ingest callbacks are used to notify the app of the SDK status, including the callback for preview start, the callback for rendering the first frame, the callback for sending the first frame of an audio or video stream, the callback for stream ingest start, and the callback for stream ingest stop.

    • onPushStarted and onFirstFramePushed: indicates that stream ingest is successful.

    • onPushStarted: indicates that the server is connected.

    • onFirstFramePushed: indicates that the first frame of the audio or video stream is sent.

    Network callbacks

    Network callbacks are used to notify the app of the network status and link status regarding the SDK, some of which must be configured for the app.

    Basic mode: basic live streaming scenarios

    • onConnectFail: indicates that stream ingest failed. We recommend that you check whether the ingest URL is valid (for example, whether the URL contains invalid characters), whether there is an authentication issue, whether the upper limit on the number of concurrently ingested streams is exceeded, and whether the stream is in the blacklist. Make sure that the ingest URL is valid and available before you try to ingest the stream. The relevant error codes include 0x30020901 to 0x30020905 and 0x30010900 to 0x30010901.

    • onConnectionLost: indicates that the network is disconnected. After the network is disconnected, the SDK automatically attempts to reconnect to the network and fires the onReconnectStart callback. If the maximum allowed number of reconnection attempts (config.connectRetryCount) is reached but the network is still not recovered, the SDK fires the onReconnectError callback.

    • onNetworkPoor: indicates that the network speed is slow. If you receive this callback, the current network may not be able to fully support your ingested stream, even though the stream is not interrupted and can keep running. In this case, you can handle your own business logic, for example, notify the user on the user interface (UI) of the app.

    • onNetworkRecovery: indicates that the network is recovered.

    • onReconnectError: indicates that the network reconnection failed. We recommend that you check the current network and re-ingest the stream when the network recovers.

    • onSendDataTimeout: indicates that a timeout occurred when the data was sent. We recommend that you check the current network and re-ingest the stream when the network recovers.

    • onPushURLAuthenticationOverdue: indicates that the signed ingest URL is about to expire. If URL signing is enabled, the ingest URL contains the auth_key field, which Alibaba Cloud regularly verifies. This callback is fired 1 minute before the ingest URL expires. After the callback is returned, you must specify a new ingest URL to ensure that stream ingest is not interrupted when the original URL expires.

    Interactive mode: co-streaming scenarios

    • onConnectFail: indicates that stream ingest failed. We recommend that you check whether the token in the ingest URL for co-streaming is valid and whether the network is normal. Make sure that the ingest URL is valid and the network is normal before you try to ingest the stream.

    • onConnectionStatusChange: indicates that the connection status changes. In the callback, the connection status is returned. For example, the network is disconnected, the network connection is being established, the network is connected, and the network connection fails. If AliLiveConnectionStatusFailed is returned in the callback, the connection cannot be recovered. In this case, check the current network and re-ingest the stream after the network recovers. We recommend that you configure this callback in interactive mode to obtain the connection status.

    • onPushURLTokenWillExpire: indicates that the token in the ingest URL for co-streaming is about to expire. This callback is fired 30 seconds before the token expires. After receiving the callback, you must promptly request an ingest URL for co-streaming that contains a new token from the business server and call refreshPushURLToken to pass in the new token to the SDK.

    • onPushURLTokenExpired: indicates that the token in the ingest URL for co-streaming has expired. If this callback is fired, you need to use an ingest URL that contains a new token to re-ingest the stream.

    • onPusherNetworkQualityChanged: indicates that the upstream network quality changes. The callback can be used to rate the upstream network quality.

    • onConnectionLost: indicates that the network is disconnected. In interactive mode, if the onConnectionLost callback is fired, the connection cannot be recovered. We recommend that you check the current network and re-ingest the stream after the network recovers.

    Error callbacks

    • onSystemError: indicates a system device exception. You must destroy the engine and try again.

    • onSDKError: indicates an SDK error. You need to perform operations based on the error code.

      • If the error code is 805438211, the device performance is poor and the frame rate for encoding and rendering is low. You need to prompt the streamer and stop time-consuming business logic, such as advanced retouching and animation, at the app layer.

      • You need to pay special attention to the callbacks that are related to microphone and camera permissions. The 268455940 error code indicates that the app requires the permissions on the microphone. The 268455939 error code indicates that the app requires the permissions on the camera.

      • For other error codes, no additional operations are required. All error codes are recorded in logs.

    Background music callbacks

    • onOpenFailed: indicates that the background music failed to start. Check whether the music file is valid and whether the path of the music file that is specified in the relevant method is correct. You can call the startBGMAsync method to play the music again.

    • onDownloadTimeout: indicates a timeout during the playback of the background music. This usually occurs when the background music comes from a URL. In this case, check the network status and call the startBGMAsync method to play the music again.

    Handle special cases

    Network disconnection

    • Short-period network disconnection and network switchover: The SDK attempts to reconnect to the network when a network disconnection or a network switchover occurs. You can use the AlivcLivePushConfig class to set the reconnection timeout period and the maximum number of reconnection attempts allowed. After the SDK reconnects to the network, stream ingest is resumed. If you use ApsaraVideo Player, we recommend that you perform a reconnection operation 5 seconds after you receive a timeout notification.

    • Long-period network disconnection: The SDK fails to reconnect to the network if a reconnection request times out or the number of reconnection attempts exceeds the upper limit. In this case, the onReconnectError callback is fired. After the network connection is recovered, call reconnectAsyn to reconnect to the network. You must also reconnect the SDK to ApsaraVideo Player.

      • We recommend that you externally monitor the network connection.

      • Use the server to handle communication failures between the streamer side and player. For example, when the streamer is disconnected from the server, the server receives a callback of stream ingest interruption from Alibaba Cloud CDN. The server pushes the callback message to the player. Then, the player handles the stream ingest interruption. The server uses the same procedure to resume stream ingest.

      • Stop the playback and then restart ApsaraVideo Player to reconnect the player to the server. Call stop to stop the player and then call prepareAndPlay to restart the player. 

        mPlayer.stop();
mPlayer.prepareAndPlay(mUrl);
        Note

        For more information about ApsaraVideo Player, see Advanced features.

    Switchover to the background or screen lock

    • When the app is switched to the background or the screen is locked, you can call the pause() or resume() method of the AlivcLivePusher class to pause or resume stream ingest.

    • For non-system audio and video calls, the SDK continues recording and ingesting the audio stream. You can call the mAlivcLivePusher.setMute() method to specify whether to enable audio recording when the app is switched to the background or your screen is locked. You can set setMute to true or false.

    Bitrate settings

    The SDK supports the dynamic bitrate feature. You can use the AlivcLivePushConfig class to change the default bitrate. Different services require different video quality. The resolution, smoothness, and quality of an output video vary based on the bitrate of the ingested stream.

    • Video quality: A higher bitrate of the ingested stream indicates higher video quality. We recommend that you set a higher bitrate to ensure higher video quality.

    • Video smoothness: A higher bitrate of the ingested stream indicates that more network bandwidth is required. A higher bitrate in poor network conditions may affect the smoothness of video playback.