1--- 2title: Hello world! 3redirect_from: 4 - /guide.html 5 - /guide-v1.html 6 - /getting-started.html 7--- 8 9Another way to get started is to work through 10[the ExoPlayer codelab](https://codelabs.developers.google.com/codelabs/exoplayer-intro/). 11{:.info} 12 13For simple use cases, getting started with `ExoPlayer` consists of implementing 14the following steps: 15 161. Add ExoPlayer as a dependency to your project. 171. Create an `ExoPlayer` instance. 181. Attach the player to a view (for video output and user input). 191. Prepare the player with a `MediaItem` to play. 201. Release the player when done. 21 22These steps are described in more detail below. For a complete example, refer to 23`PlayerActivity` in the [main demo app][]. 24 25## Adding ExoPlayer as a dependency ## 26 27### Add ExoPlayer modules ### 28 29The easiest way to get started using ExoPlayer is to add it as a gradle 30dependency in the `build.gradle` file of your app module. The following will add 31a dependency to the full library: 32 33~~~ 34implementation 'com.google.android.exoplayer:exoplayer:2.X.X' 35~~~ 36{: .language-gradle} 37 38where `2.X.X` is your preferred version (the latest version can be found by 39consulting the [release notes][]). 40 41As an alternative to the full library, you can depend on only the library 42modules that you actually need. For example the following will add dependencies 43on the Core, DASH and UI library modules, as might be required for an app that 44only plays DASH content: 45 46~~~ 47implementation 'com.google.android.exoplayer:exoplayer-core:2.X.X' 48implementation 'com.google.android.exoplayer:exoplayer-dash:2.X.X' 49implementation 'com.google.android.exoplayer:exoplayer-ui:2.X.X' 50~~~ 51{: .language-gradle} 52 53When depending on individual modules they must all be the same version. 54 55The available library modules are listed below. Adding a dependency to the full 56ExoPlayer library is equivalent to adding dependencies on all of the library 57modules individually. 58 59* `exoplayer-core`: Core functionality (required). 60* `exoplayer-dash`: Support for DASH content. 61* `exoplayer-hls`: Support for HLS content. 62* `exoplayer-rtsp`: Support for RTSP content. 63* `exoplayer-smoothstreaming`: Support for SmoothStreaming content. 64* `exoplayer-transformer`: Media transformation functionality. 65* `exoplayer-ui`: UI components and resources for use with ExoPlayer. 66 67In addition to library modules, ExoPlayer has extension modules that depend on 68external libraries to provide additional functionality. Some extensions are 69available from the Maven repository, whereas others must be built manually. 70Browse the [extensions directory][] and their individual READMEs for details. 71 72More information on the library and extension modules that are available can be 73found on the [Google Maven ExoPlayer page][]. 74 75### Turn on Java 8 support ### 76 77If not enabled already, you need to turn on Java 8 support in all `build.gradle` 78files depending on ExoPlayer, by adding the following to the `android` section: 79 80~~~ 81compileOptions { 82 targetCompatibility JavaVersion.VERSION_1_8 83} 84~~~ 85{: .language-gradle} 86 87### Enable multidex ### 88 89If your Gradle `minSdkVersion` is 20 or lower, you should 90[enable multidex](https://developer.android.com/studio/build/multidex) in order 91to prevent build errors. 92 93## Creating the player ## 94 95You can create an `ExoPlayer` instance using `ExoPlayer.Builder`, which provides 96a range of customization options. The code below is the simplest example of 97creating an instance. 98 99~~~ 100ExoPlayer player = new ExoPlayer.Builder(context).build(); 101~~~ 102{: .language-java} 103 104### A note on threading ### 105 106ExoPlayer instances must be accessed from a single application thread. For the 107vast majority of cases this should be the application's main thread. Using the 108application's main thread is a requirement when using ExoPlayer's UI components 109or the IMA extension. 110 111The thread on which an ExoPlayer instance must be accessed can be explicitly 112specified by passing a `Looper` when creating the player. If no `Looper` is 113specified, then the `Looper` of the thread that the player is created on is 114used, or if that thread does not have a `Looper`, the `Looper` of the 115application's main thread is used. In all cases the `Looper` of the thread from 116which the player must be accessed can be queried using 117`Player.getApplicationLooper`. 118 119If you see `IllegalStateException` being thrown with the message "Player is 120accessed on the wrong thread", then some code in your app is accessing an 121`ExoPlayer` instance on the wrong thread (the exception's stack trace shows you 122where). You can temporarily opt out from these exceptions being thrown by 123calling `ExoPlayer.setThrowsWhenUsingWrongThread(false)`, in which case the 124issue will be logged as a warning instead. Using this opt out is not safe and 125may result in unexpected or obscure errors. It will be removed in ExoPlayer 1262.16. 127{:.info} 128 129For more information about ExoPlayer's threading model, see the 130["Threading model" section of the ExoPlayer Javadoc][]. 131 132## Attaching the player to a view ## 133 134The ExoPlayer library provides a range of pre-built UI components for media 135playback. These include `StyledPlayerView`, which encapsulates a 136`StyledPlayerControlView`, a `SubtitleView`, and a `Surface` onto which video is 137rendered. A `StyledPlayerView` can be included in your application's layout xml. 138Binding the player to the view is as simple as: 139 140~~~ 141// Bind the player to the view. 142playerView.setPlayer(player); 143~~~ 144{: .language-java} 145 146You can also use `StyledPlayerControlView` as a standalone component, which is 147useful for audio only use cases. 148 149Use of ExoPlayer's pre-built UI components is optional. For video applications 150that implement their own UI, the target `SurfaceView`, `TextureView`, 151`SurfaceHolder` or `Surface` can be set using `ExoPlayer`'s 152`setVideoSurfaceView`, `setVideoTextureView`, `setVideoSurfaceHolder` and 153`setVideoSurface` methods respectively. `ExoPlayer`'s `addTextOutput` method can 154be used to receive captions that should be rendered during playback. 155 156## Populating the playlist and preparing the player ## 157 158In ExoPlayer every piece of media is represented by a `MediaItem`. To play a 159piece of media you need to build a corresponding `MediaItem`, add it to the 160player, prepare the player, and call `play` to start the playback: 161 162~~~ 163// Build the media item. 164MediaItem mediaItem = MediaItem.fromUri(videoUri); 165// Set the media item to be played. 166player.setMediaItem(mediaItem); 167// Prepare the player. 168player.prepare(); 169// Start the playback. 170player.play(); 171~~~ 172{: .language-java} 173 174ExoPlayer supports playlists directly, so it's possible to prepare the player 175with multiple media items to be played one after the other: 176 177~~~ 178// Build the media items. 179MediaItem firstItem = MediaItem.fromUri(firstVideoUri); 180MediaItem secondItem = MediaItem.fromUri(secondVideoUri); 181// Add the media items to be played. 182player.addMediaItem(firstItem); 183player.addMediaItem(secondItem); 184// Prepare the player. 185player.prepare(); 186// Start the playback. 187player.play(); 188~~~ 189{: .language-java} 190 191The playlist can be updated during playback without the need to prepare the 192player again. Read more about populating and manipulating the playlist on the 193[Playlists page][]. Read more about the different options available when 194building media items, such as clipping and attaching subtitle files, on the 195[Media items page][]. 196 197Prior to ExoPlayer 2.12, the player needed to be given a `MediaSource` rather 198than media items. From 2.12 onwards, the player converts media items to the 199`MediaSource` instances that it needs internally. Read more about this process 200and how it can be customized on the [Media sources page][]. It's still possible 201to provide `MediaSource` instances directly to the player using 202`ExoPlayer.setMediaSource(s)` and `ExoPlayer.addMediaSource(s)`. 203{:.info} 204 205## Controlling the player ## 206 207Once the player has been prepared, playback can be controlled by calling methods 208on the player. Some of the most commonly used methods are listed below. 209 210* `play` and `pause` start and pause playback. 211* `seekTo` allows seeking within the media. 212* `hasPrevious`, `hasNext`, `previous` and `next` allow navigating through the 213 playlist. 214* `setRepeatMode` controls if and how media is looped. 215* `setShuffleModeEnabled` controls playlist shuffling. 216* `setPlaybackParameters` adjusts playback speed and audio pitch. 217 218If the player is bound to a `StyledPlayerView` or `StyledPlayerControlView`, 219then user interaction with these components will cause corresponding methods on 220the player to be invoked. 221 222## Releasing the player ## 223 224It's important to release the player when it's no longer needed, so as to free 225up limited resources such as video decoders for use by other applications. This 226can be done by calling `ExoPlayer.release`. 227 228[main demo app]: {{ site.release_v2 }}/demos/main/ 229[extensions directory]: {{ site.release_v2 }}/extensions/ 230[release notes]: {{ site.release_v2 }}/RELEASENOTES.md 231["Threading model" section of the ExoPlayer Javadoc]: {{ site.exo_sdk }}/ExoPlayer.html 232[Playlists page]: {{ site.baseurl }}/playlists.html 233[Media items page]: {{ site.baseurl }}/media-items.html 234[Media sources page]: {{ site.baseurl }}/media-sources.html 235[Google Maven ExoPlayer page]: https://maven.google.com/web/index.html#com.google.android.exoplayer 236