Troubleshooting Alibaba Cloud VOD captions

Step 1: Verify caption file format

ApsaraVideo VOD captions support only the WebVTT format (.vtt). Non-standard files fail to parse. Before you proceed, ensure that your .vtt file meets the following requirements.

1. file header: The first line must contain only WEBVTT, with no leading byte order mark (BOM) or other characters.

2. encoding format: The file must be encoded in UTF-8.

3. Timestamp format: The timestamp must be in the HH:MM:SS.mmm --> HH:MM:SS.mmm or MM:SS.mmm --> MM:SS.mmm format. Note that a space is required on both sides of -->.

4. Content separator: A blank line must separate caption blocks (the timestamp and the caption text).

Example:

WEBVTT
00:00:01.000 --> 00:00:05.000
First caption text
00:00:06.000 --> 00:00:10.000
Second caption text
NOTE This is a comment and will not be displayed in the video
00:00:11.000 --> 00:00:13.000
Third caption text

Step 2: Verify caption upload process

Uploading a caption file through the API requires two steps: obtain credentials and upload the file.

1. Obtain credentials: Call the CreateUploadAttachedMedia operation to get the upload credentials and address.

2. Upload the file: Use the upload credentials and address to upload your local .vtt caption file to Alibaba Cloud VOD storage. For more information, see Upload media files by using Alibaba Cloud VOD APIs.

Step 3: Verify public access to caption storage

Copy the caption storage address from your caption template and paste it into a browser. The browser should display the caption file content or prompt you to download the .vtt file. If neither happens, check and correct the caption storage address.

Step 4: Verify caption packaging

ApsaraVideo VOD caption packaging supports only HLS adaptive bitrate streaming URLs (in .m3u8 format). Before playback, confirm that the playback URL is an adaptive stream URL. Players cannot load packaged captions from original file URLs, such as MP4 files.

Log on to the Alibaba Cloud VOD console and navigate to Media Files > Audio/Video. In the Actions column, click Manage. On the video details page, go to the Video URL tab. The list of video URLs must contain an adaptive stream URL in .m3u8 format. If not, check and correct your caption packaging configuration. For more information, see Configure adaptive bitrate streaming. In the video output list on the same tab, check the Adaptive row. If the resolution, bitrate, and size are 0*0, 0 Kbps, and 0 B respectively, the adaptive bitrate stream packaging has failed. In this case, verify your caption packaging configuration.

Step 5: Verify player settings

Make sure the player supports WebVTT captions over HLS. The Alibaba Cloud Player SDK supports this feature by default.

1. After playback starts, click the caption settings button in the lower-right corner.

2. Verify that the menu displays the name of the configured caption track.

   Click the CC button on the player control bar to open the caption selection menu. After selecting a configured caption track, for example Chinese_xsd, the corresponding caption text appears as an overlay on the video.

3. Click the option to turn on captions.

If no caption option is available or if captions are turned off, check the player settings.