v4 (cast to device, additional vlc helper methods, bug fixes)

Author: alr2413

.gitignore

@@ -114,4 +114,5 @@ app.*.symbols
 !**/ios/**/default.pbxuser
 !**/ios/**/default.perspectivev3
 !/packages/flutter_tools/test/data/dart_dependencies_test/**/.packages
-!/dev/ci/**/Gemfile.lock
+!/dev/ci/**/Gemfile.lock
+/example/ios/Runner.xcodeproj/project.pbxproj

CHANGELOG.md

@@ -1,3 +1,12 @@
+## 4.0.0
+* Improved structure (see example for breaking changes). Example code updated also.
+* Fix android black screen issue
+* Support playing local media/subtitle file
+* Support casting media to external device
+* Updated changing audio/subtitle method
+* Support audio/subtitle delay
+credits to Alireza Setayesh (https://github.com/alr2413) and Mitch Ross (https://github.com/mitchross)
+
 ## 3.0.7
 * Updates MobileVLC to allow for changing of subtitles and adding subtiles . 
 credits to @rikaweb(https://github.com/rikaweb) and Mitch Ross (https://github.com/mitchross)

README.md

@@ -1,22 +1,55 @@
 #  VLC Player Plugin
 A VLC-powered alternative to Flutter's video_player that supports iOS and Android.
 
-<img src="https://github.com/solid-software/flutter_vlc_player/blob/master/imgpsh_mobile_save.jfif?raw=true" width="200">
+<p float="left">
+  <img src="img_example_v4.jpg" height="400">
+  <img src="imgpsh_mobile_save.jfif?raw=true" height="400">
+</p>
+
+
 
 ## Installation
 
-### Version 3.0 Upgrade For Existing Apps
-For migration to version 3, the project is based in swift. Your existing project will need to migratate
+### Version 4.0 Upgrade For Existing Apps
+To upgrade to version 4.0 (or v3.0), first you need to migrate the existing project to swift.
 
     Delete existing ios folder from root of flutter project.
     Run this command flutter create -i swift .
 
 This command will create only ios directory with swift support. See https://stackoverflow.com/questions/52244346/how-to-enable-swift-support-for-existing-project-in-flutter
 
-Change your project to use 9.0
-# Uncomment this line to define a global platform for your project
- platform :ios, '9.0'
+<hr>
+
+## Breaking Changes (from V3 to V4)
+1) Player Stop/Pause status is seperated 
+
+    previously (v3 and lower): Stop/Pause -> STOPPED,
+    <br>
+    now (v4): Stop -> STOPPED and Pause -> PAUSED. 
+
+2) Refactored belowing attributes & methods
 
+    // attributes
+    <br>
+    audioCount -> audioTracksCount
+    <br>
+    activeAudioNum -> activeAudioTrack
+    <br>
+    subtitleCount -> spuTracksCount
+    <br>
+    activeSubtitleNum -> activeSpuTrack
+    <br>
+    <br>
+    // methods
+    <br>
+    changeSound(int audioNumber) -> setAudioTrack(int audioTrackNumber)
+    <br>
+    changeSubtitle(int subtitleNumber) -> setSpuTrack(int spuTrackNumber)
+    <br>
+    addSubtitle(String filePath) -> addSubtitleTrack(String subtitlePath, ...)
+
+
+<hr>
 
 ### iOS
 For iOS, you need to opt into the Flutter embedded views preview.  
@@ -44,8 +77,21 @@ Make sure that following line in `<project root>/ios/Podfile` uncommented:
 > NOTE: While the Flutter `video_player` is not functional on iOS Simulators, this package (`flutter_vlc_player`) **is**
 > fully functional on iOS simulators.
 
+To enable vlc cast functionality for external displays (chromecast), you should also add the following:
+
+```xml
+<key>NSLocalNetworkUsageDescription</key>
+<string>Used to search for chromecast devices</string>
+<key>NSBonjourServices</key>
+<array>
+  <string>_googlecast._tcp</string>
+</array>
+```
+
+<hr>
+
 ### Android
-To load media from an internet source, your app will need the `INTERNET` permission.  
+To load media/subitle from an internet source, your app will need the `INTERNET` permission.  
 This is done by ensuring your `<project root>/android/app/src/main/AndroidManifest.xml` file contains a `uses-permission`
 declaration for `android.permission.INTERNET`:
 ```xml
@@ -54,6 +100,25 @@ declaration for `android.permission.INTERNET`:
 
 As Flutter includes this permission by default, the permission is likely already declared in the file.
 
+Note that if you got "Cleartext HTTP traffic to * is not permitted"
+you need to add the `android:usesClearTextTraffic="true"` flag in the AndroidManifest.xml file, or define a new "Network Security Configuration" file. For more information, check https://developer.android.com/training/articles/security-config
+
+<br>
+
+In order to load media/subtitle from internal device storage, you should put the storage permissions as follows:
+```xml
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
+```
+In some cases you also need to add the `android:requestLegacyExternalStorage="true"` flag to the Application tag in AndroidManifest.xml file.
+
+After that you can access the media/subtitle file by 
+
+    "/storage/emulated/0/{FilePath}"
+    "/sdcard/{FilePath}"
+
+<hr>
+
 ## Quick Start
 To start using the plugin, copy this code or follow the [example](https://github.com/solid-software/flutter_vlc_player/tree/master/example):
 
@@ -116,19 +181,48 @@ Container(
 /// VlcPlayer widget.
 const VlcPlayer({
     Key key,
+
     /// The [VlcPlayerController] that handles interaction with the platform code.
     @required this.controller,
+
     /// The aspect ratio used to display the video.
     /// This MUST be provided, however it could simply be (parentWidth / parentHeight) - where parentWidth and
     /// parentHeight are the width and height of the parent perhaps as defined by a LayoutBuilder.
     @required this.aspectRatio,
+
     /// This is the initial URL for the content. This also must be provided but [VlcPlayerController] implements
     /// [VlcPlayerController.setStreamUrl] method so this can be changed at any time.
     @required this.url,
+
+    /// Set hardware acceleration for player. Default is Automatic.
+    this.hwAcc,
+
+    /// Adds options to vlc. For more [https://wiki.videolan.org/VLC_command-line_help] If nothing is provided,
+    /// vlc will run without any options set.
+    this.options,
+
+    /// Set true if the provided url is local file
+    this.isLocalMedia,
+
+    /// The video should be played automatically.
+    this.autoplay,
+
+    /// Set the external subtitle to load with video
+    this.subtitle,
+
+    /// Set true if the provided subtitle is local file
+    this.isLocalSubtitle,
+
+    /// Set true if the provided subtitle is selected by default
+    this.isSubtitleSelected,
+
+    /// Loop the playback forever
+    this.loop,
+
     /// Before the platform view has initialized, this placeholder will be rendered instead of the video player.
     /// This can simply be a [CircularProgressIndicator] (see the example.)
     this.placeholder,
-});
+  });
 ```
 
 ```dart
@@ -137,7 +231,11 @@ VlcPlayerController({
     /// This is a callback that will be executed once the platform view has been initialized.
     /// If you want the media to play as soon as the platform view has initialized, you could just call
     /// [VlcPlayerController.play] in this callback. (see the example)
-    VoidCallback onInit
+    VoidCallback onInit,
+
+    /// This is a callback that will be executed every time a new cast device detected/removed
+    /// It should be defined as "void Function(CastStatus, String, String)", where the CastStatus is an enum { DEVICE_ADDED, DEVICE_DELETED } and the next two String arguments are name and displayName of cast device, respectively.
+    CastCallback onCastHandler
 }){
 
   /*** PROPERTIES (Getters) ***/
@@ -155,6 +253,8 @@ VlcPlayerController({
   /// - PlayingState.PLAYING
   /// - PlayingState.BUFFERING
   /// - PlayingState.STOPPED
+  /// - PlayingState.PAUSED
+  /// - PlayingState.ERROR
   /// - null (When the player is uninitialized)
   PlayingState playingState;
 
@@ -168,8 +268,8 @@ VlcPlayerController({
   int duration = Duration.zero;
 
   /// This is the dimensions of the content (height and width).
-  /// (SAFE) This value is always safe to use - it is set to Size.zero when the player is uninitialized.
-  Size size = Size.zero;
+  /// (SAFE) This value is always safe to use - it is set to VlcMediaSize.zero when the player is uninitialized.
+  VlcMediaSize size = VlcMediaSize.zero;
 
   /// This is the aspect ratio of the content as returned by VLC once the content has been loaded.
   /// (Not to be confused with the aspect ratio provided to the [VlcPlayer] widget, which is simply used for an
@@ -180,19 +280,55 @@ VlcPlayerController({
   /// at which VLC is playing the content has changed.)
   double playbackSpeed;
 
+  /// Returns the number of available audio tracks embedded in media except the original audio.
+  int audioTracksCount;
+
+  /// Returns the active audio track index. "-1" means audio is disabled.
+  int activeAudioTrack;
+
+  /// Returns the number of available subtitle tracks embedded in media.
+  int spuTracksCount;
+
+  /// Returns the active subitlte track index. "-1" means subitle is disabled.
+  int activeSpuTrack;
+
   /*** METHODS ***/
-  /// [url] - the URL of the stream to start playing.
   /// This stops playback and changes the URL. Once the new URL has been loaded, the playback state will revert to
   /// its state before the method was called. (i.e. if setStreamUrl is called whilst media is playing, once the new
   /// URL has been loaded, the new stream will begin playing.)
-  Future<void> setStreamUrl(String url);
+  /// [url] - the URL of the stream to start playing.
+  /// [isLocalMedia] - Set true if the media url is on local storage.
+  /// [subtitle] - Set subtitle url if you wanna add subtitle on media loading.
+  /// [isLocalSubtitle] - Set true if subtitle is on local storage
+  /// [isSubtitleSelected] - Set true if you wanna force the added subtitle to start display on media.
+  Future<void> setStreamUrl(String url, {bool isLocalMedia, String subtitle, bool isLocalSubtitle, bool isSubtitleSelected});
 
+  /// Start playing media.
   Future<void> play();
+
+  /// Pause media player.
   Future<void> pause();
+  
+  /// Stop media player.
   Future<void> stop();
 
+  /// Returns true if media is playing.
+  Future<bool> isPlaying();
+
   /// [time] - time in milliseconds to jump to.
   Future<void> setTime(int time);
+  
+  /// Returns current media seek time in milliseconds.
+  Future<int> getTime();
+
+  /// Returns duration/length of loaded video in milliseconds.
+  Future<int> getDuration();
+
+  /// [volume] - Set vlc volume level which should be in range [0-100].
+  Future<void> setVolume(int volume);
+
+  /// Returns current vlc volume level.
+  Future<int> getVolume();
 
   /// [speed] - the rate at which VLC should play media.
   /// For reference:
@@ -201,11 +337,103 @@ VlcPlayerController({
   /// 0.5 is half speed.
   Future<void> setPlaybackSpeed(double speed);
 
+  /// Returns the vlc playback speed.
+  Future<double> getPlaybackSpeed();
+
+  /// Return the number of subtitle tracks (both embedded and inserted)
+  Future<int> getSpuTracksCount();
+
+  /// Return all subtitle tracks as array of <Int, String>
+  /// The key parameter is the index of subtitle which is used for changing subtitle and the value is the display name of subtitle
+  Future<Map<dynamic, dynamic>> getSpuTracks();
+
+  /// [spuTrackNumber] - the subtitle index obtained from getSpuTracks()
+  /// Change active subtitle index (set -1 to disable subtitle).
+  Future<void> setSpuTrack(int spuTrackNumber);
+
+  /// Returns selected spu track index
+  Future<int> getSpuTrack();
+
+  /// [delay] - the amount of time in milliseconds which vlc subtitle should be delayed. (both positive & negative value appliable)
+  Future<void> setSpuDelay(int delay);
+
+  /// Returns the amount of subtitle time delay.
+  Future<int> getSpuDelay();
+
+  
+  /// [subtitlePath] - URL of subtitle
+  /// [isLocalSubtitle] - Set true if subtitle is on local storage
+  /// [isSubtitleSelected] - Set true if you wanna force the added subtitle to start display on media.
+  /// Add extra subtitle to media.
+  Future<void> addSubtitleTrack(String subtitlePath,
+      {bool isLocalSubtitle, bool isSubtitleSelected});
+
+  /// Returns the number of audio tracks
+  Future<int> getAudioTracksCount();
+
+  /// Returns all audio tracks as array of <Int, String>
+  /// The key parameter is the index of audio track which is used for changing audio and the value is the display name of audio
+  Future<Map<dynamic, dynamic>> getAudioTracks();
+
+  /// Returns selected audio track index
+  Future<int> getAudioTrack();
+
+  /// [audioTrackNumber] - the audio track index obtained from getAudioTracks()
+  /// Change active audio track index (set -1 to mute).
+  Future<void> setAudioTrack(int audioTrackNumber);
+
+  /// [delay] - the amount of time in milliseconds which vlc audio should be delayed. (both positive & negative value appliable)
+  Future<void> setAudioDelay(int delay);
+
+  /// Returns the amount of audio track time delay.
+  Future<int> getAudioDelay();
+
+  /// Returns the number of video tracks
+  Future<int> getVideoTracksCount();
+  
+  /// Returns all video tracks as array of <Int, String>
+  /// The key parameter is the index of video track and the value is the display name of video track
+  Future<Map<dynamic, dynamic>> getVideoTracks();
+
+  /// Returns an object which contains information about current video track
+  Future<dynamic> getCurrentVideoTrack();
+
+  /// Returns selected video track index
+  Future<int> getVideoTrack();
+
+  /// [scale] - the video scale value
+  /// Set video scale
+  Future<void> setVideoScale(double scale);
+
+  /// Returns video scale
+  Future<double> getVideoScale();
+
+  /// [aspect] - the video apect ratio like "16:9"
+  /// Set video aspect ratio
+  Future<void> setVideoAspectRatio(String aspect);
+
+  /// Returns video aspect ratio
+  Future<String> getVideoAspectRatio();
+
   /// Returns binary data for a snapshot of the media at the current frame.
   Future<Uint8List> takeSnapshot();
 
+  /// Start vlc cast discovery to find external display devices (chromecast)
+  Future<void> startCastDiscovery();
+
+  /// Stop vlc cast and cast discovery
+  Future<void> stopCastDiscovery();
+
+  /// Returns all detected cast devices as array of <String, String>
+  /// The key parameter is the name of cast device and the value is the display name of cast device
+  Future<Map<dynamic, dynamic>> getCastDevices();
+
+  /// [castDevice] - name of cast device 
+  /// Start vlc video casting to the selected device. Set null if you wanna to stop video casting.
+  Future<void> startCasting(String castDevice);
+
   /// Disposes the platform view and unloads the VLC player.
-  void dispose();
+  Future<void> dispose();
 
 }
 ```