Merge pull request #872 from floodoo/master

feat: Add `showSubtitles` flag to control subtitles (#648)

Author: diegotori

README.md

@@ -129,11 +129,17 @@ optionsTranslation: OptionsTranslation(
 
 ## Subtitles
 
-> Since version 1.1.0 chewie supports subtitles. Here you can see how to use them.
+> Since version 1.1.0, Chewie supports subtitles.
 
-You can provide an `List<Subtitle>` and customize your subtitles with the `subtitleBuilder` function.
+Chewie allows you to enhance the video playback experience with text overlays. You can add a `List<Subtitle>` to your `ChewieController` and fully customize their appearance using the `subtitleBuilder` function.
 
-Add subtitles to your `ChewieController` like the following example:
+### Showing Subtitles by Default
+
+Chewie provides the `showSubtitles` flag, allowing you to control whether subtitles are displayed automatically when the video starts. By default, this flag is set to `false`.
+
+### Adding Subtitles
+
+Here’s an example of how to add subtitles to your `ChewieController`:
 
 ```dart
 ChewieController(
@@ -151,9 +157,10 @@ ChewieController(
       index: 1,
       start: const Duration(seconds: 10),
       end: const Duration(seconds: 20),
-      text: 'Whats up? :)',
+      text: 'What’s up? :)',
     ),
   ]),
+  showSubtitles: true, // Automatically display subtitles
   subtitleBuilder: (context, subtitle) => Container(
     padding: const EdgeInsets.all(10.0),
     child: Text(
@@ -164,9 +171,16 @@ ChewieController(
 );
 ```
 
-The `index` attribute is for if you want to structure your subtitles in your database and provide your indexes here. `end` and `text` are the key attributes. 
+### Subtitle Structure
+
+The `Subtitle` model contains the following key attributes:
 
-The Duration defines which part of your video your subtitles should start and end. For example, if your video is 10 minutes long and you want to add a subtitle between: `00:00` and `00:10`'th of a second:
+- **`index`**: A unique identifier for the subtitle, useful for database integration.
+- **`start`**: The starting point of the subtitle, defined as a `Duration`.
+- **`end`**: The ending point of the subtitle, defined as a `Duration`.
+- **`text`**: The subtitle text that will be displayed.
+
+For example, if your video is 10 minutes long and you want to add a subtitle that appears between `00:00` and `00:10`, you can define it like this:
 
 ```dart
 Subtitle(
@@ -177,6 +191,10 @@ Subtitle(
 ),
 ```
 
+### Customizing Subtitles
+
+Use the `subtitleBuilder` function to customize how subtitles are rendered, allowing you to modify text styles, add padding, or apply other customizations to your subtitles.
+
 ## Example
 
 Please run the app in the [`example/`](https://github.com/brianegan/chewie/tree/master/example) folder to start playing!

example/lib/app/app.dart

@@ -41,9 +41,9 @@ class _ChewieDemoState extends State<ChewieDemo> {
   }
 
   List<String> srcs = [
-    "https://assets.mixkit.co/videos/preview/mixkit-spinning-around-the-earth-29351-large.mp4",
-    "https://assets.mixkit.co/videos/preview/mixkit-daytime-city-traffic-aerial-view-56-large.mp4",
-    "https://assets.mixkit.co/videos/preview/mixkit-a-girl-blowing-a-bubble-gum-at-an-amusement-park-1226-large.mp4"
+    "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
+    "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4",
+    "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4",
   ];
 
   Future<void> initializePlayer() async {
@@ -126,6 +126,7 @@ class _ChewieDemoState extends State<ChewieDemo> {
         ];
       },
       subtitle: Subtitles(subtitles),
+      showSubtitles: true,
       subtitleBuilder: (context, dynamic subtitle) => Container(
         padding: const EdgeInsets.all(10.0),
         child: subtitle is InlineSpan

lib/src/chewie_player.dart

@@ -288,6 +288,7 @@ class ChewieController extends ChangeNotifier {
     this.zoomAndPan = false,
     this.maxScale = 2.5,
     this.subtitle,
+    this.showSubtitles = false,
     this.subtitleBuilder,
     this.customControls,
     this.errorBuilder,
@@ -339,6 +340,7 @@ class ChewieController extends ChangeNotifier {
     bool? zoomAndPan,
     double? maxScale,
     Subtitles? subtitle,
+    bool? showSubtitles,
     Widget Function(BuildContext, dynamic)? subtitleBuilder,
     Widget? customControls,
     WidgetBuilder? bufferingBuilder,
@@ -391,6 +393,7 @@ class ChewieController extends ChangeNotifier {
       optionsBuilder: optionsBuilder ?? this.optionsBuilder,
       additionalOptions: additionalOptions ?? this.additionalOptions,
       showControls: showControls ?? this.showControls,
+      showSubtitles: showSubtitles ?? this.showSubtitles,
       subtitle: subtitle ?? this.subtitle,
       subtitleBuilder: subtitleBuilder ?? this.subtitleBuilder,
       customControls: customControls ?? this.customControls,
@@ -454,6 +457,12 @@ class ChewieController extends ChangeNotifier {
   /// Add a List of Subtitles here in `Subtitles.subtitle`
   Subtitles? subtitle;
 
+  /// Determines whether subtitles should be shown by default when the video starts.
+  ///
+  /// If set to `true`, subtitles will be displayed automatically when the video
+  /// begins playing. If set to `false`, subtitles will be hidden by default.
+  bool showSubtitles;
+
   /// The controller for the video you want to play
   final VideoPlayerController videoPlayerController;
 

lib/src/cupertino/cupertino_controls.dart

@@ -641,7 +641,8 @@ class _CupertinoControlsState extends State<CupertinoControls>
   }
 
   Future<void> _initialize() async {
-    _subtitleOn = chewieController.subtitle?.isNotEmpty ?? false;
+    chewieController.showSubtitles &&
+        (chewieController.subtitle?.isNotEmpty ?? false);
     controller.addListener(_updateState);
 
     _updateState();

lib/src/material/material_controls.dart

@@ -525,7 +525,8 @@ class _MaterialControlsState extends State<MaterialControls>
   }
 
   Future<void> _initialize() async {
-    _subtitleOn = chewieController.subtitle?.isNotEmpty ?? false;
+    _subtitleOn = chewieController.showSubtitles &&
+        (chewieController.subtitle?.isNotEmpty ?? false);
     controller.addListener(_updateState);
 
     _updateState();

lib/src/material/material_desktop_controls.dart

@@ -493,7 +493,8 @@ class _MaterialDesktopControlsState extends State<MaterialDesktopControls>
   }
 
   Future<void> _initialize() async {
-    _subtitleOn = chewieController.subtitle?.isNotEmpty ?? false;
+    _subtitleOn = chewieController.showSubtitles &&
+        (chewieController.subtitle?.isNotEmpty ?? false);
     controller.addListener(_updateState);
 
     _updateState();