Subtitle Configuration

Better Player provides comprehensive support for subtitles, allowing you to load them from various sources and customize their appearance.

Subtitle Sources

Subtitles can be loaded from Network, File, or Memory sources (.srt, .vtt, or .ttml/.dfxp/.xml), or parsed automatically from HLS/DASH manifests (useAsmsSubtitles: true). You can also provide multiple subtitle tracks for a single video.

note

Soft-subtitles embedded directly inside standalone .mkv or .mp4 container files are not extracted by the Dart subtitle renderer. Extract them to an external .srt/.vtt/.ttml source or serve the stream via HLS/DASH with useAsmsSubtitles: true.

Example: Network Subtitles

var dataSource = PlayerDataSource(
    DataSourceType.network,
    "video_url",
    subtitles: PlayerSubtitlesSource.single(
        type: PlayerSubtitlesSourceType.network,
        url: "https://example.com/subtitles.srt"
    ),
);

Example: Multiple Subtitle Tracks

var dataSource = PlayerDataSource(
    DataSourceType.network,
    "hls_url",
    subtitles: [
        PlayerSubtitlesSource(
          type: PlayerSubtitlesSourceType.network,
          name: "English",
          urls: ["url_en"],
        ),
        PlayerSubtitlesSource(
          type: PlayerSubtitlesSourceType.network,
          name: "German",
          urls: ["url_de"],
        ),
    ],
);

Example: TTML / DFXP Subtitles

var dataSource = PlayerDataSource(
    DataSourceType.network,
    "video_url",
    subtitles: PlayerSubtitlesSource.single(
        type: PlayerSubtitlesSourceType.network,
        url: "https://example.com/subtitles.ttml",
        name: "English TTML",
    ),
);

Better Player automatically detects TTML / IMSC1 XML and parses:

• Clock-time formats (hh:mm:ss.fraction, SMPTE frames hh:mm:ss:ff) and timecounts (10s, 500ms, dur).
• Style inheritance across <tt>, <div>, <p>, and <span> elements.
• Custom colors (tts:color), weights, styles, and alignments.
• Line breaks (<br/>) and inline tags.

Embedded Closed Captions (CEA-608 / CEA-708)

For live broadcasts and HLS streams with CEA-608 / CEA-708 closed captions inside the video stream, Better Player parses them when useAsmsSubtitles: true:

var dataSource = PlayerDataSource(
    DataSourceType.network,
    "https://example.com/stream.m3u8",
    useAsmsSubtitles: true,
);

You can also specify embedded caption tracks manually on any data source:

var dataSource = PlayerDataSource(
    DataSourceType.network,
    "https://example.com/stream.m3u8",
    subtitles: [
        PlayerSubtitlesSource(
            type: PlayerSubtitlesSourceType.embedded,
            name: "CC1",
            index: 0,
            isClosedCaption: true,
        ),
    ],
);

The underlying platform engine decodes the caption cues from the video stream, and Better Player renders them in Flutter using your PlayerSubtitlesConfiguration.

Styling & Customization

The appearance of subtitles is controlled via PlayerSubtitlesConfiguration.

var betterPlayerConfiguration = PlayerConfiguration(
    subtitlesConfiguration: PlayerSubtitlesConfiguration(
        fontSize: 20,
        fontColor: Colors.white,
        outlineEnabled: true,
        outlineColor: Colors.black,
        alignment: Alignment.bottomCenter,
    ),
);

Parameters

• fontSize, fontColor, fontFamily: Basic text styling.
• outlineEnabled, outlineColor, outlineSize: Text border styling for better legibility.
• leftPadding, rightPadding, bottomPadding: Adjust subtitle positioning.
• alignment: The alignment of the subtitle text on the screen.
• backgroundColor: The background color of the subtitle text box.

Updating Styling at Runtime

Call setPlayerSubtitlesConfiguration on BetterPlayerController to update subtitle styling dynamically during playback:

betterPlayerController.setPlayerSubtitlesConfiguration(
  const PlayerSubtitlesConfiguration(
    fontSize: 22,
    fontColor: Colors.yellow,
  ),
);

Accessing Current Subtitles

To retrieve the text of the currently displayed subtitle, use the renderedSubtitle property on the BetterPlayerController.