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 |
|
|
|
iOS | |||
Windows | |||
macOS | |||
Linux |
Web
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 |
|
|
iOS | H.264 |
Note FLV and MPEG-DASH protocols are not supported. | |
H.265 |
| ||
Windows | H.264 | ||
macOS | H.264 |
| |
H.265 |
|
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 |
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.
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.
If playback errors such as long startup duration occurs when you play an MP4 video or an MOV video failed to be played, the error may be caused by the format of the video file. To accelerate data parsing, place the moov atom ahead of 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"
orffprobe "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. ApsaraVideo VOD 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. |