Media playback

How it works

Whether an audio or video file can be played depends on its Status. Only videos with a Normal status (the Status field is Normal) can be played. You can obtain the playback URLs for these videos using the ApsaraVideo VOD API or SDK.

The following diagrams show the status changes of a video from upload to playback.

• With transcoding

  

• Without transcoding

  

Therefore, before you obtain a playback URL, you must make sure that the video status is Normal.

Determination Method

After you upload a video, it is not immediately ready for playback. ApsaraVideo VOD must first confirm that the video is received. Use event notifications to determine when the uploaded video is ready to play.

• For videos or audio files that are not transcoded, you can play them after you receive a Video upload completed event notification. Then, you can call the GetPlayInfo operation to obtain the playback URL. Only files in the following formats can be played directly without transcoding: MP4, FLV, M3U8, MP3, and WEBM.

• For transcoded videos, you can play them after you receive a Single Definition Transcoding Complete event notification. To ensure that all definitions are available, wait for the Transcode complete event notification before you process the video.

Prerequisites

• Configure an accelerated domain name: Make sure that the ApsaraVideo VOD domain name has completed its ICP filing. For more information, see Domain name requirements. ApsaraVideo VOD does not require you to configure a CDN accelerated domain name (whether a CDN domain name is required depends on how you want to access the video): If you do not configure an accelerated domain name, you can call the Get Video Playback URLs operation (GetPlayInfo) to obtain an OSS URL that contains a time-limited authentication parameter and use it for playback (playback works even without an accelerated domain name). If you configure an accelerated domain name, you can use the CDN domain name for anonymous access, or implement more flexible cache control through URL signing. Both methods support normal playback, so configuring an accelerated domain name is not a required step for playback.

• Resolve the CNAME record for the domain name: Make sure that you have attached a CNAME record to the domain name. Otherwise, playback fails. For more information, see Configure a CNAME record with Alibaba Cloud DNS or Configure a CNAME record on DNSPod.

• Confirm the transcoding configuration: ApsaraVideo VOD can transcode or not transcode media files that you upload. For more information, see Audio and video transcoding.

• Confirm the security configuration: ApsaraVideo VOD provides multiple security features to protect your video content. These include access control, URL signing, remote authentication, video encryption, and secure download. These security configurations determine whether a video can be played. For more information, see Video security.

Playback URLs

• Configure the accelerated domain name.

  After you configure an accelerated domain name in the ApsaraVideo VOD console, the playback URL is a CDN file URL. You can view the URL on the Audio/Video > Manage > Video URL page in the console. Playback URLs can be fixed or dynamic. This depends on whether you enable URL signing in domain name management. For information about how to enable and configure URL signing, see URL signing.

  • Fixed Address

    Suitable for scenarios with low security requirements, the address remains permanently valid—that is, the address that does not contain authentication information after you disable the authentication switch (the value of the auth_key parameter in the URL is the authentication information). By default, the authentication switch is disabled after you add a domain name to the console.

  • Dynamic address

    Dynamic URLs are suitable for scenarios that have high security requirements. They are dynamically generated and expire after a specific period of time. The default validity period for dynamic URLs is the default validity period that you configure in URL signing. You can also set an expiration time when you Generate Playback URLs or Obtain Video Playback URLs. If a URL expires, Alibaba Cloud CDN returns HTTP 403 when accessed.

    Example of a dynamic URL:

    http://example.aliyundoc.com/video/aliyun-sample.mp4?auth_key=1500523200-0-0-80cd3862d699b7118eed99103f2a****

    Note

    In this example, the value of the auth_key parameter starts with 1500523200. This corresponds to 12:00:00 on July 20, 2017. If the Default Validity Period is set to 60 minutes, the URL expires at 13:00:00 on July 20, 2017.

• If no accelerated domain name is configured

  • When no accelerated domain name is configured, the returned playback URLs are OSS file URLs. In this case, URL signing is unavailable, but OSS authentication information is generated by default. For more information, see OSS - Include Signatures in URLs. When you call the Get Video Playback URLs API to obtain playback URLs, you can still use the AuthTimeout parameter to specify the time-to-live (TTL) for the video's OSS URL, but you cannot customize authentication information based on your AccessKey.

  • If you set the storage Bucket to public-read on the Storage Management page in the console, you can ignore OSS authentication information (for more information, see Storage Management). In this case, the URL is permanently valid, but there is a risk of hotlinking and illegal downloads. Therefore, the storage Bucket should be set to private whenever possible.

For more information about common settings for playback URLs, see Common playback settings.

You can obtain playback URLs in one of the following ways:

• Directly: View the event notification after transcoding is complete, or call the GetPlayInfo operation.

• Using a playback credential: Use the ApsaraVideo Player SDK and call the GetVideoPlayAuth operation to obtain a playback credential. The ApsaraVideo Player SDK automatically uses the credential to obtain the playback URL.

Playback methods

• Preview in the ApsaraVideo VOD console

  The ApsaraVideo VOD preview player provides features such as fast-forward, volume control, captions, audio tracks, resolution switching, and live comments. These features make it easy to preview your videos.

  • On the Audio/Video page in the console, select a video to preview. Encrypted streams are played by default.

  • On the Audio/Video > Manage > Video URL page in the console, select a stream to preview. To ensure video security, only unencrypted streams can be previewed.

• Integrate the ApsaraVideo Player SDK

  Before integrating the ApsaraVideo Player SDK, note the following version and authentication requirements:

  Recommended version: Use ApsaraVideo Player SDK 2.37.6 or later. This version resolves HLS playback compatibility issues with Chrome 141+ and Edge browsers, fixes abnormal plugin rendering, and addresses memory leak problems.

  Starting from SDK version 2.28.0, License authentication is mandatory. To configure License:

  1. Apply for a License Key on the SDK Management page in the ApsaraVideo VOD console. The Web standard edition License is currently free.

  2. During player initialization, configure the domain (the domain name of the page where the player is embedded, not the video storage or CDN domain) and licenseKey parameters.

  For details on obtaining and configuring a License, see How to obtain and configure a Web Player License?

  Resource path change: Starting from SDK version 2.16.3, the URL paths for JS and CSS resources have changed. When upgrading, update all resource references to the new paths.

  Integration methods:

  • VID + PlayAuth playback: Obtain a playback credential from the server and send it to the client for playback. This method provides high security. For more information, see Obtain a playback credential.

  • URL-based playback: Pass the obtained playback URL directly to the player. For more information, see Play a video using a playback URL.

  • Choosing between the standard edition and the professional edition: The ApsaraVideo Player SDK is available in a standard edition and a professional edition. The professional edition additionally supports advanced features such as H.266 encoding, DASH, external subtitles, preloading, pre-rendering, and advanced ABR strategies, none of which are included in the standard edition. If you only need basic playback control (such as playback of on-demand or live videos, variable-speed playback, and resolution switching), the standard edition is sufficient. If you need the advanced features listed above, we recommend that you purchase the professional edition.

  Important

  Important: Higher SDK versions enforce stricter parameter validation. In URL-based playback mode, do not specify incompatible parameters such as format:m3u8, and do not mix VID/PlayAuth parameters. The SDK does not support backward compatibility with all legacy APIs.

  • Dynamic watermark: The Web player supports dynamic watermarks (marquee/random flickering). Configure using the watermark parameter. This can coexist with static watermarks configured in the console.

  • Download control: Browsers provide a built-in download button that cannot be removed through link settings. To control download permissions, integrate the SDK and use parameters to manage download behavior.

  • Autoplay without SDK: When not using the ApsaraVideo SDK, implement autoplay by setting both autoplay:true and muted:true to comply with browser autoplay policies.

  • MPS playback method: The MPS playback method (using accId/accSecret) is still supported but no longer maintained. We recommend migrating to the recommended playback methods.

  • Blob URL: The new player may display blob URLs in the address bar. This is normal MSE (Media Source Extensions) behavior and not an error.

• Integrate a third-party player

  • Integrate a third-party player to play a video using a playback URL.

  • After you obtain a playback URL, pass it to your player. This method is flexible but requires you to implement features such as resolution switching and exception handling.

Playback security (limits on playback and download)

• Video security

  To protect your video content, ApsaraVideo VOD provides multiple security features. These include blacklists and whitelists, URL signing, and video encryption (Alibaba Cloud proprietary cryptography and HLS encryption). For more information, see Video security overview.

• Account security

  To ensure the security of your account, do not use the AccessKey pair of your Alibaba Cloud account or of a RAM user on the clients, especially web clients to access ApsaraVideo VOD. For more information, see Overview.

Billing description

• If you configure an accelerated domain name, you are charged for the CDN service when audio or video files are played.

• If you do not configure an accelerated domain name, you are charged for outbound traffic from storage when audio or video files are played.

For more information, see Basic service billing.

FAQ

How do I troubleshoot video playback failures?

1. Check the network: Confirm that the client has normal network connectivity.

2. Browser compatibility (Chrome/Edge 141+): If m3u8 playback fails, flickers, or returns error 4400 on new versions of Chrome or Edge, upgrade the Web Player to version 2.37.6 or later and verify that the License is correctly configured.

3. Parameter validation: In URL-based playback mode, verify that you have not incorrectly set format:m3u8 or mixed VID and PlayAuth parameters. The SDK enforces strict parameter validation in newer versions.

4. MEDIA_ERR_SRC_NOT_SUPPORTED or fragLoadError (403): Check Safari's native playback capability, CORS configuration, hotlink protection whitelist, and PlayAuth validity period (100 seconds).

5. ERR_CONNECTION_TIMED_OUT: Check local network connectivity, firewall rules, and CDN status.

6. Check the video status: Call the Get Audio and Video Playback URLs API or check in the console whether the video status is Normal.

7. Check the playback URL or credentials: Verify whether the auth_key has expired or the signature is valid.

8. Check the player: Confirm that the player supports the video format. For information about the formats supported by ApsaraVideo Player, see Features of ApsaraVideo Player SDK.

9. Stuttering or failed playback when a mobile browser directly opens a copied playback URL: This occurs when the playback URL lacks a valid URL signing signature, or the domain name has Referer hotlink protection enabled and blocks the request. Solution: Verify whether URL signing is enabled for the playback URL and whether it carries a valid auth_key signature. Check the Referer hotlink protection whitelist configuration for the domain name. We recommend that you use a signed playback URL or access the video through the Player SDK instead of exposing the raw playback URL directly.

10. Audio and video are out of sync during fast-forward playback in the video component of a WeChat mini program: This occurs because the native video component in WeChat mini programs does not fully support edit lists at the underlying level, causing the initial audio offset to accumulate during fast-forward playback or seek operations. Solution: We recommend that you use the ApsaraVideo Player SDK for web instead of the native video component, or transcode the video to improve compatibility.

11. The Web player stops working after a Chrome browser upgrade (HLS compatibility issue): We recommend that you upgrade the ApsaraVideo Player SDK for web to version 2.37.8 or later to resolve this compatibility issue, and apply for and configure a free License as needed (for how to apply for a License, see the description under "Prerequisites").

For more information about troubleshooting other errors, see Troubleshoot playback errors.

How do I play encrypted videos?

ApsaraVideo VOD offers multiple encryption methods, such as Alibaba Cloud proprietary cryptography and HLS encryption. To use encryption, configure an encrypted transcoding template group to transcode the video. Then, use the ApsaraVideo Player SDK to decrypt and play the video. For more information, see Video encryption.

Encrypted playback fails with InvalidParameter, indicating that the Rand parameter is invalid

If playback of an encrypted video fails with an InvalidParameter error indicating that the Rand parameter is invalid, you must set the corresponding encryptType parameter in the playback configuration. For more information, see the video encryption instructions in Video encryption.

What are the usage notes for common Player SDK APIs?

The following are common pitfalls and correct usage patterns when calling Player SDK APIs:

• Getting playback position on iOS: Use the position parameter from the onCurrentPositionUpdate callback. After seeking, listen for the AVPEventSeekEnd event before retrieving the position.

• getPlayTime() return value: Returns the playback duration as an integer in seconds. This reflects actual playback time (excluding pauses and seek operations). During speed-adjusted playback, the duration is calculated based on physical elapsed time.

• Switching video quality with selectTrack: If selectTrack fails when switching quality, use setQuality + setStartTime + prepare as a temporary workaround.

• Switching videos with replayByVidAndPlayAuth: When switching videos using replayByVidAndPlayAuth, explicitly pass the swScriptURL parameter (an absolute HTTPS URL) to support private encryption on older iOS versions.

• Setting start time: Setting the playback start time does not affect manual seek bar operations by the user.

• Buffer cleanup: The SDK currently does not support a dynamic buffer cleanup API during playback.

How to obtain and configure a Web Player License?

Frequently asked questions about Web Player License:

• How to apply: Apply for a License free of charge on the SDK Management page in the ApsaraVideo VOD console.

• Domain binding: The License is bound to the domain name shown in the browser's address bar of the page where the player is embedded (subdomains are supported). It is not bound to the video storage or CDN acceleration domain.

• No certificate file needed: The License is a string Key obtained via API. There is no need to download or deploy a certificate file to your server. Simply pass the domain and licenseKey parameters during player initialization.

• Shared video resources: Different Licenses can share the same video resource.

• Local debugging with HTTPS: If License validation fails due to HTTPS certificate issues during local testing, you can use one of the following methods (for testing only):

  • Use mkcert to generate a self-signed certificate.

  • Add the --ignore-certificate-errors flag when launching Chrome.

  • Deploy to a valid HTTPS test server.

• SDK 2.34 and later: License configuration is mandatory for the player to function properly.

• Data compliance for older SDK versions: Older versions of the ApsaraVideo Player SDK for web have data compliance issues. If you use the player outside mainland China, you must upgrade to a version that requires a License and bind a valid License. For how to apply for and configure a License, see License FAQ.

How to handle Web Player style and component issues?

Common issues and solutions for player styles and components:

• Missing icons in local deployment: If icons are missing during local deployment, download the complete /skins/default/ directory or update the relative paths in the CSS to use CDN addresses.

• QualityComponent quality switching error: When switching quality using QualityComponent, if you encounter a t.getQuality is not a function error, add the args callback function to your configuration and upgrade aliplayercomponents to version 1.1.2 or later.

• Cover image overlapping progress bar (VID + PlayAuth mode): When the cover image overlaps the progress bar in VID + PlayAuth mode, hide it using CSS (.prism-cover) or enable autoplay + muted to bypass the issue.

• WeChat browser HLS compatibility: For HLS playback issues in the built-in WeChat browser, configure useHlsNative: false to force the fMP4 playback solution.

How to specify a version when installing the Player SDK via npm?

To install a specific version of the Player SDK, use the following command:

npm install aliyun-aliplayer@<version> --save

For example, to install version 2.27.1:

npm install aliyun-aliplayer@2.27.1 --save