Install the package using your preferred package manager.
npm install --save hls-hooks
yarn add hls-hooks
The provider is responsible for creating the state used by the player. All hooks used must be in the child components of the provider. You can specify some default values to the provider. You could add the provider to the root render call as an example.
import {HlsHooksProvider} from "hls-hooks";
// ...
root.render(
<React.StrictMode>
<HlsHooksProvider
source="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
>
<App />
</HlsHooksProvider>
</React.StrictMode>
);The video element is responsible for rendering the player. It accepts the same attributes as the html <video> element (it is really just a wrapper around the <video> tag that adds the required events).
import React from "react";
import {Video} from "hls-hooks";
const App = () => {
return (
<div>
<Video />
</div>
);
};
export default App;Hooks provide the main functionality to build your player. Let's extend the previous component to include a play/pause button.
import React from "react";
import {Video, useIsPlaying} from "hls-hooks";
const App = () => {
const [isPlaying, setIsPlaying] = useIsPlaying();
return (
<div>
<Video />
<button
onClick={() => setIsPlaying(!isPlaying)}
>
{isPlaying ? "Pause" : "Play"}
</button>
</div>
);
};
export default App;The library follows semantic versioning. Breaking changes will see a major version bump, new features will be a minor version bump and fixes will be patch versions.
import {HlsHooksProvider} from "hls-hooks";
return (
<HlsHooksProvider
volume={0.5}
position={35}
source="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
playbackRate={1.0}
>
...
</HlsHooksProvider>
);Creates a new context for a video player. To display the video player you should include a <Video /> child element.
Default value: 1.0
A number between 0 and 1 to use as the initial volume of the player.
Default value: undefined
Position to start at in the video, in seconds. Ignored if the default source is not also defined.
Default value: undefined
Video to load on initialisation.
Default value: 1.0
The default speed to play the video at.
See Events.
import {Video} from "hls-hooks";
return (
<Video />
);Renders the video from a <HlsHooksProvider>.
See <video> on MDN.
import {useAudioTrack, MediaPlaylist} from "hls-hooks";
const useAudioTrack: () => [
available: MediaPlaylist[],
selected: number | undefined
];Get the available audio tracks, and any currently selected track.
import {useAvailable} from "hls-hooks";
const useAvailable: () => [number, number][];Get a list of ranges that have been buffered.
NOTE: The first item in the list may not start with exactly zero, even if the video has been played from the start.
import {useDuration} from "hls-hooks";
const useDuration: () => number|undefined;Get the duration of the video.
import {useIsPlaying} from "hls-hooks";
const useIsPlaying: () => [
isPlaying: boolean,
setIsPlaying: (isPlaying: boolean) => void
];Get or set if the video is currently playing (or paused).
import {usePlaybackState} from "hls-hooks";
const usePlaybackState: () => [
playbackState: HlsPlaybackStates,
setPlaybackState: (playbackState: HlsPlaybackStates) => void
];Get or set the current playback state.
Possible states:
none- the video player is newly createdloading- the video is bufferingready- the video has loaded enough to begin playbackplaying- the video is playingpaused- the video is pausederror- the player has had an unrecoverable error
import {usePosition} from "hls-hooks";
const usePosition: () => [
position: number|undefined,
setPosition: (position: number) => void
];Get or set the current position in the video, in seconds.
import {useQuality} from "hls-hooks";
const useQuality: () => [
qualities: Level[],
quality: number|undefined
];Get the available qualities, and any currently selected quality.
import {useRefs} from "hls-hooks";
const useRefs: () => [
videoElementRef?: RefObject<HTMLVideoElement>,
hlsRef?: RefObject<Hls|null>
];Get references to the current <video> element and the HLS.js Hls object.
import {useSource} from "hls-hooks";
const useSource: () => [
source: string|undefined,
setSource: (source: string|undefined) => void
];Get or set the current video source.
import {useSubtitleTrack, MediaPlaylist} from "hls-hooks";
const useSubtitleTrack: () => [
available: MediaPlaylist[],
selected: number | undefined
];Get the available subtitle tracks, and any currently selected track.
import {useVolume} from "hls-hooks";
const useVolume: () => [
volume: number,
muted: boolean,
setVolume: (volume: number) => void,
setMuted: (muted: boolean) => void
];Get or set the volume and muted status.
NOTE: Muting instead of setting the volume to zero will restore the previous volume level on unmute.
Event raised when the source of the video is changed.
Event raised when the volume is changed.
Event raised when the available qualities are changed.
Event raised when the selected quality is changed.
Event raised when the available audio tracks change.
Event raised when the selected audio track changes.
Event raised when the available subtitle tracks change.
Event raised when the selected subtitle track changes.
Event raised when the current position in the video is changed.
Event raised when the length of the video is changed.
Event raised when the amount of video that is buffered changes.
Event raised when the playback speed changes.
Event raised when the playback state of the video changes.