chewie: a Flutter video player UI layer built on top of the video_player plugin

video_player handles the playback layer; chewie sits on top as a UI wrapper

chewie does not play video. The video_player Flutter plugin handles low-level access to video playback on Android, iOS and web, while chewie takes whatever video_player provides and wraps it in a Material or Cupertino UI. The result is a player with play and pause buttons, a progress bar, volume controls, full-screen mode and an options menu, without the implementing developer having to write those widgets.

Both packages are separate pub.dev dependencies and must both appear in the project's pubspec.yaml. That separation is architectural. Every network request, codec decision, buffer and platform-specific media call happens inside video_player and the native platform code it calls. chewie has no code path for those operations and no ability to affect them. A team that needs to understand or fix a playback behavior will find the relevant code in video_player, not in chewie.

Three UI themes are included: MaterialControls for standard Android-style layouts, CupertinoControls for iOS-style layouts, and MaterialDesktopControls for desktop screens and pointer-based input. The README shows preview screenshots of all three, which is the quickest way to judge which theme matches the app's design before writing any code.

IMPORTANT section appears first in the table of contents, routing all exceptions to video_player

The README table of contents has 14 entries. The first entry, before Installation at item 4 and before Using it at item 5, is a section titled IMPORTANT!!! in uppercase. It states that chewie is not responsible for any issues caused by video_player because chewie is a UI layer on top of it. Any PlatformException raised during video playback is described as exclusive to video_player, and developers are directed to the Flutter team's issue tracker rather than the chewie repository.

That disclaimer is worth examining carefully. It covers PlatformExceptions arising from video playback specifically. It does not state that chewie itself is free of bugs; it is a statement about where playback exceptions originate. A developer debugging a crash first needs to determine whether the exception comes from platform media code, which belongs to video_player, or from chewie's widget layer. Placing the disclaimer as item 1 in the table of contents means it is easy to skip for a developer who jumps directly to Installation or Using it.

For adoption decisions, the disclaimer signals that chewie's scope is narrow by design. It renders controls. Platform codec coverage, network handling and streaming behavior are set by video_player, and chewie inherits those constraints without being able to modify them. The README's table of contents also lists Android warning and iOS warning as separate items 13 and 14, but those sections are not shown in the repository listing here; pub.dev has the full text.

Two packages in pubspec.yaml and three objects to initialize a working player

Both chewie and video_player must appear under dependencies:

dependencies:
  chewie: <latest_version>
  video_player: <latest_version>

The README uses `<latest_version>` as a placeholder rather than pinning a specific version, so checking pub.dev for current versions is a required step before adding these lines.

Three objects build a working player. First, create a VideoPlayerController pointed at the video source, such as a network URL. Call await videoPlayerController.initialize() before using it. Second, create a ChewieController with the initialized VideoPlayerController, plus configuration options like autoPlay and looping. Third, create a Chewie widget that takes the ChewieController.

Disposing both controllers is documented as required. The README shows overriding the dispose method of a StatefulWidget to call videoPlayerController.dispose() followed by chewieController.dispose() and then super.dispose(). Skipping disposal leaves the underlying platform resources that video_player holds open, which causes leaks.

Options open in a bottom sheet by default; optionsBuilder replaces the entire presentation

Tapping the options button opens a showModalBottomSheet with 2 built-in items: one for playback speed and one for subtitles. These are passed as OptionItem objects. To add more items, supply an additionalOptions callback to ChewieController, returning a list of OptionItem instances. Each item takes an onTap callback, an iconData from Flutter's Icons class, and a title string.

For apps where a bottom sheet does not fit the design, the entire options surface can be replaced with the optionsBuilder method. The callback receives the context and the list of default options, which already includes any additionalOptions provided, so the custom presentation starts with the full list rather than an empty one. The README shows replacing the bottom sheet with an AlertDialog as an example.

Option label text is configurable through OptionsTranslation. The README shows 3 configurable strings: playbackSpeedButtonText, subtitlesButtonText and cancelButtonText. Localized apps that need option labels in other languages pass an OptionsTranslation to the ChewieController. The README does not document a translation lookup mechanism; the strings are passed at controller construction time and are fixed after that.

pauseOnBackgroundTap converts the whole player area into a play/pause target

With pauseOnBackgroundTap set to true in ChewieController, any tap on the video area toggles playback. Users no longer need to target the center play/pause icon. The README presents this as eliminating the requirement to hit a small target during casual viewing.

The reversal of that convenience is that any accidental tap also triggers the toggle. An app where the video area carries other touchable elements, custom gesture recognizers or floating overlays faces potential conflict. The README does not document how pauseOnBackgroundTap interacts with full-screen mode, the subtitle display layer, or the options overlay when those are active at the same time. A team adding this feature to a complex player layout should test the tap behavior against every other interactive element in the view hierarchy before shipping.

The feature defaults to false, which means existing code relying on explicit icon taps is not affected by upgrading to a chewie version that includes this option. Enabling it is a deliberate opt-in, and disabling it returns to the icon-tap behavior without any other configuration change.

The README code sample for enabling it is minimal: one key in the ChewieController constructor. The comment in the sample confirms the intent: allow tapping anywhere on the video to pause and play.

Text overlays added in 1.1.0 default to hidden; three API points control their display

Starting with version 1.1.0, ChewieController accepts a List<Subtitle> for text overlays during playback. Three configuration points control the subtitle experience: the data itself, a subtitleStyle property for restyling the default subtitle box, and a subtitleBuilder function for replacing the default box with any custom widget.

The showSubtitles flag controls whether subtitles appear automatically when playback starts, and it defaults to false. Subtitles added to the controller are present but hidden until either the user enables them through the options menu, which lists Subtitles as one of the 2 default items, or the developer sets showSubtitles to true explicitly. For an app where subtitles should be on from the first frame of playback, that flag must be set.

The README's subtitles section ends before covering the full Subtitle type. Its fields and the supported subtitle format are not shown; pub.dev is the appropriate reference for those details. The same limitation applies to the chapters and casting features listed in the table of contents: both items appear in the ToC but not in the README text available in the repository.

N-1 Flutter policy carries a broad exception, and video_player is the no-wrapper alternative

The README states a Flutter version compatibility policy: chewie targets N-1 support at minimum, meaning the second most recent Flutter version. The very next sentence qualifies that promise: major changes between Flutter versions or changes to chewie's own dependencies may force breaking updates published as major or minor versions. The commitment is a best-effort floor with a broad exception built in, not a firm guarantee.

For a project pinned to an older Flutter version, this means compatibility cannot be assumed across chewie updates. The default branch is master. The last push was on 2026-09-16 with no GitHub releases, and the MIT licence is in the LICENSE file at the repository root.

The direct alternative to chewie is using video_player without the wrapper. That approach requires writing play, pause, seek and volume widgets by hand, but it removes the chewie UI layer entirely and gives full control over appearance and gesture handling. For teams whose visual requirements do not fit Material or Cupertino conventions, or who need tight touch handling in the player, the direct video_player path avoids the wrapper layer. The cost is the development time spent writing what chewie provides.

Editorial conclusion

chewie suits teams that want Material or Cupertino video controls without writing them from scratch, and whose platform requirements align with what video_player supports on Android, iOS and web. Any playback error belongs to video_player, not chewie. Before shipping, read the Android and iOS warning sections in the full README on pub.dev, confirm the current chewie build supports your installed Flutter edition under the N-1 policy, and test pauseOnBackgroundTap against any custom overlays your app places on the video.

Frequently asked questions

Official sources

1. fluttercommunity/chewie on GitHub
2. Issues
3. License: MIT
4. README