youtube-iframe-ctrl

YouTube iFrame Controller

Simple YouTube iFrame controller with no additional dependencies and no YouTube iFrame API script.

Demo with examples: youtube-iframe-ctrl.mihau.co

Toss a Coin to Your Developer

If you this package helped you and you would like to spare me some change - you can do it via buymeacoffee.com or buycoffee.to.

The official YouTube documentation requires you to add an external script to your page and create an iFrame with JavaScript to control the player inside the iFrame. This can be complicated if you only want to perform simple actions. Most packages available on NPM are just wrappers for the official YouTube script (downloading it under the hood and exposing the same API). This module does not require the official YouTube iFrame API script or any other dependencies. It contains just a few lines of code and provides all the functionalities of the official API.

Table of Contents

• Installation
• Usage
• Methods
• Properties
• Events
• Quick note about autoplay

Installation

To install the YouTubeIFrameCtrl you can use npm:

npm install youtube-iframe-ctrl@1.0.0-beta

Usage

Here's an example of how to use the YouTubeIFrameCtrl:

Add iframe to your page / html.

IMPORTANT NOTE:

You must add enablejsapi=1 query parameter to YouTube url - otherwise iFrame controller will not work.

<iframe
  id="youtube-iframe"
  src="https://www.youtube-nocookie.com/embed/jNQXAC9IVRw?enablejsapi=1"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  referrerpolicy="strict-origin-when-cross-origin"
  allowfullscreen
>
</iframe>

import YouTubeIFrameCtrl from 'youtube-iframe-ctrl';

// Assuming you have an iframe element with id 'youtube-iframe'
const iframeElement = document.getElementById('youtube-iframe');
const youTubeIFrameCtrl = new YouTubeIFrameCtrl(iframe);

async function play() {
  // Mute video
  await youTubeIFrameCtrl.mute()
  // Play video
  await youTubeIFrameCtrl.play()
}

play()

Methods

async play(): Promise<void>

Plays the video. Under the hood it uses command() method. IMPORTANT! If you would like autoplay a video it must be muted first! More info at the end of readme.

Example:

youTubeIFrameCtrl.play()

async pause(): Promise<void>

Pauses the video. Under the hood it uses command() method.

Example:

youTubeIFrameCtrl.pause()

async stop(): Promise<void>

Stops the video. Under the hood it uses command() method.

Example:

youTubeIFrameCtrl.stop()

async mute(): Promise<void>

Mutes the video. Under the hood it uses command() method.

Example:

youTubeIFrameCtrl.mute()

async unMute(): Promise<void>

Unmutes the video. Under the hood it uses command() method.

Example:

youTubeIFrameCtrl.unmute()

async command(command: string, args?: any[]): Promise<void>

Sends a command to the YouTube player. command argument can be a name of any command accepted by YouTube iFrame player API, below you'll find a list of all know commands (it's based on my foundings after studing some YouTube player JS source files):

Command	Arguments	Info
play	-	Play video (you can use play method of YouTube iFrame Controller instead)
pause	-	Pause video (you can use pause method of YouTube iFrame Controller instead)
stop	-	Stop video (you can use stop method of YouTube iFrame Controller instead)
mute	-	Mute video (you can use mute method of YouTube iFrame Controller instead)
unMute	-	Unmute video (you can use unMute method of YouTube iFrame Controller instead)
seekTo	seconds: number, allowSeekAhead: boolean	Seek to a specified time in seconds
setVolume	volume: number	Set the volume (0-100)

Properties

playerState: string

Returns the current player state as a string.

Events

YouTube iFtame Controller adds some custom events to the iFrame element.

ytstatechange

Dispatched when the player state changes. The event detail contains the new player state.

Example

iframeElement.addEventListener('ytstatechange', (event) => {
  console.log('Player state changed to:', event.detail);
});

ytmessage

Dispatched when a message is received from the YouTube player. The event detail contains the message data.

iframeElement.addEventListener('ytmessage', (event) => {
  console.log('Message sent from youtube player:', event.detail);
});

Quick note about autoplay

YouTube does not allow unmuted videos to autoplay without user interaction (likely using UserActivation to check if user interacted with the page, though I haven't confirmed it). If you want to play a YouTube video on page load, it must be muted first.