Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge deinem KI-Tool die Capgo Skills mit folgendem Befehl hinzu:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze anschließend diesen Prompt:

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

Wenn du ein manuelles Setup bevorziehst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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

Importieren

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

Quickstart

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

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

Häufige Fehlerquellen

• Listener: Handles entfernen, wenn Screens unmounten.
• Einmal initialisieren: Setup beim App-Bootstrap ausführen.
• Single Source of Truth: vertraue src/definitions.ts im GitHub Repo.

YouTube Referer-Blocking im Main WebView beheben

Falls YouTube innerhalb des Plugins funktioniert, aber fehlschlägt, wenn die App YouTube-Seiten, Embeds oder APIs über das Haupt-WebView von Capacitor lädt, aktiviere patchRefererHeader in deiner Capacitor Konfiguration.

Bei aktivierter Option patcht das Plugin Capacitor während des Sync/Updates, sodass abgefangene YouTube-Requests einen gültigen Referer header.

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

• Nur youtube.com, youtube-nocookie.com, und youtu.be Requests sind betroffen.
• Requests, die bereits einen Referer header behalten ihren ursprünglichen Wert.
• refererHeader ist optional und standardmäßig auf https://www.youtube.com.
• Unterstützt auf Capacitor 8.x für installierte iOS- und Android-Plattformen.

API Übersicht

initialize

Initialisiert eine neue YouTube-Player-Instanz.

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

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

destroy

Zerstört eine Player-Instanz und gibt Ressourcen frei.

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

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

stopVideo

Stoppt die Videowiedergabe und bricht das Laden ab. Nutze dies sparsam – pauseVideo() ist meist besser.

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

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

playVideo

Das aktuell in der Warteschlange befindliche oder geladene Video abspielen. Der finale Player-Status ist PLAYING (1).

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

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

pauseVideo

Das aktuell laufende Video pausieren. Der finale Player-Status ist PAUSED (2), sofern nicht bereits ENDED (0).

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

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

seekTo

Zu einer bestimmten Zeit im Video springen. Wenn der Player pausiert ist, bleibt er pausiert. Wenn er läuft, spielt er weiter.

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

const result = await YoutubePlayer.seekTo({
  playerId: 'player-id-123',
  seconds: 10,
  allowSeekAhead: true,
});
console.log(result);

loadVideoById

Ein Video anhand seiner YouTube-ID laden und abspielen.

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

const result = await YoutubePlayer.loadVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

cueVideoById

Video per ID laden, ohne es abzuspielen.\nLädt Thumbnail und bereitet den Player vor, fordert das Video aber erst bei einem Aufruf von playVideo() an.

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

const result = await YoutubePlayer.cueVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

loadVideoByUrl

Ein Video über die vollständige URL laden und abspielen.

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

const result = await YoutubePlayer.loadVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

cueVideoByUrl

Ein Video per URL vorbereiten, ohne es abzuspielen.

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

const result = await YoutubePlayer.cueVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

cuePlaylist

Eine Playlist vorbereiten, ohne sie abzuspielen. Lädt die Playlist und bereitet das erste Video vor.

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

const result = await YoutubePlayer.cuePlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

loadPlaylist

Eine Playlist laden und abspielen.

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

const result = await YoutubePlayer.loadPlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

nextVideo

Das nächste Video der Playlist abspielen.

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

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

previousVideo

Das vorherige Video der Playlist abspielen.

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

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

playVideoAt

Ein bestimmtes Video per Index abspielen.

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

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

mute

Stummschalten des Player-Audios.

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

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

unMute

Ton des Players wieder einschalten.

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

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

isMuted

Prüfen, ob der Player aktuell stummgeschaltet ist.

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

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

setVolume

Die Lautstärke des Players festlegen.

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

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

getVolume

Die aktuelle Lautstärke des Players abrufen. Gibt die Lautstärke auch zurück, wenn der Player stummgeschaltet ist.

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

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

setSize

Die Abmessungen des Players in Pixeln festlegen.

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

const result = await YoutubePlayer.setSize({
  playerId: 'player-id-123',
  width: 1080,
  height: 1920,
});
console.log(result);

getPlaybackRate

Die aktuelle Wiedergabegeschwindigkeit abrufen.

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

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

setPlaybackRate

Die Wiedergabegeschwindigkeit festlegen.

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

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

getAvailablePlaybackRates

Liste der verfügbaren Wiedergabegeschwindigkeiten für das aktuelle Video abrufen.

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

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

setLoop

Playlist-Loop aktivieren oder deaktivieren. Wenn aktiviert, startet die Playlist nach dem letzten Video von vorne.

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

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

setShuffle

Playlist-Shuffle aktivieren oder deaktivieren.

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

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

getVideoLoadedFraction

Den Anteil des Videos abrufen, der gepuffert wurde. Zuverlässiger als die veralteten Methoden getVideoBytesLoaded/getVideoBytesTotal.

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

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

getPlayerState

Den aktuellen Status des Players abrufen.

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

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

getAllPlayersEventsState

Event-Status aller aktiven Player abrufen. Ideal zum Tracking mehrerer Player-Instanzen.

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

const result = await YoutubePlayer.getAllPlayersEventsState();
console.log(result);

getCurrentTime

Die aktuelle Wiedergabeposition in Sekunden abrufen.

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

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

toggleFullScreen

Den Vollbildmodus ein- oder ausschalten.

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

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

getPlaybackQuality

Die aktuelle Wiedergabequalität abrufen.

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

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

setPlaybackQuality

Die gewünschte Wiedergabequalität festlegen. Die tatsächliche Qualität kann je nach Netzwerkbedingungen variieren.

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

const result = await YoutubePlayer.setPlaybackQuality({
  playerId: 'player-id-123',
  suggestedQuality: IPlaybackQuality.SMALL,
});
console.log(result);

getAvailableQualityLevels

Liste der verfügbaren Qualitätsstufen für das aktuelle Video abrufen.

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

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

getDuration

Die Dauer des aktuellen Videos in Sekunden abrufen.

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

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

getVideoUrl

Die YouTube.com-URL des aktuellen Videos abrufen.

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

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

getVideoEmbedCode

Den Embed code für das aktuelle Video abrufen. Gibt den HTML-iframe-Embed code zurück.

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

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

getPlaylist

Ein Array der Video-IDs in der aktuellen Playlist abrufen.

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

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

getPlaylistIndex

Den Index des aktuell abgespielten Videos in der Playlist abrufen.

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

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

getIframe

Hol dir das iframe-DOM-Element für den Player. Nur für Web-Plattformen.

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

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

addEventListener

Einen Event Listener zum Player hinzufügen. Nur Web-Plattform.

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

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

removeEventListener

Einen Event Listener vom Player entfernen. Nur Web-Plattform.

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

await YoutubePlayer.removeEventListener({
  playerId: 'player-id-123',
  eventName: 'onReady',
  listener: (event) => {
    console.log(event);
  },
});

Typ-Referenz

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

Diese Seite wird aus dem Plugin- src/definitions.ts. Führe den Sync erneut aus, wenn sich der öffentliche API upstream ändert.

Weiter mit Getting Started

Wenn Sie ... verwenden Erste Schritte Um Dashboard- und API-Operationen zu planen, verbinde es mit Verwendung von @capgo/capacitor-youtube-player für die native Funktion in „Verwendung von @capgo/capacitor-youtube-player“, API Übersicht für Details zur Implementierung in der Übersicht zu API, Einführung für das Implementierungsdetail in der Einleitung, API Keys für die Implementierungsdetails in den API Keys und Geräte für die Implementierungsdetails bei Devices.