Getting Started

Install

bun add @capgo/capacitor-youtube-player
bunx cap sync

Import

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

API Overview

initialize

Initialize a new YouTube player instance.

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

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

destroy

Destroy a player instance and free resources.

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

await YoutubePlayer.destroy({} as PlayerIdOptions);

stopVideo

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

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

await YoutubePlayer.stopVideo({} as PlayerIdOptions);

playVideo

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

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

await YoutubePlayer.playVideo({} as PlayerIdOptions);

pauseVideo

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

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

await YoutubePlayer.pauseVideo({} as PlayerIdOptions);

seekTo

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

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

await YoutubePlayer.seekTo({} as SeekToOptions);

loadVideoById

Load and play a video by its YouTube ID.

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

await YoutubePlayer.loadVideoById({} as VideoByIdMethodOptions);

cueVideoById

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

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

await YoutubePlayer.cueVideoById({} as VideoByIdMethodOptions);

loadVideoByUrl

Load and play a video by its full URL.

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

await YoutubePlayer.loadVideoByUrl({} as VideoByUrlMethodOptions);

cueVideoByUrl

Cue a video by URL without playing it.

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

await YoutubePlayer.cueVideoByUrl({} as VideoByUrlMethodOptions);

cuePlaylist

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

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

await YoutubePlayer.cuePlaylist({} as PlaylistMethodOptions);

loadPlaylist

Load and play a playlist.

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

await YoutubePlayer.loadPlaylist({} as PlaylistMethodOptions);

nextVideo

Play the next video in the playlist.

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

await YoutubePlayer.nextVideo({} as PlayerIdOptions);

previousVideo

Play the previous video in the playlist.

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

await YoutubePlayer.previousVideo({} as PlayerIdOptions);

playVideoAt

Play a specific video in the playlist by index.

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

await YoutubePlayer.playVideoAt({} as PlayVideoAtOptions);

mute

Mute the player audio.

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

await YoutubePlayer.mute({} as PlayerIdOptions);

unMute

Unmute the player audio.

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

await YoutubePlayer.unMute({} as PlayerIdOptions);

isMuted

Check if the player is currently muted.

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

await YoutubePlayer.isMuted({} as PlayerIdOptions);

setVolume

Set the player volume level.

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

await YoutubePlayer.setVolume({} as SetVolumeOptions);

getVolume

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

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

await YoutubePlayer.getVolume({} as PlayerIdOptions);

setSize

Set the player dimensions in pixels.

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

await YoutubePlayer.setSize({} as SetSizeOptions);

getPlaybackRate

Get the current playback rate.

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

await YoutubePlayer.getPlaybackRate({} as PlayerIdOptions);

setPlaybackRate

Set the playback speed.

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

await YoutubePlayer.setPlaybackRate({} as SetPlaybackRateOptions);

getAvailablePlaybackRates

Get list of available playback rates for current video.

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

await YoutubePlayer.getAvailablePlaybackRates({} as PlayerIdOptions);

setLoop

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

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

await YoutubePlayer.setLoop({} as SetLoopOptions);

setShuffle

Enable or disable playlist shuffle.

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

await YoutubePlayer.setShuffle({} as SetShuffleOptions);

getVideoLoadedFraction

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

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

await YoutubePlayer.getVideoLoadedFraction({} as PlayerIdOptions);

getPlayerState

Get the current state of the player.

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

await YoutubePlayer.getPlayerState({} as PlayerIdOptions);

getAllPlayersEventsState

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

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

await YoutubePlayer.getAllPlayersEventsState();

getCurrentTime

Get the current playback position in seconds.

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

await YoutubePlayer.getCurrentTime({} as PlayerIdOptions);

toggleFullScreen

Toggle fullscreen mode on or off.

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

await YoutubePlayer.toggleFullScreen({} as ToggleFullScreenOptions);

getPlaybackQuality

Get the current playback quality.

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

await YoutubePlayer.getPlaybackQuality({} as PlayerIdOptions);

setPlaybackQuality

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

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

await YoutubePlayer.setPlaybackQuality({} as SetPlaybackQualityOptions);

getAvailableQualityLevels

Get list of available quality levels for current video.

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

await YoutubePlayer.getAvailableQualityLevels({} as PlayerIdOptions);

getDuration

Get the duration of the current video in seconds.

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

await YoutubePlayer.getDuration({} as PlayerIdOptions);

getVideoUrl

Get the YouTube.com URL for the current video.

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

await YoutubePlayer.getVideoUrl({} as PlayerIdOptions);

getVideoEmbedCode

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

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

await YoutubePlayer.getVideoEmbedCode({} as PlayerIdOptions);

getPlaylist

Get array of video IDs in the current playlist.

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

await YoutubePlayer.getPlaylist({} as PlayerIdOptions);

getPlaylistIndex

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

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

await YoutubePlayer.getPlaylistIndex({} as PlayerIdOptions);

getIframe

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

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

await YoutubePlayer.getIframe({} as PlayerIdOptions);

addEventListener

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

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

YoutubePlayer.addEventListener({
  playerId: 'my-player',
  eventName: 'onStateChange',
  listener: (event) => {
  console.log('Player state:', event.data);
  },
});

removeEventListener

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

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

await YoutubePlayer.removeEventListener({} as PlayerEventListenerOptions<TEvent>);

Type Reference

PlayerIdOptions

export interface PlayerIdOptions {
  playerId: string;
}

SeekToOptions

export interface SeekToOptions extends PlayerIdOptions {
  playerId: string;
  seconds: number;
  allowSeekAhead: boolean;
}

VideoByIdMethodOptions

export interface VideoByIdMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsById;
}

VideoByUrlMethodOptions

export interface VideoByUrlMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsByUrl;
}

PlaylistMethodOptions

export interface PlaylistMethodOptions extends PlayerIdOptions {
  playerId: string;
  playlistOptions: IPlaylistOptions;
}

PlayVideoAtOptions

export interface PlayVideoAtOptions extends PlayerIdOptions {
  playerId: string;
  index: number;
}

SetVolumeOptions

export interface SetVolumeOptions extends PlayerIdOptions {
  playerId: string;
  volume: number;
}

SetSizeOptions

export interface SetSizeOptions extends PlayerIdOptions {
  playerId: string;
  width: number;
  height: number;
}

SetPlaybackRateOptions

export interface SetPlaybackRateOptions extends PlayerIdOptions {
  playerId: string;
  suggestedRate: number;
}

SetLoopOptions

export interface SetLoopOptions extends PlayerIdOptions {
  playerId: string;
  loopPlaylists: boolean;
}

SetShuffleOptions

export interface SetShuffleOptions extends PlayerIdOptions {
  playerId: string;
  shufflePlaylist: boolean;
}

ToggleFullScreenOptions

export interface ToggleFullScreenOptions extends PlayerIdOptions {
  playerId: string;
  isFullScreen: boolean | null | undefined;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.

Keep going from Getting Started

If you are using Getting Started to plan dashboard and API operations, connect it with Using @capgo/capacitor-youtube-player for the native capability in Using @capgo/capacitor-youtube-player, API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, and Devices for the implementation detail in Devices.