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:

``sh
npm install youtube-iframe-ctrl
`

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.

---

`html
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
>

`

`js
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

$3

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:

`js
youTubeIFrameCtrl.play()
`

$3

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

Example:

`js
youTubeIFrameCtrl.pause()
`

$3

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

Example:

`js
youTubeIFrameCtrl.stop()
`

$3

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

Example:

`js
youTubeIFrameCtrl.mute()
`

$3

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

Example:

`js
youTubeIFrameCtrl.unmute()
`

$3

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

$3

Returns the current player state as a string.

Events

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

$3

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

Example

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

$3

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

`js
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.