Registry / web-framework / youtube-player

youtube-player

library5.6.0jsnpmunverified

youtube-player provides a robust abstraction layer over the official YouTube IFrame Player API. It addresses common pain points like managing global callbacks and ensuring player readiness by registering listeners, queuing API calls until the player is ready, and wrapping all player functions in promises. This allows for a more synchronous-looking, chainable API experience, significantly simplifying interactions with the YouTube player. The current stable version is 5.6.0, with the last notable updates in 2019, indicating a mature and relatively low-churn project. Key differentiators include its promise-based API, automatic state management, and non-interference with global YIPA callback functions, offering a cleaner, more reliable way to embed and control YouTube videos in web applications.

web-framework communication

npm install youtube-player

github ↗package ↗

INSTALL

IMPORT

SIG · YOUTUBE-PLAYER

youtube-player

web-frameworkjavascriptv5.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YouTubePlayer

✓ import YouTubePlayer from 'youtube-player';

✗ const YouTubePlayer = require('youtube-player');

The library primarily uses ESM imports; CommonJS `require` might work in some transpiled environments but ESM is preferred. `YouTubePlayer` is a factory function.

player.on

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

✗ player.addEventListener('stateChange', (event) => { /* ... */ });

The library uses its own `.on()` and `.off()` event emitter API, not standard DOM event listeners.

player.loadVideoById

✓ player.loadVideoById('VIDEO_ID').then(() => { /* ... */ });

✗ player.loadVideoById('VIDEO_ID'); // Not waiting for promise

All player functions return a Promise that resolves after the underlying YouTube API call has completed. Always `.then()` or `await` the result for reliable sequencing.

This quickstart demonstrates how to initialize a YouTube player, load a video by ID, listen for state changes and errors, and control playback using `playVideo`, `pauseVideo`, and `stopVideo`. It also shows how to destroy the player.

import YouTubePlayer from 'youtube-player'; // In a real application, this div would already exist in your HTML. // For demonstration, we'll simulate its presence. const playerElement = document.createElement('div'); playerElement.id = 'video-player-container'; document.body.appendChild(playerElement); let player; async function initializePlayer() { player = YouTubePlayer('video-player-container', { width: 640, height: 360, videoId: 'M7lc1UVf-VE', playerVars: { autoplay: 0, controls: 1 } }); player.on('stateChange', (event) => { const stateName = { '-1': 'unstarted', '0': 'ended', '1': 'playing', '2': 'paused', '3': 'buffering', '5': 'video cued' }[event.data]; console.log(`Player state changed: ${stateName} (Code: ${event.data})`); }); player.on('error', (error) => { console.error('YouTube Player Error:', error); }); try { console.log('Player initialized. Loading video...'); await player.loadVideoById('dQw4w9WgXcQ'); // Rick Astley - Never Gonna Give You Up console.log('Video loaded. Playing...'); await player.playVideo(); setTimeout(async () => { console.log('Pausing video after 5 seconds...'); await player.pauseVideo(); console.log('Video paused. Current time:', await player.getCurrentTime()); }, 5000); setTimeout(async () => { console.log('Stopping video after 10 seconds...'); await player.stopVideo(); console.log('Video stopped.'); // To clean up the player console.log('Destroying player...'); await player.destroy(); console.log('Player destroyed.'); playerElement.remove(); }, 10000); } catch (error) { console.error('Failed to control player:', error); } } initializePlayer();

Debug

Known issues

breakingVersion 5.0.0 introduced breaking changes by removing some internal and deprecated methods. While the change was described as unlikely to break external applications, direct usage of such methods would fail.

fix

Review your code for any reliance on internal or deprecated methods prior to upgrading to v5.0.0. Stick to the documented public API.

affects: >=5.0.0

gotchaThe built version of `youtube-player` does not include polyfills. Applications targeting older browser environments must provide their own polyfills (e.g., for Promises).

fix

Ensure your build process includes necessary polyfills for features like `Promise` if you are supporting older browsers or environments that do not natively provide them.

affects: >=1.0.0

gotchaThe library has not seen significant feature updates since 2018 (v5.5.0) and the last minor fix was in 2019 (v5.6.0). While stable, this could mean slower adoption of new YouTube IFrame Player API features or potential compatibility issues with very recent browser changes if the underlying YouTube API itself evolves rapidly.

fix

Monitor the official YouTube IFrame Player API documentation for any breaking changes or new features you intend to use. Consider the maintenance status when planning for long-term projects.

affects: >=5.6.0

Errors

Common errors & fixes

TypeError: YouTubePlayer is not a function

Incorrect import statement or attempting to use `require()` in an ESM-only context.

fix

Ensure you are using `import YouTubePlayer from 'youtube-player';` at the top of your module. If using CommonJS, ensure your environment supports interop or use appropriate transpilation.

Unhandled Rejection (TypeError): player.playVideo is not a function or player.on is not a function

Attempting to call player methods or register events on the `player` object before it's properly initialized or after it's been destroyed.

fix

All player control methods return promises. Ensure you `await` or chain `.then()` calls for sequential operations. If the player was previously destroyed, you must re-initialize it before using its methods.

ReferenceError: Promise is not defined

Running the library in an environment (e.g., older browser, specific Node.js versions) that lacks native Promise support and no polyfill has been provided.

fix

Include a Promise polyfill (e.g., `core-js`, `es6-promise`) in your application bundle to ensure `Promise` is available globally before `youtube-player` is initialized.

Upgrade

Version history

5.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gajus/youtube-player ↗

packagehttps://www.npmjs.com/package/youtube-player ↗