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:
- GitHub Issues - Report bugs or request features
- API Documentation - Complete parameter reference
- Check device logs for detailed error information