tiny-essentials 1.28.5 → 1.28.6

package/dist/v1/libs/TinyMediaPlayer/Youtube.cjs

@@ -10,6 +10,7 @@ var objChecker = require('../../basics/objChecker.cjs');
  * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
  * @typedef {import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
  * @typedef {import('./index.mjs').ContentTimeData} ContentTimeData
+ * @typedef {import('./index.mjs').ContentData} ContentData
  *
  * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerState} YTPlayerState
  * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerErrors} YTPlayerErrors
@@ -187,7 +188,30 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
    * @throws {TypeError} If the `videoId` is not a valid string.
    */
   static createIframeContainer(options) {
-    const { videoId, width = 640, height = 360, hidden = true, autoplay = false } = options;
+    const {
+      videoId,
+      width = 640,
+      height = 360,
+      hidden = true,
+      autoplay = false,
+      ivLoadPolicy = true,
+      list = null,
+      listType = null,
+      ccLangPref = null,
+      ccLoadPolicy = false,
+      color = null,
+      controls = true,
+      disableKb = false,
+      loop = false,
+      end = null,
+      start = null,
+      playlist = null,
+      playsinline = false,
+      widgetReferrer = null,
+      rel = true,
+      fs = true,
+      hl = null,
+    } = options;
 
     if (typeof videoId !== 'string' || videoId.trim() === '') {
       throw new TypeError('The "videoId" property is required and must be a valid string.');
@@ -196,7 +220,7 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     const iframe = document.createElement('iframe');
 
     // enablejsapi=1 is required to allow control via the YouTube API
-    iframe.src = `https://www.youtube.com/embed/${videoId}?autoplay=${autoplay ? 1 : 0}&enablejsapi=1`;
+    iframe.src = `https://www.youtube.com/embed/${videoId}?autoplay=${autoplay ? 1 : 0}&rel=${rel ? 1 : 0}&iv_load_policy=${ivLoadPolicy ? 1 : 3}&loop=${loop ? 1 : 0}&playsinline=${playsinline ? 1 : 0}&fs=${fs ? 1 : 0}${typeof playlist === 'string' || Array.isArray(playlist) ? `&playlist=${!Array.isArray(playlist) ? playlist : playlist.join(',')}` : ''}${typeof ccLangPref === 'string' ? `&cc_lang_pref=${ccLangPref}` : ''}${typeof end === 'string' || typeof end === 'number' ? `&end=${end}` : ''}${typeof start === 'string' || typeof start === 'number' ? `&start=${start}` : ''}&cc_load_policy=${ccLoadPolicy ? 1 : 0}${typeof list === 'string' ? `&list=${list}` : ''}${typeof listType === 'string' ? `&listType=${listType}` : ''}${typeof widgetReferrer === 'string' ? `&widget_referrer=${widgetReferrer}` : ''}${typeof color === 'string' ? `&color=${color}` : ''}${typeof hl === 'string' ? `&hl=${hl}` : ''}&controls=${controls ? 1 : 0}&disablekb=${disableKb ? 1 : 0}&enablejsapi=1`;
 
     iframe.style.width = `${width}px`;
     iframe.style.height = `${height}px`;
@@ -243,6 +267,8 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
   /** @type {HTMLIFrameElement} */
   #container;
 
+  #isReady = false;
+
   /** @type {Promise<void>} */
   #apiLoadedPromise;
 
@@ -265,9 +291,26 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     return this.#currentContentId;
   }
 
+  /** @type {number} */
+  #lastReportedTime = 0;
+
   /** @type {ReturnType<typeof setInterval>|null} */
   #timeUpdateInterval = null;
 
+  /** @type {number} */
+  #pollingTimeUpdateValue = 250;
+
+  get pollingTimeUpdateValue() {
+    checkDestroy(this.#destroyed);
+    return this.#pollingTimeUpdateValue;
+  }
+
+  set pollingTimeUpdateValue(timeMs) {
+    checkDestroy(this.#destroyed);
+    if (typeof timeMs !== 'number') throw new TypeError('Time must be a number.');
+    this.#pollingTimeUpdateValue = timeMs;
+  }
+
   /**
    * Gets whether the adapter has been destroyed.
    * @returns {boolean}
@@ -336,6 +379,24 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     return this.#currentVolume;
   }
 
+  /**
+   * Synchronously checks whether the YouTube media adapter is fully initialized and ready.
+   * @returns {boolean} True if the adapter is ready, false otherwise.
+   */
+  isReady() {
+    checkDestroy(this.#destroyed);
+    return this.#isReady;
+  }
+
+  /**
+   * Asynchronously waits until the YouTube media adapter is fully initialized and ready.
+   * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+   */
+  async waitIsReady() {
+    checkDestroy(this.#destroyed);
+    return promiseUtils.waitForTrue(() => this.#isReady);
+  }
+
   /**
    * Retrieves a consolidated object containing all time-related metrics for the current media content.
    * @returns {ContentTimeData} An object containing total, current, remaining time, and playback percentage.
@@ -353,8 +414,7 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
    * @param {MediaContent} content - The media content to evaluate.
    * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
    */
-  canHandle(content) {
-    checkDestroy(this.#destroyed);
+  static canHandle(content) {
     if (!objChecker.isValidObj(content)) {
       throw new TypeError('Content must be a valid object.');
     }
@@ -364,9 +424,21 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     return youtubeRegex.test(content.url);
   }
 
+  /**
+   * Determines if the content is a valid YouTube URL or ID.
+   * @param {MediaContent} content - The media content to evaluate.
+   * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
+   */
+  canHandle(content) {
+    checkDestroy(this.#destroyed);
+    return YoutubeMediaAdapter.canHandle(content);
+  }
+
   /**
    * Plays the media content. If the player is already initialized with a different video,
    * it will load the new video automatically.
+   *
+   * Example: https://www.youtube.com/watch?v=XXXXXXXXXXX
    * @param {MediaContent} content - The media content to play.
    * @returns {Promise<void>}
    * @throws {TypeError} If the content data is invalid.
@@ -394,6 +466,9 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     if (this.#currentContentId !== targetVideoId) {
       this.#currentContentId = targetVideoId;
       this.#player?.loadVideoById(targetVideoId);
+      // Reset the last reported time to 0 to prevent a false 'seek' event
+      // when the new video starts playing.
+      this.#lastReportedTime = 0;
     } else {
       this.#player?.playVideo();
     }
@@ -460,7 +535,9 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
 
       // Resolve the initialization promise when the player is ready
       this.#masterEmitter?.once('onReady', () => {
+        this.#lastReportedTime = this.getCurrentTime();
         this.#startPollingTimeUpdate();
+        this.#isReady = true;
         resolve();
       });
 
@@ -470,16 +547,31 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
 
   /**
    * Starts a polling interval to emit 'timeupdate' events, matching the HTML5 Audio interface.
+   * Also detects 'seek' events by monitoring large jumps in the playback time.
    */
   #startPollingTimeUpdate() {
     this.#timeUpdateInterval = setInterval(() => {
-      if (
-        this.#player &&
-        this.#player.getPlayerState() === YoutubeMediaAdapter.PlayerState.PLAYING
-      ) {
+      if (!this.#player) return;
+
+      const currentTime = this.getCurrentTime();
+      const isPlaying = this.#player.getPlayerState() === YoutubeMediaAdapter.PlayerState.PLAYING;
+
+      if (isPlaying) {
+        const diff = Math.abs(currentTime - this.#lastReportedTime);
+
+        // If the time jump is greater than 1 second, we interpret it as a 'seek' event.
+        // This captures both programmatic seeks and user interactions with the YouTube UI.
+        if (diff > 1000) {
+          this.emit('seek', currentTime / 1000);
+        }
+
         this.#masterEmitter?.emit('timeupdate', this.getTimeData());
       }
-    }, 250);
+
+      // Always update the last reported time to keep it in sync with the actual player position.
+      // This prevents false 'seek' events when resuming playback after a pause or a seek while paused.
+      this.#lastReportedTime = currentTime;
+    }, this.#pollingTimeUpdateValue);
   }
 
   /**
@@ -537,9 +629,8 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
   async seek(timeMs) {
     checkDestroy(this.#destroyed);
     if (typeof timeMs !== 'number') throw new TypeError('Time must be a number.');
-    const currentTime = timeMs / 1000;
-    this.#player?.seekTo(currentTime, true);
-    this.emit('seek', currentTime);
+    const targetTimeInSeconds = timeMs / 1000;
+    this.#player?.seekTo(targetTimeInSeconds, true);
   }
 
   /**
@@ -613,6 +704,27 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
       : null;
   }
 
+  /**
+   * Retrieves the metadata of the currently loaded YouTube video, returning a structured
+   * object containing details such as the video ID, title, author, and duration.
+   * @returns {Promise<ContentData>}
+   */
+  async getContentData() {
+    const video = this.#player?.getVideoData();
+    if (!video) throw new Error('No video data available from the YouTube player.');
+    return {
+      id: String(video.video_id ?? ''),
+      createdAt: '',
+      artistId: '',
+      artistName: String(video.author ?? ''),
+      description: '',
+      title: String(video.title ?? ''),
+      duration: Number(video.progressBarEndPositionUtcTimeMillis ?? 0),
+      avatar: this.getThumbnailUrl() ?? '',
+      url: `https://youtu.be/${this.#currentContentId}`,
+    };
+  }
+
   /**
    * Cleans up the instance and disconnects from the shared player.
    */

package/dist/v1/libs/TinyMediaPlayer/Youtube.d.mts

@@ -2,6 +2,7 @@
  * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
  * @typedef {import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
  * @typedef {import('./index.mjs').ContentTimeData} ContentTimeData
+ * @typedef {import('./index.mjs').ContentData} ContentData
  *
  * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerState} YTPlayerState
  * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerErrors} YTPlayerErrors
@@ -26,6 +27,7 @@
 export type PictureDataType = import('../../basics/mediaContent.mjs').PictureDataType;
 export type MediaContent = import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>;
 export type ContentTimeData = import('./index.mjs').ContentTimeData;
+export type ContentData = import('./index.mjs').ContentData;
 export type YTPlayerState = import('./docs/YouTubePlayer.mjs').YTPlayerState;
 export type YTPlayerErrors = import('./docs/YouTubePlayer.mjs').YTPlayerErrors;
 export type YTQuality = import('./docs/YouTubePlayer.mjs').YTQuality;
@@ -66,6 +68,74 @@ export type IframeContainerOptions = {
      * - If true, the video will start automatically upon loading.
      */
     autoplay?: boolean;
+    /**
+     * - The ID of a playlist to load.
+     */
+    list?: string | null;
+    /**
+     * - The type of list to load (e.g., 'playlist').
+     */
+    listType?: string | null;
+    /**
+     * - The preferred language for closed captions.
+     */
+    ccLangPref?: string | null;
+    /**
+     * - Whether to load closed captions by default (0 for off, 1 for on).
+     */
+    ccLoadPolicy?: boolean;
+    /**
+     * - The color of the player controls (e.g., 'red', 'white').
+     */
+    color?: string | null;
+    /**
+     * - Whether to display the player controls.
+     */
+    controls?: boolean;
+    /**
+     * - Whether to disable keyboard controls.
+     */
+    disableKb?: boolean;
+    /**
+     * - Whether the video should loop.
+     */
+    loop?: boolean;
+    /**
+     * - The time in seconds when the video should end.
+     */
+    end?: number | string | null;
+    /**
+     * - The time in seconds when the video should start.
+     */
+    start?: number | string | null;
+    /**
+     * - A comma-separated list of video IDs to be played as a playlist.
+     */
+    playlist?: string | string[] | null;
+    /**
+     * - Whether to play the video inline on mobile devices.
+     */
+    playsinline?: boolean;
+    /**
+     * - The URL of the page where the player is embedded.
+     */
+    widgetReferrer?: string | null;
+    /**
+     * - Whether to show related videos from the same channel.
+     */
+    rel?: boolean;
+    /**
+     * - The language of the player interface.
+     */
+    hl?: string | null;
+    /**
+     * - Whether to allow the player to enter fullscreen mode.
+     */
+    fs?: boolean;
+    /**
+     * - The policy for showing video annotations (1 to show, 3 to hide).
+     */
+    ivLoadPolicy?: boolean;
 };
 import { BaseMediaAdapter } from './index.mjs';
 import YouTubePlayer from './docs/YouTubePlayer.mjs';
@@ -140,6 +210,8 @@ declare class YoutubeMediaAdapter extends BaseMediaAdapter {
     static getThumbnailUrl(videoId: string, quality?: string): string;
     get id(): string;
     get currentContentId(): string | null;
+    get pollingTimeUpdateValue(): number;
+    set pollingTimeUpdateValue(timeMs: number);
     /**
      * Gets whether the adapter has been destroyed.
      * @returns {boolean}
@@ -164,11 +236,27 @@ declare class YoutubeMediaAdapter extends BaseMediaAdapter {
      * @returns {number} The current volume level from 0.0 to 1.0.
      */
     get volume(): number;
+    /**
+     * Synchronously checks whether the YouTube media adapter is fully initialized and ready.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isReady(): boolean;
+    /**
+     * Asynchronously waits until the YouTube media adapter is fully initialized and ready.
+     * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+     */
+    waitIsReady(): Promise<void>;
     /**
      * Retrieves a consolidated object containing all time-related metrics for the current media content.
      * @returns {ContentTimeData} An object containing total, current, remaining time, and playback percentage.
      */
     getTimeData(): ContentTimeData;
+    /**
+     * Determines if the content is a valid YouTube URL or ID.
+     * @param {MediaContent} content - The media content to evaluate.
+     * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
+     */
+    static canHandle(content: MediaContent): boolean;
     /**
      * Determines if the content is a valid YouTube URL or ID.
      * @param {MediaContent} content - The media content to evaluate.
@@ -178,6 +266,8 @@ declare class YoutubeMediaAdapter extends BaseMediaAdapter {
     /**
      * Plays the media content. If the player is already initialized with a different video,
      * it will load the new video automatically.
+     *
+     * Example: https://www.youtube.com/watch?v=XXXXXXXXXXX
      * @param {MediaContent} content - The media content to play.
      * @returns {Promise<void>}
      * @throws {TypeError} If the content data is invalid.
@@ -239,6 +329,12 @@ declare class YoutubeMediaAdapter extends BaseMediaAdapter {
      * @returns {string|null} The thumbnail URL or null if no video is loaded.
      */
     getThumbnailUrl(quality?: string): string | null;
+    /**
+     * Retrieves the metadata of the currently loaded YouTube video, returning a structured
+     * object containing details such as the video ID, title, author, and duration.
+     * @returns {Promise<ContentData>}
+     */
+    getContentData(): Promise<ContentData>;
     /**
      * Cleans up the instance and disconnects from the shared player.
      */

package/dist/v1/libs/TinyMediaPlayer/Youtube.mjs

@@ -2,6 +2,7 @@
  * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
  * @typedef {import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
  * @typedef {import('./index.mjs').ContentTimeData} ContentTimeData
+ * @typedef {import('./index.mjs').ContentData} ContentData
  *
  * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerState} YTPlayerState
  * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerErrors} YTPlayerErrors
@@ -34,6 +35,23 @@
  * @property {number|string} [height=360] - The iframe height in pixels or a string (e.g., '100%').
  * @property {boolean} [hidden=true] - If true, the iframe will be invisible (opacity 0) and will not respond to clicks (pointer-events none) and appends it to the document body.
  * @property {boolean} [autoplay=false] - If true, the video will start automatically upon loading.
+ * @property {string|null} [list=null] - The ID of a playlist to load.
+ * @property {string|null} [listType=null] - The type of list to load (e.g., 'playlist').
+ * @property {string|null} [ccLangPref=null] - The preferred language for closed captions.
+ * @property {boolean} [ccLoadPolicy=false] - Whether to load closed captions by default (0 for off, 1 for on).
+ * @property {string|null} [color=null] - The color of the player controls (e.g., 'red', 'white').
+ * @property {boolean} [controls=true] - Whether to display the player controls.
+ * @property {boolean} [disableKb=false] - Whether to disable keyboard controls.
+ * @property {boolean} [loop=false] - Whether the video should loop.
+ * @property {number|string|null} [end=null] - The time in seconds when the video should end.
+ * @property {number|string|null} [start=null] - The time in seconds when the video should start.
+ * @property {string|string[]|null} [playlist=null] - A comma-separated list of video IDs to be played as a playlist.
+ * @property {boolean} [playsinline=false] - Whether to play the video inline on mobile devices.
+ * @property {string|null} [widgetReferrer=null] - The URL of the page where the player is embedded.
+ * @property {boolean} [rel=true] - Whether to show related videos from the same channel.
+ * @property {string|null} [hl=null] - The language of the player interface.
+ * @property {boolean} [fs=true] - Whether to allow the player to enter fullscreen mode.
+ * @property {boolean} [ivLoadPolicy=true] - The policy for showing video annotations (1 to show, 3 to hide).
  */
 import { EventEmitter } from 'events';
 import { BaseMediaAdapter } from './index.mjs';
@@ -181,13 +199,13 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
      * @throws {TypeError} If the `videoId` is not a valid string.
      */
     static createIframeContainer(options) {
-        const { videoId, width = 640, height = 360, hidden = true, autoplay = false } = options;
+        const { videoId, width = 640, height = 360, hidden = true, autoplay = false, ivLoadPolicy = true, list = null, listType = null, ccLangPref = null, ccLoadPolicy = false, color = null, controls = true, disableKb = false, loop = false, end = null, start = null, playlist = null, playsinline = false, widgetReferrer = null, rel = true, fs = true, hl = null, } = options;
         if (typeof videoId !== 'string' || videoId.trim() === '') {
             throw new TypeError('The "videoId" property is required and must be a valid string.');
         }
         const iframe = document.createElement('iframe');
         // enablejsapi=1 is required to allow control via the YouTube API
-        iframe.src = `https://www.youtube.com/embed/${videoId}?autoplay=${autoplay ? 1 : 0}&enablejsapi=1`;
+        iframe.src = `https://www.youtube.com/embed/${videoId}?autoplay=${autoplay ? 1 : 0}&rel=${rel ? 1 : 0}&iv_load_policy=${ivLoadPolicy ? 1 : 3}&loop=${loop ? 1 : 0}&playsinline=${playsinline ? 1 : 0}&fs=${fs ? 1 : 0}${typeof playlist === 'string' || Array.isArray(playlist) ? `&playlist=${!Array.isArray(playlist) ? playlist : playlist.join(',')}` : ''}${typeof ccLangPref === 'string' ? `&cc_lang_pref=${ccLangPref}` : ''}${typeof end === 'string' || typeof end === 'number' ? `&end=${end}` : ''}${typeof start === 'string' || typeof start === 'number' ? `&start=${start}` : ''}&cc_load_policy=${ccLoadPolicy ? 1 : 0}${typeof list === 'string' ? `&list=${list}` : ''}${typeof listType === 'string' ? `&listType=${listType}` : ''}${typeof widgetReferrer === 'string' ? `&widget_referrer=${widgetReferrer}` : ''}${typeof color === 'string' ? `&color=${color}` : ''}${typeof hl === 'string' ? `&hl=${hl}` : ''}&controls=${controls ? 1 : 0}&disablekb=${disableKb ? 1 : 0}&enablejsapi=1`;
         iframe.style.width = `${width}px`;
         iframe.style.height = `${height}px`;
         iframe.setAttribute('frameborder', '0');
@@ -226,6 +244,7 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
     #player = null;
     /** @type {HTMLIFrameElement} */
     #container;
+    #isReady = false;
     /** @type {Promise<void>} */
     #apiLoadedPromise;
     /** @type {number} */
@@ -241,8 +260,22 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
     get currentContentId() {
         return this.#currentContentId;
     }
+    /** @type {number} */
+    #lastReportedTime = 0;
     /** @type {ReturnType<typeof setInterval>|null} */
     #timeUpdateInterval = null;
+    /** @type {number} */
+    #pollingTimeUpdateValue = 250;
+    get pollingTimeUpdateValue() {
+        checkDestroy(this.#destroyed);
+        return this.#pollingTimeUpdateValue;
+    }
+    set pollingTimeUpdateValue(timeMs) {
+        checkDestroy(this.#destroyed);
+        if (typeof timeMs !== 'number')
+            throw new TypeError('Time must be a number.');
+        this.#pollingTimeUpdateValue = timeMs;
+    }
     /**
      * Gets whether the adapter has been destroyed.
      * @returns {boolean}
@@ -300,6 +333,22 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
         checkDestroy(this.#destroyed);
         return this.#currentVolume;
     }
+    /**
+     * Synchronously checks whether the YouTube media adapter is fully initialized and ready.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isReady() {
+        checkDestroy(this.#destroyed);
+        return this.#isReady;
+    }
+    /**
+     * Asynchronously waits until the YouTube media adapter is fully initialized and ready.
+     * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+     */
+    async waitIsReady() {
+        checkDestroy(this.#destroyed);
+        return waitForTrue(() => this.#isReady);
+    }
     /**
      * Retrieves a consolidated object containing all time-related metrics for the current media content.
      * @returns {ContentTimeData} An object containing total, current, remaining time, and playback percentage.
@@ -316,8 +365,7 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
      * @param {MediaContent} content - The media content to evaluate.
      * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
      */
-    canHandle(content) {
-        checkDestroy(this.#destroyed);
+    static canHandle(content) {
         if (!isValidObj(content)) {
             throw new TypeError('Content must be a valid object.');
         }
@@ -326,9 +374,20 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
         const youtubeRegex = /(?:youtube\.com\/(?:[^\/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^"&?\/\s]{11})/;
         return youtubeRegex.test(content.url);
     }
+    /**
+     * Determines if the content is a valid YouTube URL or ID.
+     * @param {MediaContent} content - The media content to evaluate.
+     * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
+     */
+    canHandle(content) {
+        checkDestroy(this.#destroyed);
+        return YoutubeMediaAdapter.canHandle(content);
+    }
     /**
      * Plays the media content. If the player is already initialized with a different video,
      * it will load the new video automatically.
+     *
+     * Example: https://www.youtube.com/watch?v=XXXXXXXXXXX
      * @param {MediaContent} content - The media content to play.
      * @returns {Promise<void>}
      * @throws {TypeError} If the content data is invalid.
@@ -351,6 +410,9 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
         if (this.#currentContentId !== targetVideoId) {
             this.#currentContentId = targetVideoId;
             this.#player?.loadVideoById(targetVideoId);
+            // Reset the last reported time to 0 to prevent a false 'seek' event
+            // when the new video starts playing.
+            this.#lastReportedTime = 0;
         }
         else {
             this.#player?.playVideo();
@@ -412,7 +474,9 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
             this.#masterEmitter = masterEmitter;
             // Resolve the initialization promise when the player is ready
             this.#masterEmitter?.once('onReady', () => {
+                this.#lastReportedTime = this.getCurrentTime();
                 this.#startPollingTimeUpdate();
+                this.#isReady = true;
                 resolve();
             });
             this.#attachToMaster();
@@ -420,14 +484,27 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
     }
     /**
      * Starts a polling interval to emit 'timeupdate' events, matching the HTML5 Audio interface.
+     * Also detects 'seek' events by monitoring large jumps in the playback time.
      */
     #startPollingTimeUpdate() {
         this.#timeUpdateInterval = setInterval(() => {
-            if (this.#player &&
-                this.#player.getPlayerState() === YoutubeMediaAdapter.PlayerState.PLAYING) {
+            if (!this.#player)
+                return;
+            const currentTime = this.getCurrentTime();
+            const isPlaying = this.#player.getPlayerState() === YoutubeMediaAdapter.PlayerState.PLAYING;
+            if (isPlaying) {
+                const diff = Math.abs(currentTime - this.#lastReportedTime);
+                // If the time jump is greater than 1 second, we interpret it as a 'seek' event.
+                // This captures both programmatic seeks and user interactions with the YouTube UI.
+                if (diff > 1000) {
+                    this.emit('seek', currentTime / 1000);
+                }
                 this.#masterEmitter?.emit('timeupdate', this.getTimeData());
             }
-        }, 250);
+            // Always update the last reported time to keep it in sync with the actual player position.
+            // This prevents false 'seek' events when resuming playback after a pause or a seek while paused.
+            this.#lastReportedTime = currentTime;
+        }, this.#pollingTimeUpdateValue);
     }
     /**
      * Connects this instance to the master emitter of the shared player.
@@ -480,9 +557,8 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
         checkDestroy(this.#destroyed);
         if (typeof timeMs !== 'number')
             throw new TypeError('Time must be a number.');
-        const currentTime = timeMs / 1000;
-        this.#player?.seekTo(currentTime, true);
-        this.emit('seek', currentTime);
+        const targetTimeInSeconds = timeMs / 1000;
+        this.#player?.seekTo(targetTimeInSeconds, true);
     }
     /**
      * Retrieves the current playback time.
@@ -548,6 +624,27 @@ class YoutubeMediaAdapter extends BaseMediaAdapter {
             ? YoutubeMediaAdapter.getThumbnailUrl(this.#currentContentId, quality)
             : null;
     }
+    /**
+     * Retrieves the metadata of the currently loaded YouTube video, returning a structured
+     * object containing details such as the video ID, title, author, and duration.
+     * @returns {Promise<ContentData>}
+     */
+    async getContentData() {
+        const video = this.#player?.getVideoData();
+        if (!video)
+            throw new Error('No video data available from the YouTube player.');
+        return {
+            id: String(video.video_id ?? ''),
+            createdAt: '',
+            artistId: '',
+            artistName: String(video.author ?? ''),
+            description: '',
+            title: String(video.title ?? ''),
+            duration: Number(video.progressBarEndPositionUtcTimeMillis ?? 0),
+            avatar: this.getThumbnailUrl() ?? '',
+            url: `https://youtu.be/${this.#currentContentId}`,
+        };
+    }
     /**
      * Cleans up the instance and disconnects from the shared player.
      */