@aigamo/nostalgic-diva

Nostalgic Diva

React function components for imperatively controlling embedded players (audio, Dailymotion, Niconico, SoundCloud, Twitch, Vimeo and YouTube) using refs.

This was originally developed in VocaDB/vocadb#1101 as a part of VocaDB.

NOTE: This is an independent fork of VocaDB/nostalgic-diva.

Installation

yarn add @aigamo/nostalgic-diva or npm i @aigamo/nostalgic-diva

Usage

import {
	NostalgicDiva,
	NostalgicDivaProvider,
	PlayerOptions,
} from '@aigamo/nostalgic-diva';

// Callbacks
const handleError = React.useCallback(() => {}, []);
const handlePlay = React.useCallback(() => {}, []);
const handlePause = React.useCallback(() => {}, []);
const handleEnded = React.useCallback(() => {}, []);
const handleTimeUpdate = React.useCallback(() => {}, []);

// Options
const options = React.useMemo(
	(): PlayerOptions => ({
		onError: handleError,
		onPlay: handlePlay,
		onPause: handlePause,
		onEnded: handleEnded,
		onTimeUpdate: handleTimeUpdate,
	}),
	[handleError, handlePlay, handlePause, handleEnded, handleTimeUpdate],
);

<NostalgicDivaProvider>
	<NostalgicDiva
		// Supported media types:
		// - "Audio"
		// - "Niconico"
		// - "SoundCloud"
		// - "Vimeo"
		// - "YouTube"
		src="https://www.youtube.com/watch?v=bGdtvUQ9OAs"
		options={options}
	/>
	;
</NostalgicDivaProvider>;

import { useNostalgicDiva } from '@aigamo/nostalgic-diva';

const diva = useNostalgicDiva();

// Play
await diva.play();

// Pause
await diva.pause();

// Mute
await diva.setMuted(true);

// Unmute
await diva.setMuted(false);

// Seek
await diva.setCurrentTime(seconds);

or by using a Web Component

import { defineNostalgicDiva } from '@aigamo/nostalgic-diva';

defineNostalgicDiva();

<nostalgic-diva
	src="https://www.youtube.com/watch?v=bGdtvUQ9OAs"
	id="nostalgic-diva"
/>

import { NostalgicDivaElement } from '@aigamo/nostalgic-diva';

const diva = document.querySelector<NostalgicDivaElement>('#nostalgic-diva');

// Event listeners
diva.addEventListener('error', (e) => {});
diva.addEventListener('play', (e) => {});
diva.addEventListener('pause', (e) => {});
diva.addEventListener('ended', (e) => {});
diva.addEventListener('timeupdate', (e) => {});

// Play
await diva.play();

// Pause
await diva.pause();

// Mute
await diva.setMuted(true);

// Unmute
await diva.setMuted(false);

// Seek
await diva.setCurrentTime(seconds);

Imperative functions

Function	Description
loadVideo(id: string): Promise<void>	Loads a new video into an existing player.
play(): Promise<void>	Plays a video.
pause(): Promise<void>	Pauses the playback of a video.
setCurrentTime(seconds: number): Promise<void>	Sets the current playback position in seconds.
setVolume(volume: number): Promise<void>	Sets the volume level of the player on a scale from 0 to 1.
setMuted(muted: boolean): Promise<void>	Sets the muted state of the player.
getDuration(): Promise<number | undefined>	Gets the duration of the video in seconds.
getCurrentTime(): Promise<number | undefined>	Gets the current playback position of a video, measured in seconds.

Events

Event	Description
onError(event: any): void	Fired when the player experiences some sort of error.
onPlay(): void	Fired when the video plays.
onPause(): void	Fired when the video is paused.
onEnded(): void	Fired when playback reaches the end of a video.
onTimeUpdate(event: TimeEvent): void	Fired when the playback position of the video changes.

Lifecycle

1. PlayerController.attach
2. IPlayerController.loadVideo
3. PlayerOptions.onLoaded
4. IPlayerController.play
5. PlayerOptions.onPlay
6. PlayerOptions.onTimeUpdate
7. IPlayerController.pause
8. PlayerOptions.onPause
9. PlayerOptions.onEnded
10. PlayerController.detach

The attach function is called when switching from another player (Audio, Niconico, SoundCloud and YouTube), and the detach function is called when switching to another player. After the detach function is called, you cannot use any imperative functions like loadVideo, play, pause and etc.

References

• vocadb/VocaDbWeb/Scripts/ViewModels/PVs/
• React Player
• ニコニコ動画の HTML5 外部プレイヤーを JavaScript で操作する
• Widget API - SoundCloud Developers
• Player SDK: Reference - Vimeo Developer
• YouTube Player API Reference for iframe Embeds | YouTube IFrame Player API | Google Developers
• How to support Reusable State in Effects · Discussion #18 · reactwg/react-18
• Synchronizing with Effects
• dailymotion/dailymotion-sdk-js: Dailymotion JavaScript client API
• Video & Clips | Twitch Developers
• bitovi/react-to-web-component: Convert react components to native Web Components. Works with Preact too!
• Using custom elements - Web APIs | MDN