Event System

Complete reference for IAppPlayer's event system, including all event types and their parameters.

Table of Contents

Event Overview

The IAppPlayer event system provides comprehensive feedback about player state changes, user interactions, and errors. All events are delivered through the eventListener callback specified when creating the player.

IAppPlayerEvent Structure

class IAppPlayerEvent { final IAppPlayerEventType iappPlayerEventType; final Map<String, dynamic>? parameters; }

Each event contains:

  • iappPlayerEventType - The type of event that occurred
  • parameters - Optional map containing event-specific data

Event Types

Lifecycle Events

Event Type Description Parameters When Triggered
initialized Player is ready to play - After video metadata is loaded
setupDataSource Data source is being set up dataSource: IAppPlayerDataSource When switching videos or playlists
finished Video playback completed - When video reaches the end

Playback Events

Event Type Description Parameters When Triggered
play Playback started - When play() is called
pause Playback paused - When pause() is called
seekTo Seek operation performed duration: Duration When seekTo() is called
progress Playback progress update progress: Duration
duration: Duration 		Every 500ms during playback
setVolume Volume changed volume: double (0.0-1.0) When setVolume() is called
setSpeed Playback speed changed speed: double When setSpeed() is called
Note: The progress event is throttled to fire at most once every 500ms to prevent performance issues.

Buffering Events

Event Type Description Parameters When Triggered
bufferingStart Buffering started - When player starts buffering
bufferingEnd Buffering completed - When buffering finishes
bufferingUpdate Buffer progress update buffered: List<Duration> When buffer state changes

Control Events

Event Type Description Parameters When Triggered
changedSubtitles Subtitle source changed subtitlesSource: IAppPlayerSubtitlesSource When subtitle is switched
changedTrack Video track changed track: IAppPlayerAsmsTrack When HLS track is switched
changedAudioTrack Audio track changed audioTrack: IAppPlayerAsmsAudioTrack When audio track is switched
changedResolution Resolution changed url: String When quality is switched

UI Events

Event Type Description Parameters When Triggered
openFullscreen Entered fullscreen mode - When entering fullscreen
hideFullscreen Exited fullscreen mode - When exiting fullscreen
pipStart Entered picture-in-picture - When PiP starts
pipStop Exited picture-in-picture - When PiP stops
controlsVisible Controls became visible - When controls show
controlsHiddenStart Controls start hiding - When controls begin to hide
controlsHiddenEnd Controls fully hidden - When controls are hidden
changedPlayerVisibility Player visibility changed visible: bool When player visibility changes

Playlist Events

Event Type Description Parameters When Triggered
changedPlaylistItem Playlist item changed index: int When switching playlist videos
togglePlaylistShuffle Shuffle toggle triggered - When shuffle button clicked
changedPlaylistShuffle Shuffle mode changed shuffleMode: bool When shuffle state changes

Error Handling

Exception Event

Event Type Description Parameters
exception An error occurred during playback exception: String (error message)

Common Error Types

Error Type Description Handling Suggestion
PlatformException Platform-specific error Check device compatibility, try different decoder
FormatException Unsupported video format Convert video format or use different source
NetworkException Network error (403/404/timeout) Check network connection and URL validity
DrmException DRM-related error Check DRM configuration and license
UnknownException Unknown error Check detailed error message and retry

Event Examples

Complete Event Handler

dart 
// Complete event handler example
eventListener: (IAppPlayerEvent event) {
  switch (event.iappPlayerEventType) {
    // Lifecycle events
    case IAppPlayerEventType.initialized:
      print('Player initialized');
      final duration = result.activeController?.videoPlayerController?.value.duration;
      print('Total duration: ${duration?.inSeconds} seconds');
      break;
      
    case IAppPlayerEventType.play:
      print('Started playing');
      break;
      
    case IAppPlayerEventType.pause:
      print('Paused');
      break;
      
    case IAppPlayerEventType.progress:
      final progress = event.parameters?['progress'] as Duration?;
      final duration = event.parameters?['duration'] as Duration?;
      if (progress != null && duration != null) {
        final percent = (progress.inSeconds / duration.inSeconds * 100).toStringAsFixed(1);
        print('Progress: $percent%');
      }
      break;
      
    case IAppPlayerEventType.bufferingStart:
      print('Buffering...');
      break;
      
    case IAppPlayerEventType.bufferingEnd:
      print('Buffering complete');
      break;
      
    case IAppPlayerEventType.finished:
      print('Playback finished');
      break;
      
    case IAppPlayerEventType.exception:
      final error = event.parameters?['exception'];
      print('Playback error: $error');
      break;
      
    case IAppPlayerEventType.openFullscreen:
      print('Entered fullscreen');
      break;
      
    case IAppPlayerEventType.hideFullscreen:
      print('Exited fullscreen');
      break;
      
    case IAppPlayerEventType.changedPlaylistItem:
      final index = event.parameters?['index'] as int?;
      print('Switched to playlist item ${index! + 1}');
      break;
      
    case IAppPlayerEventType.changedPlaylistShuffle:
      final shuffleMode = event.parameters?['shuffleMode'] as bool?;
      print('Shuffle mode: ${shuffleMode ? "On" : "Off"}');
      break;
      
    case IAppPlayerEventType.changedAudioTrack:
      final audioTrack = event.parameters?['audioTrack'] as IAppPlayerAsmsAudioTrack?;
      print('Audio track changed: ${audioTrack?.label} (${audioTrack?.language})');
      break;
      
    default:
      break;
  }
}

Best Practices

Recommended

  • Always handle the exception event
  • Use progress event for UI updates (already throttled)
  • Check event parameters for null before use
  • Implement retry logic for network errors
  • Track buffering events for analytics

Avoid

  • Don't perform heavy operations in event handlers
  • Don't ignore error events
  • Don't assume event order (except lifecycle)
  • Don't call setState() directly without checking mounted
  • Don't forget to handle playlist-specific events