Better Player
Better video player for Flutter, with multiple configuration options. Solving typical use cases!
Introduction
This plugin is based on Chewie. Chewie is awesome plugin and works well in many cases. Better Player is a continuation of ideas introduced in Chewie. Better player fix common bugs, adds more configuration options and solves typical use cases.
Features:
✔️ Fixed common bugs
✔️ Added advanced configuration options
✔️ Refactored player controls
✔️ Playlist support
✔️ Video in ListView support
✔️ Subtitles support: (formats: SRT, WEBVTT with HTML tags support; subtitles from HLS; multiple subtitles for video)
✔️ HTTP Headers support
✔️ BoxFit of video support
✔️ Playback speed support
✔️ HLS support (track, subtitles selection)
✔️ Alternative resolution support
✔️ Cache support
✔️ Notifications support
✔️ ... and much more!
Install
- Add this to your pubspec.yaml file:
- Install it
- Import it
General Usage
Check Example project which shows how to use Better Player in different scenarios.
Basic usage
There are 2 basic methods which you can use to setup Better Player:
There methods setup basic configuration for you and allows you to start using player in few seconds.
Here is an example:
In this example, we're just showing video from url with aspect ratio = 16/9.
Better Player has many more configuration options which are presented below.
Normal usage
Create BetterPlayerDataSource and BetterPlayerController. You should do it in initState:
Create BetterPlayer widget wrapped in AspectRatio widget:
Playlist
To use playlist, you need to create dataset with multiple videos:
Then create BetterPlayerPlaylist:
BetterPlayerListViewPlayer
BetterPlayerListViewPlayer will auto play/pause video once video is visible on screen with playFraction. PlayFraction describes percent of video that must be visibile to play video. If playFraction is 0.8 then 80% of video height must be visible on screen to auto play video
You can control BetterPlayerListViewPlayer with BetterPlayerListViewPlayerController. You need to pass
BetterPlayerListViewPlayerController to BetterPlayerListVideoPlayer. See more in example app.
Subtitles
Subtitles can be configured from 3 different sources: file, network and memory. Subtitles source is passed in BetterPlayerDataSource:
Network subtitles:
File subtitles:
You can pass multiple subtitles for one video:
BetterPlayerConfiguration
You can provide configuration to your player when creating BetterPlayerController.
Possible configuration options:
BetterPlayerSubtitlesConfiguration
You can provide subtitles configuration with this class. You should put BetterPlayerSubtitlesConfiguration in BetterPlayerConfiguration.
Possible configuration options:
BetterPlayerControlsConfiguration
Configuration for player GUI. You should pass this configuration to BetterPlayerConfiguration.
BetterPlayerPlaylistConfiguration
Configure your playlist. Pass this object to BetterPlayerPlaylist
Possible configuration options:
BetterPlayerDataSource
Define source for one video in your app. There are 3 types of data sources:
- Network - data source which uses url to play video from external resources
- File - data source which uses url to play video from internal resources
- Memory - data source which uses list of bytes to play video from memory
You can use type specific factories to build your data source.
Use BetterPlayerDataSource.network to build network data source, BetterPlayerDataSource.file to build file data source and BetterPlayerDataSource.memory
to build memory data source.
Possible configuration options:
///Type of source of video
final BetterPlayerDataSourceType type;
///Url of the video
final String url;
///Subtitles configuration
///You can pass here multiple subtitles
final List<BetterPlayerSubtitlesSource> subtitles;
///Flag to determine if current data source is live stream
final bool liveStream;
/// Custom headers for player
final Map<String, String> headers;
///Should player use hls subtitles. Default is true.
final bool useHlsSubtitles;
///Should player use hls tracks
final bool useHlsTracks;
///List of strings that represents tracks names.
///If empty, then better player will choose name based on track parameters
final List<String> hlsTrackNames;
///Optional, alternative resolutions for non-hls video. Used to setup
///different qualities for video.
///Data should be in given format:
///{"360p": "url", "540p": "url2" }
final Map<String, String> resolutions;
///Optional cache configuration, used only for network data sources
final BetterPlayerCacheConfiguration cacheConfiguration;
BetterPlayerCacheConfiguration
Define cache configuration for given data source. Cache works only for network data sources.
BetterPlayerSubtitlesSource
Define source of subtitles in your video:
Possible configuration options:
BetterPlayerTranslations
You can provide translations for different languages. You need to pass list of BetterPlayerTranslations to
the BetterPlayerConfiguration. Here is an example:
There are 4 pre build in languages: EN, PL, ZH (chinese simplified), HI (hindi). If you didn't provide
any translation then EN translations will be used or any of the pre build in translations, only if it's
match current user locale.
You need to setup localizations in your app first to make it work. Here's how you can do that:
https://flutter.dev/docs/development/accessibility-and-localization/internationalization
Listen to video events
You can listen to video player events like:
After creating BetterPlayerController you can add event listener this way:
Your event listener will ne auto-disposed on dispose time :)
Change player behavior if player is not visible
You can change player behavior if player is not visible by using playerVisibilityChangedBehavior option in BetterPlayerConfiguration.
Here is an example for player used in list:
Player behavior works in the basis of VisibilityDetector (it uses visibilityFraction, which is value from 0.0 to 1.0 that describes how much given widget is on the viewport). So if value 0.0, player is not visible, so we need to pause the video. If the visibilityFraction is 1.0, we need to play it again.
Pass multiple resolutions of the video
You can setup video with different resolutions. Use resolutions parameter in data source. This should be used
only for normal videos (non-hls) to setup different qualities of the original video.
Setup player notification
![]() |
![]() |
To setup player notification use notificationConfiguration in BetterPlayerDataSource.
There are 3 majors parameters here:
title - name of the resource, shown in first line
author - author of the resource, shown in second line
imageUrl - image of the resource (optional). Can be both link to external image or internal file.
If showNotification is set as true and no title and author is provided, then empty notification will be
displayed.
User can control the player with notification buttons (i.e. play/pause, seek). When notification feature
is used when there are more players at the same time, then last player will be used. Notification will
be shown after play for the first time.
To play resource after leaving the app, set handleLifecycle as false in your BetterPlayerConfiguration.
Important note for android:
You need to add special service in android native code. Service will simply destroy all remaining notifications.
This service need to be used to handle situation when app is killed without proper player destroying.
Check BetterPlayerService in example project to see how to add this service to your app.
https://github.com/jhomlala/betterplayer/blob/feature/player_notifications/example/android/app/src/main/kotlin/com/jhomlala/better_player_example/BetterPlayerService.kt
Here is an example of player with notification: https://github.com/jhomlala/betterplayer/blob/feature/player_notifications/example/lib/pages/notification_player_page.dart
Add custom element to overflow menu
You can use BetterPlayerControlsConfiguration to add custom element to the overflow menu:
Enable/disable controls (always hidden if false)
Set overridden aspect ratio. If passed overriddenAspectRatio will be used instead of aspectRatio.
If null then aspectRatio from BetterPlayerConfiguration will be used.
Overridden duration
If overridden duration is set then video player will play video until this duration.