YouTube

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 which 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 which are invoked when player initialization succeeds or fails. 
interface YouTubePlayer.PlaybackEventListener Interface definition for callbacks which are invoked when video playback events occur. 
interface YouTubePlayer.PlayerStateChangeListener Interface definition for callbacks which 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 which are invoked when events related to playlists occur. 
interface YouTubePlayer.Provider A class which 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)
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, 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 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)
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, 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 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 backwards 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)
abstract void setPlaybackEventListener(YouTubePlayer.PlaybackEventListener listener)
abstract void setPlayerStateChangeListener(YouTubePlayer.PlayerStateChangeListener listener)
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)
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.

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.

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.

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 that the rebuffering which 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 will continue 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.

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

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 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 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)

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

public abstract int getFullscreenControlFlags ()

Gets the currently set fullscreen control flags.

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 If 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 If 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 backwards 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 backwards, 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 off 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)

Parameters
listener The listener to be notified of fullscreen toggling.

public abstract void setPlaybackEventListener (YouTubePlayer.PlaybackEventListener listener)

Parameters
listener The listener to register, or null to unregister the previous listener.

public abstract void setPlayerStateChangeListener (YouTubePlayer.PlayerStateChangeListener listener)

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)

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.