DocsICP FilingConsole
官方文档
首页

Troubleshoot video playback issues

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes how to identify and resolve video playback issues.

Troubleshooting strategy

Note

  • ApsaraVideo Player SDK is continuously updated with new features, performance enhancements, and stability improvements. If you encounter an issue, we recommend that you first check if it is resolved in the latest SDK version. Download the Player SDK.

  • If a playback issue occurs, we recommend that you first use the playback URL check tool for self-diagnosis. This tool can quickly diagnose common playback issues and provide solutions. For more information, see Troubleshoot video playback issues.

Video playback can fail for many reasons. To identify the cause, first check if the errors follow a pattern. If they do, use the possible causes in the following table to guide your investigation. If there is no clear pattern, troubleshoot the problem by examining the end device, media stream, and network. If you still cannot identify the cause, contact Alibaba Cloud technical support.

  • Errors with a distribution pattern:

    Error pattern

    Possible cause

    Playback fails for users in specific ISP networks or regions.

    The issue may be caused by local carrier network problems or CDN scheduling issues in the region.

    Playback fails on end devices with specific operating systems.

    The issue may be caused by differences in SDK implementation across platforms or system compatibility issues.

    Playback fails on specific brands or models of end devices.

    The issue may be caused by device compatibility issues.

    Playback fails for specific audio or video files.

    The issue may be caused by problems with the media file encoding, CDN prefetch, or business access policies.

  • Errors with no clear distribution pattern: The cause may be complex. In this case, trace the workflow from content to user to identify the problematic node and determine the root cause.

image

Step 1: Check the end device

End device compatibility

First, verify that the media stream protocol is supported by the operating system and application environment. If not, you must transcode the stream. For more information, see Transcoding recommendations. The following tables list the video protocols and codecs supported by the 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 media stream protocol meets the web compatibility requirements below, verify that you have an SSL certificate and have enabled cross-origin access. For more information, see Enable HTTPS secure acceleration and Configure cross-origin access.

Operating system

Video codec

Video protocol

Audio codec

Android

H.264

  • MP4

  • HLS (Partially supported. Some browsers require MSE. See the table below for details.)

  • FLV (Requires MSE)

  • AAC

  • MP3

iOS

H.264

  • MP4

  • HLS

Note

FLV and MPEG-DASH are not supported.

H.265

  • MP4

  • HLS (fMP4 segments required)

Windows

H.264

  • MP4

  • HLS (Requires MSE)

  • FLV (Requires MSE)

macOS

H.264

  • MP4

  • HLS

  • FLV (Requires MSE)

H.265

  • MP4

  • HLS (fMP4 segments required)

Some browsers on Android devices require MSE to play HLS videos. The details are as follows:

Browser on Android devices

HLS support

WeChat

Supported

DingTalk

Supported

UC/Quark

Supported

QQ Browser

Supported

Chrome

Requires MSE

Huawei Browser

Requires MSE

OPPO Browser

Supported

vivo Browser

Supported

Mi Browser

Requires MSE

Player SDK compatibility

If your device meets the compatibility requirements, use a different player to check whether the issue is related to ApsaraVideo Player SDK compatibility.

  • If the video plays correctly in another player, the issue might be with the ApsaraVideo Player SDK. In this case, contact technical support.

  • If the video also fails to play in another player, you need to check the media stream and the network.

We recommend using the following players for troubleshooting:

  • Third-party player: VLC

  • System player: ExoPlayer (Android), AVPlayer (iOS)

  • System browser (Web only): Chrome (Android, Windows), Safari (iOS, macOS)

Step 2: Check the media stream

After ruling out the preceding causes, transcode the media stream and try playing it again. If it plays correctly, the original stream was likely encoded improperly.

Note

MP4 videos may start slowly or MOV videos may fail to play if the moov atom (media data index) is located after the mdat atom (media data). Transcoding the source video to move the moov atom before the mdat atom can speed up playback parsing.

  • Use the following command to check the position of the moov atom:

    # The source video URL can be a local file path or an online URL, for example, http://pla****.alicdn.com/video/aliyunmedia.mp4
ffmpeg -v trace -i "source_video_url" 2>&1 | grep -e type:\'mdat\' -e type:\'moov\'

    In a normal scenario, the moov atom is before the mdat atom, which indicates a faststart optimization. The example output is shown below.

    # ffmpeg -v trace -i sample_faststart.mp4 2>&1 | grep -e type:\'mdat\' -e type:\'moov\'
[mov,mp4,m4a,3gp,3g2,mj2 @ 0x54d3b80] type:'moov' parent:'root' sz: 603629 40 231901466
[mov,mp4,m4a,3gp,3g2,mj2 @ 0x54d3b80] type:'mdat' parent:'root' sz: 231297797 603677 231901466

    In an abnormal scenario, the moov atom is after the mdat atom.

    # ffmpeg -v trace -i sample.mp4 2>&1 | grep -e type:"mdat" -e type:"moov"
[mov,mp4,m4a,3gp,3g2,mj2 @ 0x59e1b80] type:'mdat' parent:'root' sz: 231297797 48 231901466
[mov,mp4,m4a,3gp,3g2,mj2 @ 0x59e1b80] type:'moov' parent:'root' sz: 603629 231297845 231901466

  • Use the following command or the ffprobe command-line tool (ffprobe tool) to query information such as the audio codec and video codec of the source file. This helps you analyze if problematic videos share any patterns:

    ffprobe "input.mp4" or ffprobe "source_video_url"

    Input #0, mov, mp4, m4a, 3gp, 3g2, mj2, from 'input.mp4':
    Metadata:
      major_brand     : isom
      minor_version   : 512
      compatible_brands: isomiso2avc1mp41
      encoder         : www.aliyun.com - Media Transcoding
    Duration: 00:00:17.56, start: 0.000000, bitrate: 3088 kb/s
    Stream #0:0(und): Video: h264 (High) (avc1 / 0x31637661), yuv420p, 1440x2560, 2890 kb/s, 25 fps, 25 tbr, 12800 tbn, 50 tbc (default)
      Metadata:
        handler_name    : VideoHandler
    Stream #0:1(und): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 191 kb/s (default)
      Metadata:
        handler_name    : SoundHandler

Transcoding recommendations

  • Transcoding output: We recommend transcoding to an H.264 MP4 or HLS video stream.

  • Transcoding method: We recommend using the following Alibaba Cloud services or local tools.

    Category

    Service or tool

    Description

    Alibaba Cloud service

    ApsaraVideo VOD

    ApsaraVideo VOD provides comprehensive transcoding and transmuxing capabilities to meet various media format conversion needs. It supports standard transcoding, Narrowband HD 1.0, Narrowband HD 2.0, and source-quality transcoding. For more information, see Audio and video transcoding.

    ApsaraVideo Media Processing (MPS)

    ApsaraVideo Media Processing (MPS) transcodes multimedia data into formats suitable for playback on all platforms. It supports standard transcoding, Narrowband HD 1.0, Narrowband HD 2.0, high-speed transcoding, and resolution-doubling transcoding. This is ideal for users who store source video files in their own OSS buckets. For more information, see Media transcoding.

    Intelligent Media Services (IMS)

    Intelligent Media Services (IMS) provides on-demand transcoding and real-time transcoding capabilities. It supports transcoding of media stored in OSS or ApsaraVideo VOD, as well as transcoding of live streams. For more information, see On-demand transcoding and Real-time transcoding.

    Local tool

    FFmpeg Codecs

    Download at: FFmpeg Codecs

    Format Factory

    Download at: Format Factory

Step 3: Check the network

If the previous steps did not resolve the issue, check the network transmission to locate the cause of the playback error.

  1. Verify that the end device has a stable network connection.

    • Wi-Fi: Is the current network stable and accessible? Is the downstream network speed greater than or equal to the video bitrate?

      You can use Speedtest.net to check the downstream network speed. If the speed is lower than the video bitrate, loading failures or playback stuttering may occur.

    • Mobile network: Is the device connected to a high-speed network like 4G or 5G? What is the signal strength?

      Under weak network conditions, the speed may not be sufficient for loading media streams.

    Note

    If you experience DNS hijacking, manually configure your DNS to Alibaba Cloud Public DNS (223.5.5.5, 223.6.6.6) to restore playback.

    1. Go to Settings > Wi-Fi on your mobile device.

    2. Tap the details button to the right of your current network to open the network details page.

    3. Configure DNS.

      On the network configuration page, you will find three sections: IP address (subnet, gateway), IPv6 address (IP address, gateway), and DNS. Tap the arrow next to the DNS entry to enter the detailed configuration.

  2. Check whether CDN acceleration is enabled.

    • If CDN acceleration is not enabled, we recommend configuring it to improve the playback experience. For more information, see Add an accelerated domain name.

    • If CDN acceleration is enabled:

      • CDN configuration issue: Has the media content been prefetched? Has the content cache expired?

        A CDN cache miss, caused by content that has not been prefetched or an expired cache, can lead to loading failures or playback stuttering. This issue is common with newly uploaded videos. We recommend actively prefetching content for new videos. For more information, see Refresh and prefetch resources.

      • Other issues: Do videos from other apps play normally on the same end device?

        If the CDN is configured correctly and other apps play videos without issue, the playback error may be caused by a localized CDN scheduling problem.

  3. Check the locations of the origin server and your end users.

    If the origin server is in the Chinese mainland and users are overseas, significant stuttering may occur. In this case, deploy the origin server in a region closer to your users to improve performance.

  4. Check for peak viewing times.

    If too many people are watching at the same time, the origin server may throttle traffic, causing playback to stutter.

Related documents

If you still cannot identify the cause after following the preceding steps, check the following documents for similar cases and solutions:

Contact technical support

If the problem persists, submit a ticket. For more information about how to submit a ticket, see Contact Us.

To help us resolve your issue efficiently, provide the following information in your ticket.

Item

Example

Description

Operating system and device platform

Android 9, Xiaomi

Provide the device brand and operating system version, for example: Xiaomi with Android 9, iOS 15, Windows 11, or macOS 12.

SDK and version

Android SDK 5.4.8.0

Specify the Player SDK you are using and its version number. Player SDKs include the Web SDK, Android SDK, iOS SDK, Flutter SDK, and Windows SDK.

Video source

https://xxxxxx.m3u8

Provide the URL of the video source or the video file that reproduces the problem.

Problem description, logs, and screen recording

Playback started at 16:40 on August 29, 2022, and stuttering occurred around 17:00. The log is attached.

Describe the reproduction steps and observed symptoms in detail, including specific timestamps. For reproducible issues, provide a complete log of the reproduction steps. For information about how to obtain logs, see Obtain logs on Android or Obtain logs on iOS. If necessary, attach a screen recording.

Error pattern

The issue occurs only on Android devices, not on iOS. It is always reproducible.

Describe whether the issue follows a specific pattern and its frequency. For example, specify if the issue is limited to a certain video source, device platform, or SDK version, and whether it is intermittent or always reproducible.
Previous：FAQNext：Single-point tracing