Player Configuration

Complete reference for the IAppPlayerConfig.createPlayer() method and all its parameters.

Table of Contents

Method Signature

static Future<PlayerResult> createPlayer({ String? url, List<String>? urls, Function(IAppPlayerEvent)? eventListener, // ... many more parameters })

Return Value

Returns a Future<PlayerResult> containing:

  • controller - IAppPlayerController for single video
  • playlistController - IAppPlayerPlaylistController for playlist
  • activeController - Always returns the current active controller
  • isPlaylist - Boolean indicating playlist mode

URL Format Auto-detection

IAppPlayer automatically detects video format and live stream status based on URL patterns.

URL Pattern Detected Format Live Stream
.m3u8 HLS Yes
.mpd DASH No
.flv FLV Yes
rtmp:// RTMP Yes
rtsp:// RTSP Yes
.mp4 MP4 No
Note: Detection results are cached for performance. Use IAppPlayerConfig.clearAllCaches() to clear the cache if needed.

Required Parameters (Choose One)

Important: You must provide either url or urls, but not both. Using both will throw an ArgumentError.
Parameter Type Description
url String? Single video URL (use this OR urls)
urls List<String>? Playlist URL array (use this OR url)

Basic Parameters

Parameter Type Default Description
eventListener Function(IAppPlayerEvent)? null Player event listener callback
title String? null Video title, also used as notification title
titles List<String>? null Playlist title array
imageUrl String? null Video cover image URL, also used as notification icon
imageUrls List<String>? null Playlist cover image URL array
author String? null Notification author info (usually app name)
notificationChannelName String? null Android notification channel name
backgroundImage String? null Player background image (supports network and local)

Notification Parameters Example

dart 
// Usage example:
IAppPlayerConfig.createPlayer(
  url: 'https://example.com/video.mp4',
  title: 'Video Title',         // Video title, also used as notification main title
  imageUrl: 'cover.jpg',        // Video cover, also used as notification icon
  author: 'App Name',           // Notification subtitle (usually app name)
  notificationChannelName: 'com.example.app', // Android notification channel
);

Subtitle Parameters

Parameter Type Default Description
subtitleUrl String? null Subtitle file URL
subtitleContent String? null Subtitle content string (e.g., LRC lyrics)
subtitleUrls List<String>? null Playlist subtitle URL array
subtitleContents List<String>? null Playlist subtitle content array
subtitles List<IAppPlayerSubtitlesSource>? null Advanced subtitle configuration

Playback Control Parameters

Parameter Type Default Description
autoPlay bool true Auto-play enabled
loopVideos bool true Loop playlist
looping bool? null Loop single video (null uses config default value false). Note: Forced to false in playlist mode
startAt Duration? null Start playback position
shuffleMode bool? null Enable shuffle mode for playlist
nextVideoDelay Duration? null Delay between playlist videos
initialStartIndex int? null Playlist initial start index
Note: In playlist mode, autoPlay is ignored when switching videos (always auto-plays), and looping is forced to false.

Advanced Parameters

Parameter Type Default Description
isTV bool false TV mode, disables notifications
headers Map<String, String>? null HTTP request headers
preferredDecoderType IAppPlayerDecoderType? null Preferred decoder type
liveStream bool? null Is live stream (auto-detected if null)
audioOnly bool? null Audio-only mode

Video Configuration Parameters

Parameter Type Default Description
videoFormat IAppPlayerVideoFormat? null Video format (auto-detected)
videoExtension String? null Video file extension
dataSourceType IAppPlayerDataSourceType? null Data source type
resolutions Map<String, String>? null Resolution mapping table
overriddenDuration Duration? null Override video duration

UI Configuration Parameters

Parameter Type Default Description
placeholder Widget? null Placeholder widget before video loads
errorBuilder Widget Function(BuildContext, String?)? null Error UI builder
overlay Widget? null Overlay widget on video
aspectRatio double? null Video aspect ratio
fit BoxFit? null Video scaling mode
rotation double? null Video rotation angle (multiple of 90)
showPlaceholderUntilPlay bool? null Show placeholder until play
placeholderOnTop bool? null Placeholder on top layer

Configuration Object Parameters

Parameter Type Description
playerConfiguration IAppPlayerConfiguration? Player core configuration object
controlsConfiguration IAppPlayerControlsConfiguration? Controls configuration object
subtitlesConfiguration IAppPlayerSubtitlesConfiguration? Subtitles configuration object
bufferingConfiguration IAppPlayerBufferingConfiguration? Buffering configuration object
cacheConfiguration IAppPlayerCacheConfiguration? Cache configuration object
notificationConfiguration IAppPlayerNotificationConfiguration? Notification configuration object
drmConfiguration IAppPlayerDrmConfiguration? DRM configuration object

Control Feature Toggles

Parameter Type Default Description
enableSubtitles bool? null Enable subtitles feature
enableQualities bool? null Enable quality selection
enableAudioTracks bool? null Enable audio track selection
enableFullscreen bool? null Enable fullscreen feature
enableOverflowMenu bool? null Enable overflow menu
handleAllGestures bool? true Handle all gestures
showNotification bool? null Show notification controls (invalid in TV mode)

Fullscreen Related Parameters

Parameter Type Default Description
fullScreenByDefault bool? null Default fullscreen playback
fullScreenAspectRatio double? null Fullscreen aspect ratio
deviceOrientationsOnFullScreen List<DeviceOrientation>? null Device orientations in fullscreen
deviceOrientationsAfterFullScreen List<DeviceOrientation>? null Device orientations after fullscreen
systemOverlaysAfterFullScreen List<SystemUiOverlay>? null System UI after fullscreen
autoDetectFullscreenDeviceOrientation bool? null Auto-detect fullscreen orientation
autoDetectFullscreenAspectRatio bool? null Auto-detect fullscreen aspect ratio

Streaming Parameters

Parameter Type Default Description
useAsmsTracks bool? null Use HLS/DASH video tracks
useAsmsAudioTracks bool? null Use HLS/DASH audio tracks
useAsmsSubtitles bool? null Use HLS/DASH embedded subtitles

Other Parameters

Parameter Type Default Description
handleLifecycle bool? null Handle app lifecycle
autoDispose bool? null Auto-dispose resources
allowedScreenSleep bool? null Allow screen sleep
expandToFill bool? null Expand to fill available space
routePageBuilder IAppPlayerRoutePageBuilder? null Custom route page builder
translations List<IAppPlayerTranslations>? null Multi-language translation config
useRootNavigator bool? null Use root navigator
playerVisibilityChangedBehavior Function(double)? null Player visibility change callback

Playlist Default Values

When using playlist mode without certain parameters, the system uses these defaults:

Scenario Default Value Description
No titles provided Video 1, Video 2... Auto-generated incremental titles
No subtitle names Subtitles Default subtitle name
Notification activity name MainActivity Android default activity name
Note: Playlists use List.generate for batch data source creation, ensuring efficient handling of large video collections.

Examples

Complete Initialization Example

dart 
// Complete example with all available parameters
final result = await IAppPlayerConfig.createPlayer(
  // Basic parameters
  url: 'https://example.com/video.mp4',
  eventListener: (event) => print('Event: ${event.iappPlayerEventType}'),
  title: 'Example Video',
  imageUrl: 'https://example.com/cover.jpg',
  backgroundImage: 'assets/background.png',
  
  // Subtitle parameters
  subtitleUrl: 'https://example.com/subtitle.srt',
  subtitles: [
    IAppPlayerSubtitlesSource(
      type: IAppPlayerSubtitlesSourceType.network,
      name: "English",
      urls: ["https://example.com/english.srt"],
      selectedByDefault: true,
    ),
  ],
  
  // Playback control
  autoPlay: false,
  looping: true,
  startAt: Duration(seconds: 10),
  
  // Advanced parameters
  isTV: false,
  audioOnly: false,
  liveStream: false,
  headers: {
    'Authorization': 'Bearer token',
    'User-Agent': 'MyApp/1.0',
  },
  
  // Video configuration
  preferredDecoderType: IAppPlayerDecoderType.hardwareFirst,
  videoFormat: IAppPlayerVideoFormat.hls,
  videoExtension: '.m3u8',
  dataSourceType: IAppPlayerDataSourceType.network,
  resolutions: {
    "720p": "https://example.com/video_720p.mp4",
    "1080p": "https://example.com/video_1080p.mp4",
  },
  
  // UI configuration
  placeholder: CircularProgressIndicator(),
  errorBuilder: (context, error) => Center(child: Text('Error: $error')),
  overlay: Container(
    alignment: Alignment.topRight,
    padding: EdgeInsets.all(8),
    child: Text('Watermark', style: TextStyle(color: Colors.white)),
  ),
  aspectRatio: 16 / 9,
  fit: BoxFit.contain,
  rotation: 0,
  showPlaceholderUntilPlay: true,
  placeholderOnTop: true,
  
  // Controls feature toggles
  enableSubtitles: true,
  enableQualities: true,
  enableAudioTracks: true,
  enableFullscreen: true,
  enableOverflowMenu: true,
  handleAllGestures: true,
  showNotification: true,
  
  // Fullscreen configuration
  fullScreenByDefault: false,
  fullScreenAspectRatio: 16 / 9,
  deviceOrientationsOnFullScreen: [
    DeviceOrientation.landscapeLeft,
    DeviceOrientation.landscapeRight,
  ],
  deviceOrientationsAfterFullScreen: [
    DeviceOrientation.portraitUp,
  ],
  systemOverlaysAfterFullScreen: SystemUiOverlay.values,
  autoDetectFullscreenDeviceOrientation: false,
  autoDetectFullscreenAspectRatio: false,
  
  // Streaming parameters
  useAsmsTracks: true,
  useAsmsAudioTracks: true,
  useAsmsSubtitles: true,
  overriddenDuration: Duration(minutes: 30),
  
  // Other parameters
  handleLifecycle: true,
  autoDispose: true,
  allowedScreenSleep: false,
  expandToFill: true,
  useRootNavigator: false,
  author: 'Author Name',
  notificationChannelName: 'MyApp Video Player',
  
  // Multi-language configuration
  translations: [
    IAppPlayerTranslations(
      languageCode: 'en',
      generalDefaultError: 'Cannot play video',
      generalNone: 'None',
      generalDefault: 'Default',
      generalRetry: 'Retry',
      playlistLoadingNextVideo: 'Loading next video',
      controlsLive: 'LIVE',
      controlsNextVideoIn: 'Next video in',
      overflowMenuPlaybackSpeed: 'Playback speed',
      overflowMenuSubtitles: 'Subtitles',
      overflowMenuQuality: 'Quality',
      overflowMenuAudioTracks: 'Audio tracks',
      qualityAuto: 'Auto',
    ),
  ],
  
  // Visibility change callback
  playerVisibilityChangedBehavior: (visibility) {
    print('Player visibility: $visibility');
  },
  
  // Route page builder
  routePageBuilder: (context, animation, secondaryAnimation, child) {
    return FadeTransition(
      opacity: animation,
      child: child,
    );
  },
);

Related Documentation