Subtitle System

IAppPlayer's subtitle system configuration and usage.

Supported Subtitle Formats

Format	Description	Example
`SRT`	SubRip subtitle format	.srt files
`WEBVTT`	Web Video Text Tracks	.vtt files, supports HTML tags
`LRC`	Lyrics format	.lrc files, suitable for music
`HLS Subtitles`	HLS embedded subtitles	Auto-detected
`DASH Subtitles`	DASH embedded subtitles	Auto-detected

Basic Subtitle Configuration

Video with Subtitles

dart

final result = await IAppPlayerConfig.createPlayer(
  url: 'https://example.com/video.mp4',
  title: 'Video Title',
  subtitleUrl: 'https://example.com/subtitles.srt',
  eventListener: (event) {
    if (event.iappPlayerEventType == IAppPlayerEventType.initialized) {
      print('Player initialized');
    }
  },
);

Multiple Subtitle Languages

dart

subtitles: [
  IAppPlayerSubtitlesSource(
    type: IAppPlayerSubtitlesSourceType.network,
    name: "English",
    urls: ["https://example.com/english.srt"],
    selectedByDefault: true,
  ),
  IAppPlayerSubtitlesSource(
    type: IAppPlayerSubtitlesSourceType.network,
    name: "Spanish",
    urls: ["https://example.com/spanish.srt"],
  ),
  IAppPlayerSubtitlesSource(
    type: IAppPlayerSubtitlesSourceType.none,
    name: "Off",
  ),
],

Music Player with LRC Lyrics

dart

// Single audio file playback - Poster Mode
final squareMusicPlayer = await IAppPlayerConfig.createPlayer(
  url: 'https://example.com/song.mp3',
  title: 'Song Name',
  audioOnly: true,
  aspectRatio: 1.0,  // Poster Mode
  subtitleContent:     '''[00:02.05]愿得一人心
[00:08.64]词：胡小健 曲：罗俊霖
[00:27.48]曾在我背包小小夹层里的那个人''',  // LRC lyrics content
  eventListener: (event) {
    if (event.iappPlayerEventType == IAppPlayerEventType.progress) {
      // Get current lyrics
      final subtitle = result.activeController?.renderedSubtitle;
      if (subtitle != null && subtitle.texts != null) {
        final currentLyric = subtitle.texts!.join(' ');
        print('Current lyrics: $currentLyric');
      }
    }
  },
);

HLS Segmented Subtitle Example

dart

// HLS segmented subtitle configuration
subtitles: [
  IAppPlayerSubtitlesSource(
    type: IAppPlayerSubtitlesSourceType.network,
    name: "English Subtitles",
    asmsIsSegmented: true,  // Mark as segmented subtitles
    asmsSegmentsTime: 10000, // 10 seconds per segment
    asmsSegments: [
      IAppPlayerAsmsSubtitleSegment(
        startTime: Duration.zero,
        endTime: Duration(seconds: 10),
        realUrl: 'https://example.com/subtitle_seg1.vtt',
      ),
      IAppPlayerAsmsSubtitleSegment(
        startTime: Duration(seconds: 10),
        endTime: Duration(seconds: 20),
        realUrl: 'https://example.com/subtitle_seg2.vtt',
      ),
    ],
  ),
],

Subtitle Configuration

IAppPlayerSubtitlesConfiguration provides full control over subtitle appearance:

See the API Reference for detailed subtitle configuration parameters including font settings, outline, margins, and style options.

Subtitle Best Practices

Use SRT format for video subtitles - it's widely supported
Use LRC format for music lyrics - provides precise timing
Always provide a "None" option to turn off subtitles
Test subtitle rendering on different screen sizes
Ensure good contrast between text and background
For HLS/DASH streams, enable useAsmsSubtitles to use embedded subtitles