youtube-player-plus

Youtube Player Plus ✨

Youtube Player Plus is an easy-to-use and customizable library for embedding video playback from Youtube in your web application.

Inspired by this package: yt-player

Features

• 🌐 Utilizes the YouTube IFrame Player API
• ⚡️ Offers an incredibly fast initial loading time
  • Automatically loads the YouTube IFrame API <script> during first use
  • For an even quicker start, include <script src='https://www.youtube.com/iframe_api' defer></script> in your webpage
  • Ensures API <script> isn't loaded twice by detecting its presence
• 🚀 API commands are smoothly queued up (wait until both IFrame API and Player instance are ready)
• ⚠️  Distinguishes between serious errors and unplayable video issues
• ⏲️ Incorporates the crucial 'timeupdate' event that YouTube API is missing
• 💡 Clear and detailed code comments for easy comprehension
• 💯 Strongly typed.
• 📦 Does not rely on large dependencies or unnecessary code

Installation

Use the package manager npm to install youtube-player-plus.

 npm i youtube-player-plus

Usage

Quick Start

1.  Install and import YouTubePlayerPlus:

import YouTubePlayerPlus from 'youtube-player-plus';

2.  Create an instance with an element reference and an optional config object:

const element = 'your-element-selector'; // Or an HTMLElement reference
const options = {}; // Optional configuration object
const player = new YouTubePlayerPlus(element, options);

3.  Load a video and control playback:

player.load(videoId, autoplay, start);
player.play();
player.pause();
player.stop();

4.  Listen to events:

import type { YTAPI_PlaybackQuality, YTAPI_PlaybackRate } from 'youtube-player-plus/types'

player.on('playing', () => {});

player.on('timeupdate', (current_time: number) => {
    console.log('Current time:', current_time);
})

player.on('playbackQualityChange', (quality: YTAPI_PlaybackQuality) => {
    console.log('Player quality changed to', quality)
})

player.on('playbackRateChange', (rate: YTAPI_PlaybackRate) => {
    console.log('Player rate changed to', rate)
})

Constructor

YouTubePlayerPlus(element: HTMLElement | string, options?: YT_IFRAME_OPTIONS)

Parameters

element : HTMLElement or CSS selector - Target element or CSS selector where the YouTube player will be initialized.

options : Object - Optional configuration object for the YouTube player, default values specified below:

Property	Type	DefaultValue	Description
width	number	640	The width of the player
height	number	360	The height of the player
autoplay	boolean	false	Determines if the video should autoplay when loaded
captions	string	undefined	Sets the default language for captions
controls	boolean	true	Indicates whether the video player controls are displayed
keyboard	boolean	true	Enables/disables keyboard controls
fullscreen	boolean	true	Determines if the fullscreen button is displayed in the player
annotations	boolean	true	Displays video annotations by default
modestBranding	boolean	false	Hides the YouTube logo in the control bar
relatedVideos	boolean	true	Shows related videos from the same channel (0) or any channel (1) when playback ends
timeUpdateFrequency	number	0	Determines the frequency (in ms) of 'timeupdate' events being emitted
playsInline	boolean	true	Controls whether videos play inline or fullscreen on iOS
start	number	0	Sets the start time of the video in seconds
debug	boolean	false	Enables debug mode which logs additional messages to console
host	string	'https://www.youtube-nocookie.com'	Determines the hostname where videos are loaded from

Methods

Method	Description
load(videoId: string, autoplay?: boolean, start?: number)	Load the YouTube video.
play()	Play the loaded video.
pause()	Pause the loaded video.
stop()	Stop the loaded video.
seek(seconds: number)	Set the current playback time in seconds.
setVolume(volume: number)	Sets the player volume.
getVolume(): number	Gets the current player volume.
mute()	Mutes the player.
unMute()	Unmutes the player.
isMuted(): boolean	Get the current mute state of the player.
setSize(width: number, height: number)	Set the player's size, using the provided width and height values.
getSize(): {width: number, height: number}	Get the current player size.
setPlaybackRate(rate: number)	Sets the playback rate.
getPlaybackRate(): number	Gets the current playback rate.
getAvailablePlaybackRates(): number[]	Get a list of available playback rates.
setPlaybackQuality(suggestedQuality: YT_PLAYBACK_QUALITIES)	Sets the suggested playback quality.
getPlaybackQuality(): string	Gets the current playback quality.
getAvailablePlaybackQualities(): string[]	Get a list of available playback qualities.
getDuration(): number	Gets the total video duration in seconds.
getProgress(): number	Gets the loaded video fraction, ranging from 0 to 1.
getState(): string	Gets the current player state.
getYouTubeInstance(): object	Gets the currently used YouTube Player API instance, if available.
getPercentageWatched(): number	Gets the percentage of the video watched relative to the total duration, 0 to 1.
getCurrentTime(): number	It returns the current time of the video in seconds.
destroy()	Destroys the player instance and removes event listeners.

Getters/Setters

Property	Getter	Setter	Description
currentTime	✓	✓	Get or set the current playback time in seconds.
volume	✓	✓	Get or set the player volume.
muted	✓	✓	Get or set the mute state of the player.
size	✓	✓	Get or set the player size with a given width and height; retrieves the current size.
playbackRate	✓	✓	Get or set the playback rate.
playbackQuality	✓	✓	Get or set the current/suggested playback quality.
availablePlaybackQualities	✓		Get a list of available playback qualities.
availablePlaybackRates	✓		Get a list of available playback rates.
duration	✓		Gets the total video duration in seconds.
progress	✓		Gets the loaded video fraction, ranging from 0 to 1.
state	✓		Gets the current player state.
youTubeInstance	✓		Gets the currently used YouTube Player API instance, if available.
percentageWatched	✓		Gets the percentage of the video watched relative to the total duration, 0 to 1.

Events

Event	Data
error	error: Error
unplayable	videoId: string
timeupdate	currentTime: number
unstarted
ended
playing
cued
playbackQualityChange	quality: YTAPI_PlaybackQuality
playbackRateChange	rate: YTAPI_PlaybackRate
stateChange
ready
buffering

Listen to events

To listen to an event:

player.on('event-name', (eventData) => {
  // Your event handling logic here
});

To stop listening to an event:

player.removeListener('event-name', eventHandlerFunction);

Examples:

• vanilla-ts

Contributing

Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT