Troubleshooting

Common issues and their solutions when using IAppPlayer.

❌ Common Issues and Solutions

1. Video Cannot Play

Issue Description: Video loading fails or black screen

Solution:

dart
eventListener: (event) {
  if (event.iappPlayerEventType == IAppPlayerEventType.exception) {
    final error = event.parameters?['exception'];
    
    // Check error type and handle
    if (error.toString().contains('403')) {
      print('Authentication failed, please check headers configuration');
    } else if (error.toString().contains('404')) {
      print('Video not found');
    } else if (error.toString().contains('format')) {
      print('Video format not supported, try switching decoder');
      result.activeController?.retryDataSource();
    }
  }
}

2. Subtitles Not Displaying

Issue Description: Subtitle file loaded but not showing

Solution:

dart
// Check if subtitles loaded correctly
if (result.activeController?.subtitlesLines?.isEmpty ?? true) {
  print('Subtitles not loaded correctly');
  // Reset subtitles
  result.activeController?.setupSubtitleSource(
    IAppPlayerSubtitlesSource(
      type: IAppPlayerSubtitlesSourceType.network,
      urls: [subtitleUrl],
      selectedByDefault: true,
    ),
  );
}

3. Playback Stuttering

Issue Description: Video playback not smooth

Solution:

dart
// Monitor buffering status
eventListener: (event) {
  if (event.iappPlayerEventType == IAppPlayerEventType.bufferingUpdate) {
    final buffered = event.parameters?['buffered'] as List?;
    if (buffered != null && buffered.isNotEmpty) {
      final totalBuffered = buffered.last.inSeconds;
      print('Buffered: $totalBuffered seconds');
      
      // Pause and wait if insufficient buffering
      if (totalBuffered < 5) {
        result.activeController?.pause();
      }
    }
  }
}

4. Fullscreen Issues

Issue Description: Fullscreen transition issues or wrong orientation

Solution:

dart
// Listen to fullscreen events and customize handling
eventListener: (event) {
  if (event.iappPlayerEventType == IAppPlayerEventType.openFullscreen) {
    // Custom logic when entering fullscreen
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);
  } else if (event.iappPlayerEventType == IAppPlayerEventType.hideFullscreen) {
    // Custom logic when exiting fullscreen
    SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge);
  }
}

5. Null Value Handling

Issue Description: Player creation fails due to invalid URL

Solution:

dart
// Check parameters before creating player
final result = await IAppPlayerConfig.createPlayer(
  url: videoUrl,  // Might be null
  eventListener: (event) {},
);

// Check if player created successfully
if (result.activeController == null) {
  print('Player creation failed, please check if URL is valid');
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(content: Text('Unable to load video')),
  );
  return;
}

// Safely use controller
result.activeController?.play();

6. URL Format Validation Error

Issue Description: Playlist contains empty URLs

Solution:

dart
// Validate URLs before creating playlist
final validUrls = urls.where((url) => url.isNotEmpty).toList();

if (validUrls.isEmpty) {
  print('No valid video URLs');
  return;
}

// Create player with validated URLs
final result = await IAppPlayerConfig.createPlayer(
  urls: validUrls,
  eventListener: (event) {},
);

7. Lyrics Sync Issues

Issue Description: LRC lyrics not syncing or not retrievable

Solution:

dart
// Get current lyrics in progress event
eventListener: (event) {
  if (event.iappPlayerEventType == IAppPlayerEventType.progress) {
    // Get currently displayed lyrics
    final subtitle = result.activeController?.renderedSubtitle;
    if (subtitle != null && subtitle.texts != null) {
      final currentLyric = subtitle.texts!.join(' ');
      // Update UI to show current lyrics
      setState(() {
        _currentLyric = currentLyric;
      });
    }
  }
}

🐛 Debugging Tips

Debug Player State

dart
// Print key events in event listener
eventListener: (event) {
  print('IAppPlayer Event: ${event.iappPlayerEventType}');
  if (event.parameters != null) {
    print('Parameters: ${event.parameters}');
  }
}

// Check player state
void debugPlayerState() {
  final controller = result.activeController;
  print('=== Player State ===');
  print('Is Playing: ${controller?.isPlaying()}');
  print('Is Buffering: ${controller?.isBuffering()}');
  print('Is Initialized: ${controller?.isVideoInitialized()}');
  
  final value = controller?.videoPlayerController?.value;
  if (value != null) {
    print('Duration: ${value.duration}');
    print('Position: ${value.position}');
    print('Volume: ${value.volume}');
    print('Speed: ${value.speed}');
  }
  
  // Audio player specific: check current lyrics
  final subtitle = controller?.renderedSubtitle;
  if (subtitle != null && subtitle.texts != null) {
    print('Current Lyric: ${subtitle.texts!.join(' ')}');
  }
}

📱 Platform-specific Issues

Android
  • Multiple player instances may share cache directory
  • Recommend setting different cache keys for different videos
  • Based on ExoPlayer 2.15.1+
  • Widevine DRM requires device support. L1 provides the highest security level but may not be available on all devices
iOS
  • Enters fullscreen mode first when entering PiP
  • May have brief orientation issue when exiting PiP
  • Native HLS support (.m3u8)
  • FairPlay DRM requires certificate URL configuration. Some implementations may force L3 security level

Need More Help?

If you're still experiencing issues, try these resources: