YouTubePlayer
| com.google.android.youtube.player.YouTubePlayer |
Overview
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.
Summary
| 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.
| |||||||||||
Constants
public static final 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. 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.
See Also
public static final int FULLSCREEN_FLAG_CONTROL_ORIENTATION
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.
See Also
public static final int FULLSCREEN_FLAG_CONTROL_SYSTEM_UI
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.
See Also
public static final 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. 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
- That the player's view takes up the whole available space of application's window whenever
onFullscreen(boolean)is called. - That the activity is not recreated when the orientation changes to landscape. To achieve
this for an activity that supports portrait, you need to specify that your activity handles
some configuration changes on its own in your application's manifest, including
orientation,keyboardHiddenandscreenSize.
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.
See Also
Public methods
public abstract void addFullscreenControlFlag (int controlFlag)
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).
Parameters
| 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.
|
public abstract void cuePlaylist (String playlistId, int startIndex, int timeMillis)
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.
Parameters
| 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. |
public abstract void cuePlaylist (String playlistId)
Cues the specified playlist, but does not download any of the video streams or start playing
until play() or seekToMillis(int) is called.
Parameters
| playlistId | The ID for the playlist to be cued, as returned from the YouTube Data API. |
public abstract void cueVideo (String videoId)
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.
Parameters
| videoId | The ID of the video to be cued, as returned from the YouTube Data API. |
public abstract void cueVideo (String videoId, int timeMillis)
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.
Parameters
| 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. |
public abstract void cueVideos (List<String> videoIds, int startIndex, int timeMillis)
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.
Parameters
| 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. |
public abstract void cueVideos (List<String> videoIds)
Cues a list of videos, but does not download any of the video streams or start playing until
play() or seekToMillis(int) is called.
Parameters
| videoIds | A list of YouTube video IDs to be cued, as returned from the YouTube Data API. |
public abstract int getCurrentTimeMillis ()
Gets the current elapsed time of the playing video relative to its start.
Returns
- The current elapsed time (a number of milliseconds) of the playing video relative to its start. The result is only well-defined after the video has finished loading.
See Also
public abstract int getDurationMillis ()
Gets the duration of the currently loaded video.
Returns
- The currently loaded video's duration (in milliseconds). The result is only defined after the video has finished loading, and may change to a more accurate value when the video starts playing.
See Also
public abstract int getFullscreenControlFlags ()
Gets the currently set fullscreen control flags.
Returns
- The currently set flags. The
intis a bitwise-or ofFULLSCREEN_FLAG_CONTROL_ORIENTATION,FULLSCREEN_FLAG_CONTROL_SYSTEM_UI,FULLSCREEN_FLAG_ALWAYS_FULLSCREEN_IN_LANDSCAPEandFULLSCREEN_FLAG_CUSTOM_LAYOUT.
public abstract boolean hasNext ()
Determines whether the currently loaded playlist has a next video.
Returns
trueif there is a next video in the loaded playlist,falseotherwise.
public abstract boolean hasPrevious ()
Determines whether the currently loaded playlist has a previous video.
Returns
trueif there is a previous video in the loaded playlist,falseotherwise.
public abstract boolean isPlaying ()
Determines whether the player is currently playing.
Returns
trueif the player is currently playing, or buffering while still in the playing state,falseotherwise.
public abstract void loadPlaylist (String playlistId)
Loads and plays the specified playlist.
Note: YouTube only counts playbacks that are initiated through the native play button.
Parameters
| playlistId | The ID for the playlist to be played, as returned from the YouTube Data API. |
public abstract void loadPlaylist (String playlistId, int startIndex, int timeMillis)
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.
Parameters
| 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. |
public abstract void loadVideo (String videoId)
Loads and plays the specified video.
Note: YouTube only counts playbacks that are initiated through the native play button.
Parameters
| videoId | The ID of the video to be played, as returned from the YouTube Data API. |
public abstract void loadVideo (String videoId, int timeMillis)
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.
Parameters
| 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. |
public abstract void loadVideos (List<String> videoIds, int startIndex, int timeMillis)
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.
Parameters
| 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. |
public abstract void loadVideos (List<String> videoIds)
Loads and plays a list of videos.
Note: YouTube only counts playbacks that are initiated through the native play button.
Parameters
| videoIds | A list of YouTube video IDs to be played, as returned from the YouTube Data API. |
public abstract void next ()
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.
Throws
| NoSuchElementException | This exception is thrown if the method is called at the end of the playlist. |
public abstract void pause ()
Pauses the currently playing video.
public abstract void play ()
Starts video playback of the currently cued / loaded video.
Note: YouTube only counts playbacks that are initiated through the native play button.
public abstract void previous ()
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.
Throws
| NoSuchElementException | This exception is thrown if the method is called at the start of the playlist. |
public abstract void release ()
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.
public abstract void seekRelativeMillis (int milliSeconds)
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.
Parameters
| milliSeconds | Number of milliseconds to seek forward, if positive, or backward, if negative. |
public abstract void seekToMillis (int milliSeconds)
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.
Parameters
| milliSeconds | Time to seek to in milliseconds. |
public abstract void setFullscreen (boolean fullscreen)
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.
Parameters
| fullscreen | true if the player is fullscreen, false otherwise.
|
public abstract void setFullscreenControlFlags (int controlFlags)
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.
Parameters
| 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.
|
public abstract void setManageAudioFocus (boolean manage)
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.
Parameters
| manage | true to enable automatic handling of audio focus, false to
disable.
|
public abstract void setOnFullscreenListener (YouTubePlayer.OnFullscreenListener listener)
Registers a YouTubePlayer.OnFullscreenListener.
Parameters
| listener | The listener to be notified of fullscreen toggling. |
See Also
public abstract void setPlaybackEventListener (YouTubePlayer.PlaybackEventListener listener)
Registers a YouTubePlayer.PlaybackEventListener.
Parameters
| listener | The listener to register, or null to unregister the previous listener.
|
public abstract void setPlayerStateChangeListener (YouTubePlayer.PlayerStateChangeListener listener)
Registers a YouTubePlayer.PlayerStateChangeListener.
Parameters
| listener | The listener to register, or null to unregister the previous listener.
|
public abstract void setPlayerStyle (YouTubePlayer.PlayerStyle style)
Sets the current style for the player, which impacts the level of control the user has over the player.
Parameters
| style | The chosen YouTubePlayer.PlayerStyle. The default style is
DEFAULT.
|
public abstract void setPlaylistEventListener (YouTubePlayer.PlaylistEventListener listener)
Registers a YouTubePlayer.PlaylistEventListener.
Parameters
| listener | The listener to register, or null to unregister the previous listener.
|
public abstract void setShowFullscreenButton (boolean show)
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.
Parameters
| show | true to show the fullscreen button, false to hide it. |
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2022-11-04 UTC.