ApsaraVideo VOD:Advanced features

Play videos that have transparency configurations

/**
 * Set the alpha render mode
 *
 * @param alphaRenderMode The alpha render mode. See {@link AlphaRenderMode}.
 */
abstract public void setAlphaRenderMode(AlphaRenderMode alphaRenderMode);

//--------------Configure the view-------------
// Configure a transparent view.
//TextureView
TextureView aliplayerView; // The view used for playback.
aliplayerView.setOpaque(false);

//SurfaceView
SurfaceView aliplayerView; // The view used for playback.
aliplayerView.getHolder().setFormat(PixelFormat.TRANSLUCENT);
aliplayerView.setZOrderOnTop(true); // Display SurfaceView at the top of the window.

//-----------Configure AliPlayer-----------
// Set the alpha mode.
aliPlayer.setAlphaRenderMode(IPlayer.AlphaRenderMode.RENDER_MODE_ALPHA_AT_RIGHT);
// Specify the material that corresponds to the alpha mode.
UrlSource urlSource = new UrlSource();
urlSource.setUri("https://alivc-player.oss-cn-shanghai.aliyuncs.com/video/%E4%B8%9A%E5%8A%A1%E9%9C%80%E6%B1%82%E6%A0%B7%E6%9C%AC/alpha%E9%80%9A%E9%81%93/alpha_right.mp4");
aliPlayer.setDataSource(urlSource);
aliPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
    @Override
    public void onCompletion() {
        // Optional. If a connection error occurs when the playback of videos in a player instance is complete, you can clear the view.
        aliPlayer.clearScreen();
    }
}
aliPlayer.setAutoPlay(true);
aliPlayer.prepare();

ApsaraVideo Player SDK for Android lets you add or switch external subtitles in SRT, SSA, ASS, or VTT format for videos.

The following is an example:

1. Create a view that displays the subtitles.

   You must create different views for subtitles in different formats.

   Show code

   // Create a view that displays subtitles in the SRT or VTT format.
   SubtitleView subtitleView = new SubtitleView(getContext());
   // For Player SDK V7.6.0 or later, we recommend that you use VttSubtitleView to display subtitles in the SRT or VTT format.
   VttSubtitleView vttSubtitleView = new VttSubtitleView(getContext());
   // Create a view that displays subtitles in the ASS or SSA format.
   AssSubtitleView assSubtitleView = new AssSubtitleView(getContext());
   // Add the view that displays subtitles to the layout view.
   viewGroup.addView(assSubtitleView);

   When you integrate Player SDK V7.6.0 or later and use VttSubtitleView to display SRT and VTT subtitles, configure the following listener:

   // Required for Player SDK 7.6.0 or later
   mAliPlayer.setOnVideoSizeChangedListener(new IPlayer.OnVideoSizeChangedListener() {
       @Override
       public void onVideoSizeChanged(int width, int height) {
           int viewWidth = getWidth();
           int viewHeight = getHeight();
           IPlayer.ScaleMode mode = mVideoListPlayer.getScaleMode();
           SubTitleBase.VideoDimensions videoDimensions = SubTitleBase.getVideoDimensionsWhenRenderChanged(width, height, viewWidth, viewHeight, mode);
           vttSubtitleView.setVideoRenderSize(videoDimensions.videoDisplayWidth, videoDimensions.videoDisplayHeight);
       }
   });

2. Add subtitles.

   Important

   You must configure subtitle files in onPrepared.

   mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
       @Override
       public void onPrepared() {
           // Configure subtitles (must be configured in onPrepared)
           mAliPlayer.addExtSubtitle(EXT_SUBTITLE_URL);
       }
   });

3. Configure listeners for subtitles.

   Show code

   mAliPlayer.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
               @Override
               public void onSubtitleExtAdded(int trackIndex, String url) {
                   // trackIndex: the subtitle index; true: display the specified subtitle; false: hide the specified subtitle
                   mAliPlayer.selectExtSubtitle(trackIndex, true);
               }
   
               @Override
               public void onSubtitleShow(int trackIndex, long id, String data) {
                   // subtitle
                   SubtitleView.Subtitle subtitle = new SubtitleView.Subtitle();
                   subtitle.id = String.valueOf(id);
                   subtitle.content = data;
                   // display the subtitle
                   mSubtitleView.show(subtitle);
               }
   
               @Override
               public void onSubtitleHide(int trackIndex, long id) {
                   // remove the subtitle
                   mSubtitleView.dismiss(String.valueOf(id));
               }
   
               @Override
               public void onSubtitleHeader(int trackIndex, String header) {
               }
           }
       );

External subtitles (custom rendering with rendering components)

Based on VttSubtitleView and WebVttResolver, ApsaraVideo Player SDK fully supports WebVTT external subtitles and allows flexible customization of font size, color, and specific fonts.

1. Create CustomStyleWebVttResolver and implement WebVttResolver.

   public class CustomStyleWebVttResolver extends WebVttResolver {
   
       // Implement the constructor
       public CustomStyleWebVttResolver(Context context) {
           super(context);
           // Initialize fonts and other resources here
       }
   }

2. Override applyTextSpans to customize styles.

   This method is called after the parent class parses basic styles, allowing secondary processing of subtitles.

   • Method 1: Modify VttContentAttribute and call the parent class method.

     /**
      * Override text style application logic to achieve custom styling effects.
      * This method is called after the parent class parses basic styles, allowing secondary processing of properties such as font size and color.
      *
      * @param spannableStringBuilder Used to build styled text
      * @param vttContentAttribute Style attributes of the current text segment (including font, color, size, etc.)
      * @param start Start position of style application (inclusive)
      * @param end End position of style application (exclusive)
      */
     @Override
     protected void applyTextSpans(SpannableStringBuilder spannableStringBuilder, VttContentAttribute vttContentAttribute, int start, int end) {
         // Save original font size (unit: px) for subsequent adjustment
         // Default font size is 0.0533f times the video height
         double originalFontSizePx = vttContentAttribute.fontSizePx;
     
         // Double the font size
         vttContentAttribute.fontSizePx = originalFontSizePx * 2;
         
         // Change font color to red
         vttContentAttribute.mPrimaryColour = Color.argb(255, 255, 0, 0);
     
         // Call the parent class method to apply text styles
         super.applyTextSpans(spannableStringBuilder, vttContentAttribute, start, end);
     }

   • Directly manipulate SpannableStringBuilder to modify WebVTT styles directly.

     Important

     This method may cause loss of native WebVTT styles.

     /**
      * Override text style application logic to achieve custom styling effects.
      * This method is called after the parent class parses basic styles, allowing secondary processing of properties such as font size and color.
      *
      * @param spannableStringBuilder Used to build styled text
      * @param vttContentAttribute Style attributes of the current text segment (including font, color, size, etc.)
      * @param start Start position of style application (inclusive)
      * @param end End position of style application (exclusive)
      */
     @Override
     protected void applyTextSpans(SpannableStringBuilder spannableStringBuilder, VttContentAttribute vttContentAttribute, int start, int end) {
         // Set font color
         spannableStringBuilder.setSpan(
             new ForegroundColorSpan(Color.RED),
             start, end,
             Spanned.SPAN_EXCLUSIVE_EXCLUSIVE
         );
         
         // Set absolute font size
         spannableStringBuilder.setSpan(
             new AbsoluteSizeSpan(20), // Unit: px
             start, end,
             Spanned.SPAN_EXCLUSIVE_EXCLUSIVE
         );
         
         // Set relative font size
         // spannableStringBuilder.setSpan(
         //     new RelativeSizeSpan(2.0f), // Multiple of TextView default font size
         //     start, end,
         //     Spanned.SPAN_EXCLUSIVE_EXCLUSIVE
         // );
     }

3. Configure a custom font (Typeface).

   1. Load the custom font from the asset/fonts/ directory of your project.

      private Typeface mTypeface;
      
      public CustomStyleWebVttResolver(Context context) {
          super(context);
          initializeFonts(context);
      }
      
      private void initializeFonts(Context context) {
          try {
              // Load font from assets/fonts/
              mTypeface = Typeface.createFromAsset(context.getAssets(), "fonts/LongCang.ttf");
          } catch (Exception e) {
              Log.e("Font", "Failed to load font", e);
              mTypeface = Typeface.DEFAULT; // Safe fallback
          }
      }

   2. Apply the custom font to subtitles.

      @Override
      protected void applyTextSpans(SpannableStringBuilder builder, VttContentAttribute attr, int start, int end) {
          // Apply custom font
          // Must be placed after super.applyTextSpans() to override fonts possibly set by the parent class.
          // super.applyTextSpans() is optional.
          if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
              builder.setSpan(new TypefaceSpan(mTypeface), start, end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
          } else {
              builder.setSpan(new CustomTypefaceSpan(mTypeface), start, end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
          }
      }

      Support for older Android versions: Because TypefaceSpan in Android P (API 28) and earlier does not support direct Typeface objects, you must implement a custom MetricAffectingSpan.

      /**
        * Custom Typeface Span class
        * Inherits from MetricAffectingSpan to correctly apply Typeface during text drawing and measurement.
        * Solves the issue where standard TypefaceSpan cannot directly use Typeface objects.
      */
      private static class CustomTypefaceSpan extends MetricAffectingSpan {
      
          // Custom font to apply
          private final Typeface typeface;
      
          /**
            * Constructor
            *
            * @param typeface Typeface object to apply (must not be null)
            */
          public CustomTypefaceSpan(Typeface typeface) {
              this.typeface = typeface;
          }
      
          /**
            * Update text drawing state
            * Called during actual text drawing to set the paint font.
            *
            * @param tp TextPaint object used to draw text
            */
          @Override
          public void updateDrawState(TextPaint tp) {
              tp.setTypeface(typeface);
          }
      
          /**
            * Update text measurement state
            * Called during text layout calculation (such as width, line breaks) to ensure measurements match actual drawing.
            *
            * @param p TextPaint object used to measure text
            */
          @Override
          public void updateMeasureState(TextPaint p) {
              p.setTypeface(typeface);
          }
      }

4. Integrate into the player.

   1. Initialize the subtitle view.

      // Initialize subtitleView
      private void initSubtitleView() {
          // Get context
          Context context = getContext();
      
          // Create CustomStyleWebVttResolver 
          CustomStyleWebVttResolver mResolver = new CustomStyleWebVttResolver(context);
      
          // Create VttSubtitleView and pass CustomStyleWebVttResolver
          VttSubtitleView mVttSubtitleView = new VttSubtitleView(context, mResolver);
      
          // Add to video container
          rootView.addView(mVttSubtitleView);
      }

   2. Bind external subtitle callbacks.

      // Configure subtitle listener
      mAliPlayer.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
          @Override
          public void onSubtitleExtAdded(int trackIndex, String url) {
              mAliPlayer.selectExtSubtitle(trackIndex, true);
          }
      
          @Override
          public void onSubtitleShow(int trackIndex, long id, String data) {
              if (mVttSubtitleView != null) {
                  // Show subtitle
                  mVttSubtitleView.show(id, data); 
              }
          }
      
          @Override
          public void onSubtitleHide(int trackIndex, long id) {
              // Hide subtitle
              mVttSubtitleView.dismiss(id);
          }
      
          @Override
          public void onSubtitleHeader(int i, String header) {
              if (!TextUtils.isEmpty(header)) {
                  // Apply WebVTT header styles
                  mVttSubtitleView.setVttHeader(header);
              }
          }
      });

If the current model is in the H.265 model blacklist in the cloud or H.265 streams fail to decode, adaptive streaming is triggered. If you have configured a secondary H.264 stream, the system automatically plays the secondary H.264 stream. If you do not configure a secondary stream, software decoding is automatically used for H.265 playback.

The following sample code describes how to configure a secondary stream:

// Create a map on the application layer to store the primary stream URLs and secondary stream URLs as key-value pairs. The system queries the corresponding secondary URL based on the primary stream URL during switching.
 AliPlayerGlobalSettings.setAdaptiveDecoderGetBackupURLCallback(new AliPlayerGlobalSettings.OnGetBackupUrlCallback() {
    @Override
    public String getBackupUrlCallback(int oriBizScene, int oriCodecType, String original_url) {
        String kurl = original_url;
        if (!H265toH264Map.get(kurl).isEmpty()) {
            return H265toH264Map.get(kurl);
        } else {
            return "";
        }
    }
});

ApsaraVideo Player SDK for Android integrates specific configurations of ApsaraVideo VOD to support video preview. Only VidSts and VidAuth sources can be previewed. We recommend that you preview only VidAuth sources in ApsaraVideo VOD. For more information about how to configure and use the preview feature, see Preview videos.

VidSts vidSts = new VidSts;
....
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
configGen.setPreviewTime(20);// Set the preview duration to 20 seconds.
vidSts.setPlayConfig(configGen);// Specify the video source.
...

ApsaraVideo Player SDK for Android provides the PlayerConfig class for configuring buffer and latency settings. Sample code:

// Obtain the configuration information.
PlayerConfig config = aliPlayer.getConfig();
// Set the maximum latency. This parameter is valid only for live streaming. If the latency is excessively high, Player SDK synchronizes frames to ensure that the latency does not exceed the limit. 
config.mMaxDelayTime = 5000;
// Set the maximum buffer duration. Unit: millisecond. This parameter specifies the maximum buffer duration for the player to load data at a time. 
config.mMaxBufferDuration = 50000;
// Set the peak buffer duration. Unit: millisecond. When the network conditions are poor, the player stops loading data after the peak buffer duration elapses. 
config.mHighBufferDuration = 3000;
// Set the startup buffer duration. Unit: millisecond. A smaller value indicates a shorter startup duration. In this case, the player starts to load data soon after the playback starts. 
config.mStartBufferDuration = 500;
....// Configure other settings.
// Set the maximum cache duration. Unit: millisecond. Default value: 0. 
config.mMaxBackwardBufferDurationMs = 0;

// Configure the settings for the player.
aliPlayer.setConfig(config);

Picture-in-Picture (PiP)

Procedure:

1. In the AndroidManifest.xml file, declare the PiP permission.

   <activity
     android:name=".PictureInPictureActivity"
     android:exported="true"
     android:supportsPictureInPicture="true"
     android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation" />

2. Switch the target Activity to PiP mode.

   Rational aspectRatio = new Rational(16, 9); // Aspect ratio for PiP. Adjust based on your business needs.
   PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
   pipBuilder.setAspectRatio(aspectRatio);
   enterPictureInPictureMode(pipBuilder.build());

   You can trigger PiP mode from an OnClick event, when leaving the app, or when returning to the app. Implementation methods are as follows:

   OnClick (click event) trigger

   button.setOnClickListener(new View.OnClickListener() {
       @Override
       public void onClick(View v) {
           Rational aspectRatio = new Rational(16, 9); // Aspect ratio for PiP
           PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
           pipBuilder.setAspectRatio(aspectRatio);
           enterPictureInPictureMode(pipBuilder.build());
       }
   });

   Trigger when leaving the app

   @Override
   protected void onUserLeaveHint() {
       super.onUserLeaveHint();
       Rational aspectRatio = new Rational(16, 9); // Aspect ratio for PiP
       PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
       pipBuilder.setAspectRatio(aspectRatio);
       enterPictureInPictureMode(pipBuilder.build());
   
       Log.e(TAG, "PiP onUserLeaveHint");
   }

   Trigger when returning to the app

   @Override
   public void onBackPressed() {
       super.onBackPressed();
       // Trigger from back press
       enterPictureInPictureMode();
   }

3. Handle UI for PiP show/hide.

   @Override
   public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode, Configuration newConfig) {
       super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig);
       if (isInPictureInPictureMode) {
           // Handle entering PiP mode
           // Hide UI
           Log.e(TAG, "Entered PiP mode");
       } else {
           // Handle exiting PiP mode
           // Show UI 
           Log.e(TAG, "Exited PiP mode");
       }
   }

Live Streaming RTS Degradation

For more information, see RTS live streaming.

ApsaraVideo Player SDK for Android uses the setOutputAudioChannel method to specify the output audio channel. If the input source contains two audio channels, you can switch between the left and right audio channels. If the input source contains only one audio channel, the outputAudioChannel configuration is invalid.

/*
Specify OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_LEFT to use the left audio channel for playback.
Specify OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_RIGHT to use the right audio channel for playback.
Specify OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_NONE to use the audio channel settings of the input file.
*/
aliPlayer.setOutputAudioChannel();

You can configure a listener to obtain information about audio and video streams. Encrypted audio and video streams cannot be parsed.

// Optional. Specify whether to return the address of the underlying data.
IPlayer.RenderFrameCallbackConfig config = new IPlayer.RenderFrameCallbackConfig();
config.mVideoDataAddr = true;// Specify whether to return only the address of the underlying video data.
config.mAudioDataAddr = true;// Specify whether to return only the address of the underlying audio data.
aliPlayer.setRenderFrameCallbackConfig(config);

// Optional. Return texture_oes_id for RenderFrame after hardware decoding and return the source data for RenderFrame after software decoding.
aliPlayer.enableHardwareDecoder(true);
// Configure a listener to obtain information about audio and video streams.
aliPlayer.setOnRenderFrameCallback(frameInfo -> {
    if (frameInfo.frameType == FrameInfo.FrameType_video) {
        // The video data.
    } else {
        // The audio data.
    }
    return false;
});

You can set the background color of the player when you use ApsaraVideo Player SDK for Android. The following sample code provides examples on how to declare and call the method:

API example

/**
 * Set the background color of the video.
 *
 * @param color  ARGB
 *
 */
/****
 * Set video background color
 * @param color  ARGB
 */
abstract public void setVideoBackgroundColor(int color);

Usage Notes

// The parameter value is an eight-digit hexadecimal ARGB color value. The first two digits of an eight-digit ARGB color value represent alpha, the next two represent red, the next two represent green, and the last two represent blue.
// For example, a value of 0x0000ff00 specifies green.
aliPlayer.setVideoBackgroundColor(0x0000ff00);

Specify a domain name for vidAuth-based playback

The vidAuth method lets you specify fields such as the domain name associated with the vid. For details about the supported fields, see GetPlayInfo request parameters. The API and its usage are described below:

API Example

/**
 * Set the playback parameters.
 *
 * @param playConfig The playback parameters.
 */
public void setPlayConfig(VidPlayerConfigGen playConfig);

Usage notes

Specify the playDomain parameter when you call addPlayerConfig in VidPlayerConfigGen.

vidAuth = new VidAuth();
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
// Add the playDomain field. For more information about configurable fields, see:
// https://www.alibabacloud.com/help/zh/vod/developer-reference/api-vod-2017-03-21-getplayinfo
configGen.addPlayerConfig("playDomain", "com.xxx.xxx");
vidAuth.setPlayConfig(configGen);

H.266 decoding plug-in

H.266 (VVC/Versatile Video Coding), as the latest video coding standard, significantly reduces bitrates while maintaining the same visual quality. To optimize performance and control the main SDK size, the H.266 decoding capability is packaged as a separate plug-in for on-demand integration.

Prerequisites

1. The player or all-in-one SDK version is V7.6.0 or later.

2. You have obtained a Professional Edition license. For details, see Get a Player SDK license.

3. ApsaraVideo Player with the H.266 decoding plug-in supports playback of H.266 videos encoded by ApsaraVideo VOD transcoding only.

Integrate the plug-in

// x.x.x must match the Player SDK version number
com.aliyun.sdk.android:AlivcVVCCodec:x.x.x

// x.x.x must match the all-in-one SDK version number
com.aliyun.sdk.android:AlivcVVCCodec:x.x.x-aio

Activate the plug-in

AliPlayerGlobalSettings.enableCodecPlugin("vvc", true);

Related error codes

For error codes related to the H.266 decoding plug-in, see Common issues across platforms.

Automatically refresh playback sources

Enabling automatic playback source refresh prevents playback interruptions caused by expired authentication. This feature triggers a listener when a source expires and retrieves a new URL to ensure continuous and smooth video playback.

Prerequisites

1. The player or all-in-one SDK version is V7.9.0 or later.

2. You use VidAuth sources for playback or have configured URL signing for your business.

/**
 * Set the VidAuth source expiration listener.
 *
 * This feature enables automated VidAuth source refresh to avoid playback interruptions
 * caused by expiration. When the listener is triggered, you can refresh the VidAuth source
 * and return the updated VidAuth using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener The interface for listening to VidAuth source expiration events. See {@link OnVidAuthExpiredListener}.
 */
/****
 * Sets the listener for VidAuth source expiration events.
 *
 * This feature enables automated VidAuth source refresh to avoid playback interruptions
 * caused by expiration. When the listener is triggered, you can refresh the VidAuth source
 * and return the updated VidAuth using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener The interface for listening to VidAuth source expiration events. See {@link OnVidAuthExpiredListener}.
 *
 */
abstract public void setOnVidAuthExpiredListener(OnVidAuthExpiredListener listener);

/**
 * VidAuth source expiration notification listener, used to handle VidAuth source expiration events.
 */
/****
 * Listener for VidAuth source expiration notifications.
 * Handles events when a VidAuth source expires.
 */
public interface OnVidAuthExpiredListener {

    /**
     * Called when the player detects that the VidAuth source has expired.
     *
     * You can refresh the VidAuth source in this callback and return the new VidAuth
     * using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired VidAuth source object. See {@link VidAuth}.
     * @param callback The callback used to provide the updated VidAuth source to the player. See {@link SourceRefreshCallback}.
     */
    /****
     * Called when the player detects that the VidAuth source has expired.
     *
     * You can refresh the VidAuth source in this callback and return the new VidAuth
     * using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired VidAuth source object. See {@link VidAuth}.
     * @param callback The callback used to provide the updated VidAuth source to the player. See {@link SourceRefreshCallback}.
     */
    void onVidAuthExpired(VidAuth expiredSource, SourceRefreshCallback<VidAuth> callback);
}

/**
 * Playback source refresh callback interface, used to handle playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as URL source or VidAuth source. When the player triggers a refresh request,
 * the refresh result can be returned via this interface by invoking either the `onSuccess` or `onError` method.
 */
/****
 * A callback interface for handling playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as URL source or VidAuth source. When the player triggers a refresh request,
 * the refresh result can be returned via this interface by invoking either the `onSuccess` or `onError` method.
 */
public interface SourceRefreshCallback<T extends SourceBase> {
    /**
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object containing the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. Developers should provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    /****
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object containing the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. Developers should provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    void onSuccess(T newSource);

    /**
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string describing the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. Developers can use the `errorMsg`
     * to capture details of the failure and proceed with subsequent handling.
     */
    /****
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string describing the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. Developers can use the `errorMsg`
     * to capture details of the failure and proceed with subsequent handling.
     */
    void onError(String errorMsg);
}

// Set the VID playback credential expiration listener
aliPlayer.setOnVidAuthExpiredListener(new AliPlayer.OnVidAuthExpiredListener() {
    @Override
    public void onVidAuthExpired(VidAuth vidAuth, UrlPlayer.SourceRefreshCallback<VidAuth> sourceRefreshCallback) {
        
        String vid = vidAuth.getVid();

        // ------------------- User implementation starts -------------------
        // Call your own function to obtain a new PlayAuth from your app server.
        // clinetGetPlayAuthFunction is a sample function name. Replace it with your own implementation.
        clinetGetPlayAuthFunction(vid, new PlayAuthCallback() {
            
            /**
             * Callback for successfully obtaining a new credential.
             * @param newPlayAuth New playback credential string obtained from your server.
             */
            @Override
            public void onAuthSuccess(String newPlayAuth) {                
                // 1. Update the old vidAuth object with the new PlayAuth
                vidAuth.setPlayAuth(newPlayAuth);
                
                // 2. Return the updated object to the player via the SDK callback
                sourceRefreshCallback.onSuccess(vidAuth);
            }

            /**
             * Callback for failing to obtain a new credential.
             * @param errorMessage Detailed error message.
             */
            @Override
            public void onAuthError(String errorMessage) {                
                // Return the error message to the player via the SDK callback
                sourceRefreshCallback.onError(errorMessage);
            }
        });
        // ------------------- User implementation ends -------------------
    }
});

/**
 * Set the URL source expiration listener.
 *
 * This feature enables URL refresh to avoid playback interruptions caused by
 * URL expiration due to authentication. When the listener is triggered,
 * you can refresh the URL source and return the updated URL source using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener Listener for handling URL source expiration events. See {@link OnURLSourceExpiredListener}.
 *
 * <p>For more information on configuring URL authentication, see
 * <a href="https://www.alibabacloud.com/help/zh/vod/user-guide/configure-url-signing?spm=a2c4g.11186623.0.0.560c4140fGh8MW">URL authentication documentation</a>.</p>
 */
/****
 * Sets the listener for URL source expiration events.
 *
 * This feature enables URL refresh to avoid playback interruptions caused by
 * URL expiration due to authentication. When the listener is triggered,
 * you can refresh the URL source and return the updated URL source using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener Listener for handling URL source expiration events. See {@link OnURLSourceExpiredListener}.
 *
 * <p>For more information on configuring URL authentication, see
 * <a href="https://www.alibabacloud.com/help/zh/vod/user-guide/configure-url-signing?spm=a2c4g.11186623.0.0.560c4140fGh8MW">URL authentication documentation</a>.</p>
 */
abstract public void setOnURLSourceExpiredListener(OnURLSourceExpiredListener listener);

/**
 * Playback source refresh callback interface, used to handle playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as URL source or VidAuth source. When the player triggers a refresh request,
 * the refresh result can be returned via this interface by invoking either the `onSuccess` or `onError` method.
 */
/****
 * A callback interface for handling playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as URL source or VidAuth source. When the player triggers a refresh request,
 * the refresh result can be returned via this interface by invoking either the `onSuccess` or `onError` method.
 */
public interface SourceRefreshCallback<T extends SourceBase> {
    /**
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object containing the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. Developers should provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    /****
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object containing the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. Developers should provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    void onSuccess(T newSource);

    /**
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string describing the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. Developers can use the `errorMsg`
     * to capture details of the failure and proceed with subsequent handling.
     */
    /****
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string describing the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. Developers can use the `errorMsg`
     * to capture details of the failure and proceed with subsequent handling.
     */
    void onError(String errorMsg);
}

/**
 * URL source expiration notification listener, used to process expired sources and prevent playback interruptions.
 */
/****
 * Listener for URL source expiration notifications.
 * This helps process expired sources and prevents playback interruptions.
 */
public interface OnURLSourceExpiredListener {

    /**
     * Called when the player detects that the URL source (UrlSource) has expired.
     *
     * You can refresh the URL source in this callback and return the new UrlSource
     * using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired UrlSource object. See {@link UrlSource}.
     * @param callback The refresh callback used to return the updated UrlSource to the player. See {@link SourceRefreshCallback}.
     */
    /****
     * Called when the player detects that the URL source (UrlSource) has expired.
     *
     * You can refresh the URL source in this callback and return the new UrlSource
     * using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired UrlSource object. See {@link UrlSource}.
     * @param callback The refresh callback used to return the updated UrlSource to the player. See {@link SourceRefreshCallback}.
     */
    void onUrlSourceExpired(UrlSource expiredSource, SourceRefreshCallback<UrlSource> callback);
}

// Set the URL expiration listener for the player
mAliyunVodPlayer.setOnURLSourceExpiredListener(new UrlPlayer.OnURLSourceExpiredListener() {
    @Override
    public void onUrlSourceExpired(UrlSource urlSource, UrlPlayer.SourceRefreshCallback<UrlSource> sourceRefreshCallback) {
        String expiredUrl = urlSource.getUri();
        Log.d(TAG, "[onUrlSourceExpired] Received expired URL: " + expiredUrl);

        // 1. Check if the authentication key is valid (assuming authenticationKey is a member variable)
        if (authenticationKey == null || authenticationKey.trim().isEmpty()) {
            Log.e(TAG, "Refresh failed: Authentication key is empty.");
            sourceRefreshCallback.onError("REFRESH_ERROR: Authentication key is missing.");
            return; // Invalid key, exit early
        }

        // 2. Calculate the expiration time for the playback URL (validity period)
        // Use the class member validTime if valid, otherwise default to 3600 seconds (1 hour)
        long validityDuration = (AliyunVodPlayerView.this.validTime > 0) ? validTime : 3600;
        long newExpireTime = (System.currentTimeMillis() / 1000) + validityDuration;

        // 3. Extract the original URL from the expired URL (using signing method A as an example)
        // Restore the original resource URL by removing the parameter part (e.g., "?auth_key=")
        int authKeyIndex = expiredUrl.indexOf("?auth_key=");
        if (authKeyIndex == -1) {
            authKeyIndex = expiredUrl.indexOf("&auth_key=");
        }
        // Ensure safe handling even if auth_key is not found
        String originalUrl = (authKeyIndex != -1) ? expiredUrl.substring(0, authKeyIndex) : expiredUrl;

        // 4. Generate a new authenticated URL using the utility class
        String newAuthUrl = CdnAuthUtil.aAuth(originalUrl, authenticationKey, newExpireTime);

        // 5. Check the generated authenticated URL and return the result via the callback
        if (newAuthUrl != null && !newAuthUrl.isEmpty()) {
            Log.i(TAG, "Refresh success, new URL: " + newAuthUrl);
            // Create a UrlSource object and set the new URL as required by the SDK
            UrlSource resultSource = new UrlSource();
            resultSource.setUri(newAuthUrl);
            sourceRefreshCallback.onSuccess(resultSource);
        } else {
            Log.e(TAG, "Refresh failed: Failed to generate new authorized URL.");
            sourceRefreshCallback.onError("REFRESH_ERROR: Failed to generate new URL.");
        }
    }
});

Utility function supplement

Take signing method A as an example.

// Function to generate an authenticated URL
private String generateAuthUrl(String uri, String key, long exp) {
    Pattern uriPattern = Pattern.compile("^(https?://)?([^/?]+)(/[^?]*)?(\\?.*)?$");
    Matcher m = uriPattern.matcher(uri);

    if (!m.matches()) {
        return null;
    }

    String scheme = (m.group(1) != null) ? m.group(1) : "http://";
    String host = m.group(2);
    String path = (m.group(3) != null) ? m.group(3) : "/";
    String args = (m.group(4) != null) ? m.group(4) : "";

    String rand = "0";
    String uid = "0";

    String sstring = String.format("%s-%d-%s-%s-%s", path, exp, rand, uid, key);
    String hashvalue = md5sum(sstring);
    String authKey = String.format("%d-%s-%s-%s", exp, rand, uid, hashvalue);

    if (!args.isEmpty()) {
        return String.format("%s%s%s%s&auth_key=%s", scheme, host, path, args, authKey);
    } else {
        return String.format("%s%s%s%s?auth_key=%s", scheme, host, path, args, authKey);
    }
}

// Utility function to calculate MD5
private String md5sum(String src) {
    try {
        MessageDigest md = MessageDigest.getInstance("MD5");
        md.update(src.getBytes(StandardCharsets.UTF_8));
        byte[] digest = md.digest();

        StringBuilder hexString = new StringBuilder();
        for (byte b : digest) {
            hexString.append(String.format("%02x", b));
        }
        return hexString.toString();
    } catch (NoSuchAlgorithmException e) {
        throw new RuntimeException("MD5 algorithm not found", e);
    }
}

Switch bound network interface controllers (NICs)

ApsaraVideo Player SDK for Android provides the AliPlayerGlobalSettings.enableSwitchNIC method to automatically switch NICs during network anomalies, ensuring stable resource playback. Sample code:

AliPlayerGlobalSettings.enableSwitchNIC(true);

ApsaraVideo Player SDK for Android supports pre-rendering of the first frame before playback starts. This improves the startup loading duration.

The following is an example:

aliPlayer.setOption(ALLOW_PRE_RENDER, 1);

ApsaraVideo Player SDK for Android lets you cache videos during playback. This reduces the startup loading time, accelerates the seeking process, reduces playback latency, and reduces traffic consumption during loop playback.

Enable local caching

// Enable local caching (default path)
AliPlayerGlobalSettings.enableLocalCache(true, this);

/**
 *  You can also use the following code to configure caching.
 *  Enable local caching. After this feature is enabled, a media file is cached on your device. 
 *  @param enable: Specifies whether to enable the local caching feature. Valid values: true and false. true indicates that the local caching feature is enabled and false indicates that the local caching feature is disabled. Default value: false. 
 *  @param maxBufferMemoryKB: This parameter is deprecated in V5.4.7.1 or later.
 *  @param localCacheDir: Required. The directory of the cached file, which is an absolute path. 
 *  AliPlayerGlobalSettings.enableLocalCache(enable, maxBufferMemoryKB, localCacheDir);
 */

/**
 * Configure settings for clearing cached files. 
 * @param expireMin - This parameter is deprecated in V5.4.7.1 or later. 
 * @param maxCapacityMB - The maximum size of cached data. Unit: MB. By default, the maximum size of cached data is 20 GB. If the specified maximum size is exceeded, the system deletes cached files based on the time when the file is cached until the size of the cached data is less than or equal to the specified maximum size. During this process, the system preferentially deletes the earliest cache files. 
 * @param freeStorageMB - The minimum free space of the disk. Unit: MB. Default value: 0. If the idle space of the disk is less than the specified minimum space, the system deletes cached files based on the time when the file is cached until the idle space of the disk is greater than or equal to the specified minimum space. During this process, the system preferentially deletes the earliest cache files. 
 * public static void setCacheFileClearConfig(long expireMin,
 *         long maxCapacityMB,
 *         long freeStorageMB)
 */

 /**
  * Configure the callback for the URL hash value of a video file. If you do not configure the callback, the SDK calculates the URL hash value using the MD5 algorithm. 
  * public static void setCacheUrlHashCallback(AliPlayerGlobalSettings.OnGetUrlHashCallback cb)
  */

Enable or disable local caching for a single URL

// Obtain the configuration information.
PlayerConfig config = aliPlayer.getConfig();
// Configure whether to enable local caching for the playback URL. Default value: true. Local caching for the URL takes effect only when local caching is enabled in AliPlayerGlobalSettings and the value of this parameter is true. If the value of this parameter is false, the local caching for the URL is disabled. 
config.mEnableLocalCache = false;
....// Configure other settings.

// Configure the settings for the player.
aliPlayer.setConfig(config);

ApsaraVideo Player SDK for Android supports video preload, which is an upgrade of the local caching feature. The video preload feature lets you specify the maximum size of memory that can be occupied by cached videos. This helps reduce the startup loading duration.

AliPlayerGlobalSettings.enableNetworkBalance(false);

1. Enable the local caching feature. For more information, see Configure local caching.

2. Configure the data source.

   VidAuth (recommended)

   VidAuth vidAuth = new VidAuth();
   vidAuth.setVid("Vid information");// Required. The ID of the video. 
   vidAuth.setPlayAuth("<yourPlayAuth>");// Required. The playback credential, which is generated by calling GetVideoPlayAuth. 
   vidAuth.setRegion("Access region");// For Player SDK V5.5.5.0 or later, this parameter is deprecated. The player automatically parses the region information. For Player SDK V5.5.5.0 or earlier, this parameter is required. Specify the ID of the region in which ApsaraVideo VOD is activated for this parameter. Default value: cn-shanghai. 
   vidAuth.setQuality("Selected definition") //"AUTO" indicates adaptive bitrate

   VidSts

   VidSts vidSts = new VidSts();
   vidSts.setVid("Vid information");// Required. The ID of the video. vidSts.setAccessKeyId("<yourAccessKeyId>");// Required. The AccessKey ID that is generated when the temporary STS token is issued. To generate the AccessKey ID, call the AssumeRole operation in STS.  vidSts.setAccessKeySecret("<yourAccessKeySecret>");// Required. The AccessKey secret that is generated when the temporary STS token is issued. To generate the AccessKey secret, call the AssumeRole operation in STS.  vidSts.setSecurityToken("<yourSecurityToken>");// Required. The STS token. To obtain the STS token, call the AssumeRole operation in STS.  vidSts.setRegion("Access region");// Required. The region in which ApsaraVideo VOD is activated. Default value: cn-shanghai.
   vidSts.setQuality("Selected definition") //"AUTO" indicates adaptive bitrate

   UrlSource

   UrlSource urlSource = new UrlSource();
   urlSource.setUri("Playback URL");// Required. The playback URL can be the URL of an audio file or video file in ApsaraVideo VOD or on a third-party video-on-demand (VOD) platform.

3. Configure task parameters.

   Note

   This applies only to multi-bitrate videos. Choose one of setDefaultBandWidth, setDefaultResolution, and setDefaultQuality.

   PreloadConfig preloadConfig = new PreloadConfig();
   // Set the bitrate for multi-bitrate streams
   preloadConfig.setDefaultBandWidth(400000);
   // Set the resolution for multi-bitrate streams
   preloadConfig.setDefaultResolution(640 * 480);
   // Set the quality for multi-bitrate streams
   preloadConfig.setDefaultQuality("FD");
   // Set the preload duration
   preloadConfig.setDuration(1000);

4. Add a task listener.

   Show code

   /**
    * Preload listener implementation
    */
   private static class PreloadListenerImpl extends OnPreloadListener {
   
       @Override
       public void onError(@NonNull String taskId, @NonNull String urlOrVid, @NonNull ErrorInfo errorInfo) {
           // Loading failed
       }
   
       @Override
       public void onCompleted(@NonNull String taskId, @NonNull String urlOrVid) {
           // Loading completed
       }
   
       @Override
       public void onCanceled(@NonNull String taskId, @NonNull String urlOrVid) {
          // Loading canceled
       }
   }

5. Build the task and add it to the MediaLoaderV2 instance to start preloading.

   VidAuth (recommended)

   // Build the preload task
   PreloadTask mPreloadTask = new PreloadTask(vidAuth, preloadConfig);
   // Get the MediaLoaderV2 instance
   MediaLoaderV2 mediaLoaderV2 = MediaLoaderV2.getInstance();
   // Add the task and start preloading
   String taskId = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

   VidSts

   // Build the preload task
   PreloadTask mPreloadTask = new PreloadTask(vidSts, preloadConfig);
   // Get the MediaLoaderV2 instance
   MediaLoaderV2 mediaLoaderV2 = MediaLoaderV2.getInstance();
   // Add the task and start preloading
   String taskId = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl);

   UrlSource

   // Build the preload task
   PreloadTask mPreloadTask = new PreloadTask(urlSource, preloadConfig);
   // Get the MediaLoaderV2 instance
   MediaLoaderV2 mediaLoaderV2 = MediaLoaderV2.getInstance();
   // Add the task and start preloading
   String taskId = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

6. Optional: Manage tasks.

   mediaLoaderV2.cancelTask(taskId);// Cancel the preload task with the specified task ID
   mediaLoaderV2.pauseTask(taskId);// Pause the preload task with the specified task ID
   mediaLoaderV2.resumeTask(taskId);// Resume the preload task with the specified task ID

7. Optional: Delete loaded files.

   You can delete loaded files to save space. ApsaraVideo Player SDK for Android does not provide a method to delete loaded files. You must delete the files in the corresponding directory in your application.

The dynamic preloading feature lets you manage cache of the video that is being played and videos that are preloaded. You can also control the number of videos that are preloaded. This helps maintain a balance between playback experience and cost.

// Enable recommended configuration and dynamic preloading
aliListPlayer.setPreloadScene(IListPlayer.SceneType.SCENE_SHORT);

// Configure baseline preload duration
// Set the preload duration to 1,000 milliseconds
PreloadConfig config = new PreloadConfig();
config.mPreloadDuration = 1000;
aliListPlayer.updatePreloadConfig(config);

// Configure the number of videos to preload. Forward and backward preloading are supported.
// 1 specifies the number of videos to preload forward. 3 specifies the number of videos to preload backward.
aliListPlayer.setPreloadCount(1, 3);

// Configure decreasing offset for dynamic preloading
aliListPlayer.enablePreloadStrategy(IListPlayer.StrategyType.STRATEGY_DYNAMIC_PRELOAD_DURATION, true);
aliListPlayer.setPreloadStrategy(IListPlayer.StrategyType.STRATEGY_DYNAMIC_PRELOAD_DURATION, "{\"algorithm\": \"sub\",\"offset\": \"200\"}");

Preloading of multi-bitrate HLS videos

You can preload videos in the same definition as the current video stream when you call the listPlayer method during the playback of multi-bitrate HLS videos. You can use different preloading modes as needed.

  /**
   * The default bitrate for playback and preloading.
   */
  /****
   * default mode, play and preload default bitrate of a stream
   */
  MultiBitratesMode_Default(0),

  /**
   * The preloading mode in which the first frame performance has a higher priority. In this case, the preloaded video is played by default.
   */
  /****
   * First frame cost (FC) priority, decrease first frame cost. only play bitrate of the hls stream which has been preloaded.
   */
  MultiBitratesMode_FCPrio(1),

  /**
   * The preloading mode in which the first frame performance and playback smoothness have the same priority. In this case, the same bitrate is used before and after you call the moveToNext method to switch videos.
   */
  /****
   * First frame and play smooth, play the same bitrate before and after moveToNext
   */
  MultiBitratesMode_FC_AND_SMOOTH(2),

  /**
   * The preloading mode in which the playback smoothness has a higher priority. In this case, the bitrate of the previous video is used by default.
   */
  /****
   * Play Smooth priority, play the same bitrate before and after moveToNext.
   */
  MultiBitratesMode_SmoothPrio(3);

// Specify the multi-bitrate preloading mode.
aliListPlayer.SetMultiBitratesMode(preLoadMode);


// Optional. Set the starting bitrate.
aliListPlayer.setDefaultBandWidth(defaultBandWidth)


// Optional. In the onPrepared callback, specify the abr mode.
aliListPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        //abr only effect on multiBitrate m3u8
        aliListPlayer.selectTrack(-1);
    }
});

HTTPDNS

// Enable the enhanced HTTPDNS feature.
AliPlayerGlobalSettings.enableEnhancedHttpDns(true);
// Optional. Add an HTTPDNS pre-resolved domain name.
DomainProcessor.getInstance().addPreResolveDomain("player.***alicdn.com");

HTTP/2

AliPlayerGlobalSettings.setUseHttp2(true);

Create TCP connections before playback requests are initiated over HTTP

You can create Transmission Control Protocol (TCP) connections before playback requests are initiated over HTTP. This reduces waiting time, ensures the timeliness and consistency of video playback, improves user experience, and optimizes the usage of network and system resources. Sample code:

// Specify the domain parameter in the host[:port] format. Separate multiple domain names with semicolons (;). The port parameter is optional.
// Configure globally.
// Add or delete TCP connections. If you specify an empty string, no TCP connections are created.
AliPlayerGlobalSettings.setOption(AliPlayerGlobalSettings.SET_PRE_CONNECT_DOMAIN, "domain1;domain2");

ApsaraVideo Player SDK for Android lets you download videos to local devices for offline playback in ApsaraVideo Player. Normal download mode and secure download mode are supported.

• Normal download

  Videos downloaded in normal download mode are not encrypted by Alibaba Cloud and can be played using third-party players.

• Secure download

  Videos downloaded in secure download mode are encrypted by Alibaba Cloud. You cannot use third-party players to play the downloaded videos. You can use only ApsaraVideo Player to play them.

Usage notes

• You can download only videos played based on VidSts or VidAuth.

• To use the video download feature, you must enable the feature and configure the download mode in the ApsaraVideo VOD console. For more information, see Offline download.

• You can resume video downloads.

Procedure

1. Optional. Configure the security file for encryption verification. You must configure the security file only when you use the secure download mode.

   Note

   Make sure that the information in the security file for encryption verification matches the application information. Otherwise, the video download fails.

   If you use the secure download mode, you must configure the key file generated in the ApsaraVideo VOD console in Player SDK. The key file is used to decrypt and verify the video for download and playback. For more information about how to generate the key file, see the Enable secure download section of the "Configure download settings" topic.

   We recommend that you configure this setting only once in the application. The following example shows how to do so:

   PrivateService.initService(getApplicationContext(),  "The path in which the encryptedApp.dat file is stored"); // We recommend that you store the encryptedApp.dat file on your mobile phone and set this parameter to the path in which the file is stored.

2. Create and configure a video downloader.

   Create a downloader using AliDownloaderFactory. Sample code:

   AliMediaDownloader mAliDownloader = null;
   ......
   // Create a downloader.
   mAliDownloader = AliDownloaderFactory.create(getApplicationContext());
   // Set the path for storing downloaded files.
   mAliDownloader.setSaveDir("The storage path");

3. Configure listeners.

   The downloader provides multiple listeners. Sample code:

   Show code

   mAliDownloader.setOnPreparedListener(new AliMediaDownloader.OnPreparedListener() {
      @Override
      public void onPrepared(MediaInfo mediaInfo) {
          // Listen for the preparation of the content to be downloaded.
      }
   });
   mAliDownloader.setOnProgressListener(new AliMediaDownloader.OnProgressListener() {
      @Override
      public void onDownloadingProgress(int percent) {
          // Listen for the percentage of the download progress.
      }
      @Override
      public void onProcessingProgress(int percent) {
          // Listen for the percentage of the processing progress.
      }
   });
   mAliDownloader.setOnErrorListener(new AliMediaDownloader.OnErrorListener() {
      @Override
      public void onError(ErrorInfo errorInfo) {
          // Listen for download errors.
      }
   });
   mAliDownloader.setOnCompletionListener(new AliMediaDownloader.OnCompletionListener() {
      @Override
      public void onCompletion() {
          // Listen for a successful download.
      }
   });

4. Prepare the download source.

   You can call the prepare method to prepare a download source. VidSts and VidAuth sources are supported. Sample code:

   • VidSts

     // Create a VidSts instance.
     VidSts aliyunVidSts = new VidSts();
     aliyunVidSts.setVid("Vid information"); // The video ID (VideoId).
     aliyunVidSts.setAccessKeyId("<yourAccessKeyId>"); // The AccessKey ID of the temporary STS AccessKey pair. You must generate this by calling the AssumeRole operation of Security Token Service (STS).
     aliyunVidSts.setAccessKeySecret("<yourAccessKeySecret>"); // The AccessKey secret of the temporary STS AccessKey pair. You must generate this by calling the AssumeRole operation of Security Token Service (STS).
     aliyunVidSts.setSecurityToken("<yourSecurityToken>"); // The Security Token Service (STS) token. You must generate this by calling the AssumeRole operation of Security Token Service (STS).
     aliyunVidSts.setRegion("Region where the video-on-demand service is deployed"); // The region where the video-on-demand service is deployed. Default value: cn-shanghai.
     // If you have enabled HLS encryption parameter pass-through in the VOD console and the default parameter name is MtsHlsUriToken, you must configure VidPlayerConfigGen and pass it to vid. For more information, see the following example.
     // If you have not enabled HLS encryption parameter pass-through in the VOD console, you do not need to integrate the following code.
     VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
     vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     aliyunVidSts.setPlayerConfig(vidConfig);
     
     // Prepare the download source.
     mAliDownloader.prepare(aliyunVidSts);

   • VidAuth

     // Create the VidAuth download source.
     VidAuth vidAuth = new VidAuth();
     vidAuth.setVid("Video ID"); // The video ID. 
     vidAuth.setPlayAuth("<yourPlayAuth>");// The playback credential, which is generated by calling GetVideoPlayAuth. 
     vidAuth.setRegion("Access region"); // This parameter is deprecated in ApsaraVideo Player SDK V5.5.5.0 or later. If you use ApsaraVideo Player SDK V5.5.5.0 or later, the player automatically parses the region information. If you use ApsaraVideo Player SDK V5.5.5.0 or earlier, this parameter is required. Specify the ID of the region in which ApsaraVideo VOD is activated for this parameter. Default value: cn-shanghai. 
     // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
     VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
     vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     vidAuth.setPlayerConfig(config);
     // Prepare the download source.
     mAliDownloader.prepare(vidAuth);

   Note

   • The output file and the input file are in the same format and cannot be changed.

   • If you enable parameter pass-through for HLS encryption in the ApsaraVideo VOD console, the default parameter is MtsHIsUriToken. For more information, see Parameter pass-through for HLS encryption. Then, set the MtsHIsUriToken value to the ApsaraVideo VOD source by following the preceding code.

5. After preparation succeeds, select an item to download and start downloading.

   After preparation succeeds, the OnPreparedListener callback is invoked. The TrackInfo object contains information such as video definitions. Select a track to download. Sample code:

   public void onPrepared(MediaInfo mediaInfo) {
       // Preparation succeeded.
       List<TrackInfo> trackInfos = mediaInfo.getTrackInfos();
       // For example, download the first track.
       mAliDownloader.selectItem(trackInfos.get(0).getIndex());
       // Start downloading.
       mAliDownloader.start();
   }

6. (Optional) Update the download source.

   VidSts or VidAuth sources may expire before the download. Therefore, we recommend that you update the download source before you start the download. Sample code:

   // Update the download source.
   mAliDownloader.updateSource(VidSts);
   // Start downloading.
   mAliDownloader.start();

7. Release the downloader after the download succeeds or fails.

   After the download succeeds, call the onCompletion or onError callback to call release to release the downloader. Sample code:

   mAliDownloader.stop();
   mAliDownloader.release();

8. Optional. Delete downloaded files.

   You can delete downloaded files during the download or after the download is complete. Sample code:

   // Delete files through the downloader object.
   mAliDownloader.deleteFile();
   // Delete files through the static method. Returns 0 if successful.
   AliDownloaderFactory.deleteFile("The path of the downloaded folder","Video ID","Video format","Index of the downloaded video");

What to do next

You can play downloaded videos using ApsaraVideo Player. Perform the following steps:

1. After the download completes, obtain the absolute path of the video file.

   String path = mAliDownloader.getFilePath();

2. Set the absolute path of the downloaded video file as the URL source for playback.

    UrlSource urlSource = new UrlSource();
           urlSource.setUri("Playback URL");// Set the absolute path of the downloaded video file. 
           aliPlayer.setDataSource(urlSource);