Skip to main content

Migrating to Better Player 1.x.x

Better Player 1.x.x introduces a federated plugin architecture and a significantly cleaner public API. The package was split into smaller specialized packages, and redundant BetterPlayer prefixes were removed from model names.

The easiest way to migrate your codebase is to use the automated Dart fix tool. We have provided a fix_data.yaml that will handle all the class renames for you.

Just run this in your terminal:

dart fix --apply

2. Real-world API Name Changes​

To make the API cleaner and more idiomatic, almost all configuration and data models have dropped the BetterPlayer prefix. Here are side-by-side real-world examples of how to migrate your code in various scenarios.

Player & Data Source Configuration​

Before (0.8.x)After (1.x.x)
BetterPlayerController(
  BetterPlayerConfiguration(
    autoPlay: true,
  ),
  betterPlayerDataSource: BetterPlayerDataSource(
    DataSourceType.network,
    "https://example.com/video.mp4",
    videoFormat: BetterPlayerVideoFormat.hls,
    cacheConfiguration: BetterPlayerCacheConfiguration(
      useCache: true,
    ),
    bufferingConfiguration: BetterPlayerBufferingConfiguration(
      minBufferMs: 50000,
    ),
    notificationConfiguration: BetterPlayerNotificationConfiguration(
      showNotification: true,
      title: "My Video",
    ),
    drmConfiguration: BetterPlayerDrmConfiguration(
      drmType: BetterPlayerDrmType.widevine,
      licenseUrl: "https://example.com/license",
    ),
  ),
)
BetterPlayerController(
  PlayerConfiguration(
    autoPlay: true,
  ),
  betterPlayerDataSource: PlayerDataSource(
    DataSourceType.network,
    "https://example.com/video.mp4",
    videoFormat: VideoFormat.hls,
    cacheConfiguration: CacheConfiguration(
      useCache: true,
    ),
    bufferingConfiguration: BufferingConfiguration(
      minBufferMs: 50000,
    ),
    notificationConfiguration: NotificationConfiguration(
      showNotification: true,
      title: "My Video",
    ),
    drmConfiguration: DrmConfiguration(
      drmType: BetterPlayerDrmType.widevine,
      licenseUrl: "https://example.com/license",
    ),
  ),
)

Controls & UI Customization​

Before (0.8.x)After (1.x.x)
BetterPlayerControlsConfiguration(
  playerTheme: BetterPlayerTheme.material,
  progressBarPlayedColor: Colors.red,
  overflowMenuCustomItems: [
    BetterPlayerOverflowMenuItem(
      Icons.star,
      "Favorite",
      () => print("Clicked"),
    ),
  ],
)
PlayerControlsConfiguration(
  playerTheme: PlayerTheme.material,
  progressBarPlayedColor: Colors.red,
  overflowMenuCustomItems: [
    PlayerOverflowMenuItem(
      Icons.star,
      "Favorite",
      () => print("Clicked"),
    ),
  ],
)

Subtitles & Tracks​

Before (0.8.x)After (1.x.x)
final source = BetterPlayerSubtitlesSource(
  type: BetterPlayerSubtitlesSourceType.network,
  urls: ["https://example.com/sub.srt"],
);

final config = BetterPlayerSubtitlesConfiguration(
  fontSize: 20,
  fontColor: Colors.white,
);
final source = PlayerSubtitlesSource(
  type: PlayerSubtitlesSourceType.network,
  urls: ["https://example.com/sub.srt"],
);

final config = PlayerSubtitlesConfiguration(
  fontSize: 20,
  fontColor: Colors.white,
);

Playlists​

Before (0.8.x)After (1.x.x)
final playlistConfig = BetterPlayerPlaylistConfiguration(
  loopVideos: true,
  nextVideoDelay: Duration(seconds: 3),
);
final playlistConfig = PlayerPlaylistConfiguration(
  loopVideos: true,
  nextVideoDelay: Duration(seconds: 3),
);

Events & Utils​

Before (0.8.x)After (1.x.x)
_controller.addEventsListener((BetterPlayerEvent event) {
  if (event.betterPlayerEventType == BetterPlayerEventType.play) {
    print("Video is playing");
  }
});
_controller.addEventsListener((PlayerEvent event) {
  if (event.betterPlayerEventType == PlayerEventType.play) {
    print("Video is playing");
  }
});

3. Parameter Renames​

  • isPictureInPictureEnabled in BetterPlayerController has been renamed to isPictureInPictureSupported to better reflect its function (it checks if the hardware/OS supports PiP, not if it's currently turned on).

4. Migrating to v1.2.0 (Direct Native Bridges)​

Better Player 1.2.0 replaces the legacy asynchronous MethodChannel communication with Direct Native Bridges. This architectural shift provides higher performance, better type safety, and more reliable state synchronization.

What Changed?​

  • Android: Migrated to JNI using jnigen. The plugin now communicates directly with the Java/Kotlin media engine without the overhead of MethodChannel serialization.
  • iOS: Migrated to Swift FFI using swiftgen. This allows Dart to call into AVPlayer logic directly through the Objective-C runtime.
  • Platform Interface:
    • Renamed VideoPlayerPlatform to BetterPlayerPlatform.
    • Removed MethodChannelVideoPlayer.

Breaking Changes for Custom Implementations​

If you have extended Better Player or implemented a custom platform backend, you must update your references:

  1. Replace VideoPlayerPlatform with BetterPlayerPlatform:

    // Before
    class MyCustomPlatform extends VideoPlayerPlatform { ... }

    // After
    class MyCustomPlatform extends BetterPlayerPlatform { ... }

  2. Legacy MethodChannelVideoPlayer Removal: The class MethodChannelVideoPlayer is no longer available. All logic has been moved to the respective FFI/JNI implementations in better_player_android and better_player_ios.