Common player issues

VOD playback failures

Playback can fail due to issues with stream encoding, network endpoints, CDNs, formats, or storage buckets. To identify the cause, check player error messages and network requests. Common issues and solutions include:

• Overdue payment: Check your account balance. If your account is overdue, videos cannot be played.

• Network client issue: The video fails to play and returns error code 4400. Error code 4400 indicates that a resource cannot be loaded due to server or network issues. Please check if an SSL certificate is configured and if the HTTPS certificate has expired or is invalid.

• Format issue: The video format is not compatible with the player. For more information about the playback formats supported by ApsaraVideo VOD, see Player SDK features.

  Note

  To play M3U8 files with authentication, you must use a custom domain name. To add a domain name, see Add an accelerated domain name.

• Bucket issue: The configured storage bucket is invalid, or the signed URL for a private bucket has expired. This causes playback failure. To resolve this, disable URL signing for the bucket and set its permission to public-read.

• Cross-domain issue: Check whether the region of your accelerated domain name is the same as the video playback region. If they are different, playback fails. You can create a new accelerated domain name or change the region of the original one.

GetPlayInfo error: Video status invalid or under review

To successfully obtain playback information, a video's main status (Status) must be Normal and its review status (AuditStatus) must be Normal. If the video status is UploadSucc (the upload is successful but transcoding is not complete) or the AuditStatus is Init (under review), you must wait for transcoding to complete and the review to pass before you can obtain the playback information. We recommend that you use the GetVideoInfo API to query the latest status of the video and check whether the global review settings are affecting the review progress.

Errors when playing local M3U8 videos

An M3U8 file contains multiple Transport Stream (TS) segments. For local playback, these segments must exist locally with correct relative paths in the M3U8 file, as remote URLs are not supported.

The M3U8 index file and its corresponding .ts segment files (such as 000000.ts, 000001.ts, etc.) must be placed in the same directory.

Local M3U8 files must follow this directory structure.

External playback failures

Troubleshoot the issue as follows:

1. Check whether the video still exists in ApsaraVideo VOD.

2. Check whether an accelerated domain name is added.

   • No accelerated domain name is added: Check the permissions of the storage bucket. Check whether the storage bucket is private. If it is private, authentication is required. To play the video directly, you can disable authentication and set the bucket permission to public-read. Note that setting a bucket to public-read poses a security risk.

   • An accelerated domain name is added: Check whether authentication is enabled. If it is, you can extend the validity period of the authentication or disable authentication. Note that disabling authentication poses a security risk.

DRM-encrypted video cannot be played in a browser

Playing DRM-encrypted videos with ApsaraVideo Player for Web is subject to browser restrictions. For more information about supported browsers, see Feature compatibility.

MtsHlsUriToken for HLS encryption

The MtsHlsUriToken parameter is a custom parameter. In standard HLS encryption, after the encryption string is written into the HLS stream, the address of a decryption server is added to the M3U8 manifest. To allow only specific users to access the video, the decryption server requires an identity authentication mechanism. The MtsHlsUriToken parameter adds an authentication layer to your decryption server. A special parameter is then generated based on this authentication logic and passed for decryption verification.

When you configure encryption, you must build a token issuance service to generate the MtsHlsUriToken. For more information, see HLS encryption - Step 4.

Slow loading for videos from UK (London) in the Chinese mainland

Access from the Chinese mainland to the UK (London) region is slower due to distance. To improve performance, add an accelerated domain name and use Global Accelerator.

Slow access and stuttering for playback outside China

Stuttering during playback is usually caused by an unstable network. If the stuttering is long enough to cause a player error, it is likely related to CDN instability. If stuttering occurs frequently, check the network requests. The network speed may not match the video's bitrate. You may need to increase the network speed or decrease the bitrate.

Excessive requests during playback of OSS videos

Check whether there is an issue with the source video. For example, check whether the player sends many duplicate requests when decoding the source video. You can use an ApsaraVideo VOD transcoding template to transcode the video before playback. For more information, see Video and audio transcoding.

Preview image resources instead of downloading them

To preview images stored in ApsaraVideo VOD instead of downloading them, you must use a custom domain name. You can add a custom domain name to ApsaraVideo VOD. For more information, see Add an accelerated domain name.

Video playback fails on some computers with error code 4400

Error code 4400 indicates that the resource cannot be loaded due to server or network issues, or an unsupported format. Check whether an SSL certificate is configured.

Short playback URLs

If a video's storage bucket permission is private, its playback URL contains an authentication string and is a long URL. If the permission is public-read or public-read-write, the playback URL does not contain the authentication string and is a short URL. For more information about storage bucket permissions and how to modify them, see Manage Storage Buckets.

Playback failure of non-transcoded videos in HLS format

When you use ApsaraVideo Player with a video ID (VID) and a playback credential, you can play only transcoded videos. You can play videos that are not transcoded only by using a URL. You can call the GetMezzanineInfo operation to obtain the source video URL or log on to the ApsaraVideo VOD console to view the video URL.

Permanence of VOD playback URLs

When a video's storage bucket permission is private, its playback URL is valid for a limited time. The auth_key authentication string in the playback URL varies based on the configured expiration time.

To obtain a permanent playback address, you must change the permission of the video's storage bucket to public-read or public-read-write. The part of the generated playback address before the ? character is a permanent address that can be used for playback indefinitely. For more information about storage bucket permissions and how to modify them, see Manage Storage Buckets.

Playback URL redirects to a browser

Playback depends on the browser's and device's decoding capabilities, often resulting in a redirect to the browser.

Updated video not appearing

After you update a video, you need to refresh the URL to retrieve the latest data. To refresh the URL in the ApsaraVideo VOD console, see Refresh and prefetch. To refresh the URL by using an API or SDK, see PreloadVodObjectCaches or RefreshMediaPlayUrls.

Getting frame pixels from the player

• ApsaraVideo Player for Android: You can obtain the pixels by listening for the OnRenderFrameCallback callback.

• ApsaraVideo Player for iOS: You can obtain the pixels by listening for the onRenderingFrame callback.

  player.renderingDelegate = self;
  
  #pragma mark CicadaRenderingDelegate
  - (BOOL)onRenderingFrame:(CicadaFrameInfo*) frameInfo{
      if(frameInfo.frameType==Cicada_FrameType_Video){
          // Video
          NSLog(@"receive HW frame:%p pts:%ld foramt %d", frameInfo.video_pixelBuffer, frameInfo.pts, CVPixelBufferGetPixelFormatType(frameInfo.video_pixelBuffer));
  
      } else if (frameInfo.frameType==Cicada_FrameType_Audio){
          // Audio
      }
      return NO;
  }

• ApsaraVideo Player for Web: This feature is not supported.

Cannot get playback URL for AVI videos

The GetPlayInfo operation does not support obtaining video streams in AVI format. Therefore, SDKs that rely on this operation cannot obtain video streams in AVI format.

You can view the playback URL of an AVI video in the ApsaraVideo VOD console. For more information, see Query audio or video files.

GetPlayInfo error: "The video has no stream to play for the request parameter"

You can troubleshoot the issue as follows:

1. Confirm that the storage class of the media asset is Standard.

   By default, the GetPlayInfo operation returns playback streams only for media assets in the Standard storage class. To obtain playback streams for media assets of other storage classes, set the StorageClass parameter in the PlayConfig parameter to All.

   Other valid values for StorageClass include Standard, IA (Infrequent Access), Archive, ColdArchive, SourceIA (Source Infrequent Access), SourceArchive (Source Archive), SourceColdArchive (Source Cold Archive), Changing (media asset status changing), and SourceChanging (source file status changing). An empty value indicates no filtering.

2. Confirm that the media asset has a transcoded stream.

   To obtain a transcoded stream, you must first perform video and audio transcoding and then call the GetPlayInfo operation. To obtain the source stream URL, see GetMezzanineInfo.

Reducing video stuttering and improving cache hit rate

You can improve the cache hit rate by configuring URL signing, refreshing and prefetching content, configuring caching, and filtering parameters.

Stuttering when seeking

If a video has too few keyframes, seeking is slow because the player must decode a larger video segment to find a frame. This causes stuttering. In this case, you can transcode the video to add more keyframes and reduce stuttering. For more information about transcoding, see Video and audio transcoding.

Error 0x200600001 MEDIA_PLAYER_ERROR_CODEC_VIDEO_NOT_SUPPORT

If the message is vvc plugin not enabled, it means the plugin is not enabled in your application. Call the AliPlayerGlobalSettings.enableCodecPlugin method to enable it.

If the message is vvc plugin not loaded, it indicates that the plugin was not successfully integrated. Check whether the plugin library is successfully imported into the project, or explicitly call loadlibrary to ensure that the plugin is loaded successfully.

Error 0x50020002 MEDIA_PLAYER_ERROR_CODEC_PREMIUM_INVALID

This indicates that a Professional Edition license was not obtained. The H.266 decoder plugin is a feature of the Professional Edition. For more information about how to obtain a Professional Edition license, see Manage licenses.

Cannot get a video thumbnail

The ApsaraVideo VOD console uses the HTTPS protocol by default. Only resources that support HTTPS can be directly previewed and displayed as screenshots. You can also open the browser's developer tools to view specific error messages.

Video unplayable during manual review

ApsaraVideo VOD has two review modes. If the review mode is set to "review before publish", the video becomes playable only after it passes the review. The two review modes are as follows:

• Publish before review: After a video is transcoded, it is marked as Normal by default and can be played directly. You must then manually review the video. If the video is blocked after the review, it cannot be played.

• Review before publish: After a video is transcoded, it enters the review process by default and is marked as Under Review. The video becomes playable only after it passes the manual review.

VideoID

For security, ApsaraVideo VOD provides a video ID (videoID) instead of a direct URL when you upload a media file. You can also obtain the videoID by calling an ApsaraVideo VOD OpenAPI. For more information, see Get a video playback URL.

After you upload a video to ApsaraVideo VOD, you obtain a videoID.

You can also obtain the videoID in the ApsaraVideo VOD console. The procedure is as follows:

1. Log on to the ApsaraVideo VOD console.

2. In the left-side navigation pane, under the Media Files section, click Audio/Video.

3. In the video list, obtain the videoID.

You can use the videoID obtained from the console to test downloading and playback. For more information about how to upload files to ApsaraVideo VOD, see Overview of the upload SDK.

AccessKey ID and AccessKey secret

An Alibaba Cloud AccessKey ID and AccessKey secret are the only credentials for accessing Alibaba Cloud APIs. The AccessKey ID is an identity identifier. The AccessKey secret is like a password. Never disclose it.

To obtain your credentials:

1. Log on to the ApsaraVideo VOD console.

2. Move the mouse pointer over your profile picture in the upper-right corner and click AccessKey in the shortcut menu.

3. On the AccessKey page, create an AccessKey pair or view the AccessKey secret of an existing AccessKey ID.

PlayKey

A playKey (API key) is a playback key used to authenticate the identity when the player SDK obtains a video playback URL. Playback authentication is a secondary authentication mechanism based on Alibaba Cloud AccessKey security authentication. It can effectively prevent hotlinking. By default, playKeys are provided for Flash, HTML5, iOS, and Android platforms based on the platforms that users may use for playback.

To obtain a key:

1. Log on to the ApsaraVideo VOD console.

2. In the left-side navigation pane, under Configuration Management, choose CDN Configuration > Download Settings. Enable secure download mode.

3. In the Get Key section, enter the Unique App Identifier and Private Key.

4. Click Generate and Download Key.

Playauth

The player supports three playback modes. The playauth mode, implemented via the setAuthInfo method, is the most secure and recommended for commercial use.

A playauth is an encrypted string that contains information such as the videoID, AccessKey ID, and AccessKey secret. The ApsaraVideo VOD service mixes and encrypts this information. When the player receives the playauth, it can play the video.

Flow: The server obtains a playback credential > The server sends the playback credential to the client > Video playback is complete.

1. Obtain a playback credential: On the server, call the playback authentication SDK (server-side SDK) to obtain a playback credential from the ApsaraVideo VOD service.

2. Completing video playback: The player SDK uses the video ID and the playback credential to obtain the video's playback URL from the ApsaraVideo VOD service. It then loads the video stream and decodes it for playback.