From e160649d9c4e0588df5f6ce06b39f18b959be0db Mon Sep 17 00:00:00 2001 From: olly Date: Fri, 8 Oct 2021 17:52:04 +0100 Subject: [PATCH] README updates for MediaSource, DataSource and UI modules PiperOrigin-RevId: 401793145 --- extensions/cronet/README.md | 37 +++++++++++++++--------------- extensions/leanback/README.md | 7 +++--- extensions/okhttp/README.md | 8 +++---- extensions/rtmp/README.md | 8 +++---- library/dash/README.md | 30 +++++++++++++++++++----- library/hls/README.md | 29 ++++++++++++++++++----- library/rtsp/README.md | 38 +++++++++++++++++++++++++++++++ library/smoothstreaming/README.md | 28 ++++++++++++++++++----- library/ui/README.md | 25 ++++++++++++++++---- 9 files changed, 157 insertions(+), 53 deletions(-) create mode 100644 library/rtsp/README.md diff --git a/extensions/cronet/README.md b/extensions/cronet/README.md index 0496e12dd5..7749d27d6b 100644 --- a/extensions/cronet/README.md +++ b/extensions/cronet/README.md @@ -1,15 +1,13 @@ -# ExoPlayer Cronet extension +# Cronet DataSource module -The Cronet extension is an [HttpDataSource][] implementation that uses -[Cronet][]. +This module provides an [HttpDataSource][] implementation that uses [Cronet][]. Cronet is the Chromium network stack made available to Android apps as a library. It takes advantage of multiple technologies that reduce the latency and -increase the throughput of the network requests that your app needs to work, -including those made by ExoPlayer. It natively supports the HTTP, HTTP/2, and -HTTP/3 over QUIC protocols. Cronet is used by some of the world's biggest -streaming applications, including YouTube, and is our recommended network stack -for most use cases. +increase the throughput of the network requests that your app needs to work. It +natively supports the HTTP, HTTP/2, and HTTP/3 over QUIC protocols. Cronet is +used by some of the world's biggest streaming applications, including YouTube, +and is our recommended network stack for most use cases. [HttpDataSource]: https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/upstream/HttpDataSource.html [Cronet]: https://developer.android.com/guide/topics/connectivity/cronet @@ -32,8 +30,8 @@ locally. Instructions for doing this can be found in the [top level README][]. ## Using the module -ExoPlayer requests data through `DataSource` instances. These instances are -obtained from instances of `DataSource.Factory`, which are instantiated and +Media components request data through `DataSource` instances. These instances +are obtained from instances of `DataSource.Factory`, which are instantiated and injected from application code. If your application only needs to play http(s) content, using the Cronet @@ -57,10 +55,10 @@ instance. #### Google Play Services -By default, ExoPlayer's Cronet extension depends on +By default, this module depends on `com.google.android.gms:play-services-cronet`, which loads an implementation of -Cronet from Google Play Services. When Google Play Services is available, -this approach is beneficial because: +Cronet from Google Play Services. When Google Play Services is available, this +approach is beneficial because: * The increase in application size is negligible. * The implementation is updated automatically by Google Play Services. @@ -87,14 +85,14 @@ use of Cronet Embedded may be appropriate if: There's also a fallback implementation of Cronet, which uses Android's default network stack under the hood. It can be used by adding a dependency on -`org.chromium.net:cronet-fallback`. This implementation should _not_ be used -with ExoPlayer, since it's more efficient to use `DefaultHttpDataSource` -directly in this case. +`org.chromium.net:cronet-fallback`. This implementation should *not* be used +with `CronetDataSource`, since it's more efficient to use +`DefaultHttpDataSource` directly in this case. When using Cronet Fallback for other networking in your application, use the more advanced approach to instantiating a `CronetEngine` described below so that you know when your application's `CronetEngine` has been obtained from the -fallback implementation. In this case, avoid using it with ExoPlayer and use +fallback implementation. In this case, avoid `CronetDataSource` and use `DefaultHttpDataSource` instead. ### CronetEngine instantiation @@ -115,8 +113,9 @@ This makes it possible to iterate through the providers in your own order of preference, trying to build a `CronetEngine` from each in turn using `CronetProvider.createBuilder()` until one has been successfully created. This approach also allows you to determine when the `CronetEngine` has been obtained -from Cronet Fallback, in which case you can avoid using it for ExoPlayer whilst -still using it for other networking performed by your application. +from Cronet Fallback, in which case you can avoid using `CronetDataSource` +whilst still using Cronet Fallback for other networking performed by your +application. [Send a simple request]: https://developer.android.com/guide/topics/connectivity/cronet/start diff --git a/extensions/leanback/README.md b/extensions/leanback/README.md index 961d674182..19b1659c45 100644 --- a/extensions/leanback/README.md +++ b/extensions/leanback/README.md @@ -1,7 +1,8 @@ -# ExoPlayer Leanback extension +# Leanback UI module -This [Leanback][] Extension provides a [PlayerAdapter][] implementation for -ExoPlayer. +This module provides a [PlayerAdapter][] wrapper for `Player`, making it +possible to connect `Player` implementations such as `ExoPlayer` to the playback +widgets provided by `androidx.leanback:leanback`. [PlayerAdapter]: https://developer.android.com/reference/android/support/v17/leanback/media/PlayerAdapter.html [Leanback]: https://developer.android.com/reference/android/support/v17/leanback/package-summary.html diff --git a/extensions/okhttp/README.md b/extensions/okhttp/README.md index 14f7799a2c..269b9a6100 100644 --- a/extensions/okhttp/README.md +++ b/extensions/okhttp/README.md @@ -1,6 +1,6 @@ -# ExoPlayer OkHttp extension +# OkHttp DataSource module -The OkHttp extension is an [HttpDataSource][] implementation that uses Square's +This module provides an [HttpDataSource][] implementation that uses Square's [OkHttp][]. OkHttp is a modern network stack that's widely used by many popular Android @@ -35,8 +35,8 @@ locally. Instructions for doing this can be found in the [top level README][]. ## Using the module -ExoPlayer requests data through `DataSource` instances. These instances are -obtained from instances of `DataSource.Factory`, which are instantiated and +Media components request data through `DataSource` instances. These instances +are obtained from instances of `DataSource.Factory`, which are instantiated and injected from application code. If your application only needs to play http(s) content, using the OkHttp diff --git a/extensions/rtmp/README.md b/extensions/rtmp/README.md index cc8d0b2ac7..3df7db9a56 100644 --- a/extensions/rtmp/README.md +++ b/extensions/rtmp/README.md @@ -1,6 +1,6 @@ -# ExoPlayer RTMP extension +# RTMP DataSource module -The RTMP extension is a [DataSource][] implementation for playing [RTMP][] +This module provides a [DataSource][] implementation for requesting [RTMP][] streams using [LibRtmp Client for Android][]. [DataSource]: https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/upstream/DataSource.html @@ -33,8 +33,8 @@ locally. Instructions for doing this can be found in the [top level README][]. ## Using the module -ExoPlayer requests data through `DataSource` instances. These instances are -obtained from instances of `DataSource.Factory`, which are instantiated and +Media components request data through `DataSource` instances. These instances +are obtained from instances of `DataSource.Factory`, which are instantiated and injected from application code. `DefaultDataSource` will automatically use the RTMP extension whenever it's diff --git a/library/dash/README.md b/library/dash/README.md index b33e763e3b..0eb871a040 100644 --- a/library/dash/README.md +++ b/library/dash/README.md @@ -1,12 +1,30 @@ -# ExoPlayer DASH library module +# ExoPlayer DASH module -Provides support for Dynamic Adaptive Streaming over HTTP (DASH) content. +Provides support for Dynamic Adaptive Streaming over HTTP (DASH) content in +ExoPlayer. + +## Getting the module + +The easiest way to get the module is to add it as a gradle dependency: + +```gradle +implementation 'com.google.android.exoplayer:exoplayer-dash:2.X.X' +``` + +where `2.X.X` is the version, which must match the version of the other media +modules being used. + +Alternatively, you can clone this GitHub project and depend on the module +locally. Instructions for doing this can be found in the [top level README][]. + +[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md + +## Using the module Adding a dependency to this module is all that's required to enable playback of -DASH `MediaItem`s added to an `ExoPlayer` or `SimpleExoPlayer` in their default -configurations. Internally, `DefaultMediaSourceFactory` will automatically -detect the presence of the module and convert DASH `MediaItem`s into -`DashMediaSource` instances for playback. +DASH media items added to `ExoPlayer` in its default configuration. Internally, +`DefaultMediaSourceFactory` will automatically detect the presence of the module +and convert a DASH `MediaItem` into a `DashMediaSource` for playback. Similarly, a `DownloadManager` in its default configuration will use `DefaultDownloaderFactory`, which will automatically detect the presence of diff --git a/library/hls/README.md b/library/hls/README.md index f11bb4f94c..93f776c25f 100644 --- a/library/hls/README.md +++ b/library/hls/README.md @@ -1,12 +1,29 @@ -# ExoPlayer HLS library module +# ExoPlayer HLS module -Provides support for HTTP Live Streaming (HLS) content. +Provides support for HTTP Live Streaming (HLS) content in ExoPlayer. + +## Getting the module + +The easiest way to get the module is to add it as a gradle dependency: + +```gradle +implementation 'com.google.android.exoplayer:exoplayer-hls:2.X.X' +``` + +where `2.X.X` is the version, which must match the version of the other media +modules being used. + +Alternatively, you can clone this GitHub project and depend on the module +locally. Instructions for doing this can be found in the [top level README][]. + +[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md + +## Using the module Adding a dependency to this module is all that's required to enable playback of -HLS `MediaItem`s added to an `ExoPlayer` or `SimpleExoPlayer` in their default -configurations. Internally, `DefaultMediaSourceFactory` will automatically -detect the presence of the module and convert HLS `MediaItem`s into -`HlsMediaSource` instances for playback. +HLS media items added to `ExoPlayer` in its default configuration. Internally, +`DefaultMediaSourceFactory` will automatically detect the presence of the module +and convert an HLS `MediaItem` into an `HlsMediaSource` for playback. Similarly, a `DownloadManager` in its default configuration will use `DefaultDownloaderFactory`, which will automatically detect the presence of diff --git a/library/rtsp/README.md b/library/rtsp/README.md new file mode 100644 index 0000000000..08837189b0 --- /dev/null +++ b/library/rtsp/README.md @@ -0,0 +1,38 @@ +# ExoPlayer RTSP module + +Provides support for RTSP playbacks in ExoPlayer. + +## Getting the module + +The easiest way to get the module is to add it as a gradle dependency: + +```gradle +implementation 'com.google.android.exoplayer:exoplayer-rtsp:2.X.X' +``` + +where `2.X.X` is the version, which must match the version of the other media +modules being used. + +Alternatively, you can clone this GitHub project and depend on the module +locally. Instructions for doing this can be found in the [top level README][]. + +[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md + +## Using the module + +Adding a dependency to this module is all that's required to enable playback of +RTSP media items added to `ExoPlayer` in its default configuration. Internally, +`DefaultMediaSourceFactory` will automatically detect the presence of the module +and convert a RTSP `MediaItem` into a `RtspMediaSource` for playback. + +For advanced playback use cases, applications can build `RtspMediaSource` +instances and pass them directly to the player. + +## Links + +* [Developer Guide][]. +* [Javadoc][]: Classes matching `com.google.android.exoplayer2.source.rtsp.*` belong to + this module. + +[Developer Guide]: https://exoplayer.dev/dash.html +[Javadoc]: https://exoplayer.dev/doc/reference/index.html diff --git a/library/smoothstreaming/README.md b/library/smoothstreaming/README.md index 1400c6dc6e..f187288666 100644 --- a/library/smoothstreaming/README.md +++ b/library/smoothstreaming/README.md @@ -1,12 +1,28 @@ -# ExoPlayer SmoothStreaming library module +# ExoPlayer SmoothStreaming module -Provides support for SmoothStreaming content. +Provides support for SmoothStreaming content in ExoPlayer. + +## Getting the module + +The easiest way to get the module is to add it as a gradle dependency: + +```gradle +implementation 'com.google.android.exoplayer:exoplayer-smoothstreaming:2.X.X' +``` + +where `2.X.X` is the version, which must match the version of the other media +modules being used. + +Alternatively, you can clone this GitHub project and depend on the module +locally. Instructions for doing this can be found in the [top level README][]. + +[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md Adding a dependency to this module is all that's required to enable playback of -SmoothStreaming `MediaItem`s added to an `ExoPlayer` or `SimpleExoPlayer` in -their default configurations. Internally, `DefaultMediaSourceFactory` will -automatically detect the presence of the module and convert SmoothStreaming -`MediaItem`s into `SsMediaSource` instances for playback. +SmoothStreaming media items added to `ExoPlayer` in its default configuration. +Internally, `DefaultMediaSourceFactory` will automatically detect the presence +of the module and convert a SmoothStreaming `MediaItem` into a `SsMediaSource` +for playback. Similarly, a `DownloadManager` in its default configuration will use `DefaultDownloaderFactory`, which will automatically detect the presence of diff --git a/library/ui/README.md b/library/ui/README.md index 21e13e1dc7..b41072427a 100644 --- a/library/ui/README.md +++ b/library/ui/README.md @@ -1,12 +1,27 @@ -# ExoPlayer UI library module +# UI module -Provides UI components and resources for use with ExoPlayer. +Provides UI components for media playback. + +## Getting the module + +The easiest way to use the module is to add it as a gradle dependency: + +```gradle +implementation 'com.google.android.exoplayer:exoplayer-ui:2.X.X' +``` + +where `2.X.X` is the version, which must match the version of the other media +modules being used. + +Alternatively, you can clone this GitHub project and depend on the module +locally. Instructions for doing this can be found in the [top level README][]. + +[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md ## Links -* [Developer Guide][]. -* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ui.*` - belong to this module. +* [Developer Guide][]. +* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ui.*` belong to this module. [Developer Guide]: https://exoplayer.dev/ui-components.html [Javadoc]: https://exoplayer.dev/doc/reference/index.html