@react-native-youtube-bridge/core/dist/index.d.mts

Core package for react-native-youtube-bridge

//#region src/constants.d.ts
declare const ERROR_CODES: {
  readonly 2: "INVALID_PARAMETER_VALUE";
  readonly 5: "HTML5_PLAYER_ERROR";
  readonly 100: "VIDEO_NOT_FOUND_OR_PRIVATE";
  readonly 101: "EMBEDDED_PLAYBACK_NOT_ALLOWED";
  readonly 150: "EMBEDDED_RESTRICTED";
  readonly 1000: "FAILED_TO_PARSE_WEBVIEW_MESSAGE";
  readonly 1001: "WEBVIEW_LOADING_ERROR";
  readonly 1002: "INVALID_YOUTUBE_VIDEO_ID";
  readonly 1003: "FAILED_TO_LOAD_YOUTUBE_API";
  readonly 1004: "UNKNOWN_ERROR";
};
declare const MATCH_URL_YOUTUBE: RegExp;
//#endregion
//#region src/types/index.d.ts
type YoutubeErrorCode = keyof typeof ERROR_CODES;
type YoutubeErrorMessage = (typeof ERROR_CODES)[YoutubeErrorCode];
/**
 * The source of the Youtube video.
 * @example
 * ```ts
 * const player = useYouTubePlayer('AbZH7XWDW_k');
 * const player = useYouTubePlayer({ videoId: 'AbZH7XWDW_k' });
 * const player = useYouTubePlayer({ url: 'https://www.youtube.com/watch?v=AbZH7XWDW_k' });
 * ```
 */
type YoutubeSource = string | {
  videoId: string | undefined;
} | {
  url: string | undefined;
} | undefined;
type ProgressData = {
  /**
   * The current time of the video.
   */
  currentTime: number;
  /**
   * The duration of the video.
   */
  duration: number;
  /**
   * The percentage of the video that has been played.
   */
  percentage: number;
  /**
   * The fraction of the video that has been loaded.
   */
  loadedFraction: number;
};
type YoutubeError = {
  /**
   * `2, 5, 100, 101, 150` YouTube error code.
   *
   * @see https://developers.google.com/youtube/iframe_api_reference#Events
   */
  code: YoutubeErrorCode;
  message: YoutubeErrorMessage;
};
declare enum PlayerState {
  UNSTARTED = -1,
  ENDED = 0,
  PLAYING = 1,
  PAUSED = 2,
  BUFFERING = 3,
  CUED = 5,
}
type PlaybackQuality = 'small' | 'medium' | 'large' | 'hd720' | 'hd1080' | 'highres';
type PlayerInfo = {
  availablePlaybackRates?: number[];
  availableQualityLevels?: PlaybackQuality[];
  currentTime?: number;
  duration?: number;
  muted?: boolean;
  playbackQuality?: PlaybackQuality;
  playbackRate?: number;
  playerState?: PlayerState;
  size?: {
    width: number;
    height: number;
  };
  volume?: number;
};
/**
 * This parameter specifies the player events.
 * @see https://developers.google.com/youtube/iframe_api_reference#Events
 */
type PlayerEvents = {
  /**
   * Callback function called when the player is ready.
   * @param {PlayerInfo} playerInfo - The player information.
   */
  onReady?: (playerInfo: PlayerInfo) => void;
  /**
   * This event fires whenever the player's state changes. The data property of the event object that the API passes to your event listener function will specify an integer that corresponds to the new player state.
   * @param {PlayerState} state - The new player state.
   */
  onStateChange?: (state: PlayerState) => void;
  /**
   * This event fires if an error occurs in the player. The API will pass an event object to the event listener function.
   * @param {YoutubeError} error - The error object.
   */
  onError?: (error: YoutubeError) => void;
  /**
   * Callback function called at the specified `progressInterval`
   * or when `seekTo` is invoked. Only triggered when `progressInterval` is
   * provided as a positive number.
   * @param {ProgressData} progress - The progress data.
   */
  onProgress?: (progress: ProgressData) => void;
  /**
   * This event fires whenever the video playback rate changes. For example, if you call the `setPlaybackRate(suggestedRate)` function, this event will fire if the playback rate actually changes.
   * @param {number} playbackRate - The new playback rate.
   */
  onPlaybackRateChange?: (playbackRate: number) => void;
  /**
   * This event fires whenever the video playback quality changes. It might signal a change in the viewer's playback environment.
   * @param {PlaybackQuality} quality - The new playback quality.
   */
  onPlaybackQualityChange?: (quality: PlaybackQuality) => void;
  /**
   * This event fires any time the browser blocks autoplay or scripted video playback features, collectively referred to as "autoplay".
   */
  onAutoplayBlocked?: () => void;
};
/**
 * This parameter specifies the player parameters.
 * @see https://developers.google.com/youtube/player_parameters
 */
type YoutubePlayerVars = {
  /**
   * This parameter specifies whether the initial video will automatically start to play when the player loads.
   * @remarks
   * - If the `muted` is not set to true when activating the `autoplay`,
   * - it may not work properly depending on browser policy. (https://developer.chrome.com/blog/autoplay)
   */
  autoplay?: boolean;
  /**
   * This parameter indicates whether the video player controls are displayed.
   * @remarks
   * - `controls: false` - Player controls do not display in the player.
   * - `controls: true` (default) - Player controls display in the player.
   * @defaultValue true
   */
  controls?: boolean;
  /**
   * In the case of a single video player, a setting of 1 causes the player to play the initial video again and again. In the case of a playlist player (or custom player), the player plays the entire playlist and then starts again at the first video.
   * @defaultValue false
   */
  loop?: boolean;
  /**
   * If the `muted` is set to true, the player will be muted.
   */
  muted?: boolean;
  /**
   * This parameter causes the player to begin playing the video at the given number of seconds from the start of the video. The parameter value is a positive integer. Note that similar to the seekTo function, the player will look for the closest keyframe to the time you specify. This means that sometimes the play head may seek to just before the requested time, usually no more than around two seconds.
   */
  startTime?: number;
  /**
   * This parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing the video. The parameter value is a positive integer.
   */
  endTime?: number;
  /**
   * This parameter controls whether videos play inline or fullscreen on iOS.
   *
   * @remarks
   * Valid values are:
   * - `playsinline: false` - Results in fullscreen playback. This is currently the default value, though the default is subject to change.
   * - `playsinline: true` - Results in inline playback for mobile browsers and for WebViews created with the `allowsInlineMediaPlayback` property set to `YES`.
   */
  playsinline?: boolean;
  /**
   * Prior to the change, this parameter indicates whether the player should show related videos when playback of the initial video ends.
   * @remarks
   * After the change, you will not be able to disable related videos. Instead, if the `rel` parameter is set to `false, related videos will come from the same channel as the video that was just played.
   */
  rel?: boolean;
  /**
   * This parameter provides an extra security measure for the IFrame API and is only supported for IFrame embeds.
   *
   * @remarks
   * - When `useInlineHtml` is `true` (iOS/Android inline WebView), if not provided, the library defaults this to `https://localhost` and sets the WebView `baseUrl` accordingly so that the document origin and this value match.
   * - When `useInlineHtml` is `false` (remote WebView), if not provided, the external page URL defaults to `https://react-native-youtube-bridge.pages.dev` and this value follows that URL. If you pass a custom `webViewUrl` (base URL), `origin` should follow that same origin.
   * - In all cases, this value MUST exactly match the document's origin that hosts the iframe for the YouTube IFrame API to function correctly.
   */
  origin?: string;
};
type YoutubePlayerConfig = {
  videoId: string;
  progressInterval?: number;
  playerVars?: YoutubePlayerVars;
} & PlayerEvents;
/**
 * The player controls.
 * @see https://developers.google.com/youtube/iframe_api_reference#Functions
 */
type PlayerControls = {
  play: () => void;
  pause: () => void;
  stop: () => void;
  seekTo: (seconds: number, allowSeekAhead?: boolean) => void;
  setVolume: (volume: number) => void;
  getVolume: () => Promise<number>;
  mute: () => void;
  unMute: () => void;
  isMuted: () => Promise<boolean>;
  getCurrentTime: () => Promise<number>;
  getDuration: () => Promise<number>;
  getVideoUrl: () => Promise<string>;
  getVideoEmbedCode: () => Promise<string>;
  getPlaybackRate: () => Promise<number>;
  setPlaybackRate: (rate: number) => void;
  getAvailablePlaybackRates: () => Promise<number[]>;
  getPlayerState: () => Promise<PlayerState>;
  getVideoLoadedFraction: () => Promise<number>;
  loadVideoById: (videoId: string, startSeconds?: number, endSeconds?: number) => void;
  cueVideoById: (videoId: string, startSeconds?: number, endSeconds?: number) => void;
  setSize: (width: number, height: number) => void;
};
type YoutubePlayerEvents = {
  ready: PlayerInfo;
  stateChange: PlayerState;
  error: YoutubeError;
  progress: ProgressData;
  playbackRateChange: number;
  playbackQualityChange: PlaybackQuality;
  autoplayBlocked: undefined;
};
type EventCallback<Data = any> = (data: Data) => any;
//#endregion
//#region src/types/webview.d.ts
interface ReadyMessageData {
  type: 'ready';
  playerInfo: PlayerInfo;
}
interface StateChangeMessageData {
  type: 'stateChange';
  state: PlayerState;
}
interface ErrorMessageData {
  type: 'error';
  error: YoutubeError;
}
interface ProgressMessageData {
  type: 'progress';
  progress: ProgressData;
}
interface PlaybackRateChangeMessageData {
  type: 'playbackRateChange';
  playbackRate: number;
}
interface PlaybackQualityChangeMessageData {
  type: 'playbackQualityChange';
  quality: PlaybackQuality;
}
interface AutoplayBlockedMessageData {
  type: 'autoplayBlocked';
}
interface CommandResultMessageData {
  type: 'commandResult';
  id: string;
  result: unknown;
}
type MessageData = ReadyMessageData | StateChangeMessageData | ErrorMessageData | ProgressMessageData | PlaybackRateChangeMessageData | PlaybackQualityChangeMessageData | AutoplayBlockedMessageData | CommandResultMessageData;
//#endregion
//#region src/types/iframe.d.ts
/**
 * @see https://developers.google.com/youtube/iframe_api_reference
 */
interface YouTubePlayer {
  addEventListener(event: string, listener: (event: CustomEvent) => void): Promise<void>;
  destroy(): Promise<void>;
  getAvailablePlaybackRates(): Promise<number[]>;
  getCurrentTime(): Promise<number>;
  getDuration(): Promise<number>;
  getIframe(): Promise<HTMLIFrameElement>;
  getOption(module: string, option: string): Promise<unknown>;
  getOptions(): Promise<string[]>;
  getOptions(module: string): Promise<object>;
  setOption(module: string, option: string, value: unknown): Promise<void>;
  setOptions(): Promise<void>;
  cuePlaylist(playlist: string | readonly string[], index?: number, startSeconds?: number, suggestedQuality?: string): Promise<void>;
  cuePlaylist(playlist: {
    listType: string;
    list?: string | undefined;
    index?: number | undefined;
    startSeconds?: number | undefined;
    suggestedQuality?: string | undefined;
  }): Promise<void>;
  loadPlaylist(playlist: string | readonly string[], index?: number, startSeconds?: number, suggestedQuality?: string): Promise<void>;
  loadPlaylist(playlist: {
    listType: string;
    list?: string | undefined;
    index?: number | undefined;
    startSeconds?: number | undefined;
    suggestedQuality?: string | undefined;
  }): Promise<void>;
  getPlaylist(): Promise<readonly string[]>;
  getPlaylistIndex(): Promise<number>;
  getPlaybackRate(): Promise<number>;
  getPlayerState(): Promise<PlayerState>;
  getVideoEmbedCode(): Promise<string>;
  getVideoLoadedFraction(): Promise<number>;
  getVideoUrl(): Promise<string>;
  getVolume(): Promise<number>;
  cueVideoById(videoId: string, startSeconds?: number, endSeconds?: number): Promise<void>;
  cueVideoById(video: {
    videoId: string;
    startSeconds?: number | undefined;
    endSeconds?: number | undefined;
    suggestedQuality?: string | undefined;
  }): Promise<void>;
  cueVideoByUrl(mediaContentUrl: string, startSeconds?: number, suggestedQuality?: string): Promise<void>;
  cueVideoByUrl(video: {
    mediaContentUrl: string;
    startSeconds?: number | undefined;
    endSeconds?: number | undefined;
    suggestedQuality?: string | undefined;
  }): Promise<void>;
  loadVideoByUrl(mediaContentUrl: string, startSeconds?: number, suggestedQuality?: string): Promise<void>;
  loadVideoByUrl(video: {
    mediaContentUrl: string;
    startSeconds?: number | undefined;
    endSeconds?: number | undefined;
    suggestedQuality?: string | undefined;
  }): Promise<void>;
  loadVideoById(videoId: string, startSeconds?: number, endSeconds?: number): Promise<void>;
  loadVideoById(video: {
    videoId: string;
    startSeconds?: number | undefined;
    endSeconds?: number | undefined;
    suggestedQuality?: string | undefined;
  }): Promise<void>;
  isMuted(): Promise<boolean>;
  mute(): Promise<void>;
  nextVideo(): Promise<void>;
  pauseVideo(): Promise<void>;
  playVideo(): Promise<void>;
  playVideoAt(index: number): Promise<void>;
  previousVideo(): Promise<void>;
  removeEventListener(event: string, listener: (event: CustomEvent) => void): Promise<void>;
  seekTo(seconds: number, allowSeekAhead: boolean): Promise<void>;
  setLoop(loopPlaylists: boolean): Promise<void>;
  setPlaybackRate(suggestedRate: number): Promise<void>;
  setShuffle(shufflePlaylist: boolean): Promise<void>;
  setSize(width: number, height: number): Promise<{
    width: number;
    height: number;
  }>;
  setVolume(volume: number): Promise<void>;
  stopVideo(): Promise<void>;
  unMute(): Promise<void>;
}
//#endregion
//#region src/WebYoutubePlayerController.d.ts
type PlayerConfig = Omit<YoutubePlayerConfig, 'source'> & {
  videoId: string;
};
declare class WebYoutubePlayerController {
  private player;
  private progressInterval;
  private callbacks;
  private progressIntervalMs;
  private seekTimeout;
  static createInstance(): WebYoutubePlayerController;
  static initialize(): Promise<void>;
  createPlayer(containerId: string, config: PlayerConfig): void;
  private handleStateChange;
  startProgressTracking(): void;
  stopProgressTracking(): void;
  private sendProgress;
  getPlayer(): YouTubePlayer | null;
  play(): void;
  pause(): void;
  stop(): void;
  seekTo(seconds: number, allowSeekAhead?: boolean): Promise<void>;
  setVolume(volume: number): void;
  getVolume(): Promise<number>;
  mute(): void;
  unMute(): void;
  isMuted(): Promise<boolean>;
  getCurrentTime(): Promise<number>;
  getDuration(): Promise<number>;
  getVideoUrl(): Promise<string>;
  getVideoEmbedCode(): Promise<string>;
  getPlaybackRate(): Promise<number>;
  getAvailablePlaybackRates(): Promise<number[]>;
  getPlayerState(): Promise<number>;
  setPlaybackRate(suggestedRate: number): Promise<void>;
  getVideoLoadedFraction(): Promise<number>;
  loadVideoById(videoId: string, startSeconds?: number, endSeconds?: number): void;
  cueVideoById(videoId: string, startSeconds?: number, endSeconds?: number): void;
  setSize(width: number, height: number): void;
  updateProgressInterval(intervalMs: number): void;
  updateCallbacks(newCallbacks: Partial<PlayerEvents>): void;
  destroy(): void;
}
//#endregion
//#region src/utils.d.ts
declare const extractVideoIdFromUrl: (url?: string) => string | undefined;
declare const validateVideoId: (videoId?: string | null) => boolean;
declare const escapeHtml: (unsafe?: string) => string;
declare const safeNumber: (value: number | undefined, defaultValue?: number) => number;
//#endregion
export { ERROR_CODES, EventCallback, MATCH_URL_YOUTUBE, MessageData, PlaybackQuality, PlayerControls, PlayerEvents, PlayerInfo, PlayerState, ProgressData, WebYoutubePlayerController, YoutubeError, YoutubePlayerConfig, YoutubePlayerEvents, YoutubePlayerVars, YoutubeSource, escapeHtml, extractVideoIdFromUrl, safeNumber, validateVideoId };