{"id":14392,"library":"youtube-player","title":"YouTube IFrame Player Abstraction","description":"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.","status":"maintenance","version":"5.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/gajus/youtube-player","tags":["javascript","youtube","iframe","player","api","promise","async","video"],"install":[{"cmd":"npm install youtube-player","lang":"bash","label":"npm"},{"cmd":"yarn add youtube-player","lang":"bash","label":"yarn"},{"cmd":"pnpm add youtube-player","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ESM imports; CommonJS `require` might work in some transpiled environments but ESM is preferred. `YouTubePlayer` is a factory function.","wrong":"const YouTubePlayer = require('youtube-player');","symbol":"YouTubePlayer","correct":"import YouTubePlayer from 'youtube-player';"},{"note":"The library uses its own `.on()` and `.off()` event emitter API, not standard DOM event listeners.","wrong":"player.addEventListener('stateChange', (event) => { /* ... */ });","symbol":"player.on","correct":"player.on('stateChange', (event) => { /* ... */ });"},{"note":"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.","wrong":"player.loadVideoById('VIDEO_ID'); // Not waiting for promise","symbol":"player.loadVideoById","correct":"player.loadVideoById('VIDEO_ID').then(() => { /* ... */ });"}],"quickstart":{"code":"import YouTubePlayer from 'youtube-player';\n\n// In a real application, this div would already exist in your HTML.\n// For demonstration, we'll simulate its presence.\nconst playerElement = document.createElement('div');\nplayerElement.id = 'video-player-container';\ndocument.body.appendChild(playerElement);\n\nlet player;\n\nasync function initializePlayer() {\n  player = YouTubePlayer('video-player-container', {\n    width: 640,\n    height: 360,\n    videoId: 'M7lc1UVf-VE',\n    playerVars: {\n      autoplay: 0,\n      controls: 1\n    }\n  });\n\n  player.on('stateChange', (event) => {\n    const stateName = {\n      '-1': 'unstarted',\n      '0': 'ended',\n      '1': 'playing',\n      '2': 'paused',\n      '3': 'buffering',\n      '5': 'video cued'\n    }[event.data];\n    console.log(`Player state changed: ${stateName} (Code: ${event.data})`);\n  });\n\n  player.on('error', (error) => {\n    console.error('YouTube Player Error:', error);\n  });\n\n  try {\n    console.log('Player initialized. Loading video...');\n    await player.loadVideoById('dQw4w9WgXcQ'); // Rick Astley - Never Gonna Give You Up\n    console.log('Video loaded. Playing...');\n    await player.playVideo();\n\n    setTimeout(async () => {\n      console.log('Pausing video after 5 seconds...');\n      await player.pauseVideo();\n      console.log('Video paused. Current time:', await player.getCurrentTime());\n    }, 5000);\n\n    setTimeout(async () => {\n      console.log('Stopping video after 10 seconds...');\n      await player.stopVideo();\n      console.log('Video stopped.');\n\n      // To clean up the player\n      console.log('Destroying player...');\n      await player.destroy();\n      console.log('Player destroyed.');\n      playerElement.remove();\n    }, 10000);\n\n  } catch (error) {\n    console.error('Failed to control player:', error);\n  }\n}\n\ninitializePlayer();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"The built version of `youtube-player` does not include polyfills. Applications targeting older browser environments must provide their own polyfills (e.g., for Promises).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=5.6.0"}],"env_vars":null,"search_vec":"'2019':81 '5.6.0':74 'abstract':4,11 'address':21 'allow':52 'api':19,37,60,98,130 'applic':125 'async':132 'automat':99 'base':97 'call':38 'callback':28,109 'chainabl':59 'churn':89 'cleaner':113 'common':22 'control':120 'current':70 'differenti':92 'emb':118 'ensur':30 'experi':61 'function':48,110 'global':27,107 'ifram':2,17,128 'includ':93 'indic':82 'interact':64 'interfer':105 'javascript':126 'key':91 'last':77 'layer':12 'like':25 'listen':35 'look':58 'low':88 'low-churn':87 'manag':26,101 'matur':84 'non':104 'non-interfer':103 'notabl':78 'offer':111 'offici':15 'pain':23 'player':3,7,18,31,41,47,68,129 'point':24 'project':90 'promis':50,96,131 'promise-bas':95 'provid':8 'queu':36 'readi':32,43 'regist':34 'relat':86 'reliabl':115 'robust':10 'signific':62 'simplifi':63 'stabl':71 'state':100 'synchron':57 'synchronous-look':56 'updat':79 'version':72 'video':122,133 'way':116 'web':124 'wrap':45 'yipa':108 'youtub':1,6,16,67,121,127 'youtube-play':5","created_at":"2026-04-20T01:59:28.470685+00:00","updated_at":"2026-04-20T01:59:28.470685+00:00","problems":[{"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.","cause":"Incorrect import statement or attempting to use `require()` in an ESM-only context.","error":"TypeError: YouTubePlayer is not a function"},{"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.","cause":"Attempting to call player methods or register events on the `player` object before it's properly initialized or after it's been destroyed.","error":"Unhandled Rejection (TypeError): player.playVideo is not a function or player.on is not a function"},{"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.","cause":"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.","error":"ReferenceError: Promise is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/gajus/youtube-player","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/youtube-player","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}