ApsaraVideo VOD:Troubleshoot playback errors

Protocol and codec support

Confirm that the protocol and codec of your media stream are supported on the target device. If the format is unsupported, transcode the stream to a compatible format. See Recommended output formats and transcoding tools.

The following tables list the protocols and codecs that ApsaraVideo Player SDK supports.

Native app

Web

HLS-encrypted video support on Android browsers

Some Android browsers require Media Source Extensions (MSEs) to play HLS-encrypted videos. The following table shows which browsers support HLS-encrypted video playback.

Test with a third-party player

If your device meets the compatibility requirements above, test with a third-party player to determine whether the issue is specific to ApsaraVideo Player SDK.

• Third-party player plays the stream successfully: The issue may be an ApsaraVideo Player SDK compatibility problem. Contact Alibaba Cloud technical support.

• Third-party player also fails: The issue is in the media stream or network. Continue to Step 2.

Recommended third-party players and browsers for testing:

Check moov atom placement (MP4 and MOV)

For MP4 and MOV files, slow startup or playback failure is often caused by incorrect atom ordering. The moov atom (metadata index) must be placed before the mdat atom (media data) so the player can parse metadata without downloading the entire file.

Run the following command to check the atom order:

# Replace with a local file path or an online video URL
ffmpeg -v trace -i "<video-source>" 2>&1 | grep -e type:\'mdat\' -e type:\'moov\'

• moov before mdat: Correct order. The video plays as expected.

  

• mdat before moov: Incorrect order. Transcode the file to move the moov atom to the front.

  

Inspect source file properties

Use ffprobe to examine the codec and other properties of the source file. This helps determine whether the error follows a codec-specific or format-specific pattern.

ffprobe "<video-source>"

Download ffprobe from FFmpeg Downloads.

Recommended output formats and transcoding tools

For maximum compatibility, transcode media streams to H.264 video in MP4 or HLS containers.

1. Verify device network connectivity

• Wi-Fi: Confirm the connection is stable and the downstream bandwidth exceeds the media bitrate. Use SpeedTest to measure downstream speed. If the downstream speed is lower than the video bitrate, buffering and loading failures occur.

• Mobile network: Confirm a 4G or 5G connection with stable signal. Playback may fail or stutter on poor mobile connections.

2. Check Alibaba Cloud CDN configuration

• CDN not activated: Activate CDN to accelerate video delivery. For more information, see Add a domain name for CDN.

• CDN activated: Check these items:

  • Cache miss: Verify that the media content is prefetched and the cached content has not expired. A cache miss causes loading failures or stuttering, especially for newly uploaded videos. Configure prefetch for new videos. For more information, see Purge and prefetch.

  • CDN scheduling: If no configuration errors exist and the stream plays in other players on the same device, the issue may be a CDN scheduling problem.

3. Check origin server and user proximity

If the origin server is deployed in the Chinese mainland and the user connects from outside the Chinese mainland, latency and stuttering may occur. Deploy the origin server in the same region as your users to reduce delivery latency.

4. Check for traffic spikes

During traffic spikes, requests to the origin server may be throttled, causing playback stuttering.