ApsaraVideo VOD:Advanced features

Play videos with transparency

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

//--------------View usage-------------
// Set View to transparent
//TextureView
TextureView aliplayerView; // View for playback
aliplayerView.setOpaque(false);

//SurfaceView
SurfaceView aliplayerView; // View for playback
aliplayerView.getHolder().setFormat(PixelFormat.TRANSLUCENT);
aliplayerView.setZOrderOnTop(true); // Place SurfaceView at the top of the display window

//-----------AliPlayer usage-----------
// Set alpha mode
aliPlayer.setAlphaRenderMode(IPlayer.AlphaRenderMode.RENDER_MODE_ALPHA_AT_RIGHT);
// Set material corresponding to alpha mode
UrlSource urlSource = new UrlSource();
urlSource.setUri("https://alivc-player.oss-cn-shanghai.aliyuncs.com/video/business_requirements_sample/alpha_channel/alpha_right.mp4");
aliPlayer.setDataSource(urlSource);
aliPlayer.setOnCompletionListener(new IPlayer.OnCompletionListener() {
    @Override
    public void onCompletion() {
        // Optional: Clear the screen if connection issues occur after single-instance playback is complete.
        aliPlayer.clearScreen();
    }
}
aliPlayer.setAutoPlay(true);
aliPlayer.prepare();

The ApsaraVideo Player SDK for Android supports adding and switching external subtitles. The SDK supports SRT, SSA, ASS, and VTT subtitle formats.

Example:

1. Create a view to display subtitles.

   Create different views based on subtitle formats.

   Click to view the code

   // Used to display SRT and VTT subtitles
   SubtitleView subtitleView = new SubtitleView(getContext());
   // For player V7.6.0 and later, we recommend using VttSubtitleView to display SRT and VTT subtitles
   VttSubtitleView vttSubtitleView = new VttSubtitleView(getContext());
   // Used to display ASS and SSA subtitles
   AssSubtitleView assSubtitleView = new AssSubtitleView(getContext());
   // Add subtitle view to layout view
   viewGroup.addView(assSubtitleView);

   If you are using Player SDK V7.6.0 or later and VttSubtitleView to display SRT and VTT subtitles, you must set the following listener:

   // Required for player V7.6.0 and 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

   Set the subtitle file in onPrepared.

   mAliPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
       @Override
       public void onPrepared() {
           // Subtitle settings (must be set in onPrepared)
           mAliPlayer.addExtSubtitle(EXT_SUBTITLE_URL);
       }
   });

3. Set subtitle-related listeners.

   Click to view the code

   mAliPlayer.setOnSubtitleDisplayListener(new IPlayer.OnSubtitleDisplayListener() {
               @Override
               public void onSubtitleExtAdded(int trackIndex, String url) {
                   // trackIndex: Subtitle index; true: Display specified subtitle; false: Hide 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 subtitle
                   mSubtitleView.show(subtitle);
               }
   
               @Override
               public void onSubtitleHide(int trackIndex, long id) {
                   // Remove subtitle
                   mSubtitleView.dismiss(String.valueOf(id));
               }
   
               @Override
               public void onSubtitleHeader(int trackIndex, String header) {
               }
           }
       );

If the current device model is in the cloud-based H.265 blacklist or if hardware decoding of an H.265 stream fails, adaptive fallback occurs. The fallback process is as follows: If an H.264 backup stream is set, the backup stream plays automatically. If no H.264 backup stream is set, the player automatically falls back to H.265 software decoding.

The following code shows how to set a backup stream:

// The application layer maintains a Map storing all key-value pairs of original URL-backup URL. When switching, query the backup URL in the Map based on the original URL
 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 "";
        }
    }
});

The ApsaraVideo Player SDK for Android, together with ApsaraVideo VOD configurations, implements a preview feature. It supports VidSts and VidAuth (recommended for ApsaraVideo VOD) playback methods. 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);// 20-second preview
vidSts.setPlayConfig(configGen);// Set for playback source
...

The ApsaraVideo Player SDK for Android provides interfaces for setting cache and latency control through PlayerConfig. The following code is an example:

// First, get the configuration
PlayerConfig config = aliPlayer.getConfig();
// Maximum delay. Note: Effective for live streaming. When delay is large, the player SDK performs frame synchronization internally to keep delay within this range.
config.mMaxDelayTime = 5000;
// Maximum buffer duration in ms. Player loads at most this much buffered data each time.
config.mMaxBufferDuration = 50000;
// High buffer duration in ms. When data is being loaded due to poor network conditions, if loaded buffer duration reaches this value, loading state ends.
config.mHighBufferDuration = 3000;
// Start buffer duration in ms. Shorter time means faster startup but may cause quick entry into loading state after playback begins.
config.mStartBufferDuration = 500;
....// Other settings
// Maximum backward buffer duration in ms. Default is 0.
config.mMaxBackwardBufferDurationMs = 0;

// Set the configuration for the player
aliPlayer.setConfig(config);

Picture-in-Picture (PiP)

The procedure is as follows:

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); // PiP aspect ratio, adjustable based on your business needs
   PictureInPictureParams.Builder pipBuilder = new PictureInPictureParams.Builder();
   pipBuilder.setAspectRatio(aspectRatio);
   enterPictureInPictureMode(pipBuilder.build());

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

   Triggered by OnClick

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

   Triggered when leaving the app

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

   Triggered when returning to the app

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

3. Handle the UI for showing and hiding the PiP window.

   @Override
   public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode, Configuration newConfig) {
       super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig);
       if (isInPictureInPictureMode) {
           // Handling when entering PiP mode
           // hide UI
           Log.e(TAG, "Entering PiP mode");
       } else {
           // Handling when exiting PiP mode
           // show UI 
           Log.e(TAG, "Exiting PiP mode");
       }
   }

Live RTS fallback

For more information, see RTS live streaming.

The ApsaraVideo Player SDK for Android uses the setOutputAudioChannel method to set the output sound channel. If the input source is dual-channel, you can use the following method to switch to the left or right channel. If the input source is single-channel, this setting has no effect.

/*
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_LEFT: Switch to left channel for playback,
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_RIGHT: Switch to right channel for playback,
OutputAudioChannel.OUTPUT_AUDIO_CHANNEL_NONE: Do not switch channels, keep input source channel for playback
*/
aliPlayer.setOutputAudioChannel();

Set a listener to obtain audio and video stream data. This feature does not support encrypted streams because they cannot be parsed.

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

// Optional configuration 2: When hardware decoding is enabled, RenderFrame returns texture_oes_id. When software decoding is enabled, RenderFrame returns source data
aliPlayer.enableHardwareDecoder(true);
// Set listener to get audio and video data
aliPlayer.setOnRenderFrameCallback(frameInfo -> {
    if (frameInfo.frameType == FrameInfo.FrameType_video) {
        // Video data
    } else {
        // Audio data
    }
    return false;
});

The ApsaraVideo Player SDK for Android supports setting the background color for player rendering. The API operation and usage instructions are as follows:

API operation example

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

Usage instructions

// Parameter is 8-digit hexadecimal data. The 8 digits are grouped in pairs, representing A (alpha transparency), R (red), G (green), and B (blue) in order
// For example, 0x0000ff00 represents green
aliPlayer.setVideoBackgroundColor(0x0000ff00);

Specify a playback domain name for VidAuth

You can use the VidAuth method to specify fields such as the domain name that corresponds to a VID. For more information about the supported fields, see GetPlayInfo request parameters. The API operation and usage instructions are as follows:

API operation example

/**
 * Sets playback parameters.
 *
 * @param playConfig Playback parameters
 */
public void setPlayConfig(VidPlayerConfigGen playConfig);

Usage instructions

You can use the addPlayerConfig method of the VidPlayerConfigGen interface to add the playDomain field.

vidAuth = new VidAuth();
VidPlayerConfigGen configGen = new VidPlayerConfigGen();
// Add playDomain field. For more information about fields that can be added, see
// https://www.alibabacloud.com/help/en/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) is the next-generation video encoding standard that can significantly save bitrate while maintaining the same image quality. To optimize performance and control the size of the main SDK, the H.266 value-added decoding capability is independently encapsulated as a plug-in, which supports on-demand integration.

Prerequisites

1. The ApsaraVideo Player SDK or All-in-One SDK is version 7.6.0 or later.

2. You have obtained a Professional Edition license. For more information, see Obtain a license for ApsaraVideo Player SDK.

3. The ApsaraVideo Player with the H.266 decoding plug-in supports only H.266 videos that are transcoded by Alibaba Cloud Transcoding.

Integrate the plug-in

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

// x.x.x should match the All-in-One SDK version number you are using
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 FAQ for players on different clients.

Auto-refresh the playback source

Enabling the playback source auto-refresh feature prevents playback interruptions caused by authentication expiration. This feature triggers a listener when the source becomes invalid and obtains a new playback address, ensuring continuous and smooth video playback.

Prerequisites

1. The ApsaraVideo Player SDK or All-in-One SDK is version 7.9.0 or later.

2. You are using a VidAuth source for playback or your business has configured URL signing.

/**
 * 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);

/**
 * 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.
     * VidAuth source expiration includes PlayAuth expiration and playback address expiration.
     *
     * 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);
}

/**
 * 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.
     */
    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.
     */
    void onError(String errorMsg);
}

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

        // ------------------- Start of user implementation -------------------
        // Call your self-implemented function to obtain a new PlayAuth from the app server.
        // clinetGetPlayAuthFunction is an example function name. Replace it with your own implementation.
        clinetGetPlayAuthFunction(vid, new PlayAuthCallback() {
            
            /**
             * Callback for successfully obtaining a new credential.
             * @param newPlayAuth The 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. Pass the updated object back to the player through the SDK's callback
                sourceRefreshCallback.onSuccess(vidAuth);
            }

            /**
             * Callback for failing to obtain a new credential.
             * @param errorMessage Detailed error message.
             */
            @Override
            public void onAuthError(String errorMessage) {                
                // Pass the error message back to the player through the SDK's callback
                sourceRefreshCallback.onError(errorMessage);
            }
        });
        // ------------------- End of user implementation -------------------
    }
});

/**
 * 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);

/**
 * 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.
     */
    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.
     */
    void onError(String errorMsg);
}

/**
 * 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}.
     */
    void onUrlSourceExpired(UrlSource expiredSource, SourceRefreshCallback<UrlSource> callback);
}

// Set the player's URL expiration listener
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 class 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 timeout period (validity) for the playback address
        // If the class member validTime is valid, use it; 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 Type A signing as an example)
        // Restore the original resource address by removing the URL parameter part (such as "?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. Use a utility class to generate a new signed URL
        String newAuthUrl = CdnAuthUtil.aAuth(originalUrl, authenticationKey, newExpireTime);

        // 5. Check the generated signed URL and return the result through the callback
        if (newAuthUrl != null && !newAuthUrl.isEmpty()) {
            Log.i(TAG, "Refresh success, new URL: " + newAuthUrl);
            // As required by the SDK, create a UrlSource object and set the new URL
            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.");
        }
    }
});

Additional utility functions

The following example uses Type A signing.

// Function to generate a signed 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);
    }
}

The ApsaraVideo Player SDK for Android supports quickly rendering the first frame before playback starts, which can improve the startup speed.

For example:

aliPlayer.setOption(ALLOW_PRE_RENDER, 1);

The ApsaraVideo Player SDK for Android provides a local cache feature. This feature improves startup speed, seek speed, and reduces stuttering when users replay videos, while it also saves traffic.

Enable local cache

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

/**
 *  You can also use the code below to set the cache.
 *  Enable local cache. After enabling, it will cache to a local file.
 *  @param enable: Local cache feature switch. true: enable, false: disable. Default is disable.
 *  @param maxBufferMemoryKB: Deprecated in V5.4.7.1 and later, no longer has an effect.
 *  @param localCacheDir: Must be set. The directory for local cache files, must be an absolute path.
 *  AliPlayerGlobalSettings.enableLocalCache(enable, maxBufferMemoryKB, localCacheDir);
 */

/**
 * Configuration for clearing local cache files.
 * @param expireMin - Deprecated in V5.4.7.1 and later, no longer has an effect.
 * @param maxCapacityMB - Maximum cache capacity in MB. Default is 20 GB. During cleanup, if the total cache size exceeds this limit, the oldest cache files will be deleted one by one, sorted by last access time, until the total size is less than or equal to the maximum capacity.
 * @param freeStorageMB - Minimum free disk space in MB. Default is 0. During cleanup, similar to maxCapacityMB, if the current disk space is less than this value, cache files will be deleted one by one according to the rule until the free storage is greater than or equal to this value or all caches are cleared.
 * public static void setCacheFileClearConfig(long expireMin,
 *         long maxCapacityMB,
 *         long freeStorageMB)
 */

 /**
  * Set the callback for the hash value of the loaded URL. If not set, the SDK uses the MD5 algorithm.
  * public static void setCacheUrlHashCallback(AliPlayerGlobalSettings.OnGetUrlHashCallback cb)
  */

Enable or disable local cache for a single URL

// First, get the configuration
PlayerConfig config = aliPlayer.getConfig();
// Whether to enable local cache for the playback URL. The default value is true. When the local cache in AliPlayerGlobalSettings is enabled, and the local cache here is also enabled (set to true), the local cache for this URL will take effect. If set to false here, the local cache for this URL is disabled.
config.mEnableLocalCache = false;
....// Other settings

// Set the configuration for the player
aliPlayer.setConfig(config);

The ApsaraVideo Player SDK for Android provides a preload feature, which is an upgrade to the local cache feature. By setting the memory size for video caching, you can further improve the startup speed of videos.

AliPlayerGlobalSettings.enableNetworkBalance(false);

1. Enable the local cache feature. For more information, see Local cache.

2. Set the data source.

   VidAuth (recommended)

   VidAuth vidAuth = new VidAuth();
   vidAuth.setVid("Vid information");// Required. The video ID (VideoId).
   vidAuth.setPlayAuth("<yourPlayAuth>");// Required. The playback credential, which needs to be generated by calling the GetVideoPlayAuth API operation of ApsaraVideo VOD.
   vidAuth.setRegion("Access region");// For player SDK V5.5.5.0 and later, this parameter is deprecated. You do not need to set the region, as the player will automatically parse it. For player SDK versions earlier than 5.5.5.0, this parameter is required. It is the access region of ApsaraVideo VOD, which defaults to cn-shanghai.
   vidAuth.setQuality("Selected definition") //"AUTO" represents adaptive bitrate

   VidSts

   VidSts vidSts = new VidSts();
   vidSts.setVid("Vid information");// Required. The video ID (VideoId). vidSts.setAccessKeyId("<yourAccessKeyId>");// Required. The AccessKey ID of the temporary STS token, which needs to be generated by calling the AssumeRole API operation of STS.  vidSts.setAccessKeySecret("<yourAccessKeySecret>");// Required. The AccessKey secret of the temporary STS token, which needs to be generated by calling the AssumeRole API operation of STS.  vidSts.setSecurityToken("<yourSecurityToken>");// Required. The STS security token, which needs to be generated by calling the AssumeRole API operation of STS.  vidSts.setRegion("Access region");// Required. The access region of ApsaraVideo VOD, which defaults to cn-shanghai.
   vidSts.setQuality("Selected definition") //"AUTO" represents adaptive bitrate

   UrlSource

   UrlSource urlSource = new UrlSource();
   urlSource.setUri("Playback URL");// Required. The playback URL, which can be a third-party VOD URL or a playback URL in ApsaraVideo VOD.

3. Set task parameters.

   Note

   This applies only to multi-bitrate videos. You can choose one of setDefaultBandWidth, setDefaultResolution, or setDefaultQuality.

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

4. Add a task listener.

   Click to view the code

   /**
    * Preload listener implementation
    */
   private static class PreloadListenerImpl extends OnPreloadListener {
   
       @Override
       public void onError(@NonNull String taskId, @NonNull String urlOrVid, @NonNull ErrorInfo errorInfo) {
           // Loading error
       }
   
       @Override
       public void onCompleted(@NonNull String taskId, @NonNull String urlOrVid) {
           // Loading complete
       }
   
       @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 as needed to save space. The ApsaraVideo Player SDK for Android does not provide a deletion interface. You need to delete the files in the loading directory of the app.

The dynamic preload strategy allows integrators to control both the cache of the currently playing video and the number and cache of preloaded items. This helps businesses balance playback experience with cost.

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

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

// Configure the number of items for bidirectional preloading.
// Preload 1 item forward and 3 items backward.
aliListPlayer.setPreloadCount(1, 3);

// Configure the 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\"}");

Preload multi-bitrate HLS videos

In the listPlayer + multi-bitrate HLS video playback scenario, integrators can preload a stream with the same definition as the currently playing video. They can also choose the preload mode based on their business needs.

  /**
   * Default mode, plays and preloads the default bitrate of a stream
   */
  MultiBitratesMode_Default(0),

  /**
   * First frame cost (FC) priority, decreases first frame cost. Only plays the bitrate of the HLS stream which has been preloaded.
   */
  MultiBitratesMode_FCPrio(1),

  /**
   * Balances first frame and play smoothness. The video bitrate is consistent before and after switching (moveToNext), and first frame performance is also considered.
   */
  MultiBitratesMode_FC_AND_SMOOTH(2),

  /**
   * Play smooth priority. The video starts playing at the bitrate of the previous video by default.
   */
  MultiBitratesMode_SmoothPrio(3);

// Select the multi-bitrate loading mode
aliListPlayer.SetMultiBitratesMode(preLoadMode);


// (Optional) Select the startup bitrate
aliListPlayer.setDefaultBandWidth(defaultBandWidth)


// (Optional) In the onPrepared callback, select the ABR mode
aliListPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
        // ABR only affects multi-bitrate m3u8
        aliListPlayer.selectTrack(-1);
    }
});

HTTPDNS

// Enable enhanced HTTPDNS
AliPlayerGlobalSettings.enableEnhancedHttpDns(true);
// Optional: Add a domain name for HTTPDNS pre-resolution
DomainProcessor.getInstance().addPreResolveDomain("player.***alicdn.com");

HTTP/2

AliPlayerGlobalSettings.setUseHttp2(true);

Pre-establish TCP connections for HTTP

For HTTP video playback requests (not HTTPS), pre-establishing a TCP connection can significantly improve the user experience, reduce network connection time, ensure immediate and continuous playback, and optimize the use of network and system resources. The usage is as follows:

// The domain format is host[:port], where port is optional. Use a semicolon (;) to separate multiple domain names
// Global settings
// The full interface uses the current string as the standard for each setting (more - add, less - delete). An empty string stops pre-connection
AliPlayerGlobalSettings.setOption(AliPlayerGlobalSettings.SET_PRE_CONNECT_DOMAIN, "domain1;domain2");

The ApsaraVideo Player SDK for Android provides a video download feature for ApsaraVideo VOD. This allows users to cache videos locally to be viewed offline using ApsaraVideo Player. It also offers two download methods: normal download and secure download.

• Normal download

  The downloaded video data is not encrypted by Alibaba Cloud. Users can play it with a third-party player.

• Secure download

  The downloaded video data is encrypted by Alibaba Cloud. Third-party players cannot play it. It can be played only using the ApsaraVideo Player.

Instructions

• The video download feature is supported only for VidSts and VidAuth methods.

• To use the player's video download feature, you need to enable and configure the download mode in the ApsaraVideo VOD console. For more information, see Offline download.

• Video download supports resumable downloads.

Procedure

1. Optional: Configure the encryption file for secure download. This is required only for secure download, not for normal download.

   Note

   Ensure that the configured encryption file is consistent with the app information. Otherwise, the video download fails.

   If you set the download method to secure download, you need to configure the player SDK with the key file generated in the ApsaraVideo VOD console. This is used for decryption and verification during video download and playback. For more information about how to generate the key file, see Enable secure download.

   We recommend that you configure this once in the Application class. The following code is an example:

   PrivateService.initService(getApplicationContext(),  "File path where encryptedApp.dat is located"); // We recommend storing the encryptedApp.dat file on the phone and then setting the local file path of the encryption file here

2. Create and set up the downloader.

   You can create a downloader using AliDownloaderFactory. The following code is an example:

   AliMediaDownloader mAliDownloader = null;
   ......
   // Create the downloader
   mAliDownloader = AliDownloaderFactory.create(getApplicationContext());
   // Configure the save path for the download
   mAliDownloader.setSaveDir("Save folder address");

3. Set listeners.

   The downloader provides multiple event listeners. The following code is an example:

   Click to view the code

   mAliDownloader.setOnPreparedListener(new AliMediaDownloader.OnPreparedListener() {
      @Override
      public void onPrepared(MediaInfo mediaInfo) {
          // Successfully prepared the download item
      }
   });
   mAliDownloader.setOnProgressListener(new AliMediaDownloader.OnProgressListener() {
      @Override
      public void onDownloadingProgress(int percent) {
          // Download progress percentage
      }
      @Override
      public void onProcessingProgress(int percent) {
          // Processing progress percentage
      }
   });
   mAliDownloader.setOnErrorListener(new AliMediaDownloader.OnErrorListener() {
      @Override
      public void onError(ErrorInfo errorInfo) {
          // Download error
      }
   });
   mAliDownloader.setOnCompletionListener(new AliMediaDownloader.OnCompletionListener() {
      @Override
      public void onCompletion() {
          // Download successful
      }
   });

4. Prepare the download source.

   You can use the prepare method to prepare the download source. The download source supports VidSts and VidAuth methods. The following code is an example:

   • VidSts

     // Create a VidSts object.
     VidSts aliyunVidSts = new VidSts();
     aliyunVidSts.setVid("your_video_id"); // The video ID.
     aliyunVidSts.setAccessKeyId("<yourAccessKeyId>"); // The AccessKey ID of the temporary STS token. To obtain the token, you must call the AssumeRole operation of STS.
     aliyunVidSts.setAccessKeySecret("<yourAccessKeySecret>"); // The AccessKey secret of the temporary STS token. To obtain the token, you must call the AssumeRole operation of STS.
     aliyunVidSts.setSecurityToken("<yourSecurityToken>"); // The security token. To obtain the token, you must call the AssumeRole operation of STS.
     aliyunVidSts.setRegion("your_region_id"); // The ID of the region where VOD is activated. Default value: cn-shanghai.
      // If you enabled HLS encryption with parameter pass-through in the VOD console and the default parameter name is MtsHlsUriToken, you must set the config parameter and pass it to the VidSts object. For more information, see the following code.
      // If you did not enable HLS encryption with 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 a VidAuth object.
     VidAuth vidAuth = new VidAuth();
     vidAuth.setVid("Your Video ID");// The video ID (VideoId).
     vidAuth.setPlayAuth("<yourPlayAuth>");// The playback credential. You must call the GetVideoPlayAuth operation of the VOD service to generate the credential.
     vidAuth.setRegion("The region");// For player SDKs V5.5.5.0 and later, this parameter is deprecated. You do not need to set the region because the player automatically parses the region. For player SDKs earlier than V5.5.5.0, this parameter is required. It specifies the region where the VOD service is activated. The default value is cn-shanghai.
     // If you enable pass-through of HLS encryption parameters in the VOD console and the default parameter name is MtsHlsUriToken, you must set the config and pass it to the VidAuth object. For more information, see the following code.
     VidPlayerConfigGen vidConfig = new VidPlayerConfigGen();
     vidConfig.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     vidAuth.setPlayerConfig(vidConfig);
     // Prepare the download source.
     mAliDownloader.prepare(vidAuth);

   Note

   • The source file format and the output download file format are the same and cannot be changed.

   • If you enable HLS standard encryption parameter pass-through in the VOD console, the default parameter name is MtsHIsUriToken. For more information, see HLS standard encryption parameter pass-through. In this case, you must set the MtsHIsUriToken value in the VOD source as shown in the code above.

5. After the preparation is successful, select a download item and start the download.

   After the preparation is successful, the OnPreparedListener method is called. The returned TrackInfo object contains information such as the definition of each video stream. You can select a Track to download. The following code is an example:

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

6. (Optional) Update the download source.

   To prevent VidSts and VidAuth from expiring, you can also update the download source information before you start the download. The following code is an example:

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

7. After the download succeeds or fails, release the downloader.

   After the download is complete, you can call release in the onCompletion or onError callback to release the downloader. The following code is an example:

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

8. Optional: Delete the downloaded files.

   During or after the download, you can delete the downloaded files. The following code is an example:

   // Delete the file through the object
   mAliDownloader.deleteFile();
   // Delete through a static method. If successful, it returns 0
   AliDownloaderFactory.deleteFile("Path of the download folder to be deleted", "Video ID", "Video format", "Index of the downloaded video");

What to do next

The downloaded video can be played using the ApsaraVideo Player. The method is as follows:

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

   String path = mAliDownloader.getFilePath();

2. Set the absolute path for playback using the UrlSource method.

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