Data Sources

Complete reference for IAppPlayerDataSource configuration and related classes.

Table of Contents

Data Source Overview

IAppPlayerDataSource is the core configuration object that defines how a video/audio resource should be loaded and played. It supports various sources including network URLs, local files, and memory data.

Creating a Data Source

static IAppPlayerDataSource createDataSource({ required String url, bool? liveStream, Map<String, String>? headers, more parameters >> })

Basic Parameters

Parameter Type Required Description
type IAppPlayerDataSourceType ✓ Data source type (network/file/memory)
url String ✓ Video URL or file path (needs trim, cannot be empty)
bytes List<int>? - Byte array for memory data source

Data Source Types

Type Description Use Case
network Network video Online video playback
file Local file Downloaded videos
memory Memory data Encrypted videos or dynamically generated
Note: Memory data source creates temporary files, automatically cleaned up on dispose or data source switch

Video Format

Parameter Type Description
videoFormat IAppPlayerVideoFormat? Video format (hls/dash/ss/other)
videoExtension String? Video file extension
liveStream bool? Is live stream

Video Format Types

Format Description File Extension
hls HTTP Live Streaming .m3u8
dash Dynamic Adaptive Streaming .mpd
ss Smooth Streaming .ism/manifest
other Other formats .mp4, .webm, .mkv, etc.

Supported Video Formats

Platform Supported Formats
Android MP4, WebM, MKV, MP3, AAC, HLS(.m3u8), DASH(.mpd), SmoothStreaming, FLV, AVI, MOV, TS
iOS MP4, M4V, MOV, MP3, HLS(.m3u8), AAC
Web Depends on browser (typically MP4, WebM, HLS)

Subtitle Configuration

Parameter Type Description
subtitles List<IAppPlayerSubtitlesSource>? Subtitle source list
useAsmsSubtitles bool Use HLS/DASH embedded subtitles

IAppPlayerSubtitlesSource

Subtitle configuration supports multiple formats including SRT, WebVTT, and LRC for lyrics.

For detailed subtitle configuration and examples, including LRC lyrics support, see Advanced Features → Subtitle System

Audio/Video Tracks (ASMS)

ASMS refers to Adaptive Streaming Media Sources, including HLS multi-bitrate video tracks, DASH multi-bitrate video tracks, multi-language audio tracks, and embedded subtitle tracks.
Parameter Type Description
useAsmsTracks bool Use HLS tracks (defaults based on liveStream)
useAsmsAudioTracks bool Use HLS/DASH audio tracks
asmsTrackNames List<String>? Custom track names

IAppPlayerAsmsTrack Properties

Property Type Description
id String? Track ID
width int? Video width
height int? Video height
bitrate int? Bitrate
frameRate int? Frame rate
codecs String? Codec format
mimeType String? MIME type

Network Configuration

Parameter Type Description
headers Map<String, String>? HTTP request headers
overriddenDuration Duration? Override video duration

Request Headers Example

dart 
headers: {
  'Authorization': 'Bearer token',
  'User-Agent': 'MyApp/1.0',
  'Referer': 'https://myapp.com',
}

Quality Configuration

Parameter Type Description
resolutions Map<String, String>? Multi-resolution URL mapping
dart 
// Resolution configuration example
resolutions: {
  "360p": "https://example.com/video_360p.mp4",
  "720p": "https://example.com/video_720p.mp4",
  "1080p": "https://example.com/video_1080p.mp4",
  "Auto": "auto",  // Special value for auto selection
}

Cache Configuration

IAppPlayerCacheConfiguration

Parameter Type Default Description
useCache bool Based on stream type Enable cache. Default based on liveStream:
• Non-live: true
• Live: false
preCacheSize int 10MB Pre-cache size
maxCacheSize int 300MB Max cache size
maxCacheFileSize int 50MB Single file max cache size
key String? null Cache key to distinguish different videos

Cache Key Naming Convention

dart 
// Recommended cache key naming convention
// Format: [app_name]_[type]_[unique_id]_[version]
cacheConfiguration: IAppPlayerCacheConfiguration(
  useCache: true,
  key: 'myapp_video_${videoId}_v1',
  // Or use URL MD5
  // key: md5.convert(utf8.encode(videoUrl)).toString(),
),

// Practical examples
// Movie: myapp_movie_tt0111161_v1
// Series: myapp_series_s01e01_12345_v1  
// Live: don't use cache
// User video: myapp_user_${userId}_${videoId}_v1

Notification Configuration

IAppPlayerNotificationConfiguration

Notification configuration object for controlling player notification bar display.

Parameter Type Default Description
showNotification bool false Show notification (true by default in non-TV mode)
activityName String? "MainActivity" Android Activity name
Note: Notification config is not created in TV mode, even if parameters are set

DRM Configuration

IAppPlayerDrmConfiguration

Parameter Type Description Platform
drmType IAppPlayerDrmType? DRM type Universal
token String? DRM token Universal
licenseUrl String? License URL Universal
certificateUrl String? Certificate URL iOS (FairPlay)
headers Map<String, String>? DRM request headers Universal
clearKey String? ClearKey configuration (JSON string) Android

For detailed DRM configuration examples including Widevine, FairPlay, and ClearKey, see Advanced Features → DRM Configuration

Buffering Configuration

IAppPlayerBufferingConfiguration

Parameter Type Default Description Platform
minBufferMs int? See notes Min buffer time (ms)
Live: 15s
VOD: 20s 		Android
maxBufferMs int? See notes Max buffer time (ms)
Live: 15s
VOD: 30s 		Android
bufferForPlaybackMs int? 3000 Buffer needed for playback (default 3s) Android
bufferForPlaybackAfterRebufferMs int? 5000 Buffer needed after re-buffering (default 5s) Android
Note: If buffering configuration is not provided, the system will automatically create appropriate default configuration based on whether it's a live stream.

Usage Examples

Complete Data Source Example

dart 
// Complete data source configuration example
final dataSource = IAppPlayerConfig.createDataSource(
  // Basic parameters
  url: 'https://example.com/video.mp4',
  liveStream: false,
  
  // Video format
  videoFormat: IAppPlayerVideoFormat.other,
  videoExtension: '.mp4',
  
  // Headers for authentication
  headers: {
    'Authorization': 'Bearer token',
    'User-Agent': 'MyApp/1.0',
  },
  
  // Multiple resolutions
  resolutions: {
    "360p": "https://example.com/video_360p.mp4",
    "720p": "https://example.com/video_720p.mp4",
    "1080p": "https://example.com/video_1080p.mp4",
    "Auto": "auto",
  },
  
  // Subtitles
  subtitles: [
    IAppPlayerSubtitlesSource(
      type: IAppPlayerSubtitlesSourceType.network,
      name: "English",
      urls: ["https://example.com/en.srt"],
      selectedByDefault: true,
    ),
    IAppPlayerSubtitlesSource(
      type: IAppPlayerSubtitlesSourceType.network,
      name: "Spanish",
      urls: ["https://example.com/es.srt"],
    ),
  ],
  
  // Cache configuration
  cacheConfiguration: IAppPlayerCacheConfiguration(
    useCache: true,
    maxCacheSize: 314572800, // 300MB
    maxCacheFileSize: 52428800, // 50MB
    key: 'myapp_video_${videoId}_v1',
  ),
  
  // Notification configuration
  notificationConfiguration: IAppPlayerNotificationConfiguration(
    showNotification: true,
    title: 'Now Playing',
    author: 'MyApp',
    imageUrl: 'https://example.com/cover.jpg',
    notificationChannelName: 'com.example.myapp',
    activityName: 'MainActivity',
  ),
  
  // Buffering configuration
  bufferingConfiguration: IAppPlayerBufferingConfiguration(
    minBufferMs: 20000, // 20 seconds
    maxBufferMs: 30000, // 30 seconds
    bufferForPlaybackMs: 3000, // 3 seconds
    bufferForPlaybackAfterRebufferMs: 5000, // 5 seconds
  ),
  
  // HLS/DASH tracks
  useAsmsTracks: true,
  useAsmsAudioTracks: true,
  useAsmsSubtitles: true,
);

Live Stream Example

dart 
// HLS live stream configuration
final liveDataSource = IAppPlayerConfig.createDataSource(
  url: 'https://example.com/live.m3u8',
  liveStream: true,
  title: 'Live Channel',
  
  // Live streams usually don't use cache
  cacheConfiguration: IAppPlayerCacheConfiguration(
    useCache: false,
  ),
  
  // Live stream buffering
  bufferingConfiguration: IAppPlayerBufferingConfiguration(
    minBufferMs: 15000, // 15 seconds
    maxBufferMs: 15000, // 15 seconds
    bufferForPlaybackMs: 2000, // 2 seconds
    bufferForPlaybackAfterRebufferMs: 3000, // 3 seconds
  ),
  
  // Enable adaptive streaming tracks
  useAsmsTracks: true,
  useAsmsAudioTracks: true,
);

DRM Protected Content

dart 
// Basic DRM configuration example
final drmDataSource = IAppPlayerConfig.createDataSource(
  url: 'https://example.com/protected_video.mpd',
  videoFormat: IAppPlayerVideoFormat.dash,
  
  drmConfiguration: IAppPlayerDrmConfiguration(
    drmType: IAppPlayerDrmType.widevine,
    licenseUrl: 'https://license.server.com/widevine',
    headers: {
      'Authorization': 'Bearer drm_token',
    },
  ),
  
  headers: {
    'Authorization': 'Bearer access_token',
  },
);

// For comprehensive DRM examples (Widevine, FairPlay, ClearKey), 
// see Advanced Features → DRM Configuration

Local File Example

dart 
// Playing a local file
final localDataSource = IAppPlayerConfig.createDataSource(
  url: '/storage/emulated/0/Movies/video.mp4',
  dataSourceType: IAppPlayerDataSourceType.file,
  liveStream: false,
  
  // Local files don't need cache
  cacheConfiguration: IAppPlayerCacheConfiguration(
    useCache: false,
  ),
  
  // Can still use subtitles
  subtitleUrl: '/storage/emulated/0/Movies/video.srt',
);

Best Practices

Recommendations
  • Use cache keys to distinguish different videos
  • Disable cache for live streams
  • Set appropriate headers for authenticated content
  • Configure buffering based on network conditions
  • Test DRM configuration on target devices
Common Issues
  • Multiple players may share cache directory
  • Memory data source creates temporary files
  • DRM requires proper license configuration
  • Too large buffer may cause memory issues
  • Notifications don't work in TV mode

Memory Usage Optimization Guidelines

dart 
// Recommended memory usage limits
// Single video instance:
// - 480p: 30-50MB
// - 720p: 50-80MB  
// - 1080p: 80-120MB
// - 4K: 150-200MB

// Device type recommendations:
// Mobile devices:
//   - Max simultaneous playback: 1-2 videos
//   - Cache size: 50-200MB
//   - Preload: Max 1 video

// Tablet devices:
//   - Max simultaneous playback: 2-3 videos
//   - Cache size: 100-500MB
//   - Preload: Max 2 videos

// TV devices:
//   - Max simultaneous playback: 1 video
//   - Cache size: 200MB-1GB
//   - Preload: 2-3 videos

Buffer Debounce Mechanism

  • Buffer state changes have 500ms default debounce time
  • Can adjust debounce time via setBufferingDebounceTime() method
  • Debounce mechanism avoids frequent buffer state switches, improving user experience

ASMS Subtitle Segment Smart Loading

  • HLS/DASH segmented subtitles use on-demand loading strategy
  • Pre-loads next 5 segment periods based on current playback position
  • Avoids loading all subtitle segments at once, saving memory and bandwidth
  • Subtitle segment position check has 1 second minimum interval to avoid frequent checks

Playlist Resource Management

  • IAppPlayerPlaylistController's dispose method force-releases internal player controller
  • Automatically pauses current video when switching playlists
  • Recommend calling dispose method when component is destroyed to release all resources