hibna
Repositories
1
 Projects Packages Public Activity Starred Repositories

@source/player (3.1.2)

Published 2026-02-13 03:12:04 +00:00 by hibna

Installation

@source:registry=
npm install @source/player@3.1.2
"@source/player": "3.1.2"

About this package

@source/player

@source/player is a modular, highly customizable React video player library for VOD and live streaming workflows.

Current package version: 3.1.0.

Why this player

  • 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.

  1. 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}
  1. Install:
npm install @source/player
# or
pnpm add @source/player
# or
yarn add @source/player
  1. 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

Dependencies

Development Dependencies

ID Version
@eslint/js ^9.38.0
@testing-library/jest-dom ^6.9.1
@testing-library/react ^16.3.0
@testing-library/user-event ^14.6.1
@types/react ^19.2.2
@types/react-dom ^19.2.2
@typescript-eslint/eslint-plugin ^8.46.2
@typescript-eslint/parser ^8.46.2
@vitejs/plugin-react ^5.1.0
@vitest/ui ^4.0.4
baseline-browser-mapping ^2.9.19
eslint ^9.38.0
eslint-plugin-react-hooks ^7.0.1
eslint-plugin-react-refresh ^0.4.24
globals ^16.4.0
jsdom ^27.0.1
prettier ^3.6.2
react ^19.2.0
react-dom ^19.2.0
terser ^5.44.0
typescript ^5.9.3
vite ^7.1.12
vite-plugin-dts ^4.5.4
vitest ^4.0.4

Keywords

react video player video-player hls rtmp flv mpegts iptv streaming media
Details
npm
2026-02-13 03:12:04 +00:00
5
Alper
MIT
66 KiB
Assets (1)
player-3.1.2.tgz 66 KiB
Versions (8) View all
3.2.0 2026-02-14
3.1.2 2026-02-13
3.1.1 2026-02-13
3.1.0 2026-02-13
3.0.1 2026-02-13