YouTubePlayer

public interface
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
enum	YouTubePlayer.ErrorReason	Describes the reason for an error in a YouTubePlayer.
interface	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).
interface	YouTubePlayer.OnInitializedListener	Interface definition for callbacks that are invoked when player initialization succeeds or fails.
interface	YouTubePlayer.PlaybackEventListener	Interface definition for callbacks that are invoked when video playback events occur.
interface	YouTubePlayer.PlayerStateChangeListener	Interface definition for callbacks that are invoked when the high-level player state changes.
enum	YouTubePlayer.PlayerStyle	The different styles available for the player.
interface	YouTubePlayer.PlaylistEventListener	Interface definition for callbacks that are invoked when events related to playlists occur.
interface	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
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.
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.
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.
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.
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.
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.
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.
abstract int	getCurrentTimeMillis() Gets the current elapsed time of the playing video relative to its start.
abstract int	getDurationMillis() Gets the duration of the currently loaded video.
abstract int	getFullscreenControlFlags() Gets the currently set fullscreen control flags.
abstract boolean	hasNext() Determines whether the currently loaded playlist has a next video.
abstract boolean	hasPrevious() Determines whether the currently loaded playlist has a previous video.
abstract boolean	isPlaying() Determines whether the player is currently playing.
abstract void	loadPlaylist(String playlistId) Loads and plays the specified playlist.
abstract void	loadPlaylist(String playlistId, int startIndex, int timeMillis) Loads and plays the specified playlist.
abstract void	loadVideo(String videoId) Loads and plays the specified video.
abstract void	loadVideo(String videoId, int timeMillis) Loads and plays the specified video.
abstract void	loadVideos(List<String> videoIds, int startIndex, int timeMillis) Loads and plays a list of videos.
abstract void	loadVideos(List<String> videoIds) Loads and plays a list of videos.
abstract void	next() Plays the next video in the loaded playlist.
abstract void	pause() Pauses the currently playing video.
abstract void	play() Starts video playback of the currently cued / loaded video.
abstract void	previous() Plays the previous video in the loaded playlist.
abstract void	release() Stop any loading or video playback and release any system resources used by this YouTubePlayer.
abstract void	seekRelativeMillis(int milliSeconds) Seeks forward or backward by the specified number of seconds.
abstract void	seekToMillis(int milliSeconds) Seeks to the specified time in the video.
abstract void	setFullscreen(boolean fullscreen) Inform the player that it is being laid out fullscreen.
abstract void	setFullscreenControlFlags(int controlFlags) Controls the automatic behavior when fullscreen mode is toggled.
abstract void	setManageAudioFocus(boolean manage) Specifies whether or not the player will handle audio focus as part of its playback lifecycle.
abstract void	setOnFullscreenListener(YouTubePlayer.OnFullscreenListener listener) Registers a YouTubePlayer.OnFullscreenListener.
abstract void	setPlaybackEventListener(YouTubePlayer.PlaybackEventListener listener) Registers a YouTubePlayer.PlaybackEventListener.
abstract void	setPlayerStateChangeListener(YouTubePlayer.PlayerStateChangeListener listener) Registers a YouTubePlayer.PlayerStateChangeListener.
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.
abstract void	setPlaylistEventListener(YouTubePlayer.PlaylistEventListener listener) Registers a YouTubePlayer.PlaylistEventListener.
abstract void	setShowFullscreenButton(boolean show) 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

• setFullscreenControlFlags(int)

Constant Value: 4 (0x00000004)

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

• setFullscreenControlFlags(int)

Constant Value: 1 (0x00000001)

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

• setFullscreenControlFlags(int)

Constant Value: 2 (0x00000002)

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, 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.

See Also

• setFullscreenControlFlags(int)

Constant Value: 8 (0x00000008)

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

• onLoaded(String)

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

• onLoaded(String)
• onVideoStarted()

public abstract int getFullscreenControlFlags ()

Gets the currently set fullscreen control flags.

Returns

• The currently set flags. The 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.

public abstract boolean hasNext ()

Determines whether the currently loaded playlist has a next video.

Returns

• true if there is a next video in the loaded playlist, false otherwise.

public abstract boolean hasPrevious ()

Determines whether the currently loaded playlist has a previous video.

Returns

• true if there is a previous video in the loaded playlist, false otherwise.

public abstract boolean isPlaying ()

Determines whether the player is currently playing.

Returns

• true if the player is currently playing, or buffering while still in the playing state, false otherwise.

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

• setFullscreenControlFlags(int)

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.

See Also

• setPlayerStyle(YouTubePlayer.PlayerStyle)
• setFullscreenControlFlags(int)