react-tv-player v1.1.7

Installation

npm install react-tv-player

Usage

Just import the player and render it in your app or page with props:

import { TVPlayer } from "react-tv-player";

function App() {
  return (
    <>
      <TVPlayer url="https://www.youtube.com/watch?v=SkVqJ1SGeL0" />
    </>
  );
}

👉 Try out the Demo (on TV and desktop browsers)

The demo source code App.tsx illustrates how the component can be initialised with more props such as metadata, custom buttons, preview images and multiple media, enabling the user to cycle through videos with next/previous buttons:

<TVPlayer
  title={mediaList[mediaIndex].title}
  subTitle={mediaList[mediaIndex].subTitle}
  url={mediaList[mediaIndex].url}
  light={mediaList[mediaIndex].preview}
  customButtons={customButtons}
  mediaCount={mediaList.length}
  onLikePress={handleLike}
/>

https://github.com/lewhunt/react-tv-player/assets/9886284/7baa4b75-491b-49f3-8cf1-698ae7f55941

Why Another Player?

I've dedicated years working with various OTT players on big-screen devices. During this journey, two persistent challenges surfaced time and again: performant UI and compatible media encodings. These hurdles often forced us to heavily customise libraries and tackle streaming difficulties, leading to added costs and frustrating delays. 😫

Enter ReactTVPlayer, an open-source media player component for TV devices that lowers the barrier to entry and seamlessly integrates with your React applications. :muscle:

What Sets It Apart?

It's designed for TV experiences out of the box, complete with customisable UI buttons and intuitive cursor plus arrow key navigation. 🎮 In addition to handling HLS and Dash streams effortlessly, it tackles the formidable challenge of playing YouTube and Vimeo urls directly on TV, saving you the hassle and cost of additional video encoding. 🎉

How Does It Work?

Under the hood, this component harnesses the power of open-source libraries like Norigin Media's spatial navigation hook. It builds upon the excellence of React Player, which utilises hls.js and dash.js. Powered by React TypeScript (although you don't need to use TypeScript to make the most of it), this library is packaged efficiently using Vite, making integration a breeze. 🙌

Key Features

• Versatility: Customisable UI buttons, title metadata and preview images to suit your needs. It can effortlessly handle a variety of URLs, from mp4 file paths and HLS/DASH streams to services like YouTube and Vimeo.
• Intuitive Navigation: The player has been designed with TV experiences in mind. Cursor and arrow-key navigation make the user experience smooth and intuitive across big-screen platforms.
• YouTube Integration: One of its unique strengths is its ability to play URLs directly from the likes of YouTube, Vimeo, SoundCloud and Twitch, eliminating the need for additional video encoding when it's not needed.
• DRM Considerations: While it supports HLS AES Encryption, it’s built with flexibility in mind, allowing for future DRM integration with hls.js and dash.js.
• Broad Device Support: From Amazon Fire TV, LG webOS and Samsung Tizen Smart TVs to Xbox consoles and desktop web browsers, ReactTVPlayer covers most big-screen devices running web apps with post-2017 Chromium browsers.

Props

The full list of props are below. Media related values such as playing, loop and muted are also mapped to state which can be accessed via the useTVPlayerStore hook instead of updating props.

Callback Props

Callback props take a function that gets fired on various player events and UI button actions:

Custom Buttons

As illustrated in the sample demo app, the player can be overridden with custom buttons. There is a selection of pre-built action types with their own icons and behaviours or you can add your own with the "custom" action type.

import { TVPlayer, TVPlayerButtonProps } from "react-tv-player";
import { faGithub } from "@fortawesome/free-brands-svg-icons";

const customButtons: TVPlayerButtonProps[] = [
  { action: "loop", align: "left" },
  { action: "like", align: "left" },
  { action: "previous", align: "center" },
  { action: "playpause", align: "center" },
  { action: "next", align: "center" },
  { action: "mute", align: "right" },
  {
    action: "custom",
    align: "right",
    label: "About",
    faIcon: faGithub,
    onPress: () => {
      window.location.href = "https://github.com/lewhunt/react-tv-player";
    },
  },
];

<TVPlayer
  url="https://www.youtube.com/watch?v=SkVqJ1SGeL0"
  customButtons={customButtons}
/>;

useTVPlayerStore Hook

For more control you can import the useTVPlayerStore custom hook to globally access player state (zustand store). View the sample app and the TVPlayerUI inner component for examples of use. Below shows the basics:

// 1. import useTVPlayerStore
import { TVPlayer, useTVPlayerStore } from "react-tv-player";

// 2. get state values (there are more availble, see TVPlayerUI.ts for reference)
const actions = useTVPlayerStore((s) => s.actions);
const playing = useTVPlayerStore((s) => s.playing);
const player = useTVPlayerStore((s) => s.player);
const likeToggle = useTVPlayerStore((s) => s.likeToggle);
s;

const logPlaybackState = () => console.log(playing);

//3. set state using the actions object
const handleLike = () => {
  console.log("like button pressed");
  actions.setLikeToggle(!likeToggle);
};

const togglePlayback = () => {
  actions.setPlaying(!playing);
};

//4. access player instance methods via the player state
const customSeek = () => player.seekTo(player.getCurrentTime() + 10);

<TVPlayer
  url="https://www.youtube.com/watch?v=SkVqJ1SGeL0"
  onLikePress={handleLike}
/>;

Instance Methods

Use the state's player reference - as in the above example - to call instance methods on the player.

👉 Try out the Demo (on TV and desktop browsers)