This topic describes how to use AliLive SDK for Android and the classes and methods in the SDK. This topic also provides examples on how to use the features provided by AliLive SDK for Android.

Note For more information about how to ingest streams on mobile devices, see Stream ingest, stream pulling, and streaming.

Features

  • Supports stream ingest over Real-Time Messaging Protocol (RTMP).
  • Adopts H.264 for video encoding and Advanced Audio Coding (AAC) for audio encoding.
  • Supports custom configurations for features such as bitrate control, resolution, and display mode.
  • Supports various camera operations.
  • Supports real-time retouching and allows you to adjust retouching effects.
  • Allows you to add animated stickers as animated watermarks and remove animated stickers.
  • Supports live stream recording.
  • Supports external audio and video input in different formats such as YUV and pulse-code modulation (PCM).
  • Supports multi-channel mixed streams.
  • Supports ingest of audio-only and video-only streams and stream ingest in the background.
  • Supports background music and allows you to manage background music.
  • Supports the capture of snapshots from streams.
  • Supports automatic reconnection and error handling.
  • Supports the audio 3A algorithm.

Classes for AliLive SDK

Class Description
AlivcLivePushConfig The class for stream ingest settings.
AlivcLivePusher The class for features.
AlivcLivePusherErrorListener The class for error callbacks.
AlivcLivePusherNetworkListener The class for network callbacks.
AlivcLivePusherInfoListener The class for stream ingest callbacks.
AlivcLivePusherBGMListener The class for background music callbacks.
AlivcLivePushCustomFilter The class for custom filter callbacks.
AlivcLivePushCustomDetect The class for custom face detection callbacks.
AlivcSnapshotListener The class for snapshot callbacks.

Limits

Take note of the following limits before you use Push SDK for Android:
  • You must configure screen orientation before stream ingest. You cannot rotate the screen during a live stream.
  • You must disable auto screen rotation for stream ingest in landscape mode.
  • In hardware encoding mode, the value of the output resolution must be an integer multiple of 16 to be compatible with the encoder. For example, if you set resolution to 540p, the output resolution is 544 × 960. You must scale the screen size of the player based on the output resolution to prevent black bars.

Procedure

The following table describes how to use AliLive SDK for Android.

Step Description References

1. Configure stream ingest parameters

Complete the stream ingest configurations, such as the basic parameters, bitrate control mode, adaptive resolution feature, and retouching feature.

Configure stream ingest parameters

2. Use AliLive SDK for Android to ingest streams

After you initialize AliLive SDK for Android, register stream ingest callbacks, and create a preview view, you can start to ingest streams. You can manage streams, configure background music, perform operations on the camera, ingest external audio sources, and add animated stickers based on your business requirements.

Notice
  • Before you start to ingest streams, you must initialize the SDK and create a preview view.
  • ApsaraVideo Live does not allow you to ingest multiple streams to a URL at the same time. If you attempt to ingest multiple streams at the same time, the second stream is rejected.

Use AliLive SDK for Android to ingest streams

3. Optional. Configure stream ingest for screen recordings

If you want to stream screen recordings, you can configure stream ingest for screen recordings.

Configure stream ingest for screen recordings

Configure stream ingest parameters

You can configure stream ingest parameters by using the AlivcLivePushConfig class. Each parameter has a default value. You can change the values of parameters based on your business requirements. For more information about the default value and valid values for each parameter, see Aliyun Live Pusher API Reference Manual for Android Platforms V4.4.1 or comments.

Note To modify these parameters in real time during stream ingest, refer to the parameters and methods provided by the AlivcLivePusher class.
  1. Complete basic stream ingest configurations.

    All parameters for basic stream ingest configurations have default values. We recommend that you use the default values. The following code provides an example:

    AlivcLivePushConfig mAlivcLivePushConfig = new
    AlivcLivePushConfig(); // The class that is used to configure stream ingest settings.
    mAlivcLivePushConfig.setResolution(AlivcResolutionEnum.RESOLUTION_540P); // By default, the resolution is set to 540p. The maximum resolution is 720p.
    mAlivcLivePushConfig.setFps(AlivcFpsEnum.FPS_20); // We recommend that you set the frame rate to 20 frames per second (FPS).
    mAlivcLivePushConfig.setEnableBitrateControl(true); // Enable the adaptive bitrate feature. The default value is true.
    mAlivcLivePushConfig.setPreviewOrientation(AlivcPreviewOrientationEnum.ORIENTATION_PORTRAIT);
    // The default screen orientation is portrait. You can change the orientation to landscape left or landscape right.
    mAlivcLivePushConfig.setAudioProfile(AlivcAudioAACProfileEnum.AlivcAudioAACProfileEnum.AAC_LC); // Configure the audio encoding format.
    Notice
    • We recommend that you set the resolution to 540p based on the performance of mobile phones and network bandwidth requirements. In most cases, mainstream apps for live streaming use 540p.
    • When the adaptive bitrate feature is disabled, the bitrate is fixed at the initial value and is not automatically adjusted between the specified maximum bitrate and the minimum bitrate. If you disable the adaptive bitrate feature, stuttering may occur when the network is unstable. Proceed with caution before you disable the adaptive bitrate feature.
  2. Specify a bitrate control mode.

    You can configure the AlivcQualityModeEnum parameter to specify a bitrate control mode. AliLive SDK for Android provides the following bitrate control modes. Specify the value of each parameter based on your business requirements.

    Bitrate control mode Description Sample code
    QM_RESOLUTION_FIRST The quality-first mode. AliLive SDK for Android configures bitrate parameters to prioritize the quality of video streams.
    mAlivcLivePug.setQualityMode(AshConfilivcQualityModeEnum.QM_RESOLUTION_FIRST);// Use the quality-first mode.
    QM_FLUENCY_FIRST The smoothness-first mode. AliLive SDK for Android configures bitrate parameters to prioritize the smoothness of video streams.
    mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_FLUENCY_FIRST); // Use the smoothness-first mode.
    QM_CUSTOM The custom mode. AliLive SDK for Android configures bitrate parameters based on your custom settings. If you use the custom mode, you can select quality-first or smoothness-first based on your business requirements. You must configure the initialVideoBitrate, minVideoBitrate, and targetVideoBitrate parameters to set the initial, minimum, and specified bitrates.
    • initialVideoBitrate: the initial bitrate when a live stream starts.
    • minVideoBitrate: In poor network conditions, the bitrate is gradually reduced to the minimum bitrate to prevent stuttering.
    • targetVideoBitrate: In good network conditions, the bitrate is gradually increased to the specified bitrate to improve the quality of the video stream.
    mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_CUSTOM);
    mAlivcLivePushConfig.setTargetVideoBitrate(1000); // The specified bitrate is 1,000 Kbit/s.
    mAlivcLivePushConfig.setMinVideoBitrate(300); // The minimum bitrate is 300 Kbit/s.
    mAlivcLivePushConfig.setInitialVideoBitrate(800); // The initial bitrate is 800 Kbit/s.
    Note
    • If you use the quality-first or smoothness-first mode, you do not need to configure the initialVideoBitrate, minVideoBitrate, and targetVideoBitrate parameters. Push SDK automatically ensures the quality or smoothness of video streams when the network is unstable.
    • If you use the custom mode, configure the bitrate parameters based on the recommended settings. The following table shows the recommended settings.
    Table 1. Recommended settings for custom bitrate (quality first)
    Resolution initialVideoBitrate minVideoBitrate targetVideoBitrate
    360P 600 300 1000
    480P 800 300 1200
    540P 1000 600 1400
    720P 1500 600 2000
    1080P 1800 1200 2500
    Table 2. Recommended settings for custom bitrate (smoothness first)
    Resolution initialVideoBitrate minVideoBitrate targetVideoBitrate
    360P 400 200 600
    480P 600 300 800
    540P 800 300 1000
    720P 1000 300 1200
    1080P 1500 1200 2200
  3. Configure the adaptive resolution feature.

    The adaptive resolution feature is used to dynamically adjust the resolution of a stream. When the adaptive resolution feature is enabled, the resolution is automatically reduced to ensure the smoothness and quality of video streams in poor network conditions. The following sample code provides an example on how to enable the adaptive resolution feature:

    mAlivcLivePushConfig.setEnableAutoResolution(true); // Enable the adaptive resolution feature. The default value is false.
    Notice
    • The adaptive resolution feature is not supported by all players. If you need to use this feature, we recommend that you use ApsaraVideo Player.
    • The adaptive resolution feature takes effect only when you use the quality-first or smoothness-first mode by configuring the AlivcQualityModeEnum parameter. This feature is unavailable if you use the custom mode.
  4. Configure the retouching feature.
    To use the retouching feature in AliLive SDK, you must import a retouching library and configure callbacks.
    1. Use Android Archive (AAR) files to import a retouching library. Add the following code to the build.gradle file of the project:
      com.aliyun.maliang.android:queen:1.7.0-official-lite
      The following table describes the modules provided in the demo that you can integrate.
      File or folder Description
      beauty The abstract class of retouching.
      beautyui The UI widgets of retouching.
      queenbeauty The retouching components of Queen SDK.
      Imageutil The Imageutil public class that is used for retouching.
    2. Configure callbacks for facial recognition and retouching.

      If you need to access a third-party retouching library, you can configure the setCustomDetect and setCustomFilter callbacks in the code.

      • The data values returned by the customDetectProcess callback that includes the long data, int width, int height, int rotation, int format, and long extra parameters are used as the pointers to collect data. The third-party retouching library can identify or process the returned data.
      • The value of the inputTexture parameter returned by the customFilterProcess callback that includes the int inputTexture, inttextureWidth, int textureHeight, and long extra parameters is the image texture that can be processed by the third-party retouching library. If you need to return a processed texture, the ID of the processed texture is returned. Otherwise, the ID of the original texture is returned.

      The following sample code provides an example on how to configure callbacks:

      /**
      * The callbacks that are used for facial recognition.
      **/
      mAlivcLivePusher.setCustomDetect(new AlivcLivePushCustomDetect() {
          @Override
          public void customDetectCreate() {
              Log.d(TAG, "customDetectCreate start");
              initBeautyManager();
              Log.d(TAG, "customDetectCreate end");
          }
      
          @Override
          public long customDetectProcess(long data, int width, int height, int rotation, int format, long extra) {
              Log.d(TAG, "customDetectProcess start: data ptr:" + data + ",width:" + width + ",height:" + height + "," + format + "," + rotation);
      
              if (mBeautyManager != null) {
                  mBeautyManager.onDrawFrame(data, BeautyImageFormat.kNV21, width, height, 0, mCameraId);
                  Log.d(TAG, "keria: " + mCameraId);
              }
              Log.d(TAG, "customDetectProcess end");
      
              return 0;
          }
      
          @Override
          public void customDetectDestroy() {
              Log.d(TAG, "customDetectDestroy start");
              destroyBeautyManager();
              Log.d(TAG, "customDetectDestroy end");
          }
      });
      
      /**
      * The callbacks that are used for retouching.
      **/
      
      mAlivcLivePusher.setCustomFilter(new AlivcLivePushCustomFilter() {
          @Override
          public void customFilterCreate() {
              Log.d(TAG, "customFilterCreate start");
      
              initBeautyManager();
      
              Log.d(TAG, "customFilterCreate end");
          }
      
          @Override
          public void customFilterUpdateParam(float fSkinSmooth, float fWhiten, float fWholeFacePink, float fThinFaceHorizontal, float fCheekPink, float fShortenFaceVertical, float fBigEye) {
      
          }
      
          @Override
          public void customFilterSwitch(boolean on) {
      
          }
      
          @Override
          public int customFilterProcess(int inputTexture, int textureWidth, int textureHeight, long extra) {
              Log.d(TAG, "customFilterProcess start: textureId" + inputTexture + ",width:" + textureWidth + ",height:" + textureHeight);
      
              int ret = mBeautyManager != null ? mBeautyManager.onTextureInput(inputTexture, textureWidth, textureHeight) : inputTexture;
      
              Log.d(TAG, "customFilterProcess end, textureId:" + ret);
              Log.d(TAG, "keria1: " + mCameraId);
      
              return ret;
          }
      
          @Override
          public void customFilterDestroy() {
              destroyBeautyManager();
          }
      });
  5. Specify an image for background stream ingest.
    AliLive SDK for Android allows you to ingest images when your app is switched to the background or the bitrate is low. This improves user experience. When your app is switched to the background, video stream ingest is paused. In this case, you can ingest only images and audio streams. For example, you can ingest an image in which a message is displayed to notify the audience that the streamer left. The following sample code provides an example on how to specify an image for stream ingest when your app is switched to the background:
    mAlivcLivePushConfig.setPausePushImage("The path of the specified image in the PNG format for stream ingest"); // Specify the image for stream ingest when your app is switched to the background.

    You can specify a static image for stream ingest in poor network conditions. If the bitrate is low, the image that you specify is ingested to prevent stuttering. The following sample code provides an example on how to specify an image for stream ingest in poor network conditions:

    mAlivcLivePushConfig.setNetworkPoorPushImage("The path of the specified image that is ingested in poor network conditions"); // Specify the image for stream ingest in poor network conditions.
  6. Configure watermarks.
    AliLive SDK for Android allows you to add one or more watermarks to an image. The image must be in the PNG format. The following sample code provides an example on how to add watermarks:
    mAlivcLivePushConfig.addWaterMark(waterPath,0.1,0.2,0.3); // Add watermarks.
    Note
    • The values of the x, y, and width parameters are relative. For example, a value of 0.1 for the x parameter indicates that the left edge of the watermark is displayed at the 10% position on the x-axis of the stream image. Therefore, if the stream resolution is 540 × 960, the value of the x parameter is 54.
    • The height of the watermark is scaled based on the width and height of the image to which the watermark is added and the input width of the watermark.
    • If you want to add a text watermark, you can convert the text into an image and call the addWaterMark method to add the image as a watermark.
  7. Specify a preview mode.
    AliLive SDK for Android supports the following preview modes. The preview mode does not affect stream ingest.
    • AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_SCALE_FILL: In this mode, the video fills the entire preview view. If the aspect ratio of the video is not the same as the aspect ratio of the preview view, the preview image is deformed.
    • AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT: In this mode, the initial aspect ratio of the video is used during the preview. If the aspect ratio of the video is not the same as the aspect ratio of the preview view, black bars appear on the preview view.
    • AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FILL: Crop the video to fit the preview view. If the aspect ratio of the video is not the same as the aspect ratio of the preview view, the video is cropped to fit the preview view.

    The following sample code provides an example on how to specify a preview mode:

    mAlivcLivePushConfig.setPreviewDisplayMode(AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT);

Use AliLive SDK for Android to ingest streams

AlivcLivePusher is the core class of AliLive SDK for Android. This class provides parameters for initialization, stream ingest callbacks, video preview, and stream ingest management. You can also use this class to modify parameters during stream ingest.
Note
  • If you use the methods in the class, execute the try-catch statement to manage exceptions.
  • You must follow the specified sequence to call the methods. If you call the methods in an invalid sequence, an error may occur.
  1. Initialize the stream ingest parameters.

    Call the init method to initialize the configured stream ingest parameters. The following code provides an example:

    AlivcLivePusher mAlivcLivePusher = new AlivcLivePusher();
    mAlivcLivePusher.init(mContext, mAlivcLivePushConfig);
    Note AlivcLivePusher does not support multiple instances. Therefore, AliLive SDK for Android provides a destroy method for each init method.
  2. Register stream ingest callbacks.
    Three types of stream ingest callbacks are provided:
    • Info: the callbacks that are used for notifications and status detection.
    • Error: the callbacks that are used when errors occur.
    • Network: the callbacks that are used to manage network services.
    When an event occurs, the callback is triggered to notify you of the event. The following code provides an example:
    /**
      * Configure the events for stream ingest errors.
      *
      * @param errorListener The listener for errors.
      */
    mAlivcLivePusher.setLivePushErrorListener(new AlivcLivePushErrorListener() {
      @Override
      public void
    onSystemError(AlivcLivePusher livePusher, AlivcLivePushError error) {
          if(error != null) {
              // Add UI notifications or custom error solutions.
          }
      }
      @Override
      public void onSDKError(AlivcLivePusher
    livePusher, AlivcLivePushError error) {
          if(error != null) {
              // Add UI notifications or custom error solutions.
          }
      }
    });
    /**
    * Configure events for stream ingest.
    *
    * @param infoListener The listener for notifications.
    */
    mAlivcLivePusher.setLivePushInfoListener(new AlivcLivePushInfoListener() {
      @Override
      public void
    onPreviewStarted(AlivcLivePusher pusher) {
          // Preview starts.
      }
      @Override
      public void
    onPreviewStoped(AlivcLivePusher pusher) {
          // Preview ends.
      }
      @Override
      public void
    onPushStarted(AlivcLivePusher pusher) {
          // Stream ingest starts.
      }
      @Override
      public void onPushPauesed(AlivcLivePusher
    pusher) {
          // Stream ingest is paused.
      }
      @Override
      public void
    onPushResumed(AlivcLivePusher pusher) {
          // Stream ingest is resumed.
      }
      @Override
      public void
    onPushStoped(AlivcLivePusher pusher) {
          // Stream ingest ends.
      }
      @Override
      public void onPushRestarted(AlivcLivePusher
    pusher) {
          // Stream ingest is restarted.
      }
      @Override
      public void
    onFirstFramePreviewed(AlivcLivePusher pusher) {
          // The first frame appears.
      }
      @Override
      public void onDropFrame(AlivcLivePusher
    pusher, int countBef, int countAft) {
          // Frames are missing.
      }
      @Override
      public void
    onAdjustBitRate(AlivcLivePusher pusher, int curBr, int targetBr) {
          // The bitrate is adjusted.
      }
      @Override
      public void onAdjustFps(AlivcLivePusher
    pusher, int curFps, int targetFps) {
          // The frame rate is adjusted.
      }
    });
    /**
    * Configure events for the network.
    *
    * @param infoListener The listener for notifications.
    */
    mAlivcLivePusher.setLivePushNetworkListener(new AlivcLivePushNetworkListener()
    {
      @Override
      public void
    onNetworkPoor(AlivcLivePusher pusher) {
          // The network is in poor conditions.
      }
      @Override
      public void
    onNetworkRecovery(AlivcLivePusher pusher) {
          // The network is recovered.
      }
      @Override
      public void
    onReconnectStart(AlivcLivePusher pusher) {
          // The reconnection starts.
      }
      @Override
      public void
    onReconnectFail(AlivcLivePusher pusher) {
          // The reconnection fails.
      }
      @Override
      public void
    onReconnectSucceed(AlivcLivePusher pusher) {
          // The reconnection is successful.
      }
      @Override
      public void
    onSendDataTimeout(AlivcLivePusher pusher) {
          // Data transmission times out.
      }
      @Override
      public void
    onConnectFail(AlivcLivePusher pusher) {
          / The connection fails.
      }
    });
    /**
    * Configure events for background music.
    *
    * @param pushBGMListener The listener for notifications.
    */
    mAlivcLivePusher.setLivePushBGMListener(new AlivcLivePushBGMListener() {
      @Override
      public void onStarted() {
          // The playback of background music starts.
      }
      @Override
      public void onStoped() {
          // The playback of background music stops.
      }
      @Override
      public void onPaused() {
          // The playback of background music is paused.
      }
      @Override
      public void onResumed() {
          // The playback of background music is resumed.
      }
      /**
       * Configure events for the playback progress.
       *
    * @param progress The callback for the playback progress.
       */
      @Override
      public void onProgress(final long
    progress, final long duration) {
      @Override
      public void onCompleted() {
          // The playback ends.
      }
      @Override
      public void onDownloadTimeout() {
          // The player times out. The player is reconnected and seeks the previous playback position.
      }
      @Override
      public void onOpenFailed() {
          // An invalid stream. The stream is inaccessible.
      }
    });
  3. Start preview.

    You can start preview after you initialize the livePusher object and configure callbacks. Use the SurfaceView parameter for camera preview. The following code provides an example:

    mAlivcLivePusher.startPreview(mSurfaceView)// Start preview. You can also call the asynchronous method startPreviewAysnc based on your requirements to start the preview.
    Notice You can call some methods only after the preview is configured, such as the methods for background music and cameras. We recommend that you perform preview before you start stream ingest.
  4. Start stream ingest.

    You can start stream ingest only after the preview succeeds. Therefore, you must configure the onPreviewStarted callback and add the following code to the callback:

    mAlivcLivePusher.startPush(mPushUrl);
    Note
    • Push SDK for Android allows you to call the startPushAsync operation to start stream ingest in an asynchronous manner.
    • Push SDK for Android supports the URLs of the streams that are ingested over RTMP. For more information about how to obtain ingest URLs, see Ingest and streaming URLs.
    • Start stream ingest by using a valid URL. Then, use a player, such as ApsaraVideo Player, FFplay, and VLC, to test stream pulling. For more information about how to obtain source URLs, see Ingest and streaming URLs.
  5. Complete other stream ingest configurations.

    AiLive SDK for Android allows you to manage stream ingest. For example, you can start, stop, restart, pause, and resume stream ingest, stop preview, and destroy stream ingest objects. You can add buttons to perform these operations. The following sample code provides an example on how to manage stream ingest:

    /* You can pause a stream that is being ingested. If you pause a stream that is being ingested, the video preview and the video stream ingest are paused at the last frame, and the audio stream continues to be ingested. */
    mAlivcLivePusher.pause();
    /* You can resume stream ingest. After you resume stream ingest, the preview and ingest of audio and video streams are resumed. */
    mAlivcLivePusher.resume();
    /* You can stop a stream that is being ingested. */
    mAlivcLivePusher.stopPush();
    /* You can stop preview. However, this operation does not take effect for a stream that is being ingested. When the preview is stopped, the preview view is frozen at the last frame. */
    mAlivcLivePusher.stopPreview();
    /* You can restart stream ingest when the stream is being ingested or when all error callbacks are received. If an error occurs, you can call only this method or the reconnectPushAsync method to restart stream ingest. You can also call the destroy method to destroy the stream ingest object. Then, you can restart all ALivcLivePusher resources that are required for operations, such as the preview and stream ingest. */
    mAlivcLivePusher.restartPush();
    /* You can call this method when the stream is being ingested or when error callbacks related to AlivcLivePusherNetworkDelegate are received. If an error occurs, you can call only this method or the restartPush method to restart stream ingest. You can also call the destroy method to destroy the stream ingest object. Then, you can restart stream ingest over RTMP. */
    mAlivcLivePusher.reconnectPushAsync();
    /* After the stream ingest object is destroyed, stream ingest and preview are stopped, and preview views are removed. All resources related to AlivcLivePusher are destroyed. */
    mAlivcLivePusher.destroy();
  6. Manage background music.

    AliLive SDK for Android allows you to manage background music. For example, you can configure the playback of background music, audio mixing, noise reduction, in-ear monitoring, and mute features. The following sample code provides an example on how to manage background music:

    /* Start the playback of background music. */
    mAlivcLivePusher.startBGMAsync(mPath);
    /* Stop the playback of background music. To change the background music, call the method that is used to start the playback of background music. You do not need to stop the playback of the current background music. */
    mAlivcLivePusher.stopBGMAsync();
    /* Pause the playback of the background music. You can call this method only after the playback of the background music starts. */
    mAlivcLivePusher.pauseBGM();
    /* Resume the playback of background music. You can call this method only after the playback of the background music is paused. */
    mAlivcLivePusher.resumeBGM();
    /* Enable looping.*/
    mAlivcLivePusher.setBGMLoop(true);
    /* Configure noise reduction. When you enable noise reduction, the system filters out non-vocal parts from collected audio. This feature may slightly reduce the volume of the human voice. We recommend that you allow your users to determine whether to enable this feature. By default, this feature is disabled.*/
    mAlivcLivePusher.setAudioDenoise(true);
    /* Configure in-ear monitoring. In-ear monitoring is suitable for scenarios that involve karaoke. If you enable in-ear monitoring, you can hear your voice on your earphones during streaming. If you disable in-ear monitoring, you cannot hear your voice on your earphones during streaming. This feature does not take effect if no earphones are detected. */
    mAlivcLivePusher.setBGMEarsBack(true);
    /* Adjust the volumes of the background music and the human voice to configure audio mixing. */
    mAlivcLivePusher.setBGMVolume(50); // Specify the volume of the background music.
    mAlivcLivePusher.setCaptureVolume(50); // Specify the volume of the human voice.
    /* Configure muting. If you enable this feature, the background music and the human voice are muted. To separately mute the background music or the human voice, call the method that is used to configure audio mixing. */
    mAlivcLivePusher.setMute(true);
    Notice You can call methods to manage background music only after the preview starts.
  7. Perform operations on the camera.

    You can perform operations on the camera in the streaming, paused, or reconnecting state. For example, you can switch between the front and rear cameras and configure the flash, focal length, zooming, and mirroring mode. The following sample code provides an example on how to perform operations on the camera:

    /* Switch between the front and rear cameras.*/
    mAlivcLivePusher.switchCamera();
    /* Enable or disable flash. You cannot enable flash for the front camera.*/
    mAlivcLivePusher.setFlash(true); 
    /* Adjust the focal length to zoom in and out images. The value of the focal length ranges from 0 to the value of the getMaxZoom parameter. */
    mAlivcLivePusher.setZoom(5);
    /* Configure manual focus. To configure manual focus, you must configure the following parameters: point and autoFocus. The point parameter specifies the coordinates of the focus point. The autoFocus parameter specifies whether to enable autofocus. The autoFocus parameter takes effect only when you call the mAlivcLivePusher.setAutoFocus method. The value of the autoFocus parameter specifies whether to enable autofocus. */
    mAlivcLivePusher.focusCameraAtAdjustedPoint(x, y, true);
    /* Configure autofocus.*/
    mAlivcLivePusher.setAutoFocus(true);
    /* Configure the mirroring mode. The methods for mirroring are PushMirror and PreviewMirror. The PushMirror method is used to enable the mirroring mode for stream ingest. The PreviewMirror method is used to enable the mirroring mode for preview. The PushMirror method takes effect only for playback images. The PreviewMirror method takes effect only for preview views. */
    mAlivcLivePusher.setPreviewMirror(false);
    mAlivcLivePusher.setPushMirror(false);
    Notice You can call methods to perform operations on cameras only after the preview starts.
  8. Configure external audio and video sources.

    AliLive SDK for Android allows you to import external audio and video sources for stream ingest. For example, you can ingest an audio or video file.

    1. Configure external audio and video sources.
      The following sample code provides an example on how to configure external audio and video sources:
      /**
      * Import custom audio data.
      * @param data The byte array of audio data.
      * @param size
      * @param sampleRate
      * @param channels
      * @param pts The presentation timestamp (PTS) of audio. Unit: microseconds.
      * This method does not control the time sequence. You must manually control the time sequence of input audio frames.
      */
      mAlivcLivePusher. inputStreamAudioData(byte[] data, int size, int sampleRate, int channels, long pts);
      /**
      * Import custom audio data.
      * @param dataptr The pointer of the native memory for audio data.
      * @param size
      * @param sampleRate
      * @param channels
      * @param pts The PTS of audio. Unit: microseconds.
      * This method does not control the time sequence. You must manually control the time sequence of input audio frames.
      */
      mAlivcLivePusher. inputStreamAudioPtr(long dataPtr, int size, int sampleRate, int channels, long pts);
    2. Import external video data.
      The following code provides an example:
      /**
      * Import custom video streams.
      *
      * @param data The byte array of the video image.
      * @param width The width of the video image.
      * @param height The height of the video image.
      * @param size The size of the video image.
      * @param stride The stride of the video image.
      * @param pts The PTS of the video image. Unit: microseconds.
      * @param rotation The rotation angle of the video image.
      * This method does not control the time sequence. You must manually control the time sequence of input video frames.
      * Note: When you call this method, you must configure setExternMainStream(true,***) in AlivcLivePushConfig.
      */
      mAlivcLivePusher. inputStreamVideoData(byte[] data, int width, int height, int stride, int size, long pts, int rotation);
      /**
      * Import custom video streams.
      *
      * @param dataptr The pointer of the native memory for the video image.
      * @param width The width of the video image.
      * @param height The height of the video image.
      * @param stride The stride of the video image.
      * @param size The size of the video image.
      * @param pts The PTS of the video image. Unit: microseconds.
      * @param rotation The rotation angle of the video image.
      * This method does not control the time sequence. You must manually control the time sequence of input video frames.
      * Note: When you call this method, you must configure setExternMainStream(true,***) in AlivcLivePushConfig.
      */
      mAlivcLivePusher. inputStreamVideoPtr(long dataptr, int width, int height, int stride, int size, long pts, int rotation);
    3. Import audio data.
      The following code provides an example:
      /**
      * AlivcImageFormat: the format of the input video images.
      * AlivcSoundFormat: the format of the input audio frames.
      * Other parameters: To specify the resolution, the audio sample rate, and the number of channels,
      configure setResolution, setAudioSamepleRate, and setAudioChannels in AlivcLivePushConfig.
      * Note: To import custom video and audio streams, call methods such as inputStreamVideoData and inputStreamAudioData. 
      */
      mAlivcLivePushConfig.setExternMainStream(true,AlivcImageFormat.IMAGE_FORMAT_YUVNV12,
      AlivcSoundFormat.SOUND_FORMAT_S16);
  9. Add animated stickers.

    AliLive SDK for Android allows you to add animated stickers as watermarks to live streams.

    1. To create an animated sticker, you can modify the materials in the demo. Create a sequence frame image for the animated sticker. Configure the following parameters in the config.json file:
      "du": 2.04,// Specify the duration for which each time the animated sticker is played.
      "n": "qizi",// Specify the name of the animated sticker. Make sure that the name of the folder in which the animated sticker is created is the same as the name of the sticker. The name of the sticker contains the name followed by the sequence number. Example: qizi0.
      "c": 68.0,// Specify the number of animation frames, which is the number of images included in an animated sticker.
      "kerneframe": 51,// Specify an image as the keyframe. For example, specify the 51st frame as the keyframe in the demo. Make sure that the specified frame exists.
      "frameArry": [
          {"time":0,"pic":0},
          {"time":0.03,"pic":1},
          {"time":0.06,"pic":2},
          ],
      // Configure the parameters of the animated sticker. In the preceding settings, "time":0,"pic":0 indicates that the first frame qizi0 is displayed 0 seconds after the start. "time":0.03,"pic":1 indicates that the second frame qizi1 is displayed 0.03 seconds after the start. Specify all frames in the animation in the same manner.
      Note Configure other fields as described in the .json file in the demo.
    2. Add an animated sticker.
      The following sample code provides an example on how to add an animated sticker:
      /**
      * Add an animated sticker.
      * @param path Specify the path of the animated sticker. The path must contain config.json.
      * @param x Specify the starting position on the x-axis. Valid values: 0 to 1.0f.
      * @param y Specify the starting position on the y-axis. Valid values: 0 to 1.0f.
      * @param w Specify the width. Valid values: 0 to 1.0f.
      * @param h Specify the height. Valid values: 0 to 1.0f.
      * @return id Specify the ID of the sticker. You must specify the sticker ID if you want to remove a sticker.
      */
      mAlivcLivePusher.addDynamicsAddons("Path of the sticker", 0.2f, 0.2f, 0.2f, 0.2f);
    3. Remove an animated sticker.
      The following sample code provides an example on how to remove an animated sticker:
      mAlivcLivePusher.removeDynamicsAddons(int id);
  10. Call other methods.
    /* In custom mode, you can change the values of the minVideoBitrate and targetVideoBitrate parameters in real time. */
    mAlivcLivePusher.setTargetVideoBitrate(800);
    mAlivcLivePusher.setMinVideoBitrate(400);
    /* Specify whether autofocus is supported.*/
    mAlivcLivePusher.isCameraSupportAutoFocus();
    /* Specify whether flash is supported. */
    mAlivcLivePusher.isCameraSupportFlash();
    /* Query whether the stream is being ingested.*/
    mAlivcLivePusher.isPushing(); 
    /* Query the ingest URL.*/
    mAlivcLivePusher.getPushUrl();
    /* Query the debugging information about stream ingest performance. For information about the parameters of stream ingest performance, see the API references or comments in the code.*/ */
    mAlivcLivePusher.getLivePushStatsInfo();
    /* Query the version number. */
     mAlivcLivePusher.getSDKVersion();
    /* Specify the log level to filter debugging information.*/
    mAlivcLivePusher.setLogLevel(AlivcLivePushLogLevelAll);
    /* Query the status of AliLive SDK for Android.*/
    AlivcLivePushStats getCurrentStatus();
    /* Query the previous error code. If no error code is returned, the output displays ALIVC_COMMON_RETURN_SUCCESS.*/
    AlivcLivePushError getLastError();

Configure stream ingest for screen recordings

AliLive SDK for Android allows you to stream screen recordings. You can stream screen recordings only after you initialize the SDK, configure preview, and start stream ingest. To stream screen recordings, perform the following steps:

  1. Configure the screen recording mode.
    You can use one of the screen recording modes described in the following table based on your business requirements.
    Screen recording mode Required configuration
    Record screen with the camera disabled
    1. When you request the screen recording permission, call the setMediaProjectionPermissionResultData method in AlivcLivePushConfig and specify the Intent object returned by MediaProjectionManager.createScreenCaptureIntent as the parameter.
    Record screen with the camera enabled
    Note Enable camera preview on the streamer side. Viewers can view the content that is recorded by using the camera.
    1. When you request the screen recording permission, you must call the setMediaProjectionPermissionResultData method in AlivcLivePushConfig and specify the Intent object returned by MediaProjectionManager.createScreenCaptureIntent as the parameter.
    2. Pass surfaceView into the StartCamera method and call this method.
    Record screen with the camera enabled
    Note Disable camera preview on the streamer side. Viewers can continue to view the content that is recorded by using the camera.
    1. When you request the screen recording permission, you must call the setMediaProjectionPermissionResultData method in AlivcLivePushConfig and specify the Intent object returned by MediaProjectionManager.createScreenCaptureIntent as the parameter.
    2. Call the StartCamera method without passing surfaceView into the method.
    3. Call the startCameraMix method to tune the position of the camera view on the viewer side.
  2. Enable screen recording.
    Screen recording uses MediaProjection. When you request the screen recording permission, you must call the setMediaProjectionPermissionResultData method in AlivcLivePushConfig and specify the Intent object returned by MediaProjectionManager.createScreenCaptureIntent as the parameter. By default, the camera is disabled during screen recording. The following sample code provides an example:
    mAlivcLivePushConfig.setMediaProjectionPermissionResultData(resultData)
  3. Configure camera preview.
    You can call the camera preview method after you enable screen recording. The following sample code provides an example:
    mAlivcLivePusher.startCamera(surfaceView); // Enable camera preview.
    mAlivcLivePusher.stopCamera(); // Disable camera preview.
    Note
    • We recommend that you set the aspect ratio of surfaceView to 1:1 in screen recording mode. This way, you no longer need to adjust the aspect ratio of surfaceView when you rotate your screen.
    • If you do not set the aspect ratio of surfaceView to 1:1, you must adjust the aspect ratio, disable camera preview, and then enable camera preview.
    • If the streamer does not require preview, set the surfaceview parameter to null.
  4. Configure camera and screen stream mixing.
    You can enable this feature when only viewers require camera preview but the streamer does not require camera preview. In most cases, this feature is used in gaming scenarios. When the streamer does not want to stream the game content, the streamer can display the camera view on top of the game content. The following sample code provides an example:
    /**
    * @param x The starting position on the x-axis. Valid values: 0 to 1.0f.
    * @param y The starting position on the y-axis. Valid values: 0 to 1.0f.
    * @param w The width of the screen. Valid values: 0 to 1.0f.
    * @param h The height of the screen. Valid values: 0 to 1.0f.
    * @return
    */
    mAlivcLivePusher.startCameraMix(x, y, w, h); // Enable camera and screen stream mixing.
    mAlivcLivePusher.stopCameraMix(); // Disable camera and screen stream mixing.
  5. Configure screen rotation.
    In screen recording mode, you can rotate the screen to switch between the portrait mode and the landscape mode. The following sample code provides an example:
    mAlivcLivePusher.setScreenOrientation(0);
    Note When you change the orientation of the screen, you must enable OrientationEventListener at the application layer and pass the orientation setting to this method.
  6. Enable or disable privacy protection.
    This feature allows the streamer to protect their privacy during live stream recording. For example, if the streamer needs to enter a password, the streamer can enable this feature. After the streamer enters the password, the streamer can disable this feature. The following sample code provides an example:
    mAlivcLivePusher.pauseScreenCapture(); // Enable privacy protection.
    mAlivcLivePusher.resumeScreenCapture(); // Disable privacy protection.
    Note If you configure the setPausePushImage method in AlivcLivePushConfig, the specified image is displayed when live stream recording is paused. If you do not configure this method, the last frame is displayed when live stream recording is paused.

Usage notes

Take note of the items described in the following table before you use AliLive SDK for Android.

Item Description
Obfuscation rules
Check the obfuscation configurations. Make sure that the package names of AliLive SDK for Android are removed from the obfuscation list.
-keep class com.alivc.** { *;}
Method call
  • You can call both synchronous and asynchronous methods. However, we recommend that you do not call asynchronous methods because these methods consume the resources of the main thread.
  • AliLive SDK for Android throws exceptions when you fail to call the required methods or call methods in an invalid sequence. You must add a try-catch statement to prevent unexpected exits.
  • The following figure shows how to call methods.Call procedure
Version upgrades

If you use AliLive SDK for Android that is earlier than V4.1.0, you must upgrade your SDK to the latest version. For more information, see Update Push SDK for Android from V4.0.2 to V4.1.0 or later.

Notice Integrate the latest version of ApsaraVideo Player SDK for Android when you upgrade AliLive SDK.