React-first component architecture (VideoPlayer, PlayerProvider, usePlayerContext)
Protocol-aware playback with automatic detection (native, hls, rtmp/flv, mpegts)
Runtime loading for streaming engines (hls.js, flv.js, mpegts.js) with CDN fallback
Built-in settings UI for speed, quality, audio track, subtitles, and subtitle style editor
Slot-style customization (children, controlsLeftExtra, controlsRightExtra)
Configurable keyboard and touch interaction
TypeScript-first API with strong exported types and an imperative ref handle

Installation

This package is published to a private registry.

Configure .npmrc:

@source:registry=https://gits.hibna.com.tr/api/packages/hibna/npm/
//gits.hibna.com.tr/api/packages/hibna/npm/:_authToken=${GITS_NPM_TOKEN}

Install:

npm install @source/player
# or
pnpm add @source/player
# or
yarn add @source/player

Ensure your app already has React and ReactDOM installed (>=18).

Optional local dependencies (if you prefer bundling instead of CDN fallback):

npm install hls.js flv.js mpegts.js

Quick start

import { VideoPlayer } from '@source/player'
import '@source/player/styles.css'

export function App() {
  return <VideoPlayer src="https://example.com/video.mp4" />
}

Common usage scenarios

1. Standard VOD playback

<VideoPlayer
  src="https://cdn.example.com/movie.mp4"
  poster="https://cdn.example.com/poster.jpg"
  controlsAutoHideDelay={2500}
/>

2. HLS playback with quality/audio menus

<VideoPlayer
  src="https://stream.example.com/master.m3u8"
  onQualityChange={(quality) => console.log('quality', quality.label)}
/>

3. IPTV MPEG-TS stream

<VideoPlayer
  src="http://provider.example/live/user/pass/channel.ts"
  protocol="mpegts"
/>

4. Subtitle style editor with local persistence

<VideoPlayer
  src="https://example.com/video.mp4"
  subtitles={[{ src: '/subs/en.vtt', lang: 'en', label: 'English', default: true }]}
  subtitleStyleEditor={{
    enabled: true,
    storageKey: 'my-player-subtitle-style',
  }}
/>

5. Modular control customization

<VideoPlayer
  src="https://example.com/video.mp4"
  controlsLeftExtra={<button type="button">Bookmark</button>}
  controlsRightExtra={<button type="button">Share</button>}
  theme={{
    primaryColor: '#22c55e',
    accentColor: '#16a34a',
    borderRadius: 18,
    fontFamily: 'Manrope, sans-serif',
  }}
/>

API at a glance

Key VideoPlayer props:

Playback: src, protocol, autoplay, loop, muted, volume, playbackRate, currentTime
Media element config: crossOrigin, preload, playsInline, controlsList
UI toggles: controls, keyboardShortcuts, pictureInPicture
Customization: theme, className, style, aspectRatio, playbackRates
Subtitles: subtitles, subtitleStyle, subtitleStyleEditor, subtitlePosition, subtitleOffset
Extensibility: children, controlsLeftExtra, controlsRightExtra
Input config: keyboardShortcutConfig, touchConfig
Localization: language, translations
Events: onPlay, onPause, onEnded, onTimeUpdate, onError, onQualityChange, onBufferStart, onBufferEnd, onFirstPlay, and more

Imperative control via ref

import { useRef } from 'react'
import { VideoPlayer, type VideoPlayerHandle } from '@source/player'

export function PlayerWithRef() {
  const playerRef = useRef<VideoPlayerHandle>(null)

  return (
    <>
      <VideoPlayer ref={playerRef} src="https://example.com/video.mp4" />
      <button type="button" onClick={() => playerRef.current?.seek(120)}>
        Jump to 02:00
      </button>
    </>
  )
}

Other exports

import {
  PlayerErrorBoundary,
  PlayerProvider,
  usePlayerContext,
  useKeyboardShortcuts,
  useTouchGestures,
  formatTime,
  parseTime,
  parseSRT,
  createSubtitleBlobURL,
  fetchSubtitle,
  validateVideoURL,
  checkVideoCORS,
  initializePolyfills,
  features,
  getTranslations,
  detectBrowserLanguage,
} from '@source/player'

Documentation map

For complete details, see DOCUMENTATION.md:

Full VideoPlayerProps and event reference
Streaming architecture (HLS/RTMP-FLV/MPEG-TS)
Subtitle rendering and style editor internals
Theme tokens and CSS variable mapping
Keyboard and touch behavior
Error handling and browser caveats

Development

npm install
npm run dev
npm run test:run
npm run build:lib

Useful scripts:

npm run lint
npm run typecheck
npm run validate:publish

License

MIT