1--- 2title: Network stacks 3--- 4 5ExoPlayer is commonly used for streaming media over the internet. It supports 6multiple network stacks for making its underlying network requests. Your choice 7of network stack can have a significant impact on streaming performance. 8 9This page outlines how to configure ExoPlayer to use your network stack of 10choice, lists the available options, and provides some guidance on how to choose 11a network stack for your application. 12 13## Configuring ExoPlayer to use a specific network stack ## 14 15ExoPlayer loads data through `DataSource` components, which it obtains from 16`DataSource.Factory` instances that are injected from application code. 17 18If your application only needs to play http(s) content, selecting a network 19stack is as simple as updating any `DataSource.Factory` instances that your 20application injects to be instances of the `HttpDataSource.Factory` 21that corresponds to the network stack you wish to use. If your application also 22needs to play non-http(s) content such as local files, use 23 24~~~ 25new DefaultDataSource.Factory( 26 ... 27 /* baseDataSourceFactory= */ new PreferredHttpDataSource.Factory(...)); 28~~~ 29{: .language-java} 30 31where `PreferredHttpDataSource.Factory` is the factory corresponding to your 32preferred network stack. The `DefaultDataSource.Factory` layer adds in support 33for non-http(s) sources such as local files. 34 35The example below shows how to build an `ExoPlayer` that will use the Cronet 36network stack and also support playback of non-http(s) content. 37 38~~~ 39// Given a CronetEngine and Executor, build a CronetDataSource.Factory. 40CronetDataSource.Factory cronetDataSourceFactory = 41 new CronetDataSource.Factory(cronetEngine, executor); 42 43// Wrap the CronetDataSource.Factory in a DefaultDataSource.Factory, which adds 44// in support for requesting data from other sources (e.g., files, resources, 45// etc). 46DefaultDataSource.Factory dataSourceFactory = 47 new DefaultDataSource.Factory( 48 context, 49 /* baseDataSourceFactory= */ cronetDataSourceFactory); 50 51// Inject the DefaultDataSource.Factory when creating the player. 52ExoPlayer player = 53 new ExoPlayer.Builder(context) 54 .setMediaSourceFactory(new DefaultMediaSourceFactory(dataSourceFactory)) 55 .build(); 56~~~ 57{: .language-java} 58 59## Supported network stacks ## 60 61ExoPlayer provides direct support for Cronet, OkHttp and Android's built-in 62network stack. It can also be extended to support any other network stack that 63works on Android. 64 65### Cronet ### 66 67[Cronet](https://developer.android.com/guide/topics/connectivity/cronet) is the 68Chromium network stack made available to Android apps as a library. It takes 69advantage of multiple technologies that reduce the latency and increase the 70throughput of the network requests that your app needs to work, including those 71made by ExoPlayer. It natively supports the HTTP, HTTP/2, and HTTP/3 over QUIC 72protocols. Cronet is used by some of the world's biggest streaming applications, 73including YouTube. 74 75ExoPlayer supports Cronet via its 76[Cronet extension](https://github.com/google/ExoPlayer/tree/dev-v2/extensions/cronet). 77Please see the extension's `README.md` for detailed instructions on how to use 78it. Note that the Cronet extension is able to use three underlying Cronet 79implementations: 80 811. **Google Play Services:** We recommend using this implementation in most 82 cases, and falling back to Android's built-in network stack 83 (i.e., `DefaultHttpDataSource`) if Google Play Services is not available. 841. **Cronet Embedded:** May be a good choice if a large percentage of your users 85 are in markets where Google Play Services is not widely available, or if you 86 want to control the exact version of the Cronet implementation being used. The 87 major disadvantage of Cronet Embedded is that it adds approximately 8MB to 88 your application. 891. **Cronet Fallback:** The fallback implementation of Cronet implements 90 Cronet's API as a wrapper around Android's built-in network stack. It should 91 not be used with ExoPlayer, since using Android's built-in network stack 92 directly (i.e., by using `DefaultHttpDataSource`) is more efficient. 93 94### OkHttp ### 95 96[OkHttp](https://square.github.io/okhttp/) is another modern network stack that 97is widely used by many popular Android applications. It supports HTTP and 98HTTP/2, but does not yet support HTTP/3 over QUIC. 99 100ExoPlayer supports OkHttp via its 101[OkHttp extension](https://github.com/google/ExoPlayer/tree/dev-v2/extensions/okhttp). 102Please see the extension's `README.md` for detailed instructions on how to use 103it. When using the OkHttp extension, the network stack is embedded within the 104application. This is similar to Cronet Embedded, however OkHttp is significantly 105smaller, adding under 1MB to your application. 106 107### Android's built-in network stack ### 108 109ExoPlayer supports use of Android's built-in network stack with 110`DefaultHttpDataSource` and `DefaultHttpDataSource.Factory`, which are part of 111the core ExoPlayer library. 112 113The exact network stack implementation depends on the software running on the 114underlying device. On most devices (as of 2021) only HTTP is supported (i.e., 115HTTP/2 and HTTP/3 over QUIC are not supported). 116 117### Other network stacks ### 118 119It's possible for applications to integrate other network stacks with ExoPlayer. 120To do this, implement an `HttpDataSource` that wraps the network stack, 121together with a corresponding `HttpDataSource.Factory`. ExoPlayer's Cronet and 122OkHttp extensions are good examples of how to do this. 123 124When integrating with a pure Java network stack, it's a good idea to implement a 125`DataSourceContractTest` to check that your `HttpDataSource` implementation 126behaves correctly. `OkHttpDataSourceContractTest` in the OkHttp extension is a 127good example of how to do this. 128 129## Choosing a network stack ## 130 131The table below outlines the pros and cons of the network stacks supported by 132ExoPlayer. 133 134| Network stack | Protocols | APK size impact | Notes | 135|:---|:--:|:--:|:---| 136| Cronet (Google Play Services) | HTTP<br>HTTP/2<br>HTTP/3 over QUIC | Small<br>(<100KB) | Requires Google Play Services. Cronet version updated automatically | 137| Cronet (Embedded) | HTTP<br>HTTP/2<br>HTTP/3 over QUIC | Large<br>(~8MB) | Cronet version controlled by app developer | 138| Cronet (Fallback) | HTTP<br>(varies by device) | Small<br>(<100KB) | Not recommended for ExoPlayer | 139| OkHttp | HTTP<br>HTTP/2 | Small<br>(<1MB) | Requires Kotlin runtime | 140| Built-in network stack | HTTP<br>(varies by device) | None | Implementation varies by device | 141 142The HTTP/2 and HTTP/3 over QUIC protocols can significantly improve media 143streaming performance. In particular when streaming adaptive media distributed 144via a content distribution network (CDN), there are cases for which use of these 145protocols can allow CDNs to operate much more efficiently. For this reason, 146Cronet's support for both HTTP/2 and HTTP/3 over QUIC (and OkHttp's support for 147HTTP/2), is a major benefit compared to using Android's built-in network stack, 148provided the servers on which the content is hosted also support these 149protocols. 150 151When considering media streaming in isolation, we recommend use of Cronet 152provided by Google Play Services, falling back to `DefaultHttpDataSource` if 153Google Play Services is unavailable. This recommendation strikes a good balance 154between enabling use of HTTP/2 and HTTP/3 over QUIC on most devices, and 155avoiding a significant increase in APK size. There are exceptions to this 156recommendation. For cases where Google Play Services is likely to be unavailable 157on a significant fraction of devices that will be running your application, 158using Cronet Embedded or OkHttp may be more appropriate. Use of the built-in 159network stack may be acceptable if APK size is a critical concern, or if media 160streaming is only a minor part of your application's functionality. 161 162Beyond just media, it's normally a good idea to choose a single network stack 163for all of the networking performed by your application. This allows resources 164(e.g., sockets) to be efficiently pooled and shared between ExoPlayer and other 165application components. 166 167To assist with resource sharing, it's recommended to use a single `CronetEngine` 168or `OkHttpClient` instance throughout your application, when using Cronet or 169OkHttp respectively. 170{:.info} 171 172Since your application will most likely need to perform networking not related 173to media playback, your choice of network stack should ultimately factor in our 174recommendations above for media streaming in isolation, the requirements of any 175other components that perform networking, and their relative importance to your 176application. 177