diff --git a/packages/video_player/video_player_platform_interface/CHANGELOG.md b/packages/video_player/video_player_platform_interface/CHANGELOG.md index acaff15f5466..7c77697dfd06 100644 --- a/packages/video_player/video_player_platform_interface/CHANGELOG.md +++ b/packages/video_player/video_player_platform_interface/CHANGELOG.md @@ -1,3 +1,7 @@ +## 1.0.3 + +* Document public API. + ## 1.0.2 * Fix unawaited futures in the tests. diff --git a/packages/video_player/video_player_platform_interface/analysis_options.yaml b/packages/video_player/video_player_platform_interface/analysis_options.yaml deleted file mode 100644 index 969b55796944..000000000000 --- a/packages/video_player/video_player_platform_interface/analysis_options.yaml +++ /dev/null @@ -1,10 +0,0 @@ -# This is a temporary file to allow us to land a new set of linter rules in a -# series of manageable patches instead of one gigantic PR. It disables some of -# the new lints that are already failing on this plugin, for this plugin. It -# should be deleted and the failing lints addressed as soon as possible. - -include: ../../../analysis_options.yaml - -analyzer: - errors: - public_member_api_docs: ignore diff --git a/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart b/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart index d8aa26d6ee46..4c1f2b67c4fc 100644 --- a/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart +++ b/packages/video_player/video_player_platform_interface/lib/video_player_platform_interface.dart @@ -119,7 +119,22 @@ abstract class VideoPlayerPlatform { void _verifyProvidesDefaultImplementations() {} } +/// Description of the data source used to create an instance of +/// the video player. class DataSource { + /// Constructs an instance of [DataSource]. + /// + /// The [sourceType] is always required. + /// + /// The [uri] argument takes the form of `'https://example.com/video.mp4'` or + /// `'file://${file.path}'`. + /// + /// The [formatHint] argument can be null. + /// + /// The [asset] argument takes the form of `'assets/video.mp4'`. + /// + /// The [package] argument must be non-null when the asset comes from a + /// package and null otherwise. DataSource({ @required this.sourceType, this.uri, @@ -128,16 +143,34 @@ class DataSource { this.package, }); + /// The way in which the video was originally loaded. + /// + /// This has nothing to do with the video's file type. It's just the place + /// from which the video is fetched from. final DataSourceType sourceType; + + /// The URI to the video file. + /// + /// This will be in different formats depending on the [DataSourceType] of + /// the original video. final String uri; + + /// **Android only**. Will override the platform's generic file format + /// detection with whatever is set here. final VideoFormat formatHint; + + /// The name of the asset. Only set for [DataSourceType.asset] videos. final String asset; + + /// The package that the asset was loaded from. Only set for + /// [DataSourceType.asset] videos. final String package; } -/// The way in which the video was originally loaded. This has nothing to do -/// with the video's file type. It's just the place from which the video is -/// fetched from. +/// The way in which the video was originally loaded. +/// +/// This has nothing to do with the video's file type. It's just the place +/// from which the video is fetched from. enum DataSourceType { /// The video was included in the app's asset files. asset, @@ -164,7 +197,14 @@ enum VideoFormat { other } +/// Event emitted from the platform implementation. class VideoEvent { + /// Creates an instance of [VideoEvent]. + /// + /// The [eventType] argument is required. + /// + /// Depending on the [eventType], the [duration], [size] and [buffered] + /// arguments can be null. VideoEvent({ @required this.eventType, this.duration, @@ -172,9 +212,22 @@ class VideoEvent { this.buffered, }); + /// The type of the event. final VideoEventType eventType; + + /// Duration of the video. + /// + /// Only used if [eventType] is [VideoEventType.initialized]. final Duration duration; + + /// Size of the video. + /// + /// Only used if [eventType] is [VideoEventType.initialized]. final Size size; + + /// Buffered parts of the video. + /// + /// Only used if [eventType] is [VideoEventType.bufferingUpdate]. final List buffered; @override @@ -196,12 +249,27 @@ class VideoEvent { buffered.hashCode; } +/// Type of the event. +/// +/// Emitted by the platform implementation when the video is initialized or +/// completed or to communicate buffering events. enum VideoEventType { + /// The video has been initialized. initialized, + + /// The playback has ended. completed, + + /// Updated information on the buffering state. bufferingUpdate, + + /// The video started to buffer. bufferingStart, + + /// The video stopped to buffer. bufferingEnd, + + /// An unknown event has been received. unknown, } diff --git a/packages/video_player/video_player_platform_interface/pubspec.yaml b/packages/video_player/video_player_platform_interface/pubspec.yaml index 38bde72e28fc..1a9454d10fef 100644 --- a/packages/video_player/video_player_platform_interface/pubspec.yaml +++ b/packages/video_player/video_player_platform_interface/pubspec.yaml @@ -4,7 +4,7 @@ author: Flutter Team homepage: https://github.com/flutter/plugins/tree/master/packages/video_player/video_player_platform_interface # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 1.0.2 +version: 1.0.3 dependencies: flutter: