# SubtitlesAPI Protocol

    public protocol SubtitlesAPI

Loads and displays subtitles.

- `onTextSegmentContent`

  Called when text segment have parsed a content. This is a callback where one can modify / fix segment content on the client side.

  #### Declaration

  Swift

      var onTextSegmentContent: StringModifierHandler? { get set }

  #### Parameters

  `content` | Incoming content text.
  `format` | Text format of the content.

- `subtitlesStyle`

  Custom Subtitle Style. It can be used to override (ignore) style properties specified in media.

  #### Declaration

  Swift

      var subtitlesStyle: SubtitlesStyle? { get set }

- `addTextTrack(_:completionHandler:)`

  Side-load subtitles content from a URL.

  Downloads and parses the subtitles content (if a supported format types). Creates a new subtitle track appended after any existing subtitle tracks. This requires the Subtitles Plugin. Subtitle tracks exist only during playback, therefore this function can only create tracks during that time-frame. Text track should define:

  - `sourceUrl`: location where to download the subtitle content file.
  - `format`: type of subtitle (webvtt, ttml etc).
  - `language`: string defined in RFC5646.

  - `label`: Display name of the track.

  Remark

  The player must be at least in `PlaybackState.ready` for this to have effect.

  Remark

  Sideloaded subtitles will not render in Airplay and Picture in Picture modes.

  #### Declaration

  Swift

      func addTextTrack(_ track: TextTrack, completionHandler: CompletionHandler?)

  #### Parameters

  `track` | Text track.
  `completionHandler` | Called when track has been downloaded, parsed and is ready to use.

- `reset()`

  Deletes all sideloaded subtitle tracks and resets internal state.

  #### Declaration

  Swift

      func reset()

- `previewSubtitles(withStyle:onView:)`

  Show a preview of the last loaded subtitles track on a UIView, useful for quickly showing the effect of changing style settings.

  Call `sideloadTrack()` before using this, to load a custom track to display. The last track loaded will always be the one displayed. This will only display the first subtitle cue in the track and keep it onscreen permanently.

  #### Declaration

  Swift

      func previewSubtitles(withStyle style: SubtitlesStyle, onView view: UIView)

  #### Parameters

  `style` | The style to use when displaying the preview.
  `view` | UIView on which to draw the subtitles preview. It should have an aspect ratio roughly equivalent to a video for accurate results.

- `getSideloadedTrackState(of:)`

  Returns the state of a sideloaded track.

  #### Declaration

  Swift

      func getSideloadedTrackState(of track: SideloadedTrack) -> SideloadedTrackState

  #### Parameters

  `track` | The sideloaded track to get the state of.

  #### Return Value

  The current state of the sideloaded track.