1---
2title: UI components
3---
4
5An app playing media requires user interface components for displaying media and
6controlling playback. The ExoPlayer library includes a UI module that contains
7a number of UI components. To depend on the UI module add a dependency as shown
8below.
9
10~~~
11implementation 'com.google.android.exoplayer:exoplayer-ui:2.X.X'
12~~~
13{: .language-gradle}
14
15The most important component is `StyledPlayerView`, a view for media
16playbacks. It displays video, subtitles and album art during playback, as
17well as playback controls.
18
19`StyledPlayerView` has a `setPlayer` method for attaching and detaching (by
20passing `null`) player instances.
21
22## StyledPlayerView ##
23
24`StyledPlayerView` can be used for both video and audio playbacks. It renders
25video and subtitles in the case of video playback, and can display artwork
26included as metadata in audio files. You can include it in your layout files
27like any other UI component. For example, a `StyledPlayerView` can be included
28with the following XML:
29
30~~~
31<com.google.android.exoplayer2.ui.StyledPlayerView
32    android:id="@+id/player_view"
33    android:layout_width="match_parent"
34    android:layout_height="match_parent"
35    app:show_buffering="when_playing"
36    app:show_shuffle_button="true"/>
37~~~
38{: .language-xml}
39
40The snippet above illustrates that `StyledPlayerView` provides several
41attributes. These attributes can be used to customize the view's behavior, as
42well as its look and feel. Most of these attributes have corresponding setter
43methods, which can be used to customize the view at runtime. The
44[`StyledPlayerView`][] Javadoc lists these attributes and setter methods in
45more detail.
46
47Once the view is declared in the layout file, it can be looked up in the
48`onCreate` method of the activity:
49
50~~~
51@Override
52protected void onCreate(Bundle savedInstanceState) {
53  super.onCreate(savedInstanceState);
54  // ...
55  playerView = findViewById(R.id.player_view);
56}
57~~~
58{: .language-java}
59
60When a player has been initialized, it can be attached to the view by calling
61`setPlayer`:
62
63~~~
64// Instantiate the player.
65player = new ExoPlayer.Builder(context).build();
66// Attach player to the view.
67playerView.setPlayer(player);
68// Set the media item to be played.
69player.setMediaItem(mediaItem);
70// Prepare the player.
71player.prepare();
72~~~
73{: .language-java}
74
75### Choosing a surface type ###
76
77The `surface_type` attribute of `StyledPlayerView` lets you set the type of
78surface used for video playback. Besides the values `spherical_gl_surface_view`
79(which is a special value for spherical video playback) and
80`video_decoder_gl_surface_view` (which is for video rendering using extension
81renderers), the allowed values are `surface_view`, `texture_view` and `none`. If
82the view is for audio playback only, `none` should be used to avoid having to
83create a surface, since doing so can be expensive.
84
85If the view is for regular video playback then `surface_view` or `texture_view`
86should be used. `SurfaceView` has a number of benefits over `TextureView` for
87video playback:
88
89* Significantly lower power consumption on many devices.
90* More accurate frame timing, resulting in smoother video playback.
91* Support for secure output when playing DRM protected content.
92* The ability to render video content at the full resolution of the display on
93  Android TV devices that upscale the UI layer.
94
95`SurfaceView` should therefore be preferred over `TextureView` where possible.
96`TextureView` should be used only if `SurfaceView` does not meet your needs. One
97example is where smooth animations or scrolling of the video surface is required
98prior to Android N, as described below. For this case, it's preferable to use
99`TextureView` only when [`SDK_INT`][] is less than 24 (Android N) and
100`SurfaceView` otherwise.
101
102`SurfaceView` rendering wasn't properly synchronized with view animations until
103Android N. On earlier releases this could result in unwanted effects when a
104`SurfaceView` was placed into scrolling container, or when it was subjected to
105animation. Such effects included the view's contents appearing to lag slightly
106behind where it should be displayed, and the view turning black when subjected
107to animation. To achieve smooth animation or scrolling of video prior to Android
108N, it's therefore necessary to use `TextureView` rather than `SurfaceView`.
109{:.info}
110
111Some Android TV devices run their UI layer at a resolution that's lower than the
112full resolution of the display, upscaling it for presentation to the user. For
113example, the UI layer may be run at 1080p on an Android TV that has a 4K
114display. On such devices, `SurfaceView` must be used to render content at the
115full resolution of the display. The full resolution of the display (in its
116current display mode) can be queried using [`Util.getCurrentDisplayModeSize`][].
117The UI layer resolution can be queried using Android's [`Display.getSize`] API.
118{:.info}
119
120### Overriding drawables ###
121
122We don't guarantee that the customizations described in the following section
123will continue to work in future versions of the library. The resource IDs may
124change name, or some may be deleted entirely. This is indicated by the
125[resource IDs being marked 'private'][].
126{:.info}
127
128`StyledPlayerView` uses `StyledPlayerControlView` to display the playback
129controls and progress bar. The drawables used by `StyledPlayerControlView` can
130be overridden by drawables with the same names defined in your application. See
131the [`StyledPlayerControlView`][] Javadoc for a list of control drawables that
132can be overridden.
133
134## Further customization ##
135
136Where customization beyond that described above is required, we expect that app
137developers will implement their own UI components rather than use those provided
138by ExoPlayer's UI module.
139
140[`StyledPlayerView`]: {{ site.exo_sdk }}/ui/StyledPlayerView.html
141[`StyledPlayerControlView`]: {{ site.exo_sdk }}/ui/StyledPlayerControlView.html
142[resource IDs being marked 'private']: https://developer.android.com/studio/projects/android-library#PrivateResources
143[`SDK_INT`]: {{ site.android_sdk }}/android/os/Build.VERSION.html#SDK_INT
144[`Util.getCurrentDisplayModeSize`]: {{ site.exo_sdk }}/util/Util.html#getCurrentDisplayModeSize(android.content.Context)
145[`Display.getSize`]: {{ site.android_sdk }}/android/view/Display.html#getSize(android.graphics.Point)
146