How to troubleshoot playback errors - ApsaraVideo VOD - Alibaba Cloud Documentation Center

This topic describes how to troubleshoot playback errors.

Troubleshooting

Playback errors can result from various causes. You can first check whether errors occur in a specific pattern as described in the following table and troubleshoot the errors. If an error occurs in a random manner, check the user device, media stream, and network connection to locate the error cause. If you cannot locate the error cause, contact Alibaba Cloud technical support and include the error information.

The following table describes the distribution characteristics of playback errors.

Distribution characteristic	Possible cause
Errors occur for users in specific regions or for users who use specific ISPs	ISP network errors or Alibaba Cloud CDN scheduling errors
Errors occur for users who use a specific operating system	SDK implementation issues on different platforms or system compatibility issues
Errors occur for users who use a specific brand of devices or a specific device model	Device compatibility issues
Errors occur on a specific media file	Encoding errors, prefetch errors, or access policy errors of the media file

If errors occur in a random manner, the causes may be complicated or difficult to locate due to a massive data volume. In this case, check each link from the source media stream to the devices to troubleshoot the errors.

Step 1: Check the device compatibility

Device compatibility

Check whether the protocol that your media stream uses is supported by the operating system and application environment on your device. If the protocol is not supported, transcode the media stream. For more information about transcoding, see Recommended output formats and tools. The following table describes the audio and video protocols and codecs supported by ApsaraVideo Player SDK.

Native App

Operating system	Video codec	Video protocol	Audio codec
Android	H.264 H.265	MP4 HLS FLV MPEG-DASH (SegmentBase and SegmentTemplate)	AAC MP3
iOS
Windows
macOS
Linux

Web

Note

If the protocol that your media stream uses meets the compatibility requirements of ApsaraVideo Player SDK for Web as described in the following table, check whether you have configured an SSL certificate and enabled cross-origin resource sharing (CORS). For more information, see Enable HTTPS secure acceleration and Configure CORS.

Operating system	Video codec	Video protocol	Audio codec
Android	H.264	MP4 HLS (MSEs are required for specific browsers) FLV (MSEs required)	AAC MP3
iOS	H.264	MP4 HLS Note FLV and MPEG-DASH protocols are not supported.
iOS	H.265	MP4 HLS (supported only for fMP4 segments)
Windows	H.264	MP4 HLS (MSEs required) FLV (MSEs required)
macOS	H.264	MP4 HLS FLV (MSEs required)
macOS	H.265	MP4 HLS (supported only for fMP4 segments)

Specific browsers on Android devices require Media Source Extensions (MSEs) to play HLS-encrypted videos. The following table describes the browsers in which HLS-encrypted videos can be played.

Browser on Android devices	Support for HLS-encrypted videos
WeChat	Supported
DingTalk	Supported
UC Browser or Quark Browser	Supported
QQ Browser	Supported
Chrome	Supported only if MSEs are installed
Huawei Browser	Supported only if MSEs are installed
OPPO Browser	Supported
Vivo Browser	Supported
Mi Browser	Supported only if MSEs are installed

Compatibility of ApsaraVideo Player SDK

If your device meets the compatibility requirements that are described in the preceding section, use a third-party player to determine whether ApsaraVideo Player SDK is compatible with your system.

If you can play the media stream in a third-party player, ApsaraVideo Player SDK may not be compatible with your system. In this case, contact Alibaba Cloud technical support.
If you cannot play the media stream in a third-party player, check whether errors occur on the media stream or network.

We recommend that you use the following players and browsers for troubleshooting:

Third-party player: VLC media player
Built-in players: ExoPlayer (Android) and AVPlayer (iOS)
System browsers on web pages: Chrome (Android and Windows) and Safari (iOS and macOS)

Step 2: Check the media stream

If no errors are found on devices, transcode the media stream and play it again. If the media stream can be played, the playback failed due to encoding errors.

Note

If a playback error such as long startup duration occurs when you play an MP4 video, the playback error may be caused by the format of the video file. To accelerate data parsing, place the moov atom before the mdat atom. The mdat atom contains the media data and the moov atom acts as the index of media data. You can transcode the media file to move the moov atom ahead of the mdat atom.

To check the location of the moov atom, run the following command:
```
// The video source address can be the path of a local file or the URL of an online video. Example: http://pla****.alicdn.com/video/aliyunmedia.mp4.
ffmpeg -v trace -i "Video source address" 2>&1 | grep -e type:\'mdat\' -e type:\'moov\'
```
In the following figure, the moov atom is placed ahead of the mdat atom. In this case, the video can be played as expected.
In the following figure, the mdat atom is placed ahead of the moov atom. In this case, playback errors may occur.
To query information about the source file such as the audio codec and video codec, download the ffprobe tool or run the following command. You can use the information to check whether playback errors occur in a specific manner.
ffprobe "input.mp4" or ffprobe "Video source address"

Recommended output formats and transcoding tools

Output format: We recommend that you transcode the media stream into an MP4 or HLS file in the H.264 format.

Transcoding tool: We recommend that you use the following Alibaba Cloud services or on-premises tools.

Category	Service or tool name	Description
Alibaba Cloud service	ApsaraVideo VOD	ApsaraVideo VOD provides comprehensive transcoding and container format conversion features for you to convert media files into various formats and supports regular transcoding, Narrowband HD 1.0 transcoding, Narrowband HD 2.0 transcoding, and original-quality transcoding. For more information, see Audio and video transcoding.
	ApsaraVideo Media Processing (MPS)	MPS supports regular transcoding, Narrowband HD 1.0 transcoding, Narrowband HD 2.0 transcoding, high-speed transcoding, and resolution-redoubling transcoding. This ensures that media streams transcoded by using MPS can be played on a wide range of platforms. MPS is ideal for users who store media source files in Object Storage Service (OSS) buckets. For more information, see Overview.
	Intelligent Media Services (IMS)	IMS supports transcoding of on-demand videos stored in OSS and ApsaraVideo VOD and live streams.
On-premises tool	FFmpeg Codecs	Download link: FFmpeg Codecs

Step 3: Check the network connection

If no errors are found on devices or media streams, check whether the network is accessible.

Check whether the network of your device is accessible.
- Check whether the Wi-Fi connection is stable and whether the downstream network speed matches the media bitrate.
  You can use SpeedTest to obtain the downstream network speed. If the downstream network speed does not match the video bitrate, stuttering occurs and the media stream fails to be loaded.
- Check whether you use a high-speed network such as 4G or 5G and whether your network is stable.
  Media streams may fail to be loaded in poor network conditions.
Check whether Alibaba Cloud CDN is activated.
- If Alibaba Cloud CDN is not activated, activate CDN to improve video playback. For more information, see Add a domain name for CDN.
- If Alibaba Cloud CDN is activated, check the following items:
  - CDN configuration errors: Check whether the media content is prefetched and whether the cached content expires.
    If the media content is not prefetched or the cached content expires, a cache miss occurs. In this case, the media stream fails to be loaded or stuttering occurs during playback. This issue frequently occurs on new videos that are uploaded to ApsaraVideo VOD. We recommend that you configure prefetch settings for new videos. For more information, see Refresh and prefetch.
  - Others: Check whether media streams can be played in other players on the same device.
    If no CDN configuration errors are found and media streams can be played in other players, playback failures may result from CDN scheduling.
Check whether the origin server and the user are located in the same region.
If the origin server is deployed in the Chinese mainland and a user accesses the server from outside the Chinese mainland, stuttering may occur. In this case, we recommend that you deploy the origin server in the same region in which the users are located to accelerate content delivery.
Check whether traffic spikes occur in a specific time range.
If traffic spikes occur, requests sent to the origin server may be throttled. This causes playback stuttering.

References

The following topics provide answers to some frequently asked questions about ApsaraVideo Player. If you cannot locate the causes, view these topics to facilitate troubleshooting.

Contact technical support

If the problem persists after you perform the preceding operations, submit a ticket to contact technical support. For more information about how to submit a ticket, see Contact us.

We recommend that you include the following information in your ticket.

Information	Example	Description
Operating system and device model	Android 9, Xiaomi	Describe the brand and operating system of the device on which the error occurred, such as Android, iOS, Windows, Mac, or Linux.
SDK type and version	Android SDK 5.4.8.0	Describe the type of the ApsaraVideo Player SDK and the version number. For example, ApsaraVideo Player SDK for Web, ApsaraVideo Player SDK for Android, ApsaraVideo Player SDK for iOS, ApsaraVideo Player SDK for Flutter, and ApsaraVideo Player SDK for Windows.
Video source	https://xxxxxx.m3u8	Provide the error playback URL or video file.
Problem description, log, and screen recording	Video playback started at 16:40 on August 29, 2022 and stuttering occurred around 17:00 on the same day. The log is provided.	Describe the operations that you performed and the problem symptom. We recommend that you include the exact points in time. If the error can be reproduced, provide the complete log for the abnormal operation in Android or iOS. You can choose to include a screen recording. For more information about how to obtain error logs, see How do I obtain the error log in ApsaraVideo Player SDK for Android? and How do I obtain the error log in ApsaraVideo Player SDK for iOS?.
Error distribution	This error occurs every time only on Android devices.	Describe whether the error is distributed in a specific pattern and the frequency of error occurrence. For example, describe whether the error occurs on a specific video source, platform, or SDK version and whether the error randomly occurs or occurs every time.