130 lines
5.5 KiB
Markdown
130 lines
5.5 KiB
Markdown
# ExoPlayer Cronet extension #
|
|
|
|
The Cronet extension is 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.
|
|
|
|
[HttpDataSource]: https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/upstream/HttpDataSource.html
|
|
[Cronet]: https://developer.android.com/guide/topics/connectivity/cronet
|
|
|
|
## Getting the extension ##
|
|
|
|
The easiest way to use the extension is to add it as a gradle dependency:
|
|
|
|
```gradle
|
|
implementation 'com.google.android.exoplayer:extension-cronet:2.X.X'
|
|
```
|
|
|
|
where `2.X.X` is the version, which must match the version of the ExoPlayer
|
|
library being used.
|
|
|
|
Alternatively, you can clone the ExoPlayer repository and depend on the module
|
|
locally. Instructions for doing this can be found in ExoPlayer's
|
|
[top level README][].
|
|
|
|
[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
|
|
|
|
## Using the extension ##
|
|
|
|
ExoPlayer requests 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
|
|
extension is as simple as updating `DataSource.Factory` instantiations in your
|
|
application code to use `CronetDataSource.Factory`. If your application also
|
|
needs to play non-http(s) content such as local files, use:
|
|
```
|
|
new DefaultDataSourceFactory(
|
|
...
|
|
/* baseDataSourceFactory= */ new CronetDataSource.Factory(...) );
|
|
```
|
|
|
|
## Cronet implementations ##
|
|
|
|
To instantiate a `CronetDataSource.Factory` you'll need a `CronetEngine`. A
|
|
`CronetEngine` can be obtained from one of a number of Cronet implementations.
|
|
It's recommended that an application should only have a single `CronetEngine`
|
|
instance.
|
|
|
|
### Available implementations ###
|
|
|
|
#### Google Play Services ####
|
|
|
|
By default, ExoPlayer's Cronet extension 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:
|
|
|
|
* The increase in application size is negligible.
|
|
* The implementation is updated automatically by Google Play Services.
|
|
|
|
The disadvantage of this approach is that the implementation is not usable on
|
|
devices that do not have Google Play Services. Unless your application also
|
|
includes one of the alternative Cronet implementations described below, you will
|
|
not be able to instantiate a `CronetEngine` in this case. Your application code
|
|
should handle this by falling back to use `DefaultHttpDataSource` instead.
|
|
|
|
#### Cronet Embedded ####
|
|
|
|
Cronet Embedded bundles a full Cronet implementation directly into your
|
|
application. To use it, add an additional dependency on
|
|
`org.chromium.net:cronet-embedded`. Cronet Embedded adds approximately 8MB to
|
|
your application, and so we do not recommend it for most use cases. That said,
|
|
use of Cronet Embedded may be appropriate if:
|
|
|
|
* A large percentage of your users are in markets where Google Play Services is
|
|
not widely available.
|
|
* You want to control the exact version of the Cronet implementation being used.
|
|
|
|
#### Cronet Fallback ####
|
|
|
|
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.
|
|
|
|
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
|
|
`DefaultHttpDataSource` instead.
|
|
|
|
### CronetEngine instantiation ###
|
|
|
|
Cronet's [Send a simple request][] page documents the simplest way of building a
|
|
`CronetEngine`, which is suitable if your application is only using the
|
|
Google Play Services implementation of Cronet.
|
|
|
|
For cases where your application also includes one of the other Cronet
|
|
implementations, you can use `CronetProvider.getAllProviders` to list the
|
|
available implementations. Providers can be identified by name:
|
|
|
|
* `CronetProviderInstaller.PROVIDER_NAME`: Google Play Services implementation.
|
|
* `CronetProvider.PROVIDER_NAME_APP_PACKAGED`: Embedded implementation.
|
|
* `CronetProvider.PROVIDER_NAME_FALLBACK`: Fallback implementation.
|
|
|
|
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.
|
|
|
|
[Send a simple request]: https://developer.android.com/guide/topics/connectivity/cronet/start
|
|
|
|
## Links ##
|
|
|
|
* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.cronet.*`
|
|
belong to this module.
|
|
|
|
[Javadoc]: https://exoplayer.dev/doc/reference/index.html
|