Upgrade from V3.x.x to V4.5.0

Compared with ApsaraVideo Player SDK V3.x.x, V4.5.0 has the following major changes:

• Integrates ApsaraVideo Player Basic and ApsaraVideo Player Pro.
• Changes dependencies.
• Changes some class names and methods.
• Changes proguard rules.

Changes in players

In the SDK V3.x.x, ApsaraVideo Player Basic and ApsaraVideo Player Pro are provided separately. ApsaraVideo Player Basic uses the AlivcMediaPlayer class to play videos from specified URLs. ApsaraVideo Player Pro uses the AliyunVodPlayer class to play videos with specified video IDs (VIDs) from ApsaraVideo for VOD. In the SDK V4.5.0, ApsaraVideo Player Basic and ApsaraVideo Player Pro are integrated. That is, the AliPlayer class is used to play both videos from specified URLs and videos with specified VIDs from ApsaraVideo for VOD.

Changes in dependencies

The SDK V3.x.x has a Gradle package compile 'com.aliyun.dpa:oss-android-sdk:+' and three dependency packages AlivcPlayer-3.x.x.aar, AlivcReporter-1.2.aar, and AliyunVodPlayer-3.x.x.aar.
The SDK V4.5.0 contains one dependency package AliyunPlayer-4.5.0-full.aar, and the Gradle package is changed to com.alivc.conan:AlivcConan:0.9.5.

Changes in classes and methods

The SDK V4.5.0 modifies some class names, adds new methods and callbacks, and deletes some methods from the SDK V3.x.x.

Changes proguard rules

The proguard rules are:

-keep class com.alivc.**{*;}
-keep class com.aliyun.**{*;}
-keep class com.cicada.**{*;}
-dontwarn com.alivc.**
-dontwarn com.aliyun.**
-dontwarn com.cicada.**

Upgrade practices

Upgrades from ApsaraVideo Player SDK V3.x.x to V4.x.x are similar. The following example shows how to upgrade from V3.4.10 to V4.5.0:

1. Replace the dependent package

V3.4.10 contains a Gradle package compile 'com.aliyun.dpa:oss-android-sdk:+' and three dependency packages AlivcPlayer-3.4.10.aar, AlivcReporter-1.2.aar, and AliyunVodPlayer-3.4.10.aar.
The SDK V4.5.0 contains one dependency package AliyunPlayer-4.5.0-full.aar, and the Gradle package is changed to 'om.alivc.conan:AlivcConan:0.9.5.

1. Local dependency

If you use local dependency, you need to replace local dependency packages and the Gradle package.

1. Replace local dependency packages: Replace the three AAR packages of V3.4.10 with the two AAR packages of V4.5.0.
   

The following figure shows the SDK dependency packages after replacement.

1. Add Alibaba Cloud Maven repository URL:
   Add Alibaba Cloud Maven repository URL to the buildscript block and the allprojects block in the build.gradle file.

maven {
    url 'https://maven.aliyun.com/repository/releases'
}

The following figure shows the build.gradle file after you add the URL.

1. Replace the Gradle package: Replace the OSS dependency with a Conan dependency.
   

The Conan dependency is as follows:

implementation 'com.alivc.conan:AlivcConan:0.9.5'

The following figure shows the SDK Gradle file after replacement.

2. Gradle dependency

If you use Gradle dependency, you need to delete local dependency packages and replace the Gradle package.

1. Delete local dependency packages: Delete the three AAR packages.
   

The following figure shows the SDK structure after local dependency packages are deleted.

1. Add Alibaba Cloud Maven repository URL:
   Add Alibaba Cloud Maven repository URL to the buildscript block and the allprojects block in the build.gradle file.

maven {
    url 'https://maven.aliyun.com/repository/releases'
}

The following figure shows the build.gradle file after you add the URL.

1. Replace the Gradle package:
   Add the reference to the AAR package AliyunPlayer-4.5.0-full.aar and the Gradle package com.alivc.conan:AlivcConan:0.9.5 to the dependencies part in the build.gradle file.

implementation 'com.aliyun.sdk.android:AliyunPlayer:4.5.0-full'
implementation 'com.alivc.conan:AlivcConan:0.9.5'

The following figure shows the build.gradle file after you add the reference.

3. Short video SDK integration

To integrate a player SDK that supports short video playback, you need to use AliyunPlayer-4.5.0-part.aar as the dependency package. In addition, you need to add the com.aliyun.video.android:AlivcFFmpeg:1.0.0 package, the version of which is compatible for both the player SDK and the short video SDK.

An FFmpeg error may occur if you choose an incorrect dependency package for SDK integration.

2. Modify code

After you replace the frameworks, an error occurs when you start to compile the project. To resolve the error, you need to use classes and methods provided by V4.5.0. Compared with V3.4.10, V4.5.0 changes package names and operations.
Especially, you need to pay attention to the following changes:

1. Player creation

V3.4.10 provides the IAliyunVodPlayer class for you to define a player object. You can use the following code to create a player object: mAliyunVodPlayer = new AliyunVodPlayer(getContext());.
V4.5.0 provides the AliPlayer class for you to define a player object. You can use the AliPlayerFactory class to create a player object:

// Define a player object.
AliPlayer mAliyunVodPlayer;
...
// Create a player object.
mAliyunVodPlayer = AliPlayerFactory.createAliPlayer(getContext().getApplicationContext());

2. Listeners

In V3.4.10, you can find listeners in the IAliyunVodPlayer class.
In V4.5.0, you can find listeners in the IPlayer class. Only some class names are changed. You need to change these class names to modify listeners.
For example, in V3.4.10, you can set the OnPreparedListener callback, as shown in the following figure.

In V4.5.0, you need to set the OnPreparedListener method, as shown in the following figure.

For most listeners that remain unchanged, you only need to modify their class name. However, for listeners that are deleted or newly added, you must modify the corresponding operations. Changes in listeners are as follows:

1. Changes in listeners

2. Details of changed listeners

The listener for the display of the first frame
is changed from OnFirstFrameStartListener in V3.4.10 to OnRenderingStartListener in V4.5.0:

public interface OnRenderingStartListener {
     void onRenderingStart();
}
public void setOnRenderingStartListener(OnRenderingStartListener l);

The listener for the stop of video playback
is changed from OnStoppedListener in V3.4.10 to OnStateChangedListener in V4.5.0:

public interface OnStateChangedListener {
    void onStateChanged(int newState);
}
public void setOnStateChangedListener(OnStateChangedListener l);

The newState parameter of the OnStateChangedListener callback indicates the new status of the player. It provides multiple values to indicate various statuses. You can use the IPlayer class to specify the status value. Status values are as follows:

/**
 * Indicates the unknown status.
 */
public static final int unknow = -1;
 /**
 * Indicates that the player is idle when it is created.
 */
public static final int idle = 0;
/**
 * Indicates that the player is initialized after you set the playback source.
 */
public static final int initalized = 1;//
/**
 * Indicates that playback preparation succeeds.
 */
public static final int prepared = 2;
/**
 * Indicates that the player is playing a video.
 */
public static final int started = 3;
/**
 * Indicates that the player pauses the playback.
 */
public static final int paused = 4;
/**
 * Indicates that the player stops the playback.
 */
public static final int stopped = 5;
/**
 * Indicates that the playback is completed.
 */
public static final int completion = 6;
/**
 * Indicates that a playback error occurs.
 */
public static final int error = 7;

The listener for the start of loop playback
is changed from OnCircleStartListener in V3.4.10 to OnInfoListener in V4.5.0:

public interface OnInfoListener {
    void onInfo(InfoBean infoBean);
}
public void setOnInfoListener(OnInfoListener l);

The InfoBean.getCode() = InfoCode.LoopingStart callback is fired when the loop playback starts.

The listener for video loading
is changed from OnLoadingListener in V3.4.10 to OnLoadingStatusListener in V4.5.0.

public interface OnLoadingStatusListener {
    void onLoadingBegin();
    void onLoadingProgress(int percent, float netSpeed);  // The unit of the percent parameter is percentage. The unit of the netSpeed parameter is Kbit/s.
    void onLoadingEnd();
}
public void setOnLoadingStatusListener(OnLoadingStatusListener l);

Note: Currently, the value of the netSpeed parameter in the onLoadingProgress method is 0.

The listener that indicates the progress of video buffering
is changed from OnBufferingUpdateListener in V3.4.10 to OnInfoListener in V4.5.0:

public interface OnInfoListener {
     void onInfo(InfoBean infoBean);
}
public void setOnInfoListener(OnInfoListener l);

The InfoBean.getCode() = InfoCode.BufferedPosition callback is fired when the buffering progress is updated. You can call the InfoBean.getExtraValue() method to obtain the buffering progress information.
The InfoBean.getCode() = InfoCode.CurrentPosition callback is fired when the playback progress is updated. You can call the InfoBean.getExtraValue() method to obtain the playback progress information.

The listener for a playback error
is changed from OnErrorListener in V3.4.10 to OnErrorListener in V4.5.0:

public interface OnErrorListener {
    void onError(ErrorInfo errorInfo);
}
public void setOnErrorListener(OnErrorListener l);

ErrorInfo is the error information class. You can call the ErrorInfo.getCode() method to obtain the error code, and call the ErrorInfo.getMsg() method to obtain the error message.

The listener for playback information
is changed from OnBufferingUpdateListener in V3.4.10 to OnInfoListener in V4.5.0:

public interface OnInfoListener {
    void onInfo(InfoBean infoBean);
}
public void setOnInfoListener(OnInfoListener l);

InfoBean is the playback information class. You can call the InfoBean.getCode() method to obtain the playback information code, and call the InfoBean.getExtraMsg() method to obtain the playback information message (if available). Information codes are as follows:

/**
 * Unknown.
 */
Unknown(-1);
/**
 * Indicate that loop playback starts. No extra value is available.
 */
LoopingStart(0),
/**
 * Indicate the buffer position. The extra value indicates the current buffer position (time point), in milliseconds.
 */
BufferedPosition(1),
/**
 * Indicate the current playback position. The extra value indicates the current playback position (time point), in milliseconds.
 */
CurrentPosition(2),
/**
 * Indicate that autoplay starts. No extra value is available.
 */
AutoPlayStart(3),
/**
 * Indicate that hard decoding is switched to soft decoding. The extra value provides detailed description.
 */
SwitchToSoftwareVideoDecoder(100),
/**
 * Indicate that the audio decoding format is not supported. The extra value provides detailed description.
 */
AudioCodecNotSupport(101),
/**
 * Indicate that the audio decoder failed. The extra value provides detailed description.
 */
AudioDecoderDeviceError(102),
/**
 * Indicate that the video decoding format is not supported. The extra value provides detailed description.
 */
VideoCodecNotSupport(103),
/**
 * Indicate that the video decoder failed. The extra value provides detailed description.
 */
VideoDecoderDeviceError(104),
/**
 * Indicate that a network error occurs. You need to try again. No extra value is available.
 */
NetworkRetry(107),
/**
 * Indicate that the caching succeeds. No extra value is available.
 */
CacheSuccess(108),
/**
 * Indicate that the caching failed. The extra value provides detailed description.
 */
CacheError(109),
/**
 Indicate that no system memory is available for storing media data.
 */
LowMemory(110),

The listener for video resolution switching
is changed from OnChangeQualityListener in V3.4.10 to OnTrackChangedListener in V4.5.0:

public interface OnTrackChangedListener {
    void onChangedSuccess(TrackInfo trackInfo);
    void onChangedFail(TrackInfo trackInfo, ErrorInfo errorInfo);
}
public void setOnTrackChangedListener(OnTrackChangedListener l);

The OnTrackChangedListener callback is fired after the selectTrack(index) method is called.

The listener for the start of autoplay
is changed from OnAutoPlayListener in V3.4.10 to OnInfoListener in V4.5.0.

public interface OnInfoListener {
    void onInfo(InfoBean infoBean);
}
public void setOnInfoListener(OnInfoListener l);

The InfoBean.getCode() = InfoCode.AutoPlayStart callback is fired when the autoplay starts.

The listener for the expiration of request information
is changed from OnTimeExpiredErrorListener in V3.4.10 to OnErrorListener in V4.5.0:

public interface OnErrorListener {
    void onError(ErrorInfo errorInfo);
}
public void setOnErrorListener(OnErrorListener l);

ErrorInfo is the error information class. You can call the ErrorInfo.getCode() method to obtain the error code, and call the ErrorInfo.getMsg() method to obtain the error message. For more information about expiration error codes, see the API reference.

3. Playback source setting

V3.4.10 calls the prepareAsync method to set parameters for the playback source, and then automatically prepares the player. In V4.5.0, you need to call the AliPlayer.setDataSource method to set parameters for the playback source.

/**
 * Set UrlSource.
 */
public void setDataSource(UrlSource urlSource);
/**
 * Set VidSts.
 */
public void setDataSource(VidSts vidSts);
/**
 * Set VidAuth.
 */
public void setDataSource(VidAuth vidAuth);
/**
 * Set VidMps.
 */
public void setDataSource(VidMps vidMps);

In V4.5.0, you can call the AliLiveShiftPlayer.setDataSource method to set time shifting during live streaming:

/**
 * Set the data source.
 */
public void setDataSource(LiveShift liveShift);

In V4.5.0 that provides the AliPlayer class to replace the AlivcMediaPlayer class, you need to set UrlSource for URL-based playback.

4. Main API operations

5. Other API operations

For more information about changes in other operations, see the API reference.