youtube-player

What is youtube-player?

The youtube-player npm package is a simple wrapper around the YouTube IFrame Player API, allowing you to easily embed and control YouTube videos in your web applications.

What are youtube-player's main functionalities?

Load a YouTube Video

This feature allows you to load a YouTube video by its ID into an HTML element with the specified ID. In this example, the video with ID 'M7lc1UVf-VE' is loaded into the element with ID 'video-player'.

const YouTubePlayer = require('youtube-player');
const player = YouTubePlayer('video-player');
player.loadVideoById('M7lc1UVf-VE');

Play a Video

This feature allows you to play the currently loaded video. The `playVideo` method starts the video playback.

player.playVideo();

Pause a Video

This feature allows you to pause the currently playing video. The `pauseVideo` method pauses the video playback.

player.pauseVideo();

Seek to a Specific Time

This feature allows you to seek to a specific time in the video. The `seekTo` method takes the time in seconds and a boolean indicating whether to allow seeking ahead of the video.

player.seekTo(30, true);

Get Video Duration

This feature allows you to get the duration of the currently loaded video. The `getDuration` method returns a promise that resolves with the duration in seconds.

player.getDuration().then(duration => console.log(duration));

Other packages similar to youtube-player

react-youtube

The react-youtube package is a React component for embedding YouTube videos. It provides a declarative way to embed and control YouTube videos in React applications. Compared to youtube-player, react-youtube is more suitable for React-based projects and offers a more React-friendly API.

youtube-iframe

The youtube-iframe package is a lightweight wrapper around the YouTube IFrame Player API. It provides similar functionalities to youtube-player but with a simpler and more minimalistic approach. It is suitable for projects that require basic YouTube video embedding and control without additional features.

youtube-api

The youtube-api package is a comprehensive wrapper around the YouTube Data API. It allows you to interact with various YouTube services, including video playback, uploading, and data retrieval. While it offers more extensive functionalities compared to youtube-player, it is more complex and suitable for projects that require deep integration with YouTube services.

README

YouTube Player

• Usage
  • Events
• Polyfills
• Examples
• Debugging
• Download
• Running the Examples

youtube-player is an abstraction of YouTube IFrame Player API (YIPA).

The downsides of using YouTube IFrame Player API are:

• Requires to define callbacks in the global scope (window).
• Requires to track the state of a player (e.g. you must ensure that video player is "ready" before you can use the API).

youtube-player:

• Registers listeners required to establish when YIPA has been loaded.
• Does not overwrite global YIPA callback functions.
• Queues player API calls until when video player is "ready".

Usage

/**
 * @typedef options
 * @see https://developers.google.com/youtube/iframe_api_reference#Loading_a_Video_Player
 * @param {Number} width
 * @param {Number} height
 * @param {String} videoId
 * @param {Object} playerVars
 * @param {Object} events
 */

/**
 * @typedef YT.Player
 * @see https://developers.google.com/youtube/iframe_api_reference
 * */

/**
 * A factory function used to produce an instance of YT.Player and queue function calls and proxy events of the resulting object.
 *
 * @param {YT.Player|HTMLElement|String} elementId Either An existing YT.Player instance,
 * the DOM element or the id of the HTML element where the API will insert an <iframe>.
 * @param {YouTubePlayer~options} options See `options` (Ignored when using an existing YT.Player instance).
 * @param {boolean} strictState A flag designating whether or not to wait for
 * an acceptable state when calling supported functions. Default: `false`.
 * See `FunctionStateMap.js` for supported functions and acceptable states.
 * @returns {Object}
 */
import YouTubePlayer from 'youtube-player';

youtube-player is a factory function.

The resulting object exposes all functions of an instance of YT.Player. The difference is that the function body is wrapped in a promise. This promise is resolved only when the player has finished loading and is ready to begin receiving API calls (onReady). Therefore, all function calls are queued and replayed only when player is ready.

This encapsulation does not affect the API other than making every function return a promise.

let player;

player = YouTubePlayer('video-player');

// 'loadVideoById' is queued until the player is ready to receive API calls.
player.loadVideoById('M7lc1UVf-VE');

// 'playVideo' is queue until the player is ready to received API calls and after 'loadVideoById' has been called.
player.playVideo();

// 'stopVideo' is queued after 'playVideo'.
player
    .stopVideo()
    .then(() => {
        // Every function returns a promise that is resolved after the target function has been executed.
    });

Events

player.on event emitter is used to listen to all YouTube IFrame Player API events, e.g.

player.on('stateChange', (event) => {
    // event.data
});

player.off removes a previously added event listener, e.g.

var listener = player.on(/* ... */);

player.off(listener);

Polyfills

Note that the built version does not inline polyfills.

You need to polyfill the environment locally (e.g. using a service such as https://polyfill.io/v2/docs/).

Examples

• Playing a video.
• Multiple players.
• Registering events handlers.

Debugging

youtube-player is using debug module to expose debugging information.

The debug namespace is "youtube-player".

To display youtube-player logs configure localStorage.debug, e.g.

localStorage.debug = 'youtube-player:*';

Download

Using NPM:

npm install youtube-player

Running the Examples

npm install
npm run build
cd ./examples
npm install
npm run start

This will start a HTTP server on port 8000.