@capgo/capacitor-youtube-player

June 16, 2026 · View on GitHub

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Embed YouTube player controls in Capacitor apps

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/youtube-player/

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-youtube-player` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-youtube-player
npx cap sync

Native Implementation

iOS

This plugin uses native WKWebView for iOS playback, which provides:

Fullscreen-only playback mode for immersive viewing experience
Direct YouTube iframe API integration
Support for all YouTube iframe API parameters
Native iOS modal presentation
Cookie support for authentication via WKWebView's HTTPCookieStore
No external dependencies - pure iOS SDK

Important: iOS always plays videos in fullscreen mode for the best user experience.

Android

This plugin uses android-youtube-player for native Android playback, which provides:

Modern, actively maintained library
Fullscreen support with immersive mode
Direct YouTube iframe API integration
Lifecycle-aware components
Cookie support via CookieManager
No API key required

Seeing com.google.android.youtube.player build errors? Upgrade to @capgo/capacitor-youtube-player v8.2.0+ and run npx cap sync android. The plugin now uses the android-youtube-player library instead of the deprecated YouTube Android Player API.

Note: Uses YouTube's iframe API internally, providing a consistent experience across platforms.

This plugin now supports privacy-enhanced mode for better GDPR compliance. When enabled, the plugin uses youtube-nocookie.com domain instead of youtube.com, which prevents YouTube from storing visitor information until they actually play the video.

Usage with Privacy-Enhanced Mode

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true, // Enable privacy-enhanced mode
});

Important Platform Notes:

Web: The privacyEnhanced option uses youtube-nocookie.com domain for better privacy
iOS: Uses native WKWebView for fullscreen-only playback with YouTube iframe API
Android: Uses android-youtube-player library with YouTube iframe API

For full GDPR compliance, you should also:

Display a cookie consent banner before loading videos
Update your privacy policy to disclose YouTube's data collection
Consider implementing a "click to load" placeholder for videos

The plugin now supports passing cookies to the YouTube player to help prevent the "sign in to confirm you're not a bot" message that YouTube sometimes displays.

Usage with Cookies

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  cookies: 'CONSENT=YES+cb; VISITOR_INFO1_LIVE=xyz123', // Your YouTube cookies
});

Platform Support:

Web: ✅ Cookies are set via document.cookie with SameSite=None; Secure attributes
iOS: ✅ Cookies are set in WKWebView's HTTPCookieStore for the .youtube.com domain (native WKWebView, fullscreen-only mode)
Android: ✅ Cookies are set via CookieManager in the WebView for YouTube domains

Important Notes:

Cookie Format: Pass cookies as a semicolon-separated string (e.g., "name1=value1; name2=value2")
Getting Cookies: You can obtain valid YouTube cookies from your browser's developer tools when signed into YouTube
Security: All cookies are automatically set with secure attributes (HTTPS only)
Domain: Cookies are set for .youtube.com to work across all YouTube subdomains
Android: Uses android-youtube-player library which is based on YouTube's iframe API, so cookies work similarly to the web platform

Common YouTube Cookies:

CONSENT: YouTube consent cookie (helps with GDPR compliance)
VISITOR_INFO1_LIVE: Visitor tracking cookie
YSC: YouTube session cookie
PREF: User preferences cookie

Fix YouTube Referer Blocking in the Main WebView

If YouTube works inside the plugin but breaks when the same app loads YouTube pages, embeds, or APIs through Capacitor's main WebView, this plugin can ship the fix for you.

When enabled, @capgo/capacitor-youtube-player patches Capacitor during cap sync / cap update and makes intercepted YouTube requests look like a real browser request by adding a valid Referer header.

Why this is useful:

No patch-package maintenance in your app.
Opt-in only: nothing changes until you enable it.
Scoped safely: only YouTube hosts are affected.
Existing request-level Referer headers still win.
Works on both iOS and Android for Capacitor 8.x.

Enable it in your Capacitor config:

{
  "plugins": {
    "YoutubePlayer": {
      "patchRefererHeader": true,
      "refererHeader": "https://www.youtube.com"
    }
  }
}

What happens when it is enabled:

The plugin hooks into Capacitor sync/update and patches the installed @capacitor/ios and @capacitor/android packages in node_modules.
Only requests for youtube.com, youtube-nocookie.com, and youtu.be are touched.
Requests that already define any Referer header keep their original value.
refererHeader is optional and defaults to https://www.youtube.com.

Good defaults:

Turn on patchRefererHeader if your app loads YouTube content in the main Capacitor WebView.
Leave refererHeader alone unless your integration needs a different valid http or https origin.

Compatibility:

Supported on Capacitor 8.x.
The patch is applied only for installed native platforms, so iOS-only and Android-only apps are both supported.

API

initialize(...)
destroy(...)
stopVideo(...)
playVideo(...)
pauseVideo(...)
seekTo(...)
loadVideoById(...)
cueVideoById(...)
loadVideoByUrl(...)
cueVideoByUrl(...)
cuePlaylist(...)
loadPlaylist(...)
nextVideo(...)
previousVideo(...)
playVideoAt(...)
mute(...)
unMute(...)
isMuted(...)
setVolume(...)
getVolume(...)
setSize(...)
getPlaybackRate(...)
setPlaybackRate(...)
getAvailablePlaybackRates(...)
setLoop(...)
setShuffle(...)
getVideoLoadedFraction(...)
getPlayerState(...)
getAllPlayersEventsState()
getCurrentTime(...)
toggleFullScreen(...)
getPlaybackQuality(...)
setPlaybackQuality(...)
getAvailableQualityLevels(...)
getDuration(...)
getVideoUrl(...)
getVideoEmbedCode(...)
getPlaylist(...)
getPlaylistIndex(...)
getIframe(...)
addEventListener(...)
removeEventListener(...)
getPluginVersion()
Interfaces
Enums

YouTube Player Plugin interface for Capacitor. Provides methods to control YouTube video playback in your app.

initialize(...)

initialize(options: IPlayerOptions) => Promise<{ playerReady: boolean; player: string; } | undefined>

Initialize a new YouTube player instance.

Param	Type	Description
`options`	`IPlayerOptions`	- Configuration options for the player

Returns: Promise<{ playerReady: boolean; player: string; }>

destroy(...)

destroy(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Destroy a player instance and free resources.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

stopVideo(...)

stopVideo(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Stop video playback and cancel loading. Use this sparingly - pauseVideo() is usually preferred.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

playVideo(...)

playVideo(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Play the currently cued or loaded video. Final player state will be PLAYING (1).

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

pauseVideo(...)

pauseVideo(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Pause the currently playing video. Final player state will be PAUSED (2), unless already ENDED (0).

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

seekTo(...)

seekTo(options: SeekToOptions) => Promise<{ result: { method: string; value: boolean; seconds: number; allowSeekAhead: boolean; }; }>

Seek to a specific time in the video. If player is paused, it remains paused. If playing, continues playing.

Param	Type	Description
`options`	`SeekToOptions`	- Player seek options

Returns: Promise<{ result: { method: string; value: boolean; seconds: number; allowSeekAhead: boolean; }; }>

loadVideoById(...)

loadVideoById(options: VideoByIdMethodOptions) => Promise<{ result: { method: string; value: boolean; options: IVideoOptionsById; }; }>

Load and play a video by its YouTube ID.

Param	Type	Description
`options`	`VideoByIdMethodOptions`	- Video loading options (ID, start time, quality, etc.)

Returns: Promise<{ result: { method: string; value: boolean; options: IVideoOptionsById; }; }>

cueVideoById(...)

cueVideoById(options: VideoByIdMethodOptions) => Promise<{ result: { method: string; value: boolean; options: IVideoOptionsById; }; }>

Cue a video by ID without playing it. Loads thumbnail and prepares player, but doesn't request video until playVideo() called.

Param	Type	Description
`options`	`VideoByIdMethodOptions`	- Video cuing options (ID, start time, quality, etc.)

Returns: Promise<{ result: { method: string; value: boolean; options: IVideoOptionsById; }; }>

loadVideoByUrl(...)

loadVideoByUrl(options: VideoByUrlMethodOptions) => Promise<{ result: { method: string; value: boolean; options: IVideoOptionsByUrl; }; }>

Load and play a video by its full URL.

Param	Type	Description
`options`	`VideoByUrlMethodOptions`	- Video loading options including media URL

Returns: Promise<{ result: { method: string; value: boolean; options: IVideoOptionsByUrl; }; }>

cueVideoByUrl(...)

cueVideoByUrl(options: VideoByUrlMethodOptions) => Promise<{ result: { method: string; value: boolean; options: IVideoOptionsByUrl; }; }>

Cue a video by URL without playing it.

Param	Type	Description
`options`	`VideoByUrlMethodOptions`	- Video cuing options including media URL

Returns: Promise<{ result: { method: string; value: boolean; options: IVideoOptionsByUrl; }; }>

cuePlaylist(...)

cuePlaylist(options: PlaylistMethodOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Cue a playlist without playing it. Loads playlist and prepares first video.

Param	Type
`options`	`PlaylistMethodOptions`

Returns: Promise<{ result: { method: string; value: boolean; }; }>

loadPlaylist(...)

loadPlaylist(options: PlaylistMethodOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Load and play a playlist.

Param	Type
`options`	`PlaylistMethodOptions`

Returns: Promise<{ result: { method: string; value: boolean; }; }>

nextVideo(...)

nextVideo(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Play the next video in the playlist.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

previousVideo(...)

previousVideo(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Play the previous video in the playlist.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

playVideoAt(...)

playVideoAt(options: PlayVideoAtOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Play a specific video in the playlist by index.

Param	Type	Description
`options`	`PlayVideoAtOptions`	- Player playlist navigation options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

mute(...)

mute(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Mute the player audio.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

unMute(...)

unMute(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Unmute the player audio.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

isMuted(...)

isMuted(options: PlayerIdOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Check if the player is currently muted.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

setVolume(...)

setVolume(options: SetVolumeOptions) => Promise<{ result: { method: string; value: number; }; }>

Set the player volume level.

Param	Type	Description
`options`	`SetVolumeOptions`	- Player volume options

Returns: Promise<{ result: { method: string; value: number; }; }>

getVolume(...)

getVolume(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the current player volume level. Returns volume even if player is muted.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

setSize(...)

setSize(options: SetSizeOptions) => Promise<{ result: { method: string; value: { width: number; height: number; }; }; }>

Set the player dimensions in pixels.

Param	Type	Description
`options`	`SetSizeOptions`	- Player size options

Returns: Promise<{ result: { method: string; value: { width: number; height: number; }; }; }>

getPlaybackRate(...)

getPlaybackRate(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the current playback rate.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

setPlaybackRate(...)

setPlaybackRate(options: SetPlaybackRateOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Set the playback speed.

Param	Type	Description
`options`	`SetPlaybackRateOptions`	- Playback rate options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

getAvailablePlaybackRates(...)

getAvailablePlaybackRates(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number[]; }; }>

Get list of available playback rates for current video.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number[]; }; }>

setLoop(...)

setLoop(options: SetLoopOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Enable or disable playlist looping. When enabled, playlist will restart from beginning after last video.

Param	Type	Description
`options`	`SetLoopOptions`	- Playlist loop options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

setShuffle(...)

setShuffle(options: SetShuffleOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Enable or disable playlist shuffle.

Param	Type	Description
`options`	`SetShuffleOptions`	- Playlist shuffle options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

getVideoLoadedFraction(...)

getVideoLoadedFraction(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the fraction of the video that has been buffered. More reliable than deprecated getVideoBytesLoaded/getVideoBytesTotal.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

getPlayerState(...)

getPlayerState(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the current state of the player.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

getAllPlayersEventsState()

getAllPlayersEventsState() => Promise<{ result: { method: string; value: Map<string, IPlayerState>; }; }>

Get event states for all active players. Useful for tracking multiple player instances.

Returns: Promise<{ result: { method: string; value: Map<string, IPlayerState>; }; }>

getCurrentTime(...)

getCurrentTime(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the current playback position in seconds.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

toggleFullScreen(...)

toggleFullScreen(options: ToggleFullScreenOptions) => Promise<{ result: { method: string; value: boolean | null | undefined; }; }>

Toggle fullscreen mode on or off.

Param	Type	Description
`options`	`ToggleFullScreenOptions`	- Fullscreen options

Returns: Promise<{ result: { method: string; value: boolean | null; }; }>

getPlaybackQuality(...)

getPlaybackQuality(options: PlayerIdOptions) => Promise<{ result: { method: string; value: IPlaybackQuality; }; }>

Get the current playback quality.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: IPlaybackQuality; }; }>

setPlaybackQuality(...)

setPlaybackQuality(options: SetPlaybackQualityOptions) => Promise<{ result: { method: string; value: boolean; }; }>

Set the suggested playback quality. Actual quality may differ based on network conditions.

Param	Type	Description
`options`	`SetPlaybackQualityOptions`	- Playback quality options

Returns: Promise<{ result: { method: string; value: boolean; }; }>

getAvailableQualityLevels(...)

getAvailableQualityLevels(options: PlayerIdOptions) => Promise<{ result: { method: string; value: IPlaybackQuality[]; }; }>

Get list of available quality levels for current video.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: IPlaybackQuality[]; }; }>

getDuration(...)

getDuration(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the duration of the current video in seconds.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

getVideoUrl(...)

getVideoUrl(options: PlayerIdOptions) => Promise<{ result: { method: string; value: string; }; }>

Get the YouTube.com URL for the current video.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: string; }; }>

getVideoEmbedCode(...)

getVideoEmbedCode(options: PlayerIdOptions) => Promise<{ result: { method: string; value: string; }; }>

Get the embed code for the current video. Returns HTML iframe embed code.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: string; }; }>

getPlaylist(...)

getPlaylist(options: PlayerIdOptions) => Promise<{ result: { method: string; value: string[]; }; }>

Get array of video IDs in the current playlist.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: string[]; }; }>

getPlaylistIndex(...)

getPlaylistIndex(options: PlayerIdOptions) => Promise<{ result: { method: string; value: number; }; }>

Get the index of the currently playing video in the playlist.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: number; }; }>

getIframe(...)

getIframe(options: PlayerIdOptions) => Promise<{ result: { method: string; value: HTMLIFrameElement; }; }>

Get the iframe DOM element for the player. Web platform only.

Param	Type	Description
`options`	`PlayerIdOptions`	- Player instance options

Returns: Promise<{ result: { method: string; value: any; }; }>

addEventListener(...)

addEventListener<TEvent extends PlayerEvent>(options: PlayerEventListenerOptions<TEvent>) => void

Add an event listener to the player. Web platform only.

Param	Type	Description
`options`	`PlayerEventListenerOptions<TEvent>`	- Event listener options

removeEventListener(...)

removeEventListener<TEvent extends PlayerEvent>(options: PlayerEventListenerOptions<TEvent>) => void

Remove an event listener from the player. Web platform only.

Param	Type	Description
`options`	`PlayerEventListenerOptions<TEvent>`	- Event listener options

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the plugin version number. Returns platform-specific version information.

Returns: Promise<{ version: string; }>

Interfaces

IPlayerOptions

Configuration options for initializing a YouTube player instance. All size and playback settings are configured through this interface.

Prop	Type	Description	Default
`playerId`	`string`	Unique identifier for the player instance. Used to reference this player in API calls.
`playerSize`	`IPlayerSize`	Dimensions of the player in pixels.
`videoId`	`string`	YouTube video ID to load.
`fullscreen`	`boolean`	Whether to start the video in fullscreen mode.	`false`
`playerVars`	`IPlayerVars`	YouTube player parameters to customize playback behavior. See: https://developers.google.com/youtube/player_parameters
`debug`	`boolean`	Enable debug logging for troubleshooting.	`false`
`privacyEnhanced`	`boolean`	Use privacy-enhanced mode (youtube-nocookie.com) for better GDPR compliance. When enabled, YouTube won't store information about visitors on your website unless they play the video. Note: Only applies to web platform. Native platforms use different APIs.	`false`
`cookies`	`string`	Cookies to be set for the YouTube player. This can help bypass the "sign in to confirm you're not a bot" message. Pass cookies as a semicolon-separated string (e.g., "name1=value1; name2=value2"). Platform Support: - Web: Sets cookies via document.cookie - iOS: Sets cookies in WKWebView's HTTPCookieStore - Android: Sets cookies via CookieManager (note: native YouTube Player API has separate session management)	`undefined`

IPlayerSize

Player dimensions in pixels.

Prop	Type	Description
`height`	`number`	Height in pixels
`width`	`number`	Width in pixels

IPlayerVars

YouTube player parameters for customizing player behavior and appearance.

Prop	Type	Description
`autoplay`	`number`	Whether to autoplay the video (0 = no, 1 = yes)
`cc_load_policy`	`number`	Force closed captions to show by default (1 = show)
`color`	`string`	Player controls color ('red' or 'white')
`controls`	`number`	Whether to show player controls (0 = hide, 1 = show, 2 = show on load)
`disablekb`	`number`	Disable keyboard controls (0 = enable, 1 = disable)
`enablejsapi`	`number`	Enable JavaScript API (1 = enable)
`end`	`number`	Time in seconds to stop playback
`fs`	`number`	Show fullscreen button (0 = hide, 1 = show)
`hl`	`string`	Player interface language (ISO 639-1 code)
`iv_load_policy`	`number`	Show video annotations (1 = show, 3 = hide)
`list`	`string`	Playlist or content ID to load
`listType`	`string`	Type of content in 'list' parameter
`loop`	`number`	Loop the video (0 = no, 1 = yes, requires playlist)
`modestbranding`	`number`	Hide YouTube logo (0 = show, 1 = hide)
`origin`	`string`	Domain origin for extra security
`playlist`	`string`	Comma-separated list of video IDs to play
`playsinline`	`number`	Play inline on iOS (0 = fullscreen, 1 = inline)
`rel`	`number`	Show related videos (0 = from same channel, 1 = any)
`showinfo`	`number`	Show video information (deprecated, always hidden)
`start`	`number`	Time in seconds to start playback

PlayerIdOptions

Prop	Type
`playerId`	`string`

SeekToOptions

Prop	Type
`playerId`	`string`
`seconds`	`number`
`allowSeekAhead`	`boolean`

IVideoOptionsById

Options for loading a video by its YouTube ID.

Prop	Type	Description
`videoId`	`string`	YouTube video ID

VideoByIdMethodOptions

Prop	Type
`playerId`	`string`
`options`	`IVideoOptionsById`

IVideoOptionsByUrl

Options for loading a video by its media URL.

Prop	Type	Description
`mediaContentUrl`	`string`	Full YouTube video URL

VideoByUrlMethodOptions

Prop	Type
`playerId`	`string`
`options`	`IVideoOptionsByUrl`

PlaylistMethodOptions

Prop	Type
`playerId`	`string`
`playlistOptions`	`IPlaylistOptions`

IPlaylistOptions

Options for loading and playing YouTube playlists.

Prop	Type	Description
`listType`	`'playlist' \| 'search' \| 'user_uploads'`	Type of playlist to load
`list`	`string`	Playlist ID or search query (depending on listType)
`playlist`	`string[]`	Array of video IDs to play as a playlist
`index`	`number`	Index of the video to start with (0-based)
`startSeconds`	`number`	Time in seconds to start the first video
`suggestedQuality`	`string`	Suggested playback quality

PlayVideoAtOptions

Prop	Type
`playerId`	`string`
`index`	`number`

SetVolumeOptions

Prop	Type
`playerId`	`string`
`volume`	`number`

SetSizeOptions

Prop	Type
`playerId`	`string`
`width`	`number`
`height`	`number`

SetPlaybackRateOptions

Prop	Type
`playerId`	`string`
`suggestedRate`	`number`

SetLoopOptions

Prop	Type
`playerId`	`string`
`loopPlaylists`	`boolean`

SetShuffleOptions

Prop	Type
`playerId`	`string`
`shufflePlaylist`	`boolean`

Map

Prop	Type
`size`	`number`

Method	Signature
clear	() => void
delete	(key: K) => boolean
forEach	(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any) => void
get	(key: K) => V \| undefined
has	(key: K) => boolean
set	(key: K, value: V) => this

IPlayerState

Internal state tracking for player events. Used to monitor which events have been triggered.

Prop	Type	Description
`events`	`{ onReady?: unknown; onStateChange?: unknown; onPlaybackQualityChange?: unknown; onError?: unknown; }`	Event handlers and their states

ToggleFullScreenOptions

Prop	Type
`playerId`	`string`
`isFullScreen`	`boolean \| null`

SetPlaybackQualityOptions

Prop	Type
`playerId`	`string`
`suggestedQuality`	`IPlaybackQuality`

PlayerEvent

Base interface for events triggered by a player.

Prop	Type	Description
`target`	`Element`	Video player corresponding to the event.

PlayerEventListenerOptions

Prop	Type
`playerId`	`string`
`eventName`	`keyof Events`
`listener`	`(event: TEvent) => void`

Events

Handlers for events fired by the player.

Prop	Type	Description
`onReady`	`PlayerEventHandler<PlayerEvent>`	Event fired when a player has finished loading and is ready to begin receiving API calls.
`onStateChange`	`PlayerEventHandler<OnStateChangeEvent>`	Event fired when the player's state changes.
`onPlaybackQualityChange`	`PlayerEventHandler<OnPlaybackQualityChangeEvent>`	Event fired when the playback quality of the player changes.
`onPlaybackRateChange`	`PlayerEventHandler<OnPlaybackRateChangeEvent>`	Event fired when the playback rate of the player changes.
`onError`	`PlayerEventHandler<OnErrorEvent>`	Event fired when an error in the player occurs
`onApiChange`	`PlayerEventHandler<PlayerEvent>`	Event fired to indicate that the player has loaded, or unloaded, a module with exposed API methods. This currently only occurs for closed captioning.

PlayerEventHandler

Handles a player event.

OnStateChangeEvent

Event for player state change.

Prop	Type	Description
`data`	`PlayerState`	New player state.

OnPlaybackQualityChangeEvent

Event for playback quality change.

Prop	Type	Description
`data`	`string`	New playback quality.

OnPlaybackRateChangeEvent

Event for playback rate change.

Prop	Type	Description
`data`	`number`	New playback rate.

OnErrorEvent

Event for a player error.

Prop	Type	Description
`data`	`PlayerError`	Which type of error occurred.

Enums

IPlaybackQuality

Members	Value	Description
`SMALL`	`'small'`	Small quality (240p)
`MEDIUM`	`'medium'`	Medium quality (360p)
`LARGE`	`'large'`	Large quality (480p)
`HD720`	`'hd720'`	High definition 720p
`HD1080`	`'hd1080'`	High definition 1080p
`HIGH_RES`	`'highres'`	Highest resolution available (1440p+)
`DEFAULT`	`'default'`	Default quality selected by YouTube

PlayerState

Members	Value	Description
`UNSTARTED`	`-1`	Video has not started (-1)
`ENDED`	`0`	Video has ended (0)
`PLAYING`	`1`	Video is currently playing (1)
`PAUSED`	`2`	Video is paused (2)
`BUFFERING`	`3`	Video is buffering (3)
`CUED`	`5`	Video is cued and ready to play (5)

PlayerError

Members	Value	Description
`InvalidParam`	`2`	The request contained an invalid parameter value.
`Html5Error`	`5`	The requested content cannot be played in an HTML5 player.
`VideoNotFound`	`100`	The video requested was not found.
`EmbeddingNotAllowed`	`101`	The owner of the requested video does not allow it to be played in embedded players.
`EmbeddingNotAllowed2`	`150`	This error is the same as 101. It's just a 101 error in disguise!

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌