When subtitles aren't working as expected, there are some steps that you can take to understand the cause of the issue. This guide will help you understand and resolve subtitle-related issues faster.

1. Which file format are you using?

Subtitle files come in various formats—each with its own features, specifications, and syntax—and support can vary across platforms. In order to understand which subtitles format you are using, you can use different tools:

Text formats (Sidecar subtitles)

These are plain-text files that can be opened in any text editor:

* Validate that your WebVTT file is correct and compliant with its specification using this free online tool: https://tools.igem.org/wiki/vtt-validator

Embedded/Binary formats

They require a more powerful tool like ffprobe to be identified:

2. Check: Single File or Fragmented Subtitles?

• Single file: Contains the subtitles for the entire video stream (used for VOD streams only)
• Fragmented subtitles: Each subtitle file only contains the subtitles for a fragment of the video stream (used for VOD and LIVE streams)

  When the subtitle track is correctly loaded by the Player, you can find this information in the Subtitles.SubtitleTrack.isFragmented property, for example inspecting player.subtitles.list()[0].isFragmented.

3. Where is the subtitle referenced?

• "In-Manifest subtitles":
  • Dash manifest (.mpd): referenced using <AdaptationSet> element with contentType="text". The mimeType parameter specifies the subtitle format. Common formats include WebVTT (text/vtt), TTML (application/ttml+xml) and ISOBMFF containers (application/mp4). For example
  manifest.mpd

  <AdaptationSet contentType="text" mimeType="application/ttml+xml" lang="ger">
      <Role schemeIdUri="urn:mpeg:dash:role:2011" value="subtitle"/>
      <Representation id="xml_ger" bandwidth="1000">
          <BaseURL>sub_ger_short.xml</BaseURL>
      </Representation>
  </AdaptationSet>
  

  You can use DASH Conformance Tool to verify that your .mpd manifest is conformant to the DASH specification.

  • HLS manifest (.m3u8): referenced using the EXT-X-MEDIA tag with TYPE=SUBTITLES. The EXT-X-MEDIA tag allows for specifying language, group ID, and a URI to the subtitle playlist or file.
  manifest.m3u8

  #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",URI="subtitles/eng.m3u8"
  

  You can use Apple's mediastreamvalidator Tool to verify that your .m3u8 manifest is conformant to the HLS specification.

• "Sideloaded subtitles": added to the Player at runtime
  • by using the PlayerSubtitlesAPI.add() function
  • by manually setting the SourceConfig.subtitleTracks configuration parameter.

    When the subtitle track is correctly loaded by the Player, you can find this information in the Subtitles.SubtitleTrack.isSideloaded property, for example inspecting player.subtitles.list()[0].isSideloaded.
    You can find additional information at: Web SDK: How to add external subtitles to the Bitmovin Player and React Native SDK: Adding external subtitle tracks

4. Which Player SDK and device are you using?

Subtitles support may vary across the different SDKs.

5. Now you can check if your subtitles are supported!

Visit Subtitles & Captions Support and verify if your subtitles are supported.
Note that for some combinations, only some of the features will be supported by our Player:

• Parsing and basic displaying
• Embedded Styling Rendering
• Positioning

6. If your subtitles are supported but you are still having issues

Inspect the Manifest and Subtitle Load Behavior

For In-Manifest (Dash or HLS) subtitles, you can generate a HAR file for troubleshooting. Inspecting your network traffic will allow you to:

1. Check the manifest that is being loaded by the player
2. Verify that your subtitles are correctly referenced in the manifest
3. Verify that the subtitles are loaded correctly and that no network errors appear

Check Subtitle Events in Player

Check if the Player was able to recognize the subtitles correctly

player.on("subtitleadded", function (e) {
	console.log(e);
	console.log(player.subtitles.list()); // Sideloaded subtitles should be available as soon as they are added
});
player.load(source).then(() => {
	console.log("Successfully created Bitmovin Player instance");
	console.log(player.subtitles.list()); // In-Manifest subtitles should already be available here
}),

Relevant APIs:

1. PlayerSubtitlesAPI
2. Subtitles Related PlayerEvents

Inspect Cue Behavior

If the subtitle track works, but the individual cues are incorrect, you can inspect the individual cues by subscribing to the related Player Events:

• CueEnter
• CueExit
• CueParsed
• CueUpdate

Styling Problems?

If the content and timing of the subtitles is correct, but the styling is off, it may be caused by your UI customization. Test the subtitles without any custom styling applied, and gradually add customizations until the issue appears. This will let you identify exactly which parameters are causing the issue.

7. Common Gotchas

• Why are my WebVTT subtitle tracks not in sync with the video?
• Why are subtitles not shown when casting from Android/iOS to a custom receiver app?
• Why do I see an additional "CC1" entry in the subtitle menu in Safari/iOS?
• Why are forced subtitles not displayed on iOS?
• How can I change the labels for video/audio qualities or subtitles in the settings menu?

8. Reach out for support!

We will gladly investigate and help with your issue!

1. Reproduce the issue:
   • WEB SDK: use our Player Playground
   • Other SDKs: use your SDK's example project
2. Open a support ticket
3. Include:
   • Findings from this guide
   • HAR file
   • Link to the Player Playground or Example source files

Following these steps will help us resolve your issue much faster!