YouTube Player Capacitor plugin

Using @capgo/capacitor-youtube-player

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

Install

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

What This Plugin Exposes

• initialize - Initialize a new YouTube player instance.
• destroy - Destroy a player instance and free resources.
• stopVideo - Stop video playback and cancel loading. Use this sparingly - pauseVideo() is usually preferred.
• playVideo - Play the currently cued or loaded video. Final player state will be PLAYING (1).

Main WebView Referer Patch

Enable patchRefererHeader when YouTube content works in the plugin but fails from Capacitor's main WebView because YouTube expects a browser-like Referer header.

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

The patch only applies to youtube.com, youtube-nocookie.com, and youtu.be requests. Existing request-level Referer headers are preserved, and refererHeader defaults to https://www.youtube.com when omitted.

Example Usage

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';

const result = await YoutubePlayer.destroy({ playerId: 'player-id-123' });
console.log(result);

stopVideo

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

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

const result = await YoutubePlayer.stopVideo({ playerId: 'player-id-123' });
console.log(result);

playVideo

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

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

const result = await YoutubePlayer.playVideo({ playerId: 'player-id-123' });
console.log(result);

Full Reference

• GitHub: https://github.com/Cap-go/capacitor-youtube-player/
• Docs: /docs/plugins/youtube-player/

Keep going from Using @capgo/capacitor-youtube-player

If you are using Using @capgo/capacitor-youtube-player to plan native media and interface behavior, connect it with @capgo/capacitor-youtube-player for the implementation detail in @capgo/capacitor-youtube-player, Getting Started for the implementation detail in Getting Started, Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities for the implementation detail in @capgo/capacitor-live-activities, and Using @capgo/capacitor-video-player for the native capability in Using @capgo/capacitor-video-player.