Skip to content

Commit

Permalink
Remove references to Player(Control)View from the dev guide
Browse files Browse the repository at this point in the history 
Remove most of the customisation documentation, since StyledPlayerView
isn't really designed to be customised as deeply as PlayerView.

Also remove most documentation around StyledPlayerControlView,
especially as a standalone controller class - since it doesn't work
well for this use-case.

#minor-release

PiperOrigin-RevId: 426090762
  • Loading branch information
@icbaker
icbaker committed Feb 21, 2022
1 parent 4112a99 commit c8e23b4
Show file tree
Hide file tree
Showing 7 changed files with 58 additions and 365 deletions.
21 changes: 10 additions & 11 deletions docs/ad-insertion.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,8 @@ Internally, `DefaultMediaSourceFactory` will wrap the content media source in an
`AdsLoader.Provider` and use it to insert ads as defined by the media item's ad
tag.

ExoPlayer's `StyledPlayerView` and `PlayerView` UI components both
implement `AdViewProvider`. The IMA extension provides an easy to use
`AdsLoader`, as described below.
ExoPlayer's `StyledPlayerView` implements `AdViewProvider`. The IMA extension
provides an easy to use `AdsLoader`, as described below.

### Playlists with ads ###

Expand Down Expand Up @@ -123,11 +122,11 @@ VAST/VMAP ad tags in the sample list.

#### UI considerations ####

`StyledPlayerView` and `PlayerView` hide controls during playback of ads
by default, but apps can toggle this behavior by calling
`setControllerHideDuringAds`, which is defined on both views. The IMA SDK will
show additional views on top of the player while an ad is playing (e.g., a 'more
info' link and a skip button, if applicable).
`StyledPlayerView` hides its transport controls during playback of ads by
default, but apps can toggle this behavior by calling
`setControllerHideDuringAds`. The IMA SDK will show additional views on top of
the player while an ad is playing (e.g., a 'more info' link and a skip button,
if applicable).

Since advertisers expect a consistent experience across apps, the IMA SDK does
not allow customization of the views that it shows while an ad is playing. It is
Expand All @@ -139,9 +138,9 @@ The IMA SDK may report whether ads are obscured by application provided views
rendered on top of the player. Apps that need to overlay views that are
essential for controlling playback must register them with the IMA SDK so that
they can be omitted from viewability calculations. When using `StyledPlayerView`
or `PlayerView` as the `AdViewProvider`, they will automatically register
their control overlays. Apps that use a custom player UI must register overlay
views by returning them from `AdViewProvider.getAdOverlayInfos`.
as the `AdViewProvider`, it will automatically register its control overlays.
Apps that use a custom player UI must register overlay views by returning them
from `AdViewProvider.getAdOverlayInfos`.

For more information about overlay views, see
[Open Measurement in the IMA SDK][].
Expand Down
1 change: 0 additions & 1 deletion docs/hls.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,5 @@ The following guidelines apply specifically for live streams:

[HlsMediaSource]: {{ site.exo_sdk }}/source/hls/HlsMediaSource.html
[HTTP Live Streaming]: https://tools.ietf.org/html/rfc8216
[UI components]: {{ site.baseurl }}/ui-components.html
[Customization page]: {{ site.baseurl }}/customization.html
[Medium post about HLS playback in ExoPlayer]: https://medium.com/google-exoplayer/hls-playback-in-exoplayer-a33959a47be7
179 changes: 34 additions & 145 deletions docs/ui-components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,20 @@ implementation 'com.google.android.exoplayer:exoplayer-ui:2.X.X'
~~~
{: .language-gradle}

The most important components are `StyledPlayerControlView`, `StyledPlayerView`,
`PlayerControlView` and `PlayerView`. The styled variants provide a more
polished user experience, however are harder to customize.
The most important component is `StyledPlayerView`, a view for media
playbacks. It displays video, subtitles and album art during playback, as
well as playback controls.

* [`StyledPlayerControlView`][] and [`PlayerControlView`][] are views for
controlling playbacks. They display standard playback controls including a
play/pause button, fast-forward and rewind buttons, and a seek bar.
* [`StyledPlayerView`][] and [`PlayerView`][] are high level views for
playbacks. They display video, subtitles and album art during playback, as
well as playback controls using a `StyledPlayerControlView` or
`PlayerControlView` respectively.
`StyledPlayerView` has a `setPlayer` method for attaching and detaching (by
passing `null`) player instances.

All four views have a `setPlayer` method for attaching and detaching (by passing
`null`) player instances.
## `StyledPlayerView` ##

## Player views ##

`StyledPlayerView` and `PlayerView` can be used for both video and audio
playbacks. They render video and subtitles in the case of video playback, and
can display artwork included as metadata in audio files. You can include them in
your layout files like any other UI component. For example, a `StyledPlayerView`
can be included with the following XML:
`StyledPlayerView` can be used for both video and audio playbacks. It renders
video and subtitles in the case of video playback, and can display artwork
included as metadata in audio files. You can include it in your layout files
like any other UI component. For example, a `StyledPlayerView` can be included
with the following XML:

~~~
<com.google.android.exoplayer2.ui.StyledPlayerView
Expand All @@ -50,7 +42,7 @@ attributes. These attributes can be used to customize the view's behavior, as
well as its look and feel. Most of these attributes have corresponding setter
methods, which can be used to customize the view at runtime. The
[`StyledPlayerView`][] Javadoc lists these attributes and setter methods in
more detail. [`PlayerView`][] defines similar attributes.
more detail.

Once the view is declared in the layout file, it can be looked up in the
`onCreate` method of the activity:
Expand Down Expand Up @@ -82,13 +74,13 @@ player.prepare();

### Choosing a surface type ###

The `surface_type` attribute of `StyledPlayerView` and `PlayerView` lets you set
the type of surface used for video playback. Besides the values
`spherical_gl_surface_view` (which is a special value for spherical video
playback) and `video_decoder_gl_surface_view` (which is for video rendering
using extension renderers), the allowed values are `surface_view`,
`texture_view` and `none`. If the view is for audio playback only, `none` should
be used to avoid having to create a surface, since doing so can be expensive.
The `surface_type` attribute of `StyledPlayerView` lets you set the type of
surface used for video playback. Besides the values `spherical_gl_surface_view`
(which is a special value for spherical video playback) and
`video_decoder_gl_surface_view` (which is for video rendering using extension
renderers), the allowed values are `surface_view`, `texture_view` and `none`. If
the view is for audio playback only, `none` should be used to avoid having to
create a surface, since doing so can be expensive.

If the view is for regular video playback then `surface_view` or `texture_view`
should be used. `SurfaceView` has a number of benefits over `TextureView` for
Expand Down Expand Up @@ -125,132 +117,29 @@ current display mode) can be queried using [`Util.getCurrentDisplayModeSize`][].
The UI layer resolution can be queried using Android's [`Display.getSize`] API.
{:.info}

## Player control views ##

When using `StyledPlayerView`, a `StyledPlayerControlView` is used internally to
provide playback controls. When using a `PlayerView`, a `PlayerControlView` is
used internally.

For specific use cases `StyledPlayerControlView` and `PlayerControlView` can
also be used as standalone components. They can be included in your layout file
as normal. For example:

~~~
<com.google.android.exoplayer2.ui.StyledPlayerControlView
android:id="@+id/player_control_view"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
~~~
{: .language-xml}

The [`StyledPlayerControlView`][] and [`PlayerControlView`][] Javadoc list the
the available attributes and setter methods for these components. Looking them
up and attaching the player is similar to the example above:

~~~
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// ...
playerControlView = findViewById(R.id.player_control_view);
}
private void initializePlayer() {
// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerControlView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
}
~~~
{: .language-java}

## Customization ##

Where significant customization is required, we expect that app developers will
implement their own UI components rather than using those provided by
ExoPlayer's UI module. That said, the provided UI components do allow for
customization by setting attributes (as described above), overriding drawables,
overriding layout files, and by specifying custom layout files.

### Overriding drawables ###

The drawables used by `StyledPlayerControlView` and `PlayerControlView`
(with their default layout files) can be overridden by drawables with the same
names defined in your application. See the [`StyledPlayerControlView`][] and
[`PlayerControlView`][] Javadoc for a list of drawables that can be overridden.
Note that overriding these drawables will also affect the appearance of
`PlayerView` and `StyledPlayerView`, since they use these views internally.

### Overriding layout files ###

All of the view components inflate their layouts from corresponding layout
files, which are specified in their Javadoc. For example when a
`PlayerControlView` is instantiated, it inflates its layout from
`exo_player_control_view.xml`. To customize these layouts, an application
can define layout files with the same names in its own `res/layout*`
directories. These layout files will override the ones provided by the ExoPlayer
library.

As an example, suppose we want our playback controls to consist of only a
play/pause button positioned in the center of the view. We can achieve this by
creating an `exo_player_control_view.xml` file in the application’s
`res/layout` directory, containing:

~~~
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent">
<ImageButton android:id="@id/exo_play"
android:layout_width="100dp"
android:layout_height="100dp"
android:layout_gravity="center"
android:background="#CC000000"
style="@style/ExoMediaButton.Play"/>
<ImageButton android:id="@id/exo_pause"
android:layout_width="100dp"
android:layout_height="100dp"
android:layout_gravity="center"
android:background="#CC000000"
style="@style/ExoMediaButton.Pause"/>
</FrameLayout>
~~~
{: .language-xml}

The change in visual appearance compared to the standard controls is shown
below.

{% include figure.html url="/images/overriding-layoutfiles.png" index="1" caption="Replacing the standard playback controls (left) with custom controls (right)" %}
We don't guarantee that the customizations described in the following section
will continue to work in future versions of the library. The resource IDs may
change name, or some may be deleted entirely. This is indicated by the
[resource IDs being marked 'private'][].
{:.info}

### Custom layout files ###
`StyledPlayerView` uses `StyledPlayerControlView` to display the playback
controls and progress bar. The drawables used by `StyledPlayerControlView` can
be overridden by drawables with the same names defined in your application. See
the [`StyledPlayerControlView`][] Javadoc for a list of control drawables that
can be overridden.

Overriding a layout file is an excellent solution for changing the layout across
the whole of an application, but what if a custom layout is required only in a
single place? To achieve this, first define a layout file as though overriding
one of the default layouts, but this time giving it a different file name, for
example `custom_controls.xml`. Second, use an attribute to indicate that this
layout should be used when inflating the view. For example when using
`PlayerView`, the layout inflated to provide the playback controls can be
specified using the `controller_layout_id` attribute:
## Further customization ##

~~~
<com.google.android.exoplayer2.ui.PlayerView android:id="@+id/player_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:controller_layout_id="@layout/custom_controls"/>
~~~
{: .language-xml}
Where customization beyond that described above is required, we expect that app
developers will implement their own UI components rather than use those provided
by ExoPlayer's UI module.

[`PlayerView`]: {{ site.exo_sdk }}/ui/PlayerView.html
[`PlayerControlView`]: {{ site.exo_sdk }}/ui/PlayerControlView.html
[`StyledPlayerView`]: {{ site.exo_sdk }}/ui/StyledPlayerView.html
[`StyledPlayerControlView`]: {{ site.exo_sdk }}/ui/StyledPlayerControlView.html
[resource IDs being marked 'private']: https://developer.android.com/studio/projects/android-library#PrivateResources
[`SDK_INT`]: {{ site.android_sdk }}/android/os/Build.VERSION.html#SDK_INT
[`Util.getCurrentDisplayModeSize`]: {{ site.exo_sdk }}/util/Util.html#getCurrentDisplayModeSize(android.content.Context)
[`Display.getSize`]: {{ site.android_sdk }}/android/view/Display.html#getSize(android.graphics.Point)
12 changes: 6 additions & 6 deletions extensions/av1/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,20 +112,20 @@ gets from the libgav1 decoder:

* GL rendering using GL shader for color space conversion

* If you are using `ExoPlayer` with `PlayerView` or `StyledPlayerView`,
enable this option by setting `surface_type` of view to be
* If you are using `ExoPlayer` with `StyledPlayerView`, enable this option
by setting the `surface_type` of the view to be
`video_decoder_gl_surface_view`.
* Otherwise, enable this option by sending `Libgav1VideoRenderer` a
message of type `Renderer.MSG_SET_VIDEO_OUTPUT` with an instance of
`VideoDecoderOutputBufferRenderer` as its object.
`VideoDecoderGLSurfaceView` is the concrete
`VideoDecoderOutputBufferRenderer` implementation used by `PlayerView`
and `StyledPlayerView`.
`VideoDecoderOutputBufferRenderer` implementation used by
`StyledPlayerView`.

* Native rendering using `ANativeWindow`

* If you are using `ExoPlayer` with `PlayerView` or `StyledPlayerView`,
this option is enabled by default.
* If you are using `ExoPlayer` with `StyledPlayerView`, this option is
enabled by default.
* Otherwise, enable this option by sending `Libgav1VideoRenderer` a
message of type `Renderer.MSG_SET_VIDEO_OUTPUT` with an instance of
`SurfaceView` as its object.
Expand Down
12 changes: 6 additions & 6 deletions extensions/vp9/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,20 +125,20 @@ gets from the libvpx decoder:

* GL rendering using GL shader for color space conversion

* If you are using `ExoPlayer` with `PlayerView` or `StyledPlayerView`,
enable this option by setting `surface_type` of view to be
* If you are using `ExoPlayer` with `StyledPlayerView`, enable this option
by setting the `surface_type` of the view to be
`video_decoder_gl_surface_view`.
* Otherwise, enable this option by sending `LibvpxVideoRenderer` a message
of type `Renderer.MSG_SET_VIDEO_OUTPUT` with an instance of
`VideoDecoderOutputBufferRenderer` as its object.
`VideoDecoderGLSurfaceView` is the concrete
`VideoDecoderOutputBufferRenderer` implementation used by `PlayerView`
and `StyledPlayerView`.
`VideoDecoderOutputBufferRenderer` implementation used by
`StyledPlayerView`.

* Native rendering using `ANativeWindow`

* If you are using `ExoPlayer` with `PlayerView` or `StyledPlayerView`,
this option is enabled by default.
* If you are using `ExoPlayer` with `StyledPlayerView`, this option is
enabled by default.
* Otherwise, enable this option by sending `LibvpxVideoRenderer` a message
of type `Renderer.MSG_SET_VIDEO_OUTPUT` with an instance of
`SurfaceView` as its object.
Expand Down
Loading

0 comments on commit c8e23b4

Please sign in to comment.