ApsaraVideo VOD:ApsaraVideo Player SDK FAQ

Troubleshooting VOD playback failures

Check player error messages and network requests to diagnose failures. Failures can be caused by stream encoding issues, network endpoint or CDN problems, format incompatibilities, or bucket configuration issues. Common causes:

• Overdue payments: Check your account balance. If your account has an overdue balance, video playback is disabled.

• Network issue: The player returns error code 4400. Error code 4400 indicates the resource cannot load due to server or network issues. Verify that your SSL certificate is configured and valid.

• Format issues: The video format is not compatible with the player. Supported formats are listed in Player SDK features.

  Note

  Playing M3U8 files with authentication requires a custom domain name. Add an accelerated domain name.

• Bucket issues: The bucket is invalid, or private bucket authentication has expired. Disable bucket authentication and set the permission to public-read.

• Cross-domain issues: Playback fails if the accelerated domain name region differs from the video playback region. Create a new accelerated domain name or change the region of the existing one.

Errors when playing local M3U8 videos

An M3U8 file references transport stream (TS) segments. For local playback, all segments must exist on the local machine at the paths specified in the M3U8 file. Remote URLs within a local M3U8 file are not supported.

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

Your local M3U8 files must follow this directory structure.

Playback fails when shared externally

Follow these steps to troubleshoot the issue:

1. Verify that the video still exists in ApsaraVideo VOD.

2. Check whether an accelerated domain name is added.

   • If no accelerated domain name is added: Check the storage bucket permissions. If the bucket is private, playback requires authentication. You can disable authentication and set the bucket to public-read, but this poses a security risk.

   • If an accelerated domain name is added: Check whether authentication is enabled. If so, extend the validity period or disable it. Disabling authentication poses a security risk.

DRM playback issues in browsers

Browser support for DRM-encrypted playback with ApsaraVideo Player for Web is limited. Supported browsers are listed in Feature compatibility.

The MtsHlsUriToken parameter

The MtsHlsUriToken is a user token for HLS encryption. The M3U8 manifest contains a URL pointing to a decryption key server. To restrict access, add an authentication layer to your key server and append the MtsHlsUriToken, generated by your authentication logic, to the decryption key URL for verification.

When you configure encryption, build a token issuance service to generate the MtsHlsUriToken. HLS encryption - Step 4.

Slow cross-region playback from OSS

Accessing the UK (London) region from the Chinese mainland results in high latency. Add an accelerated domain name and use Global Accelerator to improve performance.

Slow access and buffering for overseas playback

Buffering is typically caused by an unstable network. Prolonged buffering leading to player errors suggests CDN instability. Frequent buffering may indicate insufficient bandwidth for the video bitrate — increase your network speed or reduce the bitrate.

Excessive requests during OSS playback

Check the source video — the player may send duplicate requests during decoding. Transcode the video with an ApsaraVideo VOD template before playback. Video and audio transcoding.

Previewing images instead of downloading

Images in ApsaraVideo VOD can only be previewed in a browser through a custom domain name. The default domain forces a download. Add an accelerated domain name.

Video fails to play on some computers with error code 4400

Error code 4400 indicates the resource cannot load due to server or network issues, or an unsupported format. Verify that an SSL certificate is configured.

Generating short playback URLs

A private bucket generates long playback URLs with authentication strings. Setting the bucket to public-read or public-read-write removes the authentication string, producing shorter URLs. Manage storage buckets.

Playback issues with untranscoded videos

The ApsaraVideo Player SDK with videoID and playauth plays only transcoded videos. Untranscoded videos require a direct URL, which you can get by calling GetMezzanineInfo or viewing it in the ApsaraVideo VOD console.

Are VOD playback URLs fixed?

When a video's storage is private, its playback URL is time-sensitive — the auth_key parameter varies based on the expiration time.

For a permanent URL, set the storage bucket to public-read or public-read/write. The URL before the ? character is a permanent address. Manage Storage Buckets.

Playback redirects to a browser

Playback depends on browser and device decoding capabilities. Third-party applications often redirect to a browser for compatibility.

Updated video not displayed during playback

After updating a video, refresh the CDN cache to ensure viewers get the latest version. In the console, use Refresh and prefetch. Via API or SDK, use PreloadVodObjectCaches or SubmitMediaRefreshJob.

Getting pixel data for each frame

• Android player: You can obtain it by listening for the OnRenderFrameCallback callback.

• iOS player: You can obtain it by listening to 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 API operation does not support retrieving streams for videos in AVI format. Therefore, SDK methods that rely on this API operation cannot obtain playback URLs for AVI videos.

View the playback URL of an AVI video in the ApsaraVideo VOD console. View media asset information.

GetPlayInfo API error when obtaining a playback address: The video has no stream to play for the request parameter

Follow these steps to troubleshoot the issue:

1. Confirm the storage class of the media asset.

   By default, the GetPlayInfo operation returns playback streams only for media assets in Standard storage. To obtain playback streams for audio and video in non-Standard storage, you can set the PlayConfig parameter's StorageClass to All.

   Other valid values for StorageClass include Standard, IA (for Infrequent Access media), Archive (for Archive media), Cold Archive (for Cold Archive media), Source IA (for IA source files), Source Archive (for Archive source files), Source Cold Archive (for Cold Archive source files), Changing (for media whose storage class is being changed), and SourceChanging (for source files whose storage class is being changed). If you leave the parameter empty, no filter is applied.

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

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

Reducing buffering and improving cache hit ratio

Improve the cache hit ratio by configuring URL signing, using refresh and prefetch, optimizing cache settings, and filtering URL parameters.

Buffering when seeking

With too few keyframes, seeking requires the player to download a large segment to find the nearest keyframe, causing buffering. Transcode the video to add more keyframes. Video and audio transcoding.

Error 0x200600001 MEDIA_PLAYER_ERROR_CODEC_VIDEO_NOT_SUPPORT reported

When the message is vvc plugin not enabled, the plugin is not enabled at the application layer. Call AliPlayerGlobalSettings.enableCodecPlugin to enable it.

When the message is vvc plugin not loaded, the plugin was not integrated successfully. Verify the plugin library is imported, or call loadlibrary explicitly.

0x50020002 MEDIA_PLAYER_ERROR_CODEC_PREMIUM_INVALID error

This error indicates the Professional Edition license is missing. The H.266 decoder plugin requires a Professional Edition license. Manage licenses.

Cannot get video thumbnails

The ApsaraVideo VOD console uses HTTPS by default. Thumbnail URLs must support HTTPS for in-console preview. Check browser developer tools for specific errors.

Cannot play video during manual review

ApsaraVideo VOD provides two review modes:

• Publish before review: After transcoding, the video is marked Normal and can be played immediately. You must then manually review the video. If blocked during review, playback stops.

• Review before publish: After transcoding, the video enters review and is marked Under Review. Playback starts only after manual approval.

The videoID parameter

For security, ApsaraVideo VOD returns a videoID instead of a direct URL when you upload a media file. You can also obtain the videoID by calling the GetPlayInfo API.

After you upload a video to ApsaraVideo VOD, a videoID is returned.

You can also obtain the videoID in the ApsaraVideo VOD console. Follow these steps:

1. Log on to the ApsaraVideo VOD console.

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

3. Find the videoID (Video ID) in the video list.

Use the videoID from the console to test downloading and playback. To upload files, use the Upload SDKs.

AccessKey ID and AccessKey Secret

Your AccessKey ID and AccessKey Secret are credentials for accessing Alibaba Cloud APIs. The AccessKey ID is an identifier, and the AccessKey Secret signs API request parameters to prevent tampering. Keep the AccessKey Secret confidential.

To get your AccessKey pair:

1. Log on to the ApsaraVideo VOD console.

2. In the upper-right corner, move the pointer over your profile picture and click AccessKey Management.

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

The playKey parameter

A playKey (or API key) authenticates requests when the ApsaraVideo Player SDK retrieves a video playback URL. It serves as secondary authentication on top of AccessKey-based security, preventing hotlinking. PlayKeys are provided for Flash, H5, iOS, and Android.

To get a playKey:

1. Log on to the ApsaraVideo VOD console.

2. In the left-side navigation pane, choose Configuration Management > 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.

The playauth parameter

The ApsaraVideo Player SDK supports three playback modes for different use cases. The method that uses a playauth is the most secure and is recommended.

A playauth is an encrypted token containing the videoID and authentication information. Your server requests this token from ApsaraVideo VOD and passes it to the client, which uses it to securely retrieve the playback URL.

Workflow: Server obtains playauth > Server sends playauth to client > Client plays video.

1. Obtain a playauth: Your application server calls the server-side SDK to request a playauth from the ApsaraVideo VOD service.

2. Play the video: The ApsaraVideo Player SDK uses the videoID and the playauth to request the video's playback URL from the ApsaraVideo VOD service, then loads and decodes the video stream for playback.