Troubleshooting Alibaba Cloud VOD captions

Step 1: Verify caption file format

The Alibaba Cloud VOD caption feature supports only the Web Video Text Tracks (WebVTT) format (.vtt). Non-standard files will 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 via 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 web browser. The browser should either display the content of the caption file directly or prompt you to download the .vtt file. If it does not, check and correct the caption storage address.

Step 4: Verify caption packaging

The Alibaba Cloud VOD caption packaging feature supports only HTTP Live Streaming (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

Ensure that 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.