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.