@@ -12,28 +12,20 @@ implementation 'com.google.android.exoplayer:exoplayer-ui:2.X.X'
1212~~~
1313{: .language-gradle}
1414
15- The most important components are ` StyledPlayerControlView ` , ` StyledPlayerView ` ,
16- ` PlayerControlView ` and ` PlayerView ` . The styled variants provide a more
17- polished user experience, however are harder to customize .
15+ The most important component is ` StyledPlayerView ` , a view for media
16+ playbacks. It displays video, subtitles and album art during playback, as
17+ well as playback controls .
1818
19- * [ ` StyledPlayerControlView ` ] [ ] and [ ` PlayerControlView ` ] [ ] are views for
20- controlling playbacks. They display standard playback controls including a
21- play/pause button, fast-forward and rewind buttons, and a seek bar.
22- * [ ` StyledPlayerView ` ] [ ] and [ ` PlayerView ` ] [ ] are high level views for
23- playbacks. They display video, subtitles and album art during playback, as
24- well as playback controls using a ` StyledPlayerControlView ` or
25- ` PlayerControlView ` respectively.
19+ ` StyledPlayerView ` has a ` setPlayer ` method for attaching and detaching (by
20+ passing ` null ` ) player instances.
2621
27- All four views have a ` setPlayer ` method for attaching and detaching (by passing
28- ` null ` ) player instances.
22+ ## ` StyledPlayerView `
2923
30- ## Player views ##
31-
32- ` StyledPlayerView ` and ` PlayerView ` can be used for both video and audio
33- playbacks. They render video and subtitles in the case of video playback, and
34- can display artwork included as metadata in audio files. You can include them in
35- your layout files like any other UI component. For example, a ` StyledPlayerView `
36- can be included with the following XML:
24+ ` StyledPlayerView ` can be used for both video and audio playbacks. It renders
25+ video and subtitles in the case of video playback, and can display artwork
26+ included as metadata in audio files. You can include it in your layout files
27+ like any other UI component. For example, a ` StyledPlayerView ` can be included
28+ with the following XML:
3729
3830~~~
3931<com.google.android.exoplayer2.ui.StyledPlayerView
@@ -50,7 +42,7 @@ attributes. These attributes can be used to customize the view's behavior, as
5042well as its look and feel. Most of these attributes have corresponding setter
5143methods, which can be used to customize the view at runtime. The
5244[ ` StyledPlayerView ` ] [ ] Javadoc lists these attributes and setter methods in
53- more detail. [ ` PlayerView ` ] [ ] defines similar attributes.
45+ more detail.
5446
5547Once the view is declared in the layout file, it can be looked up in the
5648` onCreate ` method of the activity:
@@ -82,13 +74,13 @@ player.prepare();
8274
8375### Choosing a surface type ###
8476
85- The ` surface_type ` attribute of ` StyledPlayerView ` and ` PlayerView ` lets you set
86- the type of surface used for video playback. Besides the values
87- ` spherical_gl_surface_view ` (which is a special value for spherical video
88- playback) and ` video_decoder_gl_surface_view ` (which is for video rendering
89- using extension renderers), the allowed values are ` surface_view ` ,
90- ` texture_view ` and ` none ` . If the view is for audio playback only, ` none ` should
91- be used to avoid having to create a surface, since doing so can be expensive.
77+ The ` surface_type ` attribute of ` StyledPlayerView ` lets you set the type of
78+ surface 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
81+ renderers), the allowed values are ` surface_view ` , ` texture_view ` and ` none ` . If
82+ the view is for audio playback only, ` none ` should be used to avoid having to
83+ create a surface, since doing so can be expensive.
9284
9385If the view is for regular video playback then ` surface_view ` or ` texture_view `
9486should be used. ` SurfaceView ` has a number of benefits over ` TextureView ` for
@@ -125,132 +117,29 @@ current display mode) can be queried using [`Util.getCurrentDisplayModeSize`][].
125117The UI layer resolution can be queried using Android's [ ` Display.getSize ` ] API.
126118{:.info}
127119
128- ## Player control views ##
129-
130- When using ` StyledPlayerView ` , a ` StyledPlayerControlView ` is used internally to
131- provide playback controls. When using a ` PlayerView ` , a ` PlayerControlView ` is
132- used internally.
133-
134- For specific use cases ` StyledPlayerControlView ` and ` PlayerControlView ` can
135- also be used as standalone components. They can be included in your layout file
136- as normal. For example:
137-
138- ~~~
139- <com.google.android.exoplayer2.ui.StyledPlayerControlView
140- android:id="@+id/player_control_view"
141- android:layout_width="match_parent"
142- android:layout_height="match_parent"/>
143- ~~~
144- {: .language-xml}
145-
146- The [ ` StyledPlayerControlView ` ] [ ] and [ ` PlayerControlView ` ] [ ] Javadoc list the
147- the available attributes and setter methods for these components. Looking them
148- up and attaching the player is similar to the example above:
149-
150- ~~~
151- @Override
152- protected void onCreate(Bundle savedInstanceState) {
153- super.onCreate(savedInstanceState);
154- // ...
155- playerControlView = findViewById(R.id.player_control_view);
156- }
157-
158- private void initializePlayer() {
159- // Instantiate the player.
160- player = new ExoPlayer.Builder(context).build();
161- // Attach player to the view.
162- playerControlView.setPlayer(player);
163- // Set the media item to be played.
164- player.setMediaItem(mediaItem);
165- // Prepare the player.
166- player.prepare();
167- }
168- ~~~
169- {: .language-java}
170-
171- ## Customization ##
172-
173- Where significant customization is required, we expect that app developers will
174- implement their own UI components rather than using those provided by
175- ExoPlayer's UI module. That said, the provided UI components do allow for
176- customization by setting attributes (as described above), overriding drawables,
177- overriding layout files, and by specifying custom layout files.
178-
179120### Overriding drawables ###
180121
181- The drawables used by ` StyledPlayerControlView ` and ` PlayerControlView `
182- (with their default layout files) can be overridden by drawables with the same
183- names defined in your application. See the [ ` StyledPlayerControlView ` ] [ ] and
184- [ ` PlayerControlView ` ] [ ] Javadoc for a list of drawables that can be overridden.
185- Note that overriding these drawables will also affect the appearance of
186- ` PlayerView ` and ` StyledPlayerView ` , since they use these views internally.
187-
188- ### Overriding layout files ###
189-
190- All of the view components inflate their layouts from corresponding layout
191- files, which are specified in their Javadoc. For example when a
192- ` PlayerControlView ` is instantiated, it inflates its layout from
193- ` exo_player_control_view.xml ` . To customize these layouts, an application
194- can define layout files with the same names in its own ` res/layout* `
195- directories. These layout files will override the ones provided by the ExoPlayer
196- library.
197-
198- As an example, suppose we want our playback controls to consist of only a
199- play/pause button positioned in the center of the view. We can achieve this by
200- creating an ` exo_player_control_view.xml ` file in the application’s
201- ` res/layout ` directory, containing:
202-
203- ~~~
204- <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
205- android:layout_width="match_parent"
206- android:layout_height="match_parent">
207-
208- <ImageButton android:id="@id/exo_play"
209- android:layout_width="100dp"
210- android:layout_height="100dp"
211- android:layout_gravity="center"
212- android:background="#CC000000"
213- style="@style/ExoMediaButton.Play"/>
214-
215- <ImageButton android:id="@id/exo_pause"
216- android:layout_width="100dp"
217- android:layout_height="100dp"
218- android:layout_gravity="center"
219- android:background="#CC000000"
220- style="@style/ExoMediaButton.Pause"/>
221-
222- </FrameLayout>
223- ~~~
224- {: .language-xml}
225-
226- The change in visual appearance compared to the standard controls is shown
227- below.
228-
229- {% include figure.html url="/images/overriding-layoutfiles.png" index="1" caption="Replacing the standard playback controls (left) with custom controls (right)" %}
122+ We don't guarantee that the customizations described in the following section
123+ will continue to work in future versions of the library. The resource IDs may
124+ change name, or some may be deleted entirely. This is indicated by the
125+ [ resource IDs being marked 'private'] [ ] .
126+ {:.info}
230127
231- ### Custom layout files ###
128+ ` StyledPlayerView ` uses ` StyledPlayerControlView ` to display the playback
129+ controls and progress bar. The drawables used by ` StyledPlayerControlView ` can
130+ be overridden by drawables with the same names defined in your application. See
131+ the [ ` StyledPlayerControlView ` ] [ ] Javadoc for a list of control drawables that
132+ can be overridden.
232133
233- Overriding a layout file is an excellent solution for changing the layout across
234- the whole of an application, but what if a custom layout is required only in a
235- single place? To achieve this, first define a layout file as though overriding
236- one of the default layouts, but this time giving it a different file name, for
237- example ` custom_controls.xml ` . Second, use an attribute to indicate that this
238- layout should be used when inflating the view. For example when using
239- ` PlayerView ` , the layout inflated to provide the playback controls can be
240- specified using the ` controller_layout_id ` attribute:
134+ ## Further customization ##
241135
242- ~~~
243- <com.google.android.exoplayer2.ui.PlayerView android:id="@+id/player_view"
244- android:layout_width="match_parent"
245- android:layout_height="match_parent"
246- app:controller_layout_id="@layout/custom_controls"/>
247- ~~~
248- {: .language-xml}
136+ Where customization beyond that described above is required, we expect that app
137+ developers will implement their own UI components rather than use those provided
138+ by ExoPlayer's UI module.
249139
250- [ ` PlayerView ` ] : {{ site.exo_sdk }}/ui/PlayerView.html
251- [ ` PlayerControlView ` ] : {{ site.exo_sdk }}/ui/PlayerControlView.html
252140[ ` StyledPlayerView ` ] : {{ site.exo_sdk }}/ui/StyledPlayerView.html
253141[ ` StyledPlayerControlView ` ] : {{ site.exo_sdk }}/ui/StyledPlayerControlView.html
142+ [ resource IDs being marked 'private' ] : https://developer.android.com/studio/projects/android-library#PrivateResources
254143[ ` SDK_INT ` ] : {{ site.android_sdk }}/android/os/Build.VERSION.html#SDK_INT
255144[ ` Util.getCurrentDisplayModeSize ` ] : {{ site.exo_sdk }}/util/Util.html#getCurrentDisplayModeSize(android.content.Context)
256145[ ` Display.getSize ` ] : {{ site.android_sdk }}/android/view/Display.html#getSize(android.graphics.Point)
0 commit comments