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
- Automatically loads the YouTube IFrame API
- 🚀 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:
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.