@capgo/capacitor-youtube-player 8.2.0 → 8.2.1

package/dist/esm/definitions.d.ts

@@ -1,4 +1,62 @@
 import type { IPlayerState, IPlayerOptions, IPlaylistOptions, IVideoOptionsById, IVideoOptionsByUrl, IPlaybackQuality, PlayerEvent, Events } from './web/models/models';
+export interface PlayerIdOptions {
+    playerId: string;
+}
+export interface SeekToOptions extends PlayerIdOptions {
+    playerId: string;
+    seconds: number;
+    allowSeekAhead: boolean;
+}
+export interface VideoByIdMethodOptions extends PlayerIdOptions {
+    playerId: string;
+    options: IVideoOptionsById;
+}
+export interface VideoByUrlMethodOptions extends PlayerIdOptions {
+    playerId: string;
+    options: IVideoOptionsByUrl;
+}
+export interface PlaylistMethodOptions extends PlayerIdOptions {
+    playerId: string;
+    playlistOptions: IPlaylistOptions;
+}
+export interface PlayVideoAtOptions extends PlayerIdOptions {
+    playerId: string;
+    index: number;
+}
+export interface SetVolumeOptions extends PlayerIdOptions {
+    playerId: string;
+    volume: number;
+}
+export interface SetSizeOptions extends PlayerIdOptions {
+    playerId: string;
+    width: number;
+    height: number;
+}
+export interface SetPlaybackRateOptions extends PlayerIdOptions {
+    playerId: string;
+    suggestedRate: number;
+}
+export interface SetLoopOptions extends PlayerIdOptions {
+    playerId: string;
+    loopPlaylists: boolean;
+}
+export interface SetShuffleOptions extends PlayerIdOptions {
+    playerId: string;
+    shufflePlaylist: boolean;
+}
+export interface ToggleFullScreenOptions extends PlayerIdOptions {
+    playerId: string;
+    isFullScreen: boolean | null | undefined;
+}
+export interface SetPlaybackQualityOptions extends PlayerIdOptions {
+    playerId: string;
+    suggestedQuality: IPlaybackQuality;
+}
+export interface PlayerEventListenerOptions<TEvent extends PlayerEvent = PlayerEvent> extends PlayerIdOptions {
+    playerId: string;
+    eventName: keyof Events;
+    listener: (event: TEvent) => void;
+}
 /**
  * YouTube Player Plugin interface for Capacitor.
  * Provides methods to control YouTube video playback in your app.
@@ -36,10 +94,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Destroy a player instance and free resources.
      *
-     * @param playerId - ID of the player to destroy
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    destroy(playerId: string): Promise<{
+    destroy(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -49,10 +107,10 @@ export interface YoutubePlayerPlugin {
      * Stop video playback and cancel loading.
      * Use this sparingly - pauseVideo() is usually preferred.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    stopVideo(playerId: string): Promise<{
+    stopVideo(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -62,10 +120,10 @@ export interface YoutubePlayerPlugin {
      * Play the currently cued or loaded video.
      * Final player state will be PLAYING (1).
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    playVideo(playerId: string): Promise<{
+    playVideo(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -75,10 +133,10 @@ export interface YoutubePlayerPlugin {
      * Pause the currently playing video.
      * Final player state will be PAUSED (2), unless already ENDED (0).
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    pauseVideo(playerId: string): Promise<{
+    pauseVideo(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -88,12 +146,10 @@ export interface YoutubePlayerPlugin {
      * Seek to a specific time in the video.
      * If player is paused, it remains paused. If playing, continues playing.
      *
-     * @param playerId - ID of the player
-     * @param seconds - Time to seek to (in seconds)
-     * @param allowSeekAhead - Whether to make a new request to server if not buffered
+     * @param options - Player seek options
      * @returns Promise with operation result including seek parameters
      */
-    seekTo(playerId: string, seconds: number, allowSeekAhead: boolean): Promise<{
+    seekTo(options: SeekToOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -104,11 +160,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Load and play a video by its YouTube ID.
      *
-     * @param playerId - ID of the player
      * @param options - Video loading options (ID, start time, quality, etc.)
      * @returns Promise with operation result
      */
-    loadVideoById(playerId: string, options: IVideoOptionsById): Promise<{
+    loadVideoById(options: VideoByIdMethodOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -119,11 +174,10 @@ export interface YoutubePlayerPlugin {
      * Cue a video by ID without playing it.
      * Loads thumbnail and prepares player, but doesn't request video until playVideo() called.
      *
-     * @param playerId - ID of the player
      * @param options - Video cuing options (ID, start time, quality, etc.)
      * @returns Promise with operation result
      */
-    cueVideoById(playerId: string, options: IVideoOptionsById): Promise<{
+    cueVideoById(options: VideoByIdMethodOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -133,11 +187,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Load and play a video by its full URL.
      *
-     * @param playerId - ID of the player
      * @param options - Video loading options including media URL
      * @returns Promise with operation result
      */
-    loadVideoByUrl(playerId: string, options: IVideoOptionsByUrl): Promise<{
+    loadVideoByUrl(options: VideoByUrlMethodOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -147,11 +200,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Cue a video by URL without playing it.
      *
-     * @param playerId - ID of the player
      * @param options - Video cuing options including media URL
      * @returns Promise with operation result
      */
-    cueVideoByUrl(playerId: string, options: IVideoOptionsByUrl): Promise<{
+    cueVideoByUrl(options: VideoByUrlMethodOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -162,11 +214,10 @@ export interface YoutubePlayerPlugin {
      * Cue a playlist without playing it.
      * Loads playlist and prepares first video.
      *
-     * @param playerId - ID of the player
      * @param playlistOptions - Playlist configuration (type, ID, index, etc.)
      * @returns Promise with operation result
      */
-    cuePlaylist(playerId: string, playlistOptions: IPlaylistOptions): Promise<{
+    cuePlaylist(options: PlaylistMethodOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -175,11 +226,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Load and play a playlist.
      *
-     * @param playerId - ID of the player
      * @param playlistOptions - Playlist configuration (type, ID, index, etc.)
      * @returns Promise with operation result
      */
-    loadPlaylist(playerId: string, playlistOptions: IPlaylistOptions): Promise<{
+    loadPlaylist(options: PlaylistMethodOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -188,10 +238,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Play the next video in the playlist.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    nextVideo(playerId: string): Promise<{
+    nextVideo(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -200,10 +250,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Play the previous video in the playlist.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    previousVideo(playerId: string): Promise<{
+    previousVideo(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -212,11 +262,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Play a specific video in the playlist by index.
      *
-     * @param playerId - ID of the player
-     * @param index - Zero-based index of the video to play
+     * @param options - Player playlist navigation options
      * @returns Promise with operation result
      */
-    playVideoAt(playerId: string, index: number): Promise<{
+    playVideoAt(options: PlayVideoAtOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -225,10 +274,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Mute the player audio.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    mute(playerId: string): Promise<{
+    mute(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -237,10 +286,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Unmute the player audio.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with operation result
      */
-    unMute(playerId: string): Promise<{
+    unMute(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -249,10 +298,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Check if the player is currently muted.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with mute status (true = muted, false = not muted)
      */
-    isMuted(playerId: string): Promise<{
+    isMuted(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -261,11 +310,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Set the player volume level.
      *
-     * @param playerId - ID of the player
-     * @param volume - Volume level from 0 (silent) to 100 (max)
+     * @param options - Player volume options
      * @returns Promise with the volume that was set
      */
-    setVolume(playerId: string, volume: number): Promise<{
+    setVolume(options: SetVolumeOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -275,10 +323,10 @@ export interface YoutubePlayerPlugin {
      * Get the current player volume level.
      * Returns volume even if player is muted.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with current volume (0-100)
      */
-    getVolume(playerId: string): Promise<{
+    getVolume(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -287,12 +335,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Set the player dimensions in pixels.
      *
-     * @param playerId - ID of the player
-     * @param width - Width in pixels
-     * @param height - Height in pixels
+     * @param options - Player size options
      * @returns Promise with the dimensions that were set
      */
-    setSize(playerId: string, width: number, height: number): Promise<{
+    setSize(options: SetSizeOptions): Promise<{
         result: {
             method: string;
             value: {
@@ -304,10 +350,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the current playback rate.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with playback rate (e.g., 0.5, 1, 1.5, 2)
      */
-    getPlaybackRate(playerId: string): Promise<{
+    getPlaybackRate(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -316,11 +362,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Set the playback speed.
      *
-     * @param playerId - ID of the player
-     * @param suggestedRate - Desired playback rate (0.25 to 2.0)
+     * @param options - Playback rate options
      * @returns Promise with operation result
      */
-    setPlaybackRate(playerId: string, suggestedRate: number): Promise<{
+    setPlaybackRate(options: SetPlaybackRateOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -329,10 +374,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get list of available playback rates for current video.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with array of available rates
      */
-    getAvailablePlaybackRates(playerId: string): Promise<{
+    getAvailablePlaybackRates(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number[];
@@ -342,11 +387,10 @@ export interface YoutubePlayerPlugin {
      * Enable or disable playlist looping.
      * When enabled, playlist will restart from beginning after last video.
      *
-     * @param playerId - ID of the player
-     * @param loopPlaylists - true to loop, false to stop after last video
+     * @param options - Playlist loop options
      * @returns Promise with operation result
      */
-    setLoop(playerId: string, loopPlaylists: boolean): Promise<{
+    setLoop(options: SetLoopOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -355,11 +399,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Enable or disable playlist shuffle.
      *
-     * @param playerId - ID of the player
-     * @param shufflePlaylist - true to shuffle, false for sequential
+     * @param options - Playlist shuffle options
      * @returns Promise with operation result
      */
-    setShuffle(playerId: string, shufflePlaylist: boolean): Promise<{
+    setShuffle(options: SetShuffleOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -369,10 +412,10 @@ export interface YoutubePlayerPlugin {
      * Get the fraction of the video that has been buffered.
      * More reliable than deprecated getVideoBytesLoaded/getVideoBytesTotal.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with fraction between 0 and 1
      */
-    getVideoLoadedFraction(playerId: string): Promise<{
+    getVideoLoadedFraction(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -381,10 +424,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the current state of the player.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with state: -1 (unstarted), 0 (ended), 1 (playing), 2 (paused), 3 (buffering), 5 (cued)
      */
-    getPlayerState(playerId: string): Promise<{
+    getPlayerState(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -405,10 +448,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the current playback position in seconds.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with current time in seconds
      */
-    getCurrentTime(playerId: string): Promise<{
+    getCurrentTime(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -417,11 +460,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Toggle fullscreen mode on or off.
      *
-     * @param playerId - ID of the player
-     * @param isFullScreen - true for fullscreen, false for normal, null/undefined to toggle
+     * @param options - Fullscreen options
      * @returns Promise with the fullscreen state that was set
      */
-    toggleFullScreen(playerId: string, isFullScreen: boolean | null | undefined): Promise<{
+    toggleFullScreen(options: ToggleFullScreenOptions): Promise<{
         result: {
             method: string;
             value: boolean | null | undefined;
@@ -430,10 +472,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the current playback quality.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with quality level (small, medium, large, hd720, hd1080, highres, default)
      */
-    getPlaybackQuality(playerId: string): Promise<{
+    getPlaybackQuality(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: IPlaybackQuality;
@@ -443,11 +485,10 @@ export interface YoutubePlayerPlugin {
      * Set the suggested playback quality.
      * Actual quality may differ based on network conditions.
      *
-     * @param playerId - ID of the player
-     * @param suggestedQuality - Desired quality level
+     * @param options - Playback quality options
      * @returns Promise with operation result
      */
-    setPlaybackQuality(playerId: string, suggestedQuality: IPlaybackQuality): Promise<{
+    setPlaybackQuality(options: SetPlaybackQualityOptions): Promise<{
         result: {
             method: string;
             value: boolean;
@@ -456,10 +497,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get list of available quality levels for current video.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with array of available quality levels
      */
-    getAvailableQualityLevels(playerId: string): Promise<{
+    getAvailableQualityLevels(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: IPlaybackQuality[];
@@ -468,10 +509,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the duration of the current video in seconds.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with duration in seconds
      */
-    getDuration(playerId: string): Promise<{
+    getDuration(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -480,10 +521,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the YouTube.com URL for the current video.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with video URL
      */
-    getVideoUrl(playerId: string): Promise<{
+    getVideoUrl(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: string;
@@ -493,10 +534,10 @@ export interface YoutubePlayerPlugin {
      * Get the embed code for the current video.
      * Returns HTML iframe embed code.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with iframe embed code
      */
-    getVideoEmbedCode(playerId: string): Promise<{
+    getVideoEmbedCode(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: string;
@@ -505,10 +546,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get array of video IDs in the current playlist.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with array of video IDs
      */
-    getPlaylist(playerId: string): Promise<{
+    getPlaylist(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: string[];
@@ -517,10 +558,10 @@ export interface YoutubePlayerPlugin {
     /**
      * Get the index of the currently playing video in the playlist.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with zero-based index
      */
-    getPlaylistIndex(playerId: string): Promise<{
+    getPlaylistIndex(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: number;
@@ -530,10 +571,10 @@ export interface YoutubePlayerPlugin {
      * Get the iframe DOM element for the player.
      * Web platform only.
      *
-     * @param playerId - ID of the player
+     * @param options - Player instance options
      * @returns Promise with iframe element
      */
-    getIframe(playerId: string): Promise<{
+    getIframe(options: PlayerIdOptions): Promise<{
         result: {
             method: string;
             value: HTMLIFrameElement;
@@ -541,26 +582,28 @@ export interface YoutubePlayerPlugin {
     }>;
     /**
      * Add an event listener to the player.
+     * Web platform only.
      *
-     * @param playerId - ID of the player
-     * @param eventName - Name of the event (onReady, onStateChange, onError, etc.)
-     * @param listener - Callback function to handle the event
+     * @param options - Event listener options
      * @example
      * ```typescript
-     * YoutubePlayer.addEventListener('my-player', 'onStateChange', (event) => {
+     * YoutubePlayer.addEventListener({
+     *   playerId: 'my-player',
+     *   eventName: 'onStateChange',
+     *   listener: (event) => {
      *   console.log('Player state:', event.data);
+     *   },
      * });
      * ```
      */
-    addEventListener<TEvent extends PlayerEvent>(playerId: string, eventName: keyof Events, listener: (event: TEvent) => void): void;
+    addEventListener<TEvent extends PlayerEvent>(options: PlayerEventListenerOptions<TEvent>): void;
     /**
      * Remove an event listener from the player.
+     * Web platform only.
      *
-     * @param playerId - ID of the player
-     * @param eventName - Name of the event to remove listener from
-     * @param listener - The callback function to remove
+     * @param options - Event listener options
      */
-    removeEventListener<TEvent extends PlayerEvent>(playerId: string, eventName: keyof Events, listener: (event: TEvent) => void): void;
+    removeEventListener<TEvent extends PlayerEvent>(options: PlayerEventListenerOptions<TEvent>): void;
     /**
      * Get the plugin version number.
      * Returns platform-specific version information.