player/README.md

# @source/player

`@source/player` is a modular, highly customizable React media player library for VOD, live streaming, animated images, and audio playback workflows.

Current package version: `3.2.0`.

## Why this player

- React-first component architecture (`VideoPlayer`, `AudioPlayer`, `PlayerProvider`, `usePlayerContext`)
- Protocol-aware playback with automatic detection (`native`, `hls`, `rtmp/flv`, `mpegts`)
- Built-in animated image support (`.gif`, `.webp`, `.apng`, `.avif`) with minimal render path
- Dedicated audio player component for `.mp3`, `.wav`, `.flac`, `.m4a`, and similar formats
- 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`:

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

2. Install:

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

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

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

```bash
npm install hls.js flv.js mpegts.js
```

## Quick start

```tsx
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

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

### 2. HLS playback with quality/audio menus

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

### 3. IPTV MPEG-TS stream

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

### 4. Subtitle style editor with local persistence

```tsx
<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

```tsx
<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',
  }}
/>
```

### 6. Animated image playback (GIF / WebP / APNG / AVIF)

```tsx
<VideoPlayer src="https://cdn.example.com/loop.gif" />
```

### 7. Dedicated audio player

```tsx
import { AudioPlayer } from '@source/player'

<AudioPlayer
  src="https://cdn.example.com/podcast-episode.mp3"
  title="Episode 12"
  subtitle="Weekly Tech Podcast"
  artwork="https://cdn.example.com/episode-cover.jpg"
  playbackRates={[0.75, 1, 1.25, 1.5, 2]}
/>
```

## API at a glance

Key `VideoPlayer` props:

- Playback: `src`, `mediaType`, `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

Key `AudioPlayer` props:

- Source + playback: `src`, `autoplay`, `loop`, `muted`, `volume`, `playbackRate`, `currentTime`
- UI + customization: `controls`, `keyboardShortcuts`, `playbackRates`, `theme`, `className`, `style`
- Metadata + slots: `title`, `subtitle`, `artwork`, `children`, `controlsLeftExtra`, `controlsRightExtra`
- Localization + events: `language`, `translations`, `onPlay`, `onPause`, `onTimeUpdate`, `onError`, and more

## Imperative control via ref

```tsx
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

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

## Documentation map

For complete details, see `DOCUMENTATION.md`:

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

## Development

```bash
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