@ejoyful/airhbb-player

HbbTV-enabled video player for React with live streaming and interactive broadcast applications.

Features

• 🎥 HLS adaptive streaming with quality selection
• 📺 HbbTV (Hybrid broadcast broadband TV) support
• 🎮 Interactive broadcast applications
• 🎨 Customizable player controls
• 📱 Picture-in-Picture support
• 🎮 Samsung Tizen & LG webOS TV remote control support
• ⚡ Built with React and HLS.js

Installation

npm install @ejoyful/airhbb-player

Usage

import { HbbTVPlayer } from '@ejoyful/airhbb-player';
import '@ejoyful/airhbb-player/styles';

function App() {
  return (
    <HbbTVPlayer
      hlsUrl="https://example.com/stream.m3u8"
      uuid="019abc77-7198-7c99-b101-5954f9753b7e"
      autoPlay={true}
    />
  );
}

Hide colored buttons for embedded layouts:

<HbbTVPlayer
  hlsUrl="https://example.com/stream.m3u8"
  uuid="019abc77-7198-7c99-b101-5954f9753b7e"
  showColoredButtons={false}
/>

Customize button colors:

<HbbTVPlayer
  hlsUrl="https://example.com/stream.m3u8"
  uuid="019abc77-7198-7c99-b101-5954f9753b7e"
  buttonColors={{
    red: '#ff0000',
    green: '#00ff00',
    yellow: '#ffff00',
    blue: '#0000ff'
  }}
/>

Advanced configuration with callbacks:

<HbbTVPlayer
  hlsUrl="https://example.com/stream.m3u8"
  uuid="019abc77-7198-7c99-b101-5954f9753b7e"
  muted={false}
  loop={true}
  defaultQuality={2}
  playbackSpeed={1.25}
  aspectRatio="21/9"
  controlsTimeout={5000}
  onPlay={() => console.log('Video started')}
  onQualityChange={(level, info) => console.log('Quality changed to', info.height + 'p')}
  onColoredButtonClick={(color, keyCode) => console.log(`${color} button pressed`)}
  onHbbtvLoad={() => console.log('HbbTV app loaded')}
/>

Minimal player without HbbTV and buttons:

<HbbTVPlayer
  hlsUrl="https://example.com/stream.m3u8"
  uuid="019abc77-7198-7c99-b101-5954f9753b7e"
  showHbbtvOverlay={false}
  showColoredButtons={false}
  showCustomControls={false}
/>

Props

Required Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | hlsUrl | string | required | URL of the HLS stream | | uuid | string | required | UUID to fetch HbbTV URL from database |

Video Controls & Behavior

| Prop | Type | Default | Description | |------|------|---------|-------------| | autoPlay | boolean | true | Auto-play video on load | | muted | boolean | true | Start video muted | | loop | boolean | false | Loop video playback | | preload | string | 'auto' | Video preload attribute ('auto', 'metadata', 'none') | | poster | string | '' | Poster image URL |

HbbTV Overlay

| Prop | Type | Default | Description | |------|------|---------|-------------| | showHbbtvOverlay | boolean | true | Show/hide HbbTV overlay iframe |

Player UI Controls

| Prop | Type | Default | Description | |------|------|---------|-------------| | showNativeControls | boolean | true | Show native video controls | | showCustomControls | boolean | true | Show custom player controls overlay | | controlsTimeout | number | 3000 | Time in ms before controls auto-hide |

Colored Buttons Customization

| Prop | Type | Default | Description | |------|------|---------|-------------| | showColoredButtons | boolean | true | Show HbbTV colored buttons (Red/Green/Yellow/Blue) | | buttonColors | object | { red: 'red', green: 'green', yellow: 'yellow', blue: 'blue' } | Customize button colors | | buttonHeight | string | '10px' | Height of colored buttons | | buttonPadding | string | '5px' | Padding around button container | | buttonGap | string | '5px' | Gap between buttons | | buttonBorderRadius | string | '4px' | Border radius of buttons |

Quality & Performance

| Prop | Type | Default | Description | |------|------|---------|-------------| | defaultQuality | number | -1 | Default quality level index (-1 for auto) |

Playback Speed

| Prop | Type | Default | Description | |------|------|---------|-------------| | playbackSpeed | number | 1 | Initial playback speed | | playbackSpeedOptions | array | [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2] | Available playback speed options |

Visual Customization

| Prop | Type | Default | Description | |------|------|---------|-------------| | aspectRatio | string | '16/9' | Video container aspect ratio | | videoObjectFit | string | 'fill' | CSS object-fit for video element | | className | string | '' | Additional CSS class | | style | object | {} | Additional inline styles |

Event Callbacks

| Prop | Type | Description | |------|------|-------------| | onPlay | function | Called when video starts playing | | onPause | function | Called when video is paused | | onEnded | function | Called when video ends | | onError | function | Called on video or HLS errors | | onQualityChange | function | Called when quality level changes: (level, levelInfo) => {} | | onHbbtvLoad | function | Called when HbbTV overlay loads | | onColoredButtonClick | function | Called when colored button clicked: (color, keyCode) => {} |

Requirements

This player requires a proxy server to load HbbTV applications. See @ejoyful/airhbb-proxy for the companion proxy server.

TV Remote Control Support

The player includes built-in support for Samsung Tizen and LG webOS TV remote controls, including:

• Colored buttons (Red, Green, Yellow, Blue)
• Media controls (Play, Pause, Stop, Rewind, Fast Forward)
• Navigation keys

For detailed information about testing and deploying to smart TVs, see TV_REMOTE_SUPPORT.md.

License

MIT