ApsaraVideo Live:Feature Usage

Register the SDK

For information about how to apply for and configure a license, see Integrate a license for the Push SDK.

Call the license registration method early in your application's lifecycle, before you use the Push SDK.

AlivcLiveBase.setListener(new AlivcLiveBaseListener() {
  @Override
  public void onLicenceCheck(AlivcLivePushConstants.AlivcLiveLicenseCheckResultCode result, String reason) {
    Log.e(TAG, "onLicenceCheck: " + result + ", " + reason);
  }
});
AlivcLiveBase.registerSDK();

• The AlivcLiveBase class lets you set log levels, specify local log paths, and retrieve the SDK version.

• Call the registerSDK method in AlivcLiveBase to register the SDK license.

• In the onLicenceCheck method of the AlivcLiveBase#setListener interface, you can asynchronously check if the license is configured.

  Note

  This callback is triggered only after the pusher instance is initialized.

Ingest a camera stream

1. Initialize the SDK.

   After you configure the stream ingest parameters, use the init method of the Push SDK to initialize it. The following sample code shows how to do this:

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

   Note

   AlivcLivePusher does not support multiple instances. Each init call must have a corresponding destroy call.

2. Register preview callbacks.

   You can register preview callbacks using the setLivePushInfoListener method:

   /**
    * Set stream ingest notification events.
    *
    * @param infoListener The notification listener.
    */
   mAlivcLivePusher.setLivePushInfoListener(new AlivcLivePushInfoListener() {
       @Override
       public void onPreviewStarted(AlivcLivePusher pusher) {
           // A notification that the preview has started.
       }
       // Other Override methods
       //....
       //....
   });

3. Start the preview.

   After the livePusher object is initialized and the callbacks are configured, you can start the preview. You must pass the SurfaceView for the Camera preview. The following sample code shows how to do this:

   mAlivcLivePusher.startPreview(mSurfaceView)// Start the preview. You can also call the asynchronous startPreviewAysnc method as needed.

4. Start stream ingest.

   Add the following code inside the onPreviewStarted callback method.

   mAlivcLivePusher.startPush(mPushUrl);

   Note

   • Ingest URLs support RTMP and Real-Time Streaming (RTS) (artc://). For information about how to obtain an ingest URL, see Generate ingest and streaming URLs.

   • ApsaraVideo Live does not support ingesting multiple streams to the same ingest URL at the same time. The second stream ingest request is rejected.

/* You can call this method to pause an active stream. After you pause stream ingest, the video preview and video stream ingest remain on the last frame, and the audio stream continues. */
mAlivcLivePusher.pause();
/* You can call this method to resume a paused stream. After you resume stream ingest, the audio and video previews and stream ingest return to normal. */
mAlivcLivePusher.resume();
/* You can call this method to stop an active stream. After the operation is complete, stream ingest stops. */
mAlivcLivePusher.stopPush();
/* You can call this method to stop the preview only when the preview is active. Calling this method on an active stream has no effect. After the preview stops, the preview image freezes on the last frame. */
mAlivcLivePusher.stopPreview();
/* You can call this method to restart stream ingest when the stream is active or when you receive any Error-related callbacks. In an Error state, you can only call this method, reconnectPushAsync to reconnect, or destroy to destroy the stream ingest. After the operation is complete, stream ingest restarts. All resources within ALivcLivePusher, including the preview and stream ingest, are restarted. */
mAlivcLivePusher.restartPush();
/* You can call this method when the stream is active or when you receive an Error callback related to AlivcLivePusherNetworkDelegate. In an Error state, you can only call this method, restartPush to restart stream ingest, or destroy to destroy the stream ingest. After the operation is complete, the stream ingest reconnects to the RTMP URL. */
mAlivcLivePusher.reconnectPushAsync();
/* After the stream ingest is destroyed, stream ingest and the preview stop, and the preview image is removed. All resources related to AlivcLivePusher are destroyed. */
mAlivcLivePusher.destroy();

/* Switch between the front and rear cameras. */
mAlivcLivePusher.switchCamera();
/* Turn the flash on or off. You cannot turn on the flash when using the front camera. */
mAlivcLivePusher.setFlash(true); 
/* Adjust the focus to zoom the captured image. The zoom range is [0, getMaxZoom()]. */
mAlivcLivePusher.setZoom(5);
/* Manually focus. Manual focus requires two parameters: 1. point: The coordinates of the point to focus on. 2. autoFocus: Specifies whether to enable autofocus. This parameter is effective only for the current focus operation. Subsequent autofocus behavior follows the setting of the autofocus interface mentioned above. */
mAlivcLivePusher.focusCameraAtAdjustedPoint(x, y, true);
/* Set whether to enable autofocus. */
mAlivcLivePusher.setAutoFocus(true);
/* Set the image. There are two image-related interfaces: PushMirror for the ingest stream image and PreviewMirror for the preview image. The PushMirror setting affects only the playback image. The PreviewMirror setting affects only the preview image. The two do not affect each other. */
mAlivcLivePusher.setPreviewMirror(false);
mAlivcLivePusher.setPushMirror(false);

Ingest a screen sharing stream

The Push SDK supports ingesting screen sharing streams. Before you configure screen sharing, you must initialize the SDK, set up the preview, and start the stream ingest. Screen recording uses MediaProjection, which requires you to request user permission. To enable screen recording mode, pass the data returned from the permission request through this interface. By default, the camera is not enabled during screen recording.

// resultData: The system intent for screen recording.
mAlivcLivePushConfig.setMediaProjectionPermissionResultData(resultData);

mAlivcLivePusher.setScreenOrientation(0);

mAlivcLivePusher.pauseScreenCapture();// Enable privacy protection.
mAlivcLivePusher.resumeScreenCapture();// Disable privacy protection.

Ingest both screen sharing and camera streams

When ingesting a screen sharing stream, you can enable the camera to ingest both screen sharing and camera streams. There are two scenarios for ingesting both screen sharing and camera streams:

1. The streamer has a camera preview.

   Both the streamer and viewers can see the camera feed.

2. The streamer does not have a camera preview.

   For example, during a game live stream, the streamer does not want the camera view to block the game screen. However, the live content that viewers see includes the streamer's camera feed.

mAlivcLivePusher.startCamera(surfaceView);// Enable the camera preview.
mAlivcLivePusher.stopCamera();// Disable the camera preview.

mAlivcLivePusher.startCameraMix(x, y, w, h);// Enable camera stream mixing and set the mixing layout with x, y, w, and h.
mAlivcLivePusher.stopCameraMix();// Stop camera stream mixing.

Preview display modes

The Push SDK supports three preview modes. The preview display mode does not affect stream ingest.

• ALIVC_LIVE_PUSHER_PREVIEW_SCALE_FILL: The preview fills the window. If the video and window aspect ratios are different, the preview is distorted.

• ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT: The preview maintains the video's aspect ratio. If the video and window aspect ratios are different, black bars appear in the preview.

• ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FILL: The preview is cropped to fit the window's aspect ratio. If the video and window aspect ratios are different, parts of the video are cropped.

The following sample code shows how to set the preview mode:

mAlivcLivePushConfig.setPreviewDisplayMode(AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT);

Image stream ingest

To improve the user experience, the Push SDK lets you ingest a static image when the application is in the background or when the bitrate is too low.

When the application is moved to the background, video stream ingest is paused by default, and only the audio stream is ingested. During this time, you can ingest a static image. For example, you can display an image that says, "Streamer is away for a moment and will be back soon".

mAlivcLivePushConfig.setPausePushImage("Path to the background PNG image");// Set the image for background stream ingest.

When the network is poor, you can configure the SDK to ingest a static image. After you set the image, the SDK automatically ingests it when a low bitrate is detected, which helps avoid video stream stuttering. The following sample code shows how to do this:

mAlivcLivePushConfig.setNetworkPoorPushImage("Path to the poor network PNG image");// Set the image to ingest when the network is poor.

Ingest an audio-only stream

mAlivcLivePushConfig.setAudioOnly(true);

Ingest external audio and video streams

The Push SDK supports ingesting audio and video from external sources, such as an audio or video file.

Before you can ingest external audio and video streams, you must enable the custom audio and video stream input feature.

/**
* Other parameters, such as output resolution, audio sampling rate, and number of channels, are set in the config file using setResolution, setAudioSampleRate, and setAudioChannels.
*/
mAlivcLivePushConfig.setExternMainStream(true,AlivcImageFormat.IMAGE_FORMAT_YUVNV12,AlivcSoundFormat.SOUND_FORMAT_S16);

After you enable the custom audio and video stream input feature, you can ingest external audio and video streams.

/**
* This interface does not control the timing. The caller needs to control the timing of the input audio frames.
*/
mAlivcLivePusher.inputStreamAudioData(byte[] data, int size, int sampleRate, int channels, long pts);

/**
* This interface does not control the timing. The caller needs to control the timing of the input video frames.
*/
mAlivcLivePusher.inputStreamVideoData(byte[] data, int width, int height, int stride, int size, long pts, int rotation);

Configure watermarks

The Push SDK provides a feature for adding watermarks and supports multiple watermarks on a single stream. The watermark image must be a PNG file. The following sample code shows how to add a watermark:

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

Set the video quality

Three video quality modes are supported: Resolution Priority, Fluency Priority, and Custom.

mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_RESOLUTION_FIRST);// Resolution priority

mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_FLUENCY_FIRST);// Fluency priority

mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_CUSTOM);// Custom mode
mAlivcLivePushConfig.setTargetVideoBitrate(1000); // Target bitrate: 1,000 kbps
mAlivcLivePushConfig.setMinVideoBitrate(300); // Minimum bitrate: 300 kbps
mAlivcLivePushConfig.setInitialVideoBitrate(800); // Initial bitrate: 800 kbps

Adaptive resolution

Adaptive resolution dynamically adjusts the ingest resolution. When this feature is enabled, the resolution is automatically lowered in poor network conditions to improve video fluency and definition. The following sample code shows how to enable this feature:

mAlivcLivePushConfig.setEnableAutoResolution(true); // Enable adaptive resolution. It is disabled by default.

Background music

The Push SDK provides features for background music, including playback, mixing, denoising, in-ear monitoring, and muting. The following sample code shows how to use these features:

/* Start playing background music. */
mAlivcLivePusher.startBGMAsync(mPath)；
/* Stop playing background music. If background music is playing and you need to switch songs, simply call the start background music interface. You do not need to stop the currently playing background music. */
mAlivcLivePusher.stopBGMAsync();
/* Pause background music. You can call this interface only after the background music starts playing. */
mAlivcLivePusher.pauseBGM();
/* Resume background music. You can call this interface only when the background music is paused. */
mAlivcLivePusher.resumeBGM();
/* Enable loop playback for music. */
mAlivcLivePusher.setBGMLoop(true);
/* Set the denoise switch. After you turn on denoising, non-human voice parts of the captured sound are filtered. This may slightly suppress the human voice. We recommend that you let users choose whether to enable the denoising feature. It is not used by default. */
mAlivcLivePusher.setAudioDenoise(true);
/* Set the in-ear monitoring switch. The in-ear monitoring feature is mainly used in KTV scenarios. After you turn on in-ear monitoring, the streamer can hear their own voice in the headphones. After you turn it off, the streamer cannot hear their voice in the headphones. In-ear monitoring does not work without headphones. */
mAlivcLivePusher.setBGMEarsBack(true);
/* Set mixing to adjust the volume of the background music and captured human voice. */
mAlivcLivePusher.setBGMVolume(50);// Set the background music volume.
mAlivcLivePusher.setCaptureVolume(50);// Set the captured human voice volume.
/* Set mute. After you mute, both the music and human voice input are muted. To mute only the music or human voice, use the mixing volume setting interface. */
mAlivcLivePusher.setMute(true);

Capture snapshots during stream ingest

The Push SDK provides a feature to capture snapshots of the local video stream. The following sample code shows how to do this:

// Capture a snapshot of the video stream. Parameters: number of images to capture, interval between each image, and interface callback.
pusher.snapshot(1, 1, new AlivcSnapshotListener() {
    @Override
    public void onSnapshot(Bitmap bmp) {
            // You can dump the snapshot to a local PNG file. The following is 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();
        }
    }
});

Background running and screen locking

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

• For non-system audio and video calls, the SDK captures and ingests the sound. You can call the mAlivcLivePusher.setMute(true or false) interface when the application is moved to the background or the screen is locked to control whether audio is captured in the background, based on your application's requirements.

Callback listeners

Common methods and interfaces

/* In Custom mode, users can adjust the minimum and target bitrates in real time. */
mAlivcLivePusher.setTargetVideoBitrate(800);
mAlivcLivePusher.setMinVideoBitrate(400);
/* Check if autofocus is supported. */
mAlivcLivePusher.isCameraSupportAutoFocus();
/* Check if the flash is supported. */
mAlivcLivePusher.isCameraSupportFlash();
/* Get the status of whether stream ingest is in progress. */
mAlivcLivePusher.isPushing()； 
/* Get the ingest URL. */
mAlivcLivePusher.getPushUrl()；
/* Get the stream ingest performance debugging information. For specific parameters and descriptions of stream ingest performance, see the API documentation or interface comments. */
mAlivcLivePusher.getLivePushStatsInfo();
/* Get the version number. */
mAlivcLivePusher.getSDKVersion();
/* Set the log level to filter the desired debugging information as needed. */
mAlivcLivePusher.setLogLevel(AlivcLivePushLogLevelAll);
/* Get the current SDK status. */
mAlivcLivePusher.getCurrentStatus();
/* Get the last error code. If there is no error, it returns ALIVC_COMMON_RETURN_SUCCESS. */
mAlivcLivePusher.getLastError();

Integrate the retouching feature

To use the retouching feature in the Push SDK, you must import the retouching library and configure the corresponding callbacks.

1. Import the retouching library and retouching panel using Maven. Add the following code to the build.gradle file of your project. For the latest version of the Queen SDK, see the latest Demo:

   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'
   }

   You can also integrate the LiveBeauty module from the Demo:

   File or folder	Feature description
   live_beauty	Basic abstract class for retouching
   queen_beauty	Basic UI control for retouching

2. Get the LiveBeauty plugin library.

   1. Use the clone command to download the plugin library code from this path (LiveBeauty) to your local machine.

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

   2. Open the command line in the root directory of your Android Studio project. Run the following code, and then use File > New > Import Module  to import the LiveBeauty module into your Android project.

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

      Note

      In the sample code, "***/***/***" represents the location where you want to place the LiveBeauty module.

   3. In the project's settings.gradle file, add the module's path:

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

      Note

      In the sample code, "app" represents the main module.

   4. In the main module's build.gradle file, add a dependency on the LiveBeauty module:

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

   5. Click File > Sync Project with Gradle Files. Wait for Gradle to sync. Then, you can use the LiveBeauty module.

3. Configure the retouching plugin UI module.

   1. In your project's layout XML file, add the QueenBeautyMenu control. For example:

      <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. In the Activity, initialize QueenBeautyMenu. For example:

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

4. Set the face detection and retouching callbacks.

   To integrate a third-party retouching library, you can set the setCustomDetect and setCustomFilter callbacks.

   • The data parameter returned in the customDetectProcess (long data, int width, int height, int rotation, int format, long extra) callback function of AlivcLivePushCustomDetect is a pointer to the captured data. A third-party retouching library can recognize or process the data from this pointer.

   • The inputTexture parameter returned in the customFilterProcess (int inputTexture, int textureWidth, int textureHeight, long extra) callback function of AlivcLivePushCustomFilter is the texture of the image. A third-party retouching library can process this texture. To return a processed texture, return its texture ID. Otherwise, return the original inputTexture.

   Sample code

   /**
    * Face detection callback.
    */
   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() {
   
       }
   });
   
   /**
    * Retouching callback.
    */
    
    /**
    * Initialize BeautyManager.
    */
   mAlivcLivePusher.setCustomFilter(new AlivcLivePushCustomFilter() {
       @Override
       public void customFilterCreate() {
           initBeautyManager();
       }
   
    /**
    * Process the ingest video stream and add retouching 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();
       }
   });