Use Push SDK for Android

Register the SDK

To obtain and configure a license, integrate a Push SDK license.

Call the license registration API early in your application's lifecycle, before using the Push SDK for Android.

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

• Use the AlivcLiveBase class to set log levels, specify local log paths, and get the SDK version.

• You must call the registerSDK method in AlivcLiveBase to register the SDK license.

• Implement the onLicenceCheck callback in the AlivcLiveBase#setListener interface to asynchronously verify the license configuration.

  Note

  This callback is triggered only after you initialize the pusher instance.

Ingest camera stream

1. Initialize.

   Call the init method after configuring stream ingest parameters:

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

   Note

   AlivcLivePusher does not support multiple instances. Each init call must be paired with a destroy call.

2. Register preview callbacks.

   Call the setLivePushInfoListener method to register preview callbacks:

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

3. Start the preview.

   Start the preview by passing the SurfaceView for the camera preview:

   mAlivcLivePusher.startPreview(mSurfaceView); // Starts the preview. You can also call the asynchronous startPreviewAsync method based on your needs.

4. Start stream ingest.

   Add the following code inside the onPreviewStarted callback method.

   mAlivcLivePusher.startPush(mPushUrl);

   Note

   • Ingest URLs for RTMP and RTS (artc://) are supported. To get URLs, see Generate ingest and streaming URLs.

   • ApsaraVideo Live rejects concurrent stream ingest requests to the same URL.

/* Call to pause a stream that is being ingested. After pausing, the video preview and video stream ingest are held on the last frame, while audio stream ingest continues. */
mAlivcLivePusher.pause();
/* Call to resume a paused stream. After resuming, the audio and video preview and stream ingest return to normal. */
mAlivcLivePusher.resume();
/* Call to stop a stream that is being ingested. After completion, stream ingest stops. */
mAlivcLivePusher.stopPush();
/* Call to stop the preview only when in the previewing state. Calling this while ingesting a stream has no effect. After the preview stops, the preview frame freezes on the last frame. */
mAlivcLivePusher.stopPreview();
/* Call to restart stream ingest when a stream is being ingested or after receiving any error-related callback. In an error state, you can only call this API, reconnectPushAsync, or destroy. Restarting reinitializes all internal resources of AlivcLivePusher, including preview and stream ingest. */
mAlivcLivePusher.restartPush();
/* Call to reconnect a stream when it is being ingested or after receiving an error callback related to AlivcLivePusherNetworkDelegate. In an error state, you can only call this API, restartPush, or destroy. Reconnecting re-establishes the RTMP connection for stream ingest. */
mAlivcLivePusher.reconnectPushAsync();
/* Call to dispose of the stream ingest instance. After disposal, stream ingest and preview stop, and the preview surface is removed. All resources related to AlivcLivePusher are released. */
mAlivcLivePusher.destroy();

/* Switch between the front and rear cameras. */
mAlivcLivePusher.switchCamera();
/* Turn the flash on or off. Turning on the flash has no effect when the front camera is active. */
mAlivcLivePusher.setFlash(true); 
/* Adjust the focal length to zoom the captured image. The zoom range is [0, getMaxZoom()]. */
mAlivcLivePusher.setZoom(5);
/* Manually focus the camera. This requires two parameters: 1. `point` (the coordinates of the point to focus on) and 2. `autoFocus` (whether to enable autofocus for this specific operation). Subsequent autofocus behavior follows the value set by the setAutoFocus API. */
mAlivcLivePusher.focusCameraAtAdjustedPoint(x, y, true);
/* Set whether to enable autofocus. */
mAlivcLivePusher.setAutoFocus(true);
/* Configure mirroring. There are two mirroring APIs: PushMirror for the ingested stream and PreviewMirror for the local preview. PushMirror affects only the playback display, while PreviewMirror affects only the preview display. They do not affect each other. */
mAlivcLivePusher.setPreviewMirror(false);
mAlivcLivePusher.setPushMirror(false);

Ingest screen sharing stream

Screen sharing uses MediaProjection and requires user permission. Pass the permission result data to the SDK. The camera is disabled by default during screen sharing.

// resultData is the screen sharing system intent.
mAlivcLivePushConfig.setMediaProjectionPermissionResultData(resultData);

mAlivcLivePusher.setScreenOrientation(0);

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

Ingest camera and screen sharing streams

You can enable camera ingest during screen sharing. Two approaches are available:

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 gaming stream, the streamer may not want the camera view to obstruct the game. However, viewers can still see the streamer's camera feed in the final stream.

mAlivcLivePusher.startCamera(surfaceView); // Start the camera preview.
mAlivcLivePusher.stopCamera(); // Stop the camera preview.

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

Preview display mode

Three preview display modes are available. The display mode does not affect stream ingest.

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

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

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

The following code provides an example:

mAlivcLivePushConfig.setPreviewDisplayMode(AlivcPreviewDisplayMode.ALIVC_LIVE_PUSHER_PREVIEW_ASPECT_FIT);

Image stream ingest

The SDK can ingest a placeholder image when the app is in the background or the network is poor.

When the app enters the background, video ingest pauses while audio continues. Display a placeholder image to inform viewers:

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

The SDK ingests this image when it detects a low bitrate, reducing video stuttering:

mAlivcLivePushConfig.setNetworkPoorPushImage("path/to/network_poor.png"); // Set the image to ingest in poor network conditions.

Audio-only stream ingest

mAlivcLivePushConfig.setAudioOnly(true);

Ingest external audio and video streams

The SDK supports ingesting audio and video from external sources such as video files.

Enable custom audio and video input first:

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

After enabling custom audio and video input, you can ingest external streams.

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

/**
* This API does not control timing. The caller must 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

Add one or more watermarks in PNG format:

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

Configure video quality

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

mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_RESOLUTION_FIRST); // Prioritize resolution.

mAlivcLivePushConfig.setQualityMode(AlivcQualityModeEnum.QM_FLUENCY_FIRST); // Prioritize fluency.

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

Adaptive resolution

Adaptive resolution automatically lowers the resolution in poor network conditions to improve smoothness:

mAlivcLivePushConfig.setEnableAutoResolution(true); // Enable adaptive resolution. Default is false.

Background music

The SDK supports background music playback, mixing, denoising, in-ear monitoring, and muting:

/* Start playing background music. */
mAlivcLivePusher.startBGMAsync(mPath)；
/* Stop playing background music. If BGM is already playing and you need to switch songs, just call the start background music API again. You do not need to stop the current BGM. */
mAlivcLivePusher.stopBGMAsync();
/* Pause background music. This can only be called after BGM has started playing. */
mAlivcLivePusher.pauseBGM();
/* Resume background music. This can only be called when BGM is paused. */
mAlivcLivePusher.resumeBGM();
/* Enable looping for background music. */
mAlivcLivePusher.setBGMLoop(true);
/* Set the denoise switch. When enabled, non-human sounds in the captured audio are filtered. This may slightly suppress human voices. We recommend letting users choose whether to enable this feature. It is disabled by default. */
mAlivcLivePusher.setAudioDenoise(true);
/* Set the in-ear monitoring switch. This feature is mainly used in karaoke scenarios. When enabled with headphones plugged in, the streamer will hear their own voice. When disabled, they will not. This has no effect if headphones are not plugged in. */
mAlivcLivePusher.setBGMEarsBack(true);
/* Configure mixing to adjust the volume of background music and captured voice. */
mAlivcLivePusher.setBGMVolume(50); // Set background music volume.
mAlivcLivePusher.setCaptureVolume(50); // Set captured voice volume.
/* Mute the audio. This mutes both music and voice input. To mute only music or voice, use the mixing volume adjustment APIs. */
mAlivcLivePusher.setMute(true);

Stream snapshot

Take a snapshot of the local video stream:

// Take a snapshot of the video stream. Parameters: number of images to capture, interval between each capture in seconds, and a callback listener.
pusher.snapshot(1, 1, new AlivcSnapshotListener() {
    @Override
    public void onSnapshot(Bitmap bmp) {
        // You can save the snapshot to a local PNG file. The following code is an example.
        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 lock

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

• For non-system audio and video calls, the SDK captures and ingests sound. Based on your business needs, you can call the mAlivcLivePusher.setMute(true or false) API to determine whether to capture audio when the app is in the background or the screen is locked.

Callbacks

Common methods and APIs

/* In Custom mode, you can adjust the minimum and target bitrates in real time. */
mAlivcLivePusher.setTargetVideoBitrate(800);
mAlivcLivePusher.setMinVideoBitrate(400);
/* Check if the camera supports autofocus. */
mAlivcLivePusher.isCameraSupportAutoFocus();
/* Check if the camera supports flash. */
mAlivcLivePusher.isCameraSupportFlash();
/* Get the current stream ingest status. */
mAlivcLivePusher.isPushing(); 
/* Get the ingest URL. */
mAlivcLivePusher.getPushUrl();
/* Get stream ingest performance and debugging information. For details on performance parameters, see the API reference or interface comments. */
mAlivcLivePusher.getLivePushStatsInfo();
/* Get the SDK version number. */
mAlivcLivePusher.getSDKVersion();
/* Set the log level to filter debugging information as needed. */
mAlivcLivePusher.setLogLevel(AlivcLivePushLogLevelAll);
/* Get the current status of the SDK. */
mAlivcLivePusher.getCurrentStatus();
/* Get the last error code. Returns ALIVC_COMMON_RETURN_SUCCESS if there are no errors. */
mAlivcLivePusher.getLastError();

Integrate retouching

Import the retouching library and configure callbacks to enable retouching.

1. Import the retouching library via Maven. Add the following to your build.gradle file. Check the latest Demo for the SDK version.

   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	Description
   live_beauty	The base abstract class for retouching.
   queen_beauty	Base UI controls for retouching.

2. Get the LiveBeauty retouching plug-in library.

   1. Use the clone command to download the related plugin library code from the LiveBeauty path 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 example code, /*** is a placeholder for the path to 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 example code, "app" is the main module.

   4. Also, in the build.gradle file of the project's main module, add a dependency on the LiveBeauty module:

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

   5. Click File > Sync Project with Gradle Files. After the Gradle sync is complete, you can use the LiveBeauty module.

3. Configure the UI module of the retouching plug-in.

   1. Add the QueenBeautyMenu control to the layout XML file of your project. 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. Initialize QueenBeautyMenu in the Activity. 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 facial recognition and retouching callbacks.

   If you need to integrate a third-party retouching library, set the setCustomDetect and setCustomFilter callbacks.

   • In customDetectProcess, the data parameter is a pointer to captured data for third-party processing.

   • In customFilterProcess, the inputTexture parameter is the image texture for processing. Return the processed texture ID, or the original inputTexture if unmodified.

   Sample code

   /**
    * Facial recognition 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 ingested 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();
       }
   });