com.google.android.youtube.player.YouTubePlayer |
A YouTubePlayer provides methods for loading, playing and controlling YouTube video playback.
Get an instance of this class by calling
initialize
on a YouTubePlayer.Provider
such
as YouTubePlayerFragment
or YouTubePlayerView
.
Video and playlist IDs required by methods such as loadVideo(String)
or
cuePlaylist(String)
are provided by the YouTube Data API. To learn more about this API,
visit https://developers.google.com/youtube/.
The YouTubePlayer supports state saving, which is managed automatically by the YouTubePlayer.Provider
of the player. The saved state includes the loaded videos, the current playback position and
player configurations such as the current YouTubePlayer.PlayerStyle
or fullscreen control flags. The
state does not include any of the listeners that may be set on the player, so they need to be
set again after the player is recreated.
You should only call methods on a YouTubePlayer
object from the UI
thread.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
YouTubePlayer.ErrorReason | Describes the reason for an error in a YouTubePlayer . |
||||||||||
YouTubePlayer.OnFullscreenListener | Interface definition for callbacks that are invoked when the player toggles between fullscreen
on or off, either due to the user clicking the fullscreen button or a call to
setFullscreen(boolean) . |
||||||||||
YouTubePlayer.OnInitializedListener | Interface definition for callbacks that are invoked when player initialization succeeds or fails. | ||||||||||
YouTubePlayer.PlaybackEventListener | Interface definition for callbacks that are invoked when video playback events occur. | ||||||||||
YouTubePlayer.PlayerStateChangeListener | Interface definition for callbacks that are invoked when the high-level player state changes. | ||||||||||
YouTubePlayer.PlayerStyle | The different styles available for the player. | ||||||||||
YouTubePlayer.PlaylistEventListener | Interface definition for callbacks that are invoked when events related to playlists occur. | ||||||||||
YouTubePlayer.Provider | A class that implements this interface can provide a YouTubePlayer instance. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | FULLSCREEN_FLAG_ALWAYS_FULLSCREEN_IN_LANDSCAPE | Flag for setFullscreenControlFlags(int) which causes the player to automatically
enter fullscreen whenever the device enters landscape orientation. |
|||||||||
int | FULLSCREEN_FLAG_CONTROL_ORIENTATION | Flag for setFullscreenControlFlags(int) to enable automatic control of the
orientation. |
|||||||||
int | FULLSCREEN_FLAG_CONTROL_SYSTEM_UI | Flag for setFullscreenControlFlags(int) to enable automatic control of system UI. |
|||||||||
int | FULLSCREEN_FLAG_CUSTOM_LAYOUT | Flag for setFullscreenControlFlags(int) that disables the default fullscreen layout
handler, enabling you to control the transition to fullscreen layout manually. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Variant of
setFullscreenControlFlags(int) that doesn't change the already set flags,
but just adds the provided flag to the currently set flags. | |||||||||||
Cues the specified playlist, but does not download any of the video streams or start playing
until
play() or seekToMillis(int) is called. | |||||||||||
Cues the specified playlist, but does not download any of the video streams or start playing
until
play() or seekToMillis(int) is called. | |||||||||||
Loads the specified video's thumbnail and prepares the player to play the video, but does not
download any of the video stream until
play() is called. | |||||||||||
Loads the specified video's thumbnail and prepares the player to play the video, but does not
download any of the video stream until
play() is called. | |||||||||||
Cues a list of videos, but does not download any of the video streams or start playing until
play() or seekToMillis(int) is called. | |||||||||||
Cues a list of videos, but does not download any of the video streams or start playing until
play() or seekToMillis(int) is called. | |||||||||||
Gets the current elapsed time of the playing video relative to its start.
| |||||||||||
Gets the duration of the currently loaded video.
| |||||||||||
Gets the currently set fullscreen control flags.
| |||||||||||
Determines whether the currently loaded playlist has a next video.
| |||||||||||
Determines whether the currently loaded playlist has a previous video.
| |||||||||||
Determines whether the player is currently playing.
| |||||||||||
Loads and plays the specified playlist.
| |||||||||||
Loads and plays the specified playlist.
| |||||||||||
Loads and plays the specified video.
| |||||||||||
Loads and plays the specified video.
| |||||||||||
Loads and plays a list of videos.
| |||||||||||
Loads and plays a list of videos.
| |||||||||||
Plays the next video in the loaded playlist.
| |||||||||||
Pauses the currently playing video.
| |||||||||||
Starts video playback of the currently cued / loaded video.
| |||||||||||
Plays the previous video in the loaded playlist.
| |||||||||||
Stop any loading or video playback and release any system resources used by this
YouTubePlayer . | |||||||||||
Seeks forward or backward by the specified number of seconds.
| |||||||||||
Seeks to the specified time in the video.
| |||||||||||
Inform the player that it is being laid out fullscreen.
| |||||||||||
Controls the automatic behavior when fullscreen mode is toggled.
| |||||||||||
Specifies whether or not the player will handle audio focus as part of its playback lifecycle.
| |||||||||||
Registers a
YouTubePlayer.OnFullscreenListener . | |||||||||||
Registers a
YouTubePlayer.PlaybackEventListener . | |||||||||||
Registers a
YouTubePlayer.PlayerStateChangeListener . | |||||||||||
Sets the current style for the player, which impacts the level of control the user has over
the player.
| |||||||||||
Registers a
YouTubePlayer.PlaylistEventListener . | |||||||||||
Shows or hides the fullscreen button on the player controls.
|
Flag for setFullscreenControlFlags(int)
which causes the player to automatically
enter fullscreen whenever the device enters landscape orientation. Note that this flag should
only be set if your activity is locked in portrait (and is specified as such in the manifest).
The flag is useful if you don't have a landscape layout for your activity, but would like to enable landscape orientation solely for fullscreen video watching.
Note that setting this flag will always cause the screen orientation of your activity to be
switched to landscape whenever the user rotates the device to landscape orientation (using
Activity.setRequestedOrientation(int)
). On exiting fullscreen the requested screen
orientation will be reset its original value.
This flag requires FULLSCREEN_FLAG_CONTROL_ORIENTATION
to also be set.
Flag for setFullscreenControlFlags(int)
to enable automatic control of the
orientation.
The behavior is to force landscape orientation when entering fullscreen and switching back to the original orientation setting when leaving fullscreen. The implementation will also exit fullscreen automatically when the device is rotated back to portrait orientation. This should generally be set unless the application is locked in landscape orientation or you require fullscreen in portrait orientation.
Flag for setFullscreenControlFlags(int)
to enable automatic control of system UI.
When set, system UI will be hidden when user interaction is not expected and re-shown simultaneously with the player controls whenever the user interacts with the device.
The system UI includes the status bar if it is visible as well as any other bars that may be present on the device (navigation bar, system bar etc).
If the application is showing an ActionBar
, it is shown and hidden simultaneously with the
player's controls and other system UI on user interaction, provided that the action bar was
created as an overlay using Window#FEATURE_ACTION_BAR_OVERLAY
. Otherwise, it will be
hidden for the duration of the fullscreen session.
This should generally be set unless you have a specific need to control system UI manually.
Flag for setFullscreenControlFlags(int)
that disables the default fullscreen layout
handler, enabling you to control the transition to fullscreen layout manually. As well as
enabling you to implement a custom fullscreen layout, this option also provides the advantage
of avoiding the rebuffering that occurs in the default fullscreen behavior.
Use this flag if you have a fullscreen layout that you want to use when fullscreen is toggled,
either by the user clicking a fullscreen button or by a call to
setFullscreen(boolean)
.
The default fullscreen behavior will layout the video player in a fullscreen dialog. However, this default behavior requires rebuffering of the video when switching to fullscreen and back. To avoid this, developers are advised to handle the fullscreen event themselves by setting this flag.
An application implementing custom fullscreen behavior should ensure two things
onFullscreen(boolean)
is called.orientation
, keyboardHidden
and screenSize
.
This flag does not effect control of orientation and system UI. The YouTubePlayer
continues to automatically control both orientation and system UI automatically if
FULLSCREEN_FLAG_CONTROL_ORIENTATION
and FULLSCREEN_FLAG_CONTROL_SYSTEM_UI
are set, even if you are controlling layout manually with this flag set.
Variant of setFullscreenControlFlags(int)
that doesn't change the already set flags,
but just adds the provided flag to the currently set flags. Equivalent to
setFullscreenControlFlags(getFullscreenControlFlags() | controlFlag)
.
controlFlag | The flag to set. One of FULLSCREEN_FLAG_CONTROL_ORIENTATION ,
FULLSCREEN_FLAG_CONTROL_SYSTEM_UI ,
FULLSCREEN_FLAG_ALWAYS_FULLSCREEN_IN_LANDSCAPE and
FULLSCREEN_FLAG_CUSTOM_LAYOUT .
|
---|
Cues the specified playlist, but does not download any of the video streams or start playing
until play()
or seekToMillis(int)
is called.
When the user presses play or play()
is called, playback will play the video with the
specified index in the playlist, starting at the specified time in the video.
playlistId | The ID for the playlist to be cued, as returned from the YouTube Data API. |
---|---|
startIndex | The index in the playlist of the first video to be cued. |
timeMillis | The time, in milliseconds, where playback should start in the first video cued. |
Cues the specified playlist, but does not download any of the video streams or start playing
until play()
or seekToMillis(int)
is called.
playlistId | The ID for the playlist to be cued, as returned from the YouTube Data API. |
---|
Loads the specified video's thumbnail and prepares the player to play the video, but does not
download any of the video stream until play()
is called.
videoId | The ID of the video to be cued, as returned from the YouTube Data API. |
---|
Loads the specified video's thumbnail and prepares the player to play the video, but does not
download any of the video stream until play()
is called.
When the user presses play or play()
is called, playback will start at the specified
time in the video.
videoId | The ID of the video to be cued, as returned from the YouTube Data API. |
---|---|
timeMillis | The time, in milliseconds, where playback should start in the video. |
Cues a list of videos, but does not download any of the video streams or start playing until
play()
or seekToMillis(int)
is called.
When the user presses play or play()
is called, playback will play the video with the
specified index and playback will start at the specified time in the video.
videoIds | A list of YouTube video IDs to be cued, as returned from the YouTube Data API. |
---|---|
startIndex | The index in the list of the first video to be cued. |
timeMillis | The time, in milliseconds, where playback should start in the first video cued. |
Cues a list of videos, but does not download any of the video streams or start playing until
play()
or seekToMillis(int)
is called.
videoIds | A list of YouTube video IDs to be cued, as returned from the YouTube Data API. |
---|
Gets the current elapsed time of the playing video relative to its start.
Gets the duration of the currently loaded video.
Gets the currently set fullscreen control flags.
int
is a bitwise-or of
FULLSCREEN_FLAG_CONTROL_ORIENTATION
,
FULLSCREEN_FLAG_CONTROL_SYSTEM_UI
,
FULLSCREEN_FLAG_ALWAYS_FULLSCREEN_IN_LANDSCAPE
and
FULLSCREEN_FLAG_CUSTOM_LAYOUT
.
Determines whether the currently loaded playlist has a next video.
true
if there is a next video in the loaded playlist, false
otherwise.
Determines whether the currently loaded playlist has a previous video.
true
if there is a previous video in the loaded playlist, false
otherwise.
Determines whether the player is currently playing.
true
if the player is currently playing, or buffering while still in the
playing state, false
otherwise.
Loads and plays the specified playlist.
Note: YouTube only counts playbacks that are initiated through the native play button.
playlistId | The ID for the playlist to be played, as returned from the YouTube Data API. |
---|
Loads and plays the specified playlist. Playback will start at the video with the specified index and will start at the specified time in the video
Note: YouTube only counts playbacks that are initiated through the native play button.
playlistId | The ID for the playlist to be played, as returned from the YouTube Data API. |
---|---|
startIndex | The index in the playlist where playback will start. |
timeMillis | The time, in milliseconds, where playback should start in the first video played. |
Loads and plays the specified video.
Note: YouTube only counts playbacks that are initiated through the native play button.
videoId | The ID of the video to be played, as returned from the YouTube Data API. |
---|
Loads and plays the specified video. Playback will start at the specified time in the video.
Note: YouTube only counts playbacks that are initiated through the native play button.
videoId | The ID of the video to be played, as returned from the YouTube Data API. |
---|---|
timeMillis | The time, in milliseconds, where playback should start in the video. |
Loads and plays a list of videos. Playback will start at the video with the specified index and will start at the specified time in the video
Note: YouTube only counts playbacks that are initiated through the native play button.
videoIds | A list of YouTube video IDs to be played, as returned from the YouTube Data API. |
---|---|
startIndex | The index in the list of the first video to be played. |
timeMillis | The time, in milliseconds, where playback should start in the first video played. |
Loads and plays a list of videos.
Note: YouTube only counts playbacks that are initiated through the native play button.
videoIds | A list of YouTube video IDs to be played, as returned from the YouTube Data API. |
---|
Plays the next video in the loaded playlist.
Note that a second call to next()
or previous()
, before the first call has
finished (as indicated by onLoaded(String)
) might be ignored.
NoSuchElementException | This exception is thrown if the method is called at the end of the playlist. |
---|
Pauses the currently playing video.
Starts video playback of the currently cued / loaded video.
Note: YouTube only counts playbacks that are initiated through the native play button.
Plays the previous video in the loaded playlist.
Note that a second call to next()
or previous()
, before the first call has
finished (as indicated by onLoaded(String)
) might be ignored.
NoSuchElementException | This exception is thrown if the method is called at the start of the playlist. |
---|
Stop any loading or video playback and release any system resources used by this
YouTubePlayer
.
Note that after calling this method any further interaction with this YouTubePlayer
is
forbidden. A new instance must be created to re-enable playback.
Seeks forward or backward by the specified number of seconds.
If the player is paused or stopped when this function is called, the player will remain remain in the same state, but will start the video at the sought-to position when playback resumes.
milliSeconds | Number of milliseconds to seek forward, if positive, or backward, if negative. |
---|
Seeks to the specified time in the video.
If the player is paused or stopped when this function is called, the player will remain remain in the same state, but will start the video at the sought-to position when playback resumes.
milliSeconds | Time to seek to in milliseconds. |
---|
Inform the player that it is being laid out fullscreen. Calling this function may affect the looks of the player's controls, e.g. showing an option to enter or exit fullscreen, changing the layout to better suit the current player size etc.
Note: Calling this function will cause any registered YouTubePlayer.OnFullscreenListener
to fire
an onFullscreen(boolean)
event.
fullscreen | true if the player is fullscreen, false otherwise.
|
---|
Controls the automatic behavior when fullscreen mode is toggled.
This method allows you to enable or disable different parts of fullscreen behavior that can be
automated by the library. Examples include control of screen orientation, showing/hiding
system UI on fullscreen events and a default fullscreen layout. The default flags set
are FULLSCREEN_FLAG_CONTROL_SYSTEM_UI
and
FULLSCREEN_FLAG_CONTROL_ORIENTATION
.
controlFlags | Bitwise-or of FULLSCREEN_FLAG_CONTROL_ORIENTATION ,
FULLSCREEN_FLAG_CONTROL_SYSTEM_UI ,
FULLSCREEN_FLAG_ALWAYS_FULLSCREEN_IN_LANDSCAPE and
FULLSCREEN_FLAG_CUSTOM_LAYOUT . A value of 0 will disable any automatic
behavior.
|
---|
Specifies whether or not the player will handle audio focus as part of its playback lifecycle.
When true
, the player will request and abandon audio focus appropriately when playback
starts and ends, as well as pausing playback when losing audio focus. When ducking, the player
lowers its volume.
Handling the audio focus also includes pausing the player if necessary when the audio is
becoming noisy due to a change in audio outputs
(see AudioManager.ACTION_AUDIO_BECOMING_NOISY
).
The default value is true
.
manage | true to enable automatic handling of audio focus, false to
disable.
|
---|
Registers a YouTubePlayer.OnFullscreenListener
.
listener | The listener to be notified of fullscreen toggling. |
---|
Registers a YouTubePlayer.PlaybackEventListener
.
listener | The listener to register, or null to unregister the previous listener.
|
---|
Registers a YouTubePlayer.PlayerStateChangeListener
.
listener | The listener to register, or null to unregister the previous listener.
|
---|
Sets the current style for the player, which impacts the level of control the user has over the player.
style | The chosen YouTubePlayer.PlayerStyle . The default style is
DEFAULT .
|
---|
Registers a YouTubePlayer.PlaylistEventListener
.
listener | The listener to register, or null to unregister the previous listener.
|
---|
Shows or hides the fullscreen button on the player controls. The default is to show a fullscreen button which enables the user to switch between fullscreen and non-fullscreen modes. You can use this method to hide the fullscreen button if required, e.g., if you only show videos in fullscreen.
Note: Only the DEFAULT
player style supports this button, this method will
have no effect on other player styles.
show | true to show the fullscreen button, false to hide it. |
---|