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. You can
54browse the list of available modules on the [Google Maven ExoPlayer page][]. The
55full library includes all of the library modules prefixed with `exoplayer-`,
56except for `exoplayer-transformer`.
57
58In addition to library modules, ExoPlayer has extension modules that depend on
59external libraries to provide additional functionality. Some extensions are
60available from the Maven repository, whereas others must be built manually.
61Browse the [extensions directory][] and their individual READMEs for details.
62
63### Turn on Java 8 support ###
64
65If not enabled already, you need to turn on Java 8 support in all `build.gradle`
66files depending on ExoPlayer, by adding the following to the `android` section:
67
68~~~
69compileOptions {
70  targetCompatibility JavaVersion.VERSION_1_8
71}
72~~~
73{: .language-gradle}
74
75### Enable multidex ###
76
77If your Gradle `minSdkVersion` is 20 or lower, you should
78[enable multidex](https://developer.android.com/studio/build/multidex) in order
79to prevent build errors.
80
81## Creating the player ##
82
83You can create an `ExoPlayer` instance using `ExoPlayer.Builder`, which provides
84a range of customization options. The code below is the simplest example of
85creating an instance.
86
87~~~
88ExoPlayer player = new ExoPlayer.Builder(context).build();
89~~~
90{: .language-java}
91
92### A note on threading ###
93
94ExoPlayer instances must be accessed from a single application thread. For the
95vast majority of cases this should be the application's main thread. Using the
96application's main thread is a requirement when using ExoPlayer's UI components
97or the IMA extension.
98
99The thread on which an ExoPlayer instance must be accessed can be explicitly
100specified by passing a `Looper` when creating the player. If no `Looper` is
101specified, then the `Looper` of the thread that the player is created on is
102used, or if that thread does not have a `Looper`, the `Looper` of the
103application's main thread is used. In all cases the `Looper` of the thread from
104which the player must be accessed can be queried using
105`Player.getApplicationLooper`.
106
107If you see `IllegalStateException` being thrown with the message "Player is
108accessed on the wrong thread", then some code in your app is accessing an
109`ExoPlayer` instance on the wrong thread (the exception's stack trace shows you
110where).
111{:.info}
112
113For more information about ExoPlayer's threading model, see the
114["Threading model" section of the ExoPlayer Javadoc][].
115
116## Attaching the player to a view ##
117
118The ExoPlayer library provides a range of pre-built UI components for media
119playback. These include `StyledPlayerView`, which encapsulates a
120`StyledPlayerControlView`, a `SubtitleView`, and a `Surface` onto which video is
121rendered. A `StyledPlayerView` can be included in your application's layout xml.
122Binding the player to the view is as simple as:
123
124~~~
125// Bind the player to the view.
126playerView.setPlayer(player);
127~~~
128{: .language-java}
129
130You can also use `StyledPlayerControlView` as a standalone component, which is
131useful for audio only use cases.
132
133Use of ExoPlayer's pre-built UI components is optional. For video applications
134that implement their own UI, the target `SurfaceView`, `TextureView`,
135`SurfaceHolder` or `Surface` can be set using `ExoPlayer`'s
136`setVideoSurfaceView`, `setVideoTextureView`, `setVideoSurfaceHolder` and
137`setVideoSurface` methods respectively. `ExoPlayer`'s `addTextOutput` method can
138be used to receive captions that should be rendered during playback.
139
140## Populating the playlist and preparing the player ##
141
142In ExoPlayer every piece of media is represented by a `MediaItem`. To play a
143piece of media you need to build a corresponding `MediaItem`, add it to the
144player, prepare the player, and call `play` to start the playback:
145
146~~~
147// Build the media item.
148MediaItem mediaItem = MediaItem.fromUri(videoUri);
149// Set the media item to be played.
150player.setMediaItem(mediaItem);
151// Prepare the player.
152player.prepare();
153// Start the playback.
154player.play();
155~~~
156{: .language-java}
157
158ExoPlayer supports playlists directly, so it's possible to prepare the player
159with multiple media items to be played one after the other:
160
161~~~
162// Build the media items.
163MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
164MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
165// Add the media items to be played.
166player.addMediaItem(firstItem);
167player.addMediaItem(secondItem);
168// Prepare the player.
169player.prepare();
170// Start the playback.
171player.play();
172~~~
173{: .language-java}
174
175The playlist can be updated during playback without the need to prepare the
176player again. Read more about populating and manipulating the playlist on the
177[Playlists page][]. Read more about the different options available when
178building media items, such as clipping and attaching subtitle files, on the
179[Media items page][].
180
181Prior to ExoPlayer 2.12, the player needed to be given a `MediaSource` rather
182than media items. From 2.12 onwards, the player converts media items to the
183`MediaSource` instances that it needs internally. Read more about this process
184and how it can be customized on the [Media sources page][]. It's still possible
185to provide `MediaSource` instances directly to the player using
186`ExoPlayer.setMediaSource(s)` and `ExoPlayer.addMediaSource(s)`.
187{:.info}
188
189## Controlling the player ##
190
191Once the player has been prepared, playback can be controlled by calling methods
192on the player. Some of the most commonly used methods are listed below.
193
194* `play` and `pause` start and pause playback.
195* `seekTo` allows seeking within the media.
196* `hasPrevious`, `hasNext`, `previous` and `next` allow navigating through the
197  playlist.
198* `setRepeatMode` controls if and how media is looped.
199* `setShuffleModeEnabled` controls playlist shuffling.
200* `setPlaybackParameters` adjusts playback speed and audio pitch.
201
202If the player is bound to a `StyledPlayerView` or `StyledPlayerControlView`,
203then user interaction with these components will cause corresponding methods on
204the player to be invoked.
205
206## Releasing the player ##
207
208It's important to release the player when it's no longer needed, so as to free
209up limited resources such as video decoders for use by other applications. This
210can be done by calling `ExoPlayer.release`.
211
212[main demo app]: {{ site.release_v2 }}/demos/main/
213[extensions directory]: {{ site.release_v2 }}/extensions/
214[release notes]: {{ site.release_v2 }}/RELEASENOTES.md
215["Threading model" section of the ExoPlayer Javadoc]: {{ site.exo_sdk }}/ExoPlayer.html
216[Playlists page]: {{ site.baseurl }}/playlists.html
217[Media items page]: {{ site.baseurl }}/media-items.html
218[Media sources page]: {{ site.baseurl }}/media-sources.html
219[Google Maven ExoPlayer page]: https://maven.google.com/web/index.html#com.google.android.exoplayer
220