The Zype platform supports two types of subtitles: Sidecar and Embedded. Below we outline some of the key differences regarding the two types.
Sidecar Subtitles
This subtitle type refers to an uploaded external text file that is delivered to the player as a separate file from the video manifest.
You can upload subtitle files using the Subtitles tab on the edit page of any video. You can check our full article on how to upload and manage subtitles.
Note: Sidecar Subtitles are ONLY supported on Roku and Web players.
Embedded Subtitles
Unlike sidecar subtitles that are delivered separately from the video manifest, embedded subtitles are stitched into the video's HLS manifest. This type of subtitle is more widely supported across endpoint players.
Embedding a subtitle file is really simple. Below you can find a step by step guide on how to embed a subtitle into the video manifest using Zype's API:
Note: If you have the ability to host the subtitle files yourself, you can skip step 1. If you need the file to be hosted, you can follow step 1 to upload it to Zype before embedding it.
1. Upload the subtitle file on the Video Edit Options >> Subtitles tab and save it. Then, copy the link address URL which you will use in step 2.
IMPORTANT: You need to use the URL only up to the .vtt, the other characters must be deleted. For example, if the URL is like this https://gvsubtitles.zype.com/VIDEO_ID/ID/sidecar_subtitles/SUB_ID.vtt?16608, you need to remove the 16608.
2. Using a REST client or Zype's API tool, you will need to make the following call to the Subtitle Playlist endpoint
POST /videos/[REPLACE WITH video_id]/subtitle_playlists?api_key=[YOUR API KEY] HTTP/1.1
Host: api.zype.com
Content-Type: application/json
cache-control: no-cache
{
"subtitle_playlist": {
"language": "[LANGUAGE OF SOURCE SUBTITLE]",
"source_url": "[URL OBTAINED FROM PREVIOUS STEP]"
}
}
3. Erase the subtitle file from the Video Edit Options on the Admin page
To verify that the subtitle playlist has been created successfully for your desired video, you can query the View Player API endpoint for the video. Doing so will allow you to check that the subtitles have been embedded to the video manifest properly.
Note: We found and solved a bug in the transcode process that resulted in out of sync text when using embedded subtitles, this bug affects videos transcoded before July of 2020.
For affected videos, this issue can be solved by adding an offset at the top of the subtitle file, The subtitles files need to be edited by adding the following string of text:
X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:132000
The subtitle will then look similar to this:
WEBVTT
X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:132000
1
00:00:37.304 --> 00:00:39.172
We'd like to welcome all of you
...