ApsaraVideo VOD:Android player FAQ

License-related issues

Resolve invalid or expired license issues in License FAQ.

Common issues across platforms

• For platform-independent issues, check Cross-platform player FAQs.

• Experienced developers can also troubleshoot playback errors independently.

Get the current playback progress

The player SDK reports playback progress every 500 ms by default. Shorten the callback interval to get the current playback progress more frequently:

// Modify the callback interval.
PlayerConfig config = mAliyunLivePlayer.getConfig();
config.mPositionTimerIntervalMs = 100;// The callback interval in ms.
mAliyunLivePlayer.setConfig(config);

mAliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
        @Override
        public void onInfo(InfoBean infoBean) {
        if(infoBean.getCode() == InfoCode.CurrentPosition){
            // The current playback progress.
            long currentPosition = infoBean.getExtraValue();
        }
    }
});

Get source audio and video data

Raw audio and video data is returned only if you switch to software decoding and play an unencrypted video:

// Switch to software decoding.
mAliPlayer.enableHardwareDecoder(false);
IPlayer.RenderFrameCallbackConfig renderFrameCallbackConfig = new IPlayer.RenderFrameCallbackConfig();
// Specifies whether to return only the underlying video data address. Default value: true.
renderFrameCallbackConfig.mVideoDataAddr = false;
// Specifies whether to return only the underlying audio data address. Default value: false.
renderFrameCallbackConfig.mAudioDataAddr = false;
mAliPlayer.setRenderFrameCallbackConfig(renderFrameCallbackConfig);

mAliPlayer.setOnRenderFrameCallback(new IPlayer.OnRenderFrameCallback() {
    @Override
    public boolean onRenderFrame(FrameInfo frameInfo) {
        return false;
    }
});

Get the video width and height

You can get the video width and height in the following ways:

• After the AliPlayer instance of ApsaraVideo Player runs the prepare method, make sure that the instance is at least in the prepared state, and then call the following methods:

mAliyunPlayer.setOnPreparedListener(new IPlayer.OnPreparedListener() {
    @Override
    public void onPrepared() {
          mAliyunPlayer.getVideoWidth();
              mAliyunPlayer.getVideoHeight();
    }
});

• Listen for the video size change callback:

mAliyunPlayer.setOnVideoSizeChangedListener(new IPlayer.OnVideoSizeChangedListener() {
    @Override
    public void onVideoSizeChanged(int width, int height) {

    }
});

• Get the values by track:

mAliyunPlayer.setOnTrackReadyListener(new IPlayer.OnTrackReadyListener() {
    @Override
    public void onTrackReady(MediaInfo mediaInfo) {
    List<TrackInfo> trackInfos = mediaInfo.getTrackInfos();
        for (TrackInfo trackInfo : trackInfos) {
        if(trackInfo.getType() == TrackInfo.Type.TYPE_VIDEO){
        trackInfo.getVideoWidth();
        trackInfo.getVideoHeight();
        }
    }
    }
});

How do I get the pixel data of each video frame in the player?

For the Android player, listen for the OnRenderFrameCallback callback:

player.setOnRenderFrameCallback(frameInfo -> {
    if (frameInfo.frameType == FrameInfo.FrameType_video) {
        // Video data
    } else {
        // Audio data
    }
    return false;
});

Automatic bitrate switching logic

After you enable automatic bitrate switching by calling mAliPlayer.selectTrack(TrackInfo.AUTO_SELECT_INDEX), the player SDK tracks the current network speed. If the speed reaches the next bitrate within 10 seconds, the player switches to that bitrate. If the speed does not reach the next bitrate within 10 seconds, no switch occurs.

• When switching from a high bitrate to a low bitrate, if the network speed reaches the next bitrate within 10 seconds, the player finishes playing the cached high-bitrate content before it switches.

• When switching from a low bitrate to a high bitrate, if the network speed reaches the next bitrate within 10 seconds, the player switches immediately.

  To use automatic bitrate switching, first transcode the video into an adaptive bitrate stream in the console, and then configure the player to get the adaptive bitrate stream. The following example uses the VidAuth playback method:

VidAuth vidAuth = new VidAuth();
List<Definition> list = new ArrayList<>();
list.add(Definition.DEFINITION_AUTO);
vidAuth.setDefinition(list);

Custom retry logic

In network retry scenarios, the player SDK retries twice by default with a network timeout of 15 seconds. An Error callback is triggered after the retries fail.

You can customize the retry logic so that retry events are reported to your application, which then decides the actual retry behavior:

PlayerConfig config = mAliPlayer.getConfig();
// 1. Set the number of retries. In this example, it is set to 0.
config.mNetworkRetryCount = 0;
mAliPlayer.setConfig(config);

mAliPlayer.setOnInfoListener(new IPlayer.OnInfoListener() {
    @Override
    public void onInfo(InfoBean infoBean) {
        // 2. Listen for the retry event.
       if(infoBean.getCode() == InfoCode.NetworkRetry){
            // TODO: Process the logic as needed.
        }
    }
});

An unsupported protocol error occurs during Alibaba Real-Time Communication (ARTC) stream playback

Cause 1: The player SDK is integrated, but the bridge layer between the player and the RTS low-latency live streaming component (AlivcArtc) and the RTS low-latency live streaming component (RtsSDK) are not integrated.

Solution: Integrate them by following Implement RTS stream pulling on Android.

Cause 2: The version of the bridge layer (AlivcArtc) does not match the player version.

Solution: The bridge layer (AlivcArtc) and the player must use the same version number. For the implementation, see the Implement RTS stream pulling on Android topic.

Cause 3: The RTS low-latency live streaming component (RtsSDK) is not loaded.

Solution: Load the RTS low-latency live streaming component (RtsSDK) in the Application file or in the target Activity based on your requirements.

static {
    System.loadLibrary("RtsSDK");
}

Cause 4: The minSDK version is too high, so the bridge layer (AlivcArtc) is not loaded correctly.

Solution:

// 1. Modify minSdk
Downgrade minSdk to 21

// 2. Manually load the ARTC library
static {
    System.loadLibrary("RtsSDK");
    System.loadLibrary("cicada_plugin_artcSource");
}

The progress bar jumps back after a seek operation

Cause: The player uses inaccurate seek by default. After a seek operation, the player starts playback from the keyframe nearest to the seek point.

Solution: Switch to the accurate seek mode.

How do I switch between the accurate and inaccurate seek modes?

The following example shows how to switch between seek modes:

// Inaccurate seek.
mAliPlayer.seekTo(1000);
mAliPlayer.seekTo(1000, IPlayer.SeekMode.Inaccurate);
// Accurate seek.
mAliPlayer.seekTo(1000,IPlayer.SeekMode.Accurate);

The progress bar still jumps back after I switch to the accurate seek mode

Cause: Accurate seek takes longer than inaccurate seek. When the distance from the seek point to the nearest keyframe, that is, the start of a Group of Pictures (GOP), is too large and exceeds the maximum accurate seek interval, the player SDK automatically falls back to inaccurate seek, which makes the progress bar jump back.

Solution: Increase the maximum accurate seek interval through the interface. This reduces how often accurate seek falls back to inaccurate seek and improves seek accuracy. However, a longer distance from the seek point to the nearest keyframe (GOP) also means a longer seek time. Set the maximum accurate seek interval based on your business characteristics:

// Unit: ms.
mAliPlayer.setMaxAccurateSeekDelta(10000);

Local caching: Can the cache directory be set to an internal storage directory?

Yes. Replace the external storage directory of the Android device with an internal storage directory. Make sure that the internal storage directory has access permissions, and caching then works properly.

An encrypt check fail error occurs during video caching

Caching is a download operation. If secure download is enabled, make sure that the encryption verification file matches your app information. Download the encryption verification file generated in Offline download and save it to the player SDK. For more information, see Video download. A mismatch causes caching or downloading to fail.

Multi-bitrate (HLS) videos miss the cache after local caching is enabled

Symptom: You enabled local caching and preloading as described in the documentation, but one or more of the following occurs:

• Seeking back to a position that was already played does not hit the cache.

• Playback cannot continue after the network is disconnected.

• isCacheExist returns false.

• The cache directory is empty after preloading is disabled.

  Cause: In multi-bitrate (HLS) scenarios, if you do not explicitly select a stream during playback, the player uses adaptive bitrate streaming (ABR). Data in ABR mode is not written to disk, so no local cache is generated. Only the stream that you explicitly select by calling selectTrack is cached locally. If you do not call selectTrack, or if you pass TrackInfo.AUTO_SELECT_INDEX, the player handles playback as ABR.

Solution: Make sure that preloading and playback use the same definition and the same playback URL, and explicitly select that stream during playback.

• During preloading, enable local caching and preload the stream of the specified definition.

• During playback, call selectTrack in the onPrepared callback of setOnPreparedListener to select the same definition used for preloading. Pass the same playback URL used for preloading to setDataSource, and then call prepare and start.

• If the startup bitrate differs from the bitrate that is opened by default, buffering is triggered. Call setDefaultBandWidth to set the startup bitrate and reduce stuttering during switching.

A No such file or directory error occurs when playing an HLS (m3u8) video from an offline download

Symptom: After an HLS offline download, playing the local address reports No such file or directory. The issue is not always reproducible and occurs more often in scenarios such as quick swiping between pages.

Cause: To save storage space, an HLS offline download usually downloads only the TS segments and the m3u8 file of one definition, such as 540p. However, the master m3u8 file saved locally still keeps the records of all definitions, such as 1080p, 720p, 540p, and 360p. If you do not specify the downloaded definition before you call prepare, the player follows the default or adaptive logic and requests segments of other definitions that do not exist locally. This reports a file-not-found error. The common triggers are a missing call that specifies the definition, or a call made later than prepare.

Solution:

• Call setDefaultResolution before prepare to specify the same definition used for the offline download.

• Make sure that every playback entry point sets a default definition, including the branches for quick swiping, multi-instance reuse, and preload switching, so that no path is missed.

• Call getCurrentTrack to verify that the definition actually used for startup playback is the downloaded definition.

Audio and video go out of sync after switching videos, or replaying the same video misses the cache

Symptom: After local caching is enabled, audio and video go out of sync when you switch videos, such as switching episodes: the video is from the new episode while the audio is still from the previous one. Alternatively, replaying the same video does not hit the cache. Clearing the cache restores normal behavior.

Cause: After local caching is enabled, the player uses the hash returned by the setCacheUrlHashCallback callback as the unique cache identifier of each playback URL. If your custom callback does not guarantee that the same playback URL always returns the same hash and that different content returns different hashes, cache keys are mismatched. Different content then hits the same cache, which shows up as audio and video out of sync. Alternatively, the same URL returns a different hash each time and never hits the cache.

Solution:

• The callback must consistently return the same hash for the same playback URL, and different hashes for different media.

• If you remove authentication parameters to improve the cache hit ratio, remove them only from the playback URL (m3u8 or mp4) before you calculate the hash. Do not remove the authentication parameters from the keyURL of an encrypted m3u8 file. Otherwise, the keys of different videos hit the same cache and playback fails. You can handle the two cases separately by domain name inside the callback.

• If the same file has both an HTTP address and an HTTPS address, unify the protocol or remove the protocol header before you calculate the hash.

  For more information, see Local cache.

An authentication failure occurs when playing a video with Alibaba Cloud proprietary encryption

Symptom: An authentication failure is reported, or the video cannot be played, when you play a video encrypted with Alibaba Cloud proprietary encryption.

Cause: Alibaba Cloud proprietary encryption completes decryption through interaction between the player and the server, so playback must start through a vid-based playback method. If you pass the playback URL directly to the ApsaraVideo VOD UrlSource for a video with standard proprietary encryption, authentication and decryption cannot complete and playback fails.

Solution:

• On native clients, play videos with proprietary encryption through ApsaraVideo VOD VidAuth or VidSts. If the output streams also contain streams that are not encrypted with proprietary encryption, call VidPlayerConfigGen.setEncryptType(AliyunVoDEncryption) to filter for the proprietary-encrypted streams.

• Only License proprietary encryption supports ApsaraVideo VOD UrlSource playback. For MP4, append etavirp_nuyila=1 to the end of the URL. For HLS, version 6.17.0 and later can use the original URL directly. These options do not apply to standard proprietary encryption.

  For more information, see Play an encrypted video.

A crash occurs when creating the player

Troubleshoot the cause as follows:

• Check whether the CPU architecture is the x86 architecture.

  The player SDK supports only the arm64-v8a and armeabi-v7a architectures. It does not support the x86 architecture.

• Check whether the project mixes the .so files and the Maven dependencies of the player SDK.

  For example, you integrated the player SDK through a Maven dependency in build.gradle, and you also integrated the player-related dynamic libraries in the libs directory of a project module.

Recommended solution: If both are used, remove the dynamic libraries and use the Maven dependency. If you must integrate the dynamic libraries, check that the .so files of the player SDK are consistent and come from the same version. For information about how to integrate the player SDK and get the dynamic libraries, see Integrate the SDK. The player-related dynamic library files are libalivcffmpeg.so, libsaasCorePlayer.so, and libsaasDownloader.so.

• If you integrated a partial package, confirm that the AlivcFFmpeg version dependency is correct.

  For information about AlivcFFmpeg version dependencies, see AlivcFFmpeg version dependencies.

A crash occurs while the player is running

Troubleshoot the cause as follows:

• Confirm whether the crash occurred in the player SDK.

  Check whether a crash stack carries the AliyunPlayer prefix. If it does, the issue occurred in the player SDK.

• Upgrade to the latest version of the player SDK and verify whether the issue is fixed.

• If the issue persists, prepare the related crash files (including all threads), crash logs, and crash scenario details, and then see How to get issue logs.

Black bars appear during video playback

Troubleshoot the cause as follows:

• Check whether the source video itself has black bars.

• Adjust the scaling mode of the player through the following interface.

/*
SCALE_ASPECT_FILL: Fills the screen proportionally. The video is cropped.
SCALE_ASPECT_FIT: Scales the video proportionally. Black bars may appear.
SCALE_TO_FILL: Fills the screen without maintaining proportions. The video is distorted.
*/
mAliPlayer.setScaleMode();

• If the scaling mode still does not meet your requirements, adjust the size of the SurfaceView or TextureView at the application layer.

Audio plays but no video appears

Troubleshoot the cause as follows:

• Play the video with another player to check whether the video is audio-only.

• Confirm that the view used to render the video is configured correctly. For example, no display view is set for the player, or the display view is removed from the playback interface. For information about how to set the display view, see Step 4 in Basic features.

An Invalid argument error occurs when playing a local video that already has read permissions

When an Invalid argument error occurs for a local video that already has read permissions, check the file name and the absolute path of the file. Avoid paths that contain Chinese characters and spaces.

A Permission denied error occurs when playing a local video that already has read permissions

Android introduced the scoped storage feature in Android 10 (Android Q). To use the storage permissions of an Android device normally, add android:requestLegacyExternalStorage="true" to the application tag in AndroidManifest.xml.

A Redirect to a url error occasionally occurs during video playback

This error may occur because the video source is hijacked. Enable the HTTPDNS feature of the player to handle it. For more information, see Configure HTTPDNS for Android.

A black notification bar flashes on a notched screen during full-screen playback

Set an immersive status bar to resolve this issue.

A MOV video fails to play

The Android player SDK supports MOV videos. If playing a MOV video fails, check whether the moov atom (the audio and video data index) of the source video is located after the mdat atom (the audio and video data). Transcode the source video to move the moov atom before the mdat atom. For more information, see Step 2: Troubleshoot the stream.

An error indicates that the .so dynamic library of the player SDK cannot be found during initialization or playback

Troubleshoot the cause as follows:

• Check whether the CPU architecture meets the requirements.

  The player SDK provides dynamic libraries only for the arm64-v8a and armeabi-v7a architectures.

• Check whether the player SDK version is too old.

  If the player SDK version is 5.4.6.0-full or earlier, upgrade to 5.4.6.0-full-15467853 or later. For the latest and historical versions of the player SDK, see Android SDK release notes.

An error occurs when using the list player AliListPlayer to play HLS (m3u8) videos

Player SDK V5.4.5.0 and earlier do not support playing HLS (m3u8) videos with the list player AliListPlayer. Versions later than V5.4.5.0 support HLS (m3u8) list playback, but you must enable local caching. For information about how to enable local caching, see Local cache.

Does the Android player SDK support playing videos in the assets and raw folders of an Android project?

No. Copy the video to the phone storage, and then play the video by using its absolute path.

A 403 error occurs and playback fails after local caching is configured for an HLS video stream

Symptom: When you play an HLS (M3U8) video stream by using the VidAuth playback method with local caching enabled, playback fails and a 403 error is reported.

Cause: After local caching is enabled, if you exit playback before the video is fully cached, the uncached part is still requested with the expired Vid authentication information from the previous session the next time you start playback. This causes an authentication failure and a 403 error.

Solution: For player SDK V5.5.4.0 and later, if the video playback URL carries authentication parameters and the playback protocol is HLS, you can set the PlayerConfig.mEnableStrictAuthMode field to select an authentication mode. The default value is false.

• Non-strict authentication (false): Authentication is cached. If only part of the media was cached previously, the player uses the cached authentication for subsequent requests. If URL authentication has a short validity period or playback resumes after a long pause, authentication may expire. Integrate with auto-refresh playback sources to handle authentication expiration.

• Strict authentication (true): Authentication is not cached. Authentication occurs on every startup, causing startup failure without network.

• Non-strict authentication (false): Authentication is cached. If only part of the media was cached previously, the player uses the cached authentication for subsequent requests. If URL authentication has a short validity period or playback resumes after a long pause, authentication may expire. Integrate with auto-refresh playback sources to handle authentication expiration.

• Strict authentication (true): Authentication is not cached. Authentication occurs on every startup, causing startup failure without network.

Does the Android player SDK support playing a video while downloading it?

No. The Android player SDK can cache and download video files during playback when local caching is enabled, and the cached video file plays directly the next time. Taking a locally cached video file out of its file directory and playing it separately is not supported.

Does the Android player SDK support getting the buffering speed of a video?

Yes. The Android player SDK can get the buffering speed, real-time rendering frame rate, audio and video bitrates, and network download bitrate. For more information, see Get playback information.

HDR video playback is abnormal

The Android player SDK does not currently support HDR videos with a rotation angle, so playback of these videos is abnormal.

If a video is transcoded into multiple definitions, which definition does the player SDK play by default?

The default definition playback order is FD, LD, SD, HD, 2K, 4K, and OD. For the definition of each term, see definition. The player SDK searches from left to right and plays the first definition it finds.

How do I specify the default playback definition?

The following example shows how to specify the default playback definition:

// The VidSts playback method is used as an example.
VidSts vidSts = new VidSts();
// The code for setting parameters such as vid, AccessKeyId, AccessKeySecret, and token is omitted. For more information, see the player creation settings in the Basic Features topic.
/*
    Parameter 1: The desired playback definition. Valid values: FD, LD, SD, HD, 2K, 4K, and OD.
    Parameter 2: Specifies whether to enforce playback of the desired definition. false: Does not enforce playback of the desired definition. The player SDK searches for a definition to play based on the default order. true: Enforces playback of the desired definition. If the desired definition is not found, the video is not played.
*/
vidSts.setQuality("",false);

If a definition has multiple streams, which stream does the player SDK play?

If a definition has multiple streams, the player SDK plays the latest stream.

How do I play a video without a watermark but download it with a watermark?

Transcode the video into multiple definitions. Play the definition without a watermark, and download the definition with a watermark.

How to get issue logs

When you request technical support from Alibaba Cloud, submit your issue logs together with the request so that your problem can be resolved more efficiently. Get the issue logs as follows:

• Get the issue logs.

  Set the log level to AF_LOG_LEVEL_TRACE before you get the issue logs. For the detailed procedure, see Get SDK logs.

• Provide the generated logs to Alibaba Cloud technical support.