ApsaraVideo Live:Use Push SDK for Android

Features

• Supports stream ingest over Real-Time Messaging Protocol (RTMP).

• Supports stream ingest and stream pulling over the Real-Time Streaming (RTS) protocol that is based on Real-Time Communication (RTC).

• Supports co-streaming and battles.

• 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.

• Allows you to stream screen recordings.

• Supports external audio and video inputs in different formats such as YUV and pulse-code modulation (PCM).

• Supports mixing of multiple 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 video snapshots.

• Supports automatic reconnection and error handling.

• Supports the audio 3A algorithm.

• Allows you to switch between the software and hardware encoding modes for video files. This improves the stability of the encoding module.

Classes of Push SDK for Android

Limits

Procedure

The following table describes how to use the basic edition of Push SDK for Android.

Register the SDK

In Push SDK for Android V4.4.2 and later, an all-in-one license is used. You must register Push SDK for Android before you can use the stream ingest feature. For more information, see Integrate a Push SDK license.

Configure stream ingest parameters (basic edition)

You can configure stream ingest parameters by using the AlivcLivePushConfig class. Each parameter has a default value. You can change the values of the parameters based on your business requirements. For more information about the default value and valid values for each parameter, see API reference for Push SDK for Android V6.9.0 (basic edition) or API reference for Push SDK for Android V6.9.0 (interactive edition).

1. Complete basic stream ingest configurations.

   All parameters used for basic stream ingest configurations have a default value. We recommend that you use the default values.

   Sample code

   // Initialize the class for stream ingest configurations.
   mAlivcLivePushConfig = new AlivcLivePushConfig();
   // Specify the stream ingest mode. By default, the regular stream ingest mode is used.
   mAlivcLivePushConfig.setLivePushMode(AlivcLiveMode.AlivcLiveBasicMode);
   // Specify the resolution. The default resolution is 540p.
   mAlivcLivePushConfig.setResolution(AlivcResolutionEnum.RESOLUTION_540P);
   // Specify the frame rate. The default frame rate is 20 frames per second (FPS).
   mAlivcLivePushConfig.setFps(AlivcFpsEnum.FPS_25);
   // Specify the group of pictures (GOP) size. Unit: seconds. The default GOP size is 2 seconds.
   mAlivcLivePushConfig.setVideoEncodeGop(AlivcVideoEncodeGopEnum.GOP_TWO);
   // Specify whether to enable adaptive bitrate streaming. The default value is true.
   mAlivcLivePushConfig.setEnableBitrateControl(true);
   // Specify the screen orientation. The default screen orientation is portrait. You can configure the settings that allow you to press the Home key to change the orientation to landscape left or landscape right.
   mAlivcLivePushConfig.setPreviewOrientation(AlivcPreviewOrientationEnum.ORIENTATION_PORTRAIT);
   // Specify the audio encoding format. The default format is AAC-LC.
   mAlivcLivePushConfig.setAudioProfile(AlivcAudioAACProfileEnum.AAC_LC);
   // Specify the video encoding mode. By default, hardware encoding is used.
   mAlivcLivePushConfig.setVideoEncodeMode(AlivcEncodeModeEnum.Encode_MODE_HARD);
   // Specify the audio encoding mode. By default, software encoding is used.
   mAlivcLivePushConfig.setAudioEncodeMode(AlivcEncodeModeEnum.Encode_MODE_SOFT);
   // Specify whether to use the front camera or the rear camera. By default, the front camera is used.
   mAlivcLivePushConfig.setCameraType(AlivcLivePushCameraTypeEnum.CAMERA_TYPE_FRONT);
   // Specify the image that is ingested when your app is switched to the background or video stream ingest is paused.
   mAlivcLivePushConfig.setPausePushImage("TODO: Image Path");
   // Specify the image that is ingested in poor network conditions.
   mAlivcLivePushConfig.setNetworkPoorPushImage("TODO: Image Path");

   Important

   • 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.

   • If adaptive bitrate streaming is disabled, the bitrate is fixed at the initial value and is not automatically adjusted between the specified target bitrate and the minimum bitrate. In this case, stuttering may occur when the network is unstable. Proceed with caution before you disable this feature.

2. Specify the bitrate control mode.

   You can configure the AlivcQualityModeEnum parameter to specify the bitrate control mode. Push SDK for Android provides multiple bitrate control modes. Specify the value of each parameter based on your business requirements. The following table describes the bitrate control modes.

   Bitrate control mode	Description	Sample code
   QM_RESOLUTION_FIRST	The quality-first mode. Push SDK for Android configures bitrate parameters to prioritize the quality of video streams.	mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_RESOLUTION_FIRST); // Set the mode to quality-first.
   QM_FLUENCY_FIRST	The smoothness-first mode. Push SDK for Android configures bitrate parameters to prioritize the smoothness of video streams.	mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_FLUENCY_FIRST);// Set the mode to smoothness-first.
   QM_CUSTOM	The custom mode. Push 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 and specify the initial, minimum, and target 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 target bitrate to improve the quality of a video stream.	mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_CUSTOM); mAlivcLivePushConfig.setTargetVideoBitrate(1000); // The target 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 can ensure the quality or smoothness of video streams when network jitter occurs.

   • 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 in quality-first mode

   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 in smoothness-first mode

   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 you enable the adaptive resolution feature, the resolution is automatically reduced to ensure the smoothness and quality of video streams in poor network conditions. Sample code:

   mAlivcLivePushConfig.setEnableAutoResolution(true); // Specify whether to enable adaptive resolution. The default value is false.

   Important

   • 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 Push SDK for Android, you must import a retouching library and configure callbacks.

   1. Import a retouching library and a retouching panel by using Maven dependencies. Add the following code to the build.gradle file of the project, with the latest version of Queen SDK demo specified:

      implementation "com.aliyun.maliang.android:queen:2.5.0-official-full"
      implementation("com.aliyun.maliang.android:queen_menu:2.5.0-official-full") {
          exclude group: 'com.aliyun.maliang.android', module: 'queen'
      }

      The following table describes the LiveBeauty module provided in the demo that you can integrate.

      File or folder	Description
      live_beauty	The abstract class for retouching.
      queen_beauty	The user interface (UI) widgets for retouching.

   2. Obtain the LiveBeauty module.

      Note

      For information about how to obtain the license, see Obtain a license of Queen SDK.

      1. Use the clone command to download the code of the plugin library from GitHub.

         git clone https://github.com/MediaBox-Demos/amdemos-android-live.git

      2. In the root directory of the Android Studio project, open the command line interface and run the following code. Then, choose File > New > Import Module and import the LiveBeauty module into the project.

         git submodule add https://github.com/MediaBox-Demos/amdemos-android-live.git ***/***/***

         Note

         Replace the ***/***/*** part in the sample code with the path where you want to store the LiveBeauty module.

      3. Add the module path to the settings.gradle file.

         include ':app', ':LiveBeauty', ':LiveBeauty:live_queenbeauty'

         Note

         In the sample code, app is the main module of the project.

      4. In the build.gradle file of the main module, add the LiveBeauty dependencies.

         dependencies {
             implementation project(':LiveBeauty')
             implementation project(':LiveBeauty:live_queenbeauty')
         }

      5. Choose File > Sync Project with Gradle Files. The LiveBeauty module is available after the synchronization is complete.

   3. Configure the UI for the plugin.

      1. Add QueenBeautyMenu to the XML layout file.

         <com.aliyunsdk.queen.menu.QueenBeautyMenu
             android:id="@+id/beauty_beauty_menuPanel"
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
             android:layout_alignParentBottom="true"
             android:layout_centerHorizontal="true" />

      2. Initialize QueenBeautyMenu in Activity.

         // Initialize the QueenBeautyMenu panel.
         QueenMenuPanel beautyMenuPanel = QueenBeautyMenu.getPanel(context);
         beautyMenuPanel.onHideMenu(); 
         beautyMenuPanel.onHideValidFeatures(); 
         beautyMenuPanel.onHideCopyright(); 
         
         // Add the menu to the layout.
         QueenBeautyMenu beautyBeautyContainerView = findViewById(R.id.beauty_beauty_menuPanel);
         beautyBeautyContainerView.addView(beautyMenuPanel);

   4. Configure callbacks for facial recognition and retouching.

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

      • The data parameter returned by the customDetectProcess callback of AlivcLivePushCustomDetect is used as the pointer to collect data. The callback includes the long data, int width, int height, int rotation, int format, and long extra parameters. The third-party retouching library can identify or process the returned data.

      • The inputTexture parameter returned by the customFilterProcess callback of AlivcLivePushCustomFilter specifies the image texture that can be processed by the third-party retouching library. The callback includes the int inputTexture, inttextureWidth, int textureHeight, and long extra parameters. If you want to return a processed texture, the texture ID is returned. Otherwise, the value of inputTexture is returned.

      Sample code

      /**
       * Callbacks for facial recognition.
       */
      mAlivcLivePusher.setCustomDetect(new AlivcLivePushCustomDetect() {
          @Override
          public void customDetectCreate() {
      
          }
      
          @Override
          public long customDetectProcess(long dataPtr, int width, int height, int rotation, int format, long extra) {
              return 0;
          }
      
          @Override
          public void customDetectDestroy() {
      
          }
      });
      
      /**
       * Callbacks for retouching.
       */
       
       /**
       * Initialize BeautyManager.
       */
      mAlivcLivePusher.setCustomFilter(new AlivcLivePushCustomFilter() {
          @Override
          public void customFilterCreate() {
              initBeautyManager();
          }
      
       /**
       * Process the ingested stream and add beauty effects.
       */
          @Override
          public int customFilterProcess(int inputTexture, int textureWidth, int textureHeight, long extra) {
              if (mBeautyManager == null) {
                  return inputTexture;
              }
      
              return mBeautyManager.onTextureInput(inputTexture, textureWidth, textureHeight);
          }
      
          @Override
          public void customFilterDestroy() {
              destroyBeautyManager();
          }
      });

5. Specify an image for background stream ingest.

   Push 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, only audio streams are ingested. You can also specify an image that you want to ingest. For example, you can ingest an image in which a message such as The streamer will be back soon. is displayed to notify the viewers. Sample code:

   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. Sample code:

   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.

   Push SDK for Android allows you to add one or more watermarks. Watermarks must be in the PNG format. Sample code:

   mAlivcLivePushConfig.addWaterMark(waterPath,0.1,0.2,0.3); // Add a watermark.

   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 at the 10% position on the x-axis of the stream. 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 source image and the input width value 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 the preview mode.

   Push 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 window. If the aspect ratio of the video is not the same as the aspect ratio of the preview window, deformation occurs during preview.

   • AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT: In this mode, the original aspect ratio of the video is used during preview. If the aspect ratio of the video is not the same as the aspect ratio of the preview window, black bars appear on the preview window.

   • AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FILL: In this mode, the video is cropped to fit the preview window during preview. If the aspect ratio of the video is not the same as the aspect ratio of the preview window, the video is cropped.

   Sample code:

   mAlivcLivePushConfig.setPreviewDisplayMode(AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT);

Use Push SDK for Android to ingest streams (basic edition)

1. Initialize the AlivcLivePusher class.

   After you configure stream ingest parameters, call the init method to initialize the class. Sample code:

   AlivcLivePusher mAlivcLivePusher = new AlivcLivePusher();
   mAlivcLivePusher.init(mContext, mAlivcLivePushConfig);

   Note

   The AlivcLivePusher class does not support multiple instances. Therefore, you must call the destroy method once for each call of the init method.

2. Register stream ingest callbacks.

   The following stream ingest callbacks are supported:

   • Info: the callbacks that are used for notifications and status detection.

   • Error: the callbacks that are returned when errors occur.

   • Network: the callbacks that are related to network.

   When an event occurs, the corresponding callback is triggered to notify you of the event. Sample code:

   Configure the callbacks for stream ingest errors

   /**
    * Configure the callbacks 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 the callbacks for stream ingest-related notifications

   /**
    * Configure the callbacks for stream ingest-related notifications.
    *
    * @param infoListener The listener for notifications.
    */
   mAlivcLivePusher.setLivePushInfoListener(new AlivcLivePushInfoListener() {
       @Override
       public void onPreviewStarted(AlivcLivePusher pusher) {
           // Notifies that preview starts.
       }
   
       @Override
       public void onPreviewStoped(AlivcLivePusher pusher) {
           // Notifies that preview ends.
       }
   
       @Override
       public void onPushStarted(AlivcLivePusher pusher) {
           // Notifies that stream ingest starts.
       }
   
       @Override
       public void onFirstAVFramePushed(AlivcLivePusher alivcLivePusher) {
           // Notifies that the first audio and video packet is sent.
       }
   
       @Override
       public void onPushPauesed(AlivcLivePusher pusher) {
           // Notifies that stream ingest is paused.
       }
   
       @Override
       public void onPushResumed(AlivcLivePusher pusher) {
           // Notifies that stream ingest is resumed.
       }
   
       @Override
       public void onPushStoped(AlivcLivePusher pusher) {
           // Notifies that stream ingest ends.
       }
   
       @Override
       public void onPushRestarted(AlivcLivePusher pusher) {
           // Notifies that stream ingest is restarted.
       }
   
       @Override
       public void onFirstFramePreviewed(AlivcLivePusher pusher) {
           // Notifies that the first frame is rendered.
       }
   
       @Override
       public void onDropFrame(AlivcLivePusher pusher, int countBef, int countAft) {
           // Notifies that frames are missing.
       }
   
       @Override
       public void onAdjustBitRate(AlivcLivePusher pusher, int curBr, int targetBr) {
           // Notifies that the bitrate is adjusted.
       }
   
       @Override
       public void onAdjustFps(AlivcLivePusher pusher, int curFps, int targetFps) {
           // Notifies that the frame rate is adjusted.
       }
   
       @Override
       public void onPushStatistics(AlivcLivePusher alivcLivePusher, AlivcLivePushStatsInfo alivcLivePushStatsInfo) {
           // The callback for data statistics about ingested streams. This callback is returned every 2 seconds.
       }
   
       @Override
       public void onSetLiveMixTranscodingConfig(AlivcLivePusher alivcLivePusher, boolean isSuccess, String msg) {
           // The callback for cloud-based stream mixing (transcoding), which corresponds to the setLiveMixTranscodingConfig method. This callback takes effect only in interactive mode.
       }
   });

   Configure the callbacks for network-related notifications

   /**
    * Configure the callbacks for network-related notifications.
    *
    * @param infoListener The listener for notifications.
    */
   mAlivcLivePusher.setLivePushNetworkListener(new AlivcLivePushNetworkListener() {
       @Override
       public void onNetworkPoor(AlivcLivePusher pusher) {
           // Notifies that the network is in poor conditions.
       }
   
       @Override
       public void onNetworkRecovery(AlivcLivePusher pusher) {
           // Notifies that the network is recovered.
       }
   
       @Override
       public void onReconnectStart(AlivcLivePusher pusher) {
           // Notifies that the reconnection starts.
       }
   
       @Override
       public void onConnectionLost(AlivcLivePusher alivcLivePusher) {
           // Notifies that the network is disconnected.
       }
   
       @Override
       public void onReconnectFail(AlivcLivePusher pusher) {
           // Notifies that the reconnection failed.
       }
   
       @Override
       public void onReconnectSucceed(AlivcLivePusher pusher) {
           // Notifies that the reconnection is successful.
       }
   
       @Override
       public void onSendDataTimeout(AlivcLivePusher pusher) {
           // Notifies that data transmission timed out.
       }
   
       @Override
       public void onConnectFail(AlivcLivePusher pusher) {
           // Notifies that the connection failed.
       }
   
       @Override
       public String onPushURLAuthenticationOverdue(AlivcLivePusher alivcLivePusher) {
           // Notifies that the authentication expires.
           return null;
       }
   
       @Override
       public void onSendMessage(AlivcLivePusher alivcLivePusher) {
           // Notifies that the supplemental enhancement information (SEI) message is sent.
       }
   
       @Override
       public void onPacketsLost(AlivcLivePusher alivcLivePusher) {
           // The callback for packet loss during stream ingest.
       }
   });

   Configure the callbacks for notifications related to background music

   /**
    * Configure the callbacks for notifications related to background music.
    *
    * @param pushBGMListener The listener for notifications related to background music.
    */
   mAlivcLivePusher.setLivePushBGMListener(new AlivcLivePushBGMListener() {
       @Override
       public void onStarted() {
           // Notifies that the playback of background music starts.
       }
   
       @Override
       public void onStoped() {
           // Notifies that the playback of background music stops.
       }
   
       @Override
       public void onPaused() {
           // Notifies that the playback of background music is paused.
       }
   
       @Override
       public void onResumed() {
           // Notifies that the playback of background music is resumed.
       }
   
       @Override
       public void onProgress(long l, long l1) {
           // Notifies you of the playback progress.
       }
   
       @Override
       public void onCompleted() {
           // Notifies that the playback of background music ends.
       }
   
       @Override
       public void onDownloadTimeout() {
           // Notifies that the playback of background music timed out.
       }
   
       @Override
       public void onOpenFailed() {
           // Notifies that the stream is invalid.
       }
   });

3. Start preview.

   You can start preview after you initialize the livePusher object and configure callbacks. Use the SurfaceView parameter for camera preview. Sample code:

   mAlivcLivePusher.startPreview(mSurfaceView)// Start preview. You can also call the asynchronous method startPreviewAysnc to start preview based on your business requirements.

   Important

   You can call some methods only after the preview is configured, such as the methods for background music and camera control. 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 startPushAsync to start stream ingest in an asynchronous manner.

   • Push SDK for Android supports ingest URLs in the RTMP format and RTS format. Compared with ingest URLs in the RTMP format, ingest URLs in the RTS format provide improved stability and perform better in poor network conditions. We recommend that you use ingest URLs in the RTS format. For more information about the comparison between ingest URLs in the RTMP format and RTS format and how to ingest streams over RTS, see Use Push SDK to ingest streams over RTS.

   • After you use a valid ingest URL to start stream ingest, you can use a player such as ApsaraVideo Player, FFplay, or VLC to test stream pulling. For information about how to obtain a streaming URL, see Generate ingest and streaming URLs.

5. Complete other stream ingest configurations.

   Push 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 instances. You can add buttons to perform these operations.

   Sample code

   /* Pause a stream that is being ingested. For a stream that is being ingested, the video preview and video stream ingest are paused at the last frame, and the audio stream continues to be ingested. */
   mAlivcLivePusher.pause();
   /* Resume stream ingest. After you resume stream ingest, the preview and ingest of audio and video streams are resumed. */
   mAlivcLivePusher.resume();
   /* Stop a stream that is being ingested. */
   mAlivcLivePusher.stopPush();
   /* Stop preview. This operation does not take effect for a stream that is being ingested. When preview is stopped, the preview window is frozen at the last frame. */
   mAlivcLivePusher.stopPreview();
   /* Restart stream ingest when the stream is being ingested or when an error callback is fired. 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 instance. Then, you can restart all ALivcLivePusher resources that are required for operations, such as preview and stream ingest. */
   mAlivcLivePusher.restartPush();
   /* Call this method when the stream is being ingested or when an error callback related to AlivcLivePusherNetworkDelegate is fired. 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 instance. Then, you can restart stream ingest over RTMP. */
   mAlivcLivePusher.reconnectPushAsync();
   /* Destroy the stream ingest instance. After you call this method, stream ingest and preview are stopped, and the preview window is removed. All resources related to AlivcLivePusher are destroyed. */
   mAlivcLivePusher.destroy();

6. Manage background music.

   Push SDK for Android allows you to manage background music. For example, you can configure features such as the playback of background music, audio mixing, noise reduction, in-ear monitoring, and muting. Sample code:

   /* Start the playback of background music. */
   mAlivcLivePusher.startBGMAsync(mPath);
   /* Stop the playback of background music. If you want 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 background music. You can call this method only after the playback of background music starts. */
   mAlivcLivePusher.pauseBGM();
   /* Resume the playback of background music. You can call this method only after the playback of background music is paused. */
   mAlivcLivePusher.resumeBGM();
   /* Enable looping. */
   mAlivcLivePusher.setBGMLoop(true);
   /* Configure noise reduction. If you enable noise reduction, the system filters out non-vocal parts from the 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);
   /* Configure audio mixing. You can adjust the volumes of the background music and human voice. */
   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 human voice are muted. To separately mute the background music or human voice, call the method that is used to configure audio mixing. */
   mAlivcLivePusher.setMute(true);

   Important

   You can call the methods to manage background music only after the preview starts.

7. Configure stream ingest snapshots.

   Push SDK for Android allows you to capture snapshots of local video streams. Sample code:

   // Configure the video stream snapshots by setting relevant parameters, including the number of snapshots, the interval between two snapshots, and the callback.
   pusher.snapshot(1, 1, new AlivcSnapshotListener() {
       @Override
       public void onSnapshot(Bitmap bmp) {
               // You can dump each snapshot as a local PNG file. Sample code:
           String dateFormat = new SimpleDateFormat("yyyy-MM-dd-hh-mm-ss-SS").format(new Date());
           File f = new File(context.getExternalFilesDir(Environment.DIRECTORY_PICTURES), "snapshot-" + dateFormat + ".png");
           if (f.exists()) {
               f.delete();
           }
           try {
               FileOutputStream out = new FileOutputStream(f);
               bmp.compress(Bitmap.CompressFormat.PNG, 90, out);
               out.flush();
               out.close();
           } catch (FileNotFoundException e) {
               // TODO Auto-generated catch block
               e.printStackTrace();
           } catch (IOException e) {
               // TODO Auto-generated catch block
               e.printStackTrace();
           }
       }
   });

8. Perform camera-related operations.

   You can perform camera-related operations 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. Sample code:

   /* 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 or out. Valid values of the focal length: [0,getMaxZoom()]. */
   mAlivcLivePusher.setZoom(5);
   /* Configure manual focus. To configure manual focus, you must set 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 for this call. Whether autofocus is enabled otherwise varies based on the setAutoFocus method. */
   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. PushMirror takes effect only for stream playback, and PreviewMirror takes effect only for preview. */
   mAlivcLivePusher.setPreviewMirror(false);
   mAlivcLivePusher.setPushMirror(false);

   Important

   You can call the methods to perform camera-related operations only after the preview starts.

9. Configure external audio and video sources.

   Push 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.

      Sample code:

      /**
      * Import custom audio data.
      * @param data The byte array of the audio data.
      * @param size
      * @param sampleRate
      * @param channels
      * @param pts The presentation timestamp (PTS) of audio. Unit: microseconds.
      * This method does not configure the time sequence. You must manually configure 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 the audio data.
      * @param size
      * @param sampleRate
      * @param channels
      * @param pts The PTS of audio. Unit: microseconds.
      * This method does not configure the time sequence. You must manually configure the time sequence of input audio frames.
      */
      mAlivcLivePusher. inputStreamAudioPtr(long dataPtr, int size, int sampleRate, int channels, long pts);

   2. Import external video data.

      Sample code:

      /**
      * Import a custom video stream.
      *
      * @param data The byte array of the video.
      * @param width The width of the video.
      * @param height The height of the video.
      * @param size The size of the video.
      * @param stride The stride of the video.
      * @param pts The PTS of the video. Unit: microseconds.
      * @param rotation The rotation angle of the video.
      * This method does not configure the time sequence. You must manually configure 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 a custom video stream.
      *
      * @param dataptr The pointer of the native memory for the video.
      * @param width The width of the video.
      * @param height The height of the video.
      * @param stride The stride of the video.
      * @param size The size of the video.
      * @param pts The PTS of the video. Unit: microseconds.
      * @param rotation The rotation angle of the video.
      * This method does not configure the time sequence. You must manually configure 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 external audio data.

      Sample code:

      /**
      * AlivcImageFormat: the format of the input video.
      * AlivcSoundFormat: the format of the input audio frames.
      * Other parameters: To specify the output resolution, the audio sampling 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);

10. Manage animated stickers.

    Push SDK for Android allows you to add animated stickers to live streams. Animated stickers can be used as watermarks.

    1. To create an animated sticker, you can use and modify the materials provided 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 stored is the same as the name of the sticker, and the name of each frame ends with a sequence number. Example: qizi0.
       "c": 68.0,// Specify the number of 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 animated sticker is played. "time":0.03,"pic":1 indicates that the second frame qizi1 is displayed 0.03 seconds after the animated sticker is played. Configure all frames in the animated sticker in the same manner.

       Note

       For other parameters, you can retain the values in the config.json file provided in the demo.

    2. Add an animated sticker.

       Sample code:

       /**
       * Add an animated sticker.
       * @param path Specify the path of the animated sticker. The path must include the config.json file.
       * @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 ID of a sticker if you want to remove the sticker.
       */
       mAlivcLivePusher.addDynamicsAddons("Path of the sticker", 0.2f, 0.2f, 0.2f, 0.2f);

    3. Remove an animated sticker.

       Sample code:

       mAlivcLivePusher.removeDynamicsAddons(int id);

11. Call other methods.

    /* In custom mode, you can change the minimum bitrate and target bitrate 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 stream ingest performance debugging information. For more information about the parameters of stream ingest performance, see the API references or comments in the code. */
    mAlivcLivePusher.getLivePushStatsInfo();
    /*Query the SDK version number. */
    mAlivcLivePusher.getSDKVersion();
    /* Specify the log level to filter debugging information. */
    mAlivcLivePusher.setLogLevel(AlivcLivePushLogLevelAll);
    /* Query the status of Push SDK for Android. */
    AlivcLivePushStats getCurrentStatus();
    /* Query the previous error code. If no error code is returned, ALIVC_COMMON_RETURN_SUCCESS is displayed. */
    AlivcLivePushError getLastError();

Configure stream ingest for screen recordings (basic edition)

Push 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	Configure the data that is returned after you call the method to request the screen recording permissions in AlivcLivePushConfig.
   Record screen with the camera enabled Note Enable camera preview on the streamer side. Viewers can view the video content that is recorded by using the camera.	Configure the data that is returned after you call the method to request the screen recording permissions in AlivcLivePushConfig. Pass in surfaceView when you call the StartCamera method.
   Record screen with the camera enabled Note Disable camera preview on the streamer side. Viewers can view the video content that is recorded by using the camera.	Configure the data that is returned after you call the method to request the screen recording permissions in AlivcLivePushConfig. Call the StartCamera method without the need to pass in surfaceView. Call the startCameraMix method to tune the position of the camera view on the viewer side.

2. Enable screen recording.

   MediaProjection is used for screen recording. To enable screen recording, you must request the screen recording permissions, and call the setMediaProjectionPermissionResultData method in AlivcLivePushConfig to configure the returned data. By default, the camera is disabled during screen recording. The following sample code provides an example on how to configure the returned data:

   mAlivcLivePushConfig.setMediaProjectionPermissionResultData(resultData)

3. Configure camera preview.

   You can call the camera preview method after you enable screen recording. Sample code:

   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 the screen.

   • If you do not set the aspect ratio of surfaceView to 1:1, you must adjust the aspect ratio when you rotate the screen, disable camera preview, and then enable camera preview again.

   • If the streamer side does not require preview, set the surfaceView parameter to null.

4. Configure camera stream mixing.

   You can enable this feature if viewers require camera preview while the streamer side does not require camera preview. This feature is primarily used in gaming scenarios. When a streamer does not want to stream the game content, the streamer can display the camera view on top of the game content. Sample code:

   /**
   * @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 stream mixing.
   mAlivcLivePusher.stopCameraMix(); // Disable camera stream mixing.

5. Configure screen rotation.

   In screen recording mode, you can rotate the screen to switch between the portrait mode and landscape mode. Sample code:

   mAlivcLivePusher.setScreenOrientation(0);

   Note

   When you change the screen orientation, you must enable OrientationEventListener at the application layer and pass in the orientation settings to the setScreenOrientation method.

6. Configure privacy protection.

   This feature allows streamers to protect their privacy during screen recording. For example, if a streamer needs to enter a password, the streamer can enable this feature. After the streamer enters the password, the streamer can disable this feature. Sample code:

   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 screen recording is paused. If you do not configure this method, the last frame is displayed when screen recording is paused.

Configure co-streaming settings (interactive edition)

The interactive edition of Push SDK V4.4.4 or later provides the RTC-based co-streaming feature. The interactive edition of Push SDK V4.4.5 or later provides the RTC-based battle feature. Streamers and viewers can interact with each other at an ultra-low latency of less than 300 ms by using the interactive edition of Push SDK. For more information about interactive streaming, see Developer guide to co-streaming and Developer guide to battles.

Usage notes

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

-keep class com.alivc.** { *;}