youtube-player-plus v0.1.7
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.