# ๐ฌ Modern Video Player
[](https://www.npmjs.com/package/@source/player)
[](https://bundlephobia.com/package/@source/player)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
**A compact, feature-rich React video player** with zero runtime dependencies.
A feature-rich, modern video player library built with React, TypeScript, and Vite. Designed for reusability across multiple projects.
## ๐ Why Choose This Player?
| Feature | @source/player | video.js | react-player | plyr |
| ------------------------- | ---------------------------- | ---------- | ------------ | ---------- |
| **Bundle Size (gzipped)** | **~18KB JS + ~3.5KB CSS** โ
| ~500KB โ | ~50KB โ ๏ธ | ~30KB โ ๏ธ |
| **Runtime Dependencies** | **0** โ
| Many โ | Few โ ๏ธ | Few โ ๏ธ |
| **React (Web)** | **Yes** โ
| Wrapper โ ๏ธ | **Yes** โ
| Wrapper โ ๏ธ |
| **TypeScript Native** | **Yes** โ
| Types โ ๏ธ | Partial โ ๏ธ | Types โ ๏ธ |
| **HLS Support** | **Yes** โ
| Yes โ
| Yes โ
| No โ |
| **Quality Switching** | **Yes** โ
| Yes โ
| Limited โ ๏ธ | No โ |
| **Touch Gestures** | **15+** โ
| Limited โ ๏ธ | No โ | Limited โ ๏ธ |
| **Keyboard Shortcuts** | **15+** โ
| ~8 โ ๏ธ | Basic โ ๏ธ | ~10 โ ๏ธ |
| **i18n Support** | **Yes** โ
| Yes โ
| No โ | Yes โ
|
### Key Advantages
- ๐ฆ **Compact bundle** - Core player ships around ~18KB gzipped JS (+ ~3.5KB CSS)
- โก **Blazing fast** - Zero runtime dependencies means faster load times
- ๐ฏ **React-first** - Built specifically for React, not a wrapper
- ๐ง **Full TypeScript** - Complete type safety out of the box
- ๐จ **Easy customization** - CSS variables for theming
- ๐ฑ **Mobile-ready** - Comprehensive touch gesture support
- ๐ **Internationalized** - Built-in i18n with English and Turkish
- โฟ **Accessible** - ARIA labels and keyboard navigation
## โจ Features
### ๐ฎ Core Playback
- โถ๏ธ Play/Pause controls
- โญ๏ธ Seek/scrub with progress bar
- ๐ Volume control with slider
- ๐๏ธ Playback speed control
- ๐ Loop support
- ๐ผ๏ธ Custom poster/thumbnail
### ๐จ Modern UI
- Clean, minimalist design with red theme
- Smooth animations and transitions
- Auto-hiding controls
- Responsive layout (desktop & mobile)
- Custom SVG icons
- Loading spinner
- Center play button
### โจ๏ธ Keyboard Shortcuts
- `Space` or `K` - Play/Pause
- `โ` / `โ` - Seek 5 seconds
- `J` / `L` - Seek 10 seconds
- `โ` / `โ` - Volume up/down
- `M` - Mute/Unmute
- `F` - Fullscreen toggle
- `P` - Picture-in-Picture
- `0-9` - Jump to percentage (10%-90%)
- `Home` / `End` - Jump to start/end
- Shortcuts only work for the currently active/focused player instance
### ๐ฑ Touch Gestures
- **Tap** - Play/Pause
- **Double tap left** - Rewind 10 seconds
- **Double tap right** - Forward 10 seconds
- **Swipe left/right** - Seek
- **Swipe up/down** - Volume control
### ๐ Advanced Features
- **HLS Streaming** - Automatic HLS.js integration for .m3u8 files
- **IPTV Support** - MPEG-TS (.ts) streams for IPTV services
- **HTTP Range Request** - Progressive download for large MP4 files
- **Subtitles** - WebVTT and SRT support
- **Subtitle Style Editor** - Optional in-player style controls with live preview and local persistence
- **Multiple Audio Tracks** - Switch between different audio streams
- **Picture-in-Picture** - Native browser PIP support
- **Fullscreen** - Native fullscreen API
- **Buffer Indicator** - Visual buffering progress
- **Error Handling** - Graceful error states
## ๐ฆ Installation
This package is distributed through a private registry.
### 1. Configure `.npmrc`
Create `.npmrc` in your app root:
```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. Set token
Set your token in environment variables (`GITS_NPM_TOKEN`) and do not commit `.npmrc` with a hardcoded token.
### 3. Install package
```bash
npm install @source/player
# or
pnpm add @source/player
# or
yarn add @source/player
```
> **Note:** This package requires `react` (>=18) and `react-dom` (>=18) at runtime but does **not** list them as `peerDependencies` to avoid install conflicts with private registries. Make sure your project already has React installed.
> **Streaming libraries (optional):** HLS, FLV and MPEG-TS streaming libraries are loaded automatically from CDN when needed. If you prefer to bundle them locally, install them separately:
>
> ```bash
> npm install hls.js # HLS (.m3u8) streams
> npm install flv.js # FLV/RTMP streams
> npm install mpegts.js # MPEG-TS (.ts) streams
> ```
### Local development (optional)
```bash
# In this repository
npm run build:lib
npm link
# In your consuming app
npm link @source/player
```
## ๐ Usage
### Basic Example
```tsx
import { VideoPlayer } from '@source/player'
import '@source/player/styles.css'
function App() {
return
}
```
### Error Boundary (Optional)
```tsx
import { VideoPlayer, PlayerErrorBoundary } from '@source/player'
import '@source/player/styles.css'
function App() {
return (
)
}
```
### With Subtitles
```tsx
```
### Subtitle Styling (Custom Renderer)
```tsx
```
### Subtitle Style Editor (Optional)
```tsx
```
`enabled: true` adds a subtitle style editor in `Settings > Subtitles`.
Changes are previewed in real-time and saved to `localStorage` only when the user presses `Save`.
### HLS Streaming
```tsx
```
### Force Protocol (Override Auto Detection)
```tsx
```
### IPTV Streaming
```tsx
// Note: Browser support for direct .ts streams is limited
// For best compatibility, request .m3u8 (HLS) links from your IPTV provider
{
console.error('Stream error - try requesting .m3u8 format:', error)
}}
/>
```
### Custom Theme
```tsx
```
### With Volume and Playback Control
```tsx
```
### With Event Handlers
```tsx
console.log('Video started playing')}
onPause={() => console.log('Video paused')}
onEnded={() => console.log('Video ended')}
onTimeUpdate={(time) => console.log('Current time:', time)}
onVolumeChange={(volume) => console.log('Volume:', volume)}
onRateChange={(rate) => console.log('Playback rate:', rate)}
onFullscreenChange={(isFs) => console.log('Fullscreen:', isFs)}
onError={(error) => console.error('Video error:', error)}
/>
```
### Feature Detection & Polyfills
```tsx
import { features, initializePolyfills } from '@source/player'
// Initialize polyfills manually (optional - auto-initialized on VideoPlayer mount)
initializePolyfills()
// Check browser capabilities
console.log('Has PIP support:', features.hasPIP())
console.log('Has native HLS:', features.hasNativeHLS())
console.log('Has MSE for HLS.js:', features.hasMSE())
console.log('Is iOS Safari:', features.isIOSSafari())
console.log('Has volume control:', features.hasVolumeControl())
// Hide PIP button on unsupported devices
```
### CORS Error Handling
```tsx
import { validateVideoURL, checkVideoCORS } from '@source/player'
// Validate URL before loading
const validation = validateVideoURL(videoUrl)
if (!validation.valid) {
console.error(validation.error)
}
// Check CORS support (async)
const corsCheck = await checkVideoCORS(videoUrl)
if (!corsCheck.supported) {
console.error('CORS issue:', corsCheck.error)
console.log('Needs proxy:', corsCheck.needsProxy)
}
```
## ๐ ๏ธ Development
### Setup
```bash
# Install dependencies
npm install
# Start development server
npm run dev
# Build library
npm run build:lib
# Type check
npx tsc --noEmit
# Format check
npm run format:check
# Full publish validation
npm run validate:publish
```
### Project Structure
```
video-player/
โโโ src/
โ โโโ components/ # React components
โ โ โโโ controls/ # Control UI components
โ โ โโโ overlays/ # Overlay components (loading, etc.)
โ โ โโโ menus/ # Settings menus
โ โโโ contexts/ # React Context (PlayerContext)
โ โโโ hooks/ # Custom React hooks
โ โโโ utils/ # Utility functions
โ โโโ types/ # TypeScript type definitions
โ โโโ icons/ # Custom SVG icons
โ โโโ styles/ # Global styles and CSS variables
โ โโโ index.ts # Main export file
โโโ examples/ # Demo application
โโโ public/ # Static assets
โโโ dist/ # Built library (generated)
```
## ๐ API Reference
### VideoPlayer Props
#### Basic Props
| Prop | Type | Default | Description |
| --------------------- | ------------------------------------------------------------- | ------------ | -------------------------------------------------------------- |
| `src` | `string` | **required** | Video source URL (MP4, WebM, HLS, IPTV .ts) |
| `poster` | `string` | - | Poster image URL |
| `protocol` | `'auto' \| 'native' \| 'hls' \| 'rtmp' \| 'dash' \| 'mpegts'` | `'auto'` | Force playback engine instead of URL auto-detection |
| `autoplay` | `boolean` | `false` | Auto-play video on load |
| `loop` | `boolean` | `false` | Loop video playback |
| `muted` | `boolean` | `false` | Start muted |
| `volume` | `number` | - | Initial volume (0-1) |
| `playbackRate` | `number` | - | Playback speed (0.25, 0.5, 1, 1.5, 2, etc.) |
| `currentTime` | `number` | - | Initial playback position in seconds |
| `crossOrigin` | `'' \| 'anonymous' \| 'use-credentials'` | - | Sets the video `crossOrigin` attribute |
| `preload` | `'none' \| 'metadata' \| 'auto'` | `'metadata'` | Sets the video preload strategy |
| `playsInline` | `boolean` | `true` | Enables inline playback on mobile browsers |
| `controlsList` | `string` | - | Passes `controlsList` attribute to the video element |
| `controls` | `boolean` | `true` | Show player controls |
| `subtitles` | `SubtitleTrack[]` | `[]` | Subtitle tracks |
| `subtitleStyle` | `SubtitleStyle` | - | Custom subtitle text/background style |
| `subtitleStyleEditor` | `boolean \| SubtitleStyleEditorConfig` | `false` | Optional subtitle style editor UI and localStorage persistence |
| `subtitlePosition` | `'top' \| 'center' \| 'bottom'` | `'bottom'` | Subtitle vertical placement |
| `subtitleOffset` | `number \| string` | - | Subtitle offset (`px` if number) |
| `theme` | `PlayerTheme` | - | Custom theme colors |
| `language` | `string` | `'en'` | UI language ('en' or 'tr') |
| `keyboardShortcuts` | `boolean` | `true` | Enable keyboard shortcuts |
| `pictureInPicture` | `boolean` | `true` | Enable PIP button |
| `className` | `string` | - | Custom CSS class |
| `style` | `CSSProperties` | - | Inline styles |
#### Event Handlers
| Prop | Type | Description |
| -------------------------- | --------------------------------- | ------------------------------------------- |
| `onPlay` | `() => void` | Fired when playback starts |
| `onPause` | `() => void` | Fired when playback pauses |
| `onEnded` | `() => void` | Fired when playback ends |
| `onTimeUpdate` | `(currentTime: number) => void` | Fired during playback with current time |
| `onVolumeChange` | `(volume: number) => void` | Fired when volume changes |
| `onError` | `(error: Error) => void` | Fired on playback error |
| `onLoadedMetadata` | `() => void` | Fired when video metadata is loaded |
| `onSeeking` | `() => void` | Fired when seeking starts |
| `onSeeked` | `() => void` | Fired when seeking completes |
| `onProgress` | `(buffered: number) => void` | Fired during download progress |
| `onDurationChange` | `(duration: number) => void` | Fired when duration changes |
| `onRateChange` | `(playbackRate: number) => void` | Fired when playback rate changes |
| `onFullscreenChange` | `(isFullscreen: boolean) => void` | Fired when fullscreen state changes |
| `onPictureInPictureChange` | `(isPip: boolean) => void` | Fired when PIP state changes |
| `onWaiting` | `() => void` | Fired when buffering starts |
| `onCanPlay` | `() => void` | Fired when enough data is available to play |
### PlayerErrorBoundary Props
| Prop | Type | Description |
| ----------- | ------------------------------------------------------------- | -------------------------------------- |
| `children` | `ReactNode` | Wrapped player/content tree |
| `fallback` | `ReactNode \| (error: Error, retry: () => void) => ReactNode` | Optional custom fallback UI |
| `onError` | `(error: Error, errorInfo: React.ErrorInfo) => void` | Called when render errors are captured |
| `onReset` | `() => void` | Called when retry/reset is triggered |
| `resetKeys` | `readonly unknown[]` | Resets boundary when any key changes |
### SubtitleTrack
```typescript
interface SubtitleTrack {
src: string // Subtitle file URL (.vtt or .srt)
lang: string // Language code (e.g., 'en', 'tr')
label: string // Display label
default?: boolean // Set as default subtitle
}
```
```typescript
interface SubtitleStyleEditorConfig {
enabled?: boolean // Enables subtitle style editor in settings
storageKey?: string // localStorage key (default: 'source-player-subtitle-style')
}
```
### PlayerTheme
```typescript
interface PlayerTheme {
primaryColor?: string // Primary color (default: #ef4444)
accentColor?: string // Accent/hover color (default: #dc2626)
backgroundColor?: string // Background color (default: #000000)
textColor?: string // Text color (default: #ffffff)
}
```
## ๐ฏ Browser Support
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile Safari 14+
- Chrome Mobile 90+
## ๐ Bundle Size
- Core player JS bundle: **~18KB** (gzipped)
- Core player CSS bundle: **~3.5KB** (gzipped)
- HLS.js (optional, lazy-loaded): **~200KB** (only when using HLS streams)
- MPEGTS.js (optional, lazy-loaded): **~72KB** (gzipped, only for `.ts` streams)
- Zero runtime dependencies (React is a prerequisite, see installation notes)
## ๐ง Technical Details
### Native Browser APIs Used
- HTML5 Video API
- Fullscreen API
- Picture-in-Picture API
- Fetch API (Range Requests)
- TextTrack API (subtitles)
- Touch Events API
- Keyboard Events API
### Streaming Support
**MP4/WebM (Progressive Download)**
- Uses HTTP Range Requests
- Browser automatically chunks the download
- No additional library needed
- Works with any standard web server that supports Range headers
**HLS (.m3u8)**
- Automatically detects HLS sources
- Lazy loads hls.js library when needed
- Safari has native HLS support (no library needed)
- Adaptive bitrate streaming
### Performance Optimizations
- Lazy loading of HLS.js with CDN fallback
- CSS-only animations
- Debounced control hiding
- Optimized re-renders with React.memo
- Tree-shakeable exports
- Memory leak prevention with proper cleanup
- Polyfills for older browser support
### Error Handling & Reliability
- **CORS Detection**: Automatically detects and reports CORS issues with helpful error messages
- **HLS.js Fallback**: If npm package fails to load, automatically falls back to CDN
- **Memory Management**: Proper cleanup of HLS instances to prevent memory leaks
- **Browser Polyfills**: Vendor prefix support for Fullscreen and PIP APIs
- **URL Validation**: Validates video URLs before attempting to load
- **Feature Detection**: Checks browser capabilities before using advanced features
## ๐ง TODO / Future Enhancements
- [x] Multiple audio track UI and switching
- [x] Quality selector for HLS streams
- [x] Playback speed menu
- [x] Settings panel
- [ ] Chapters/markers support
- [ ] Thumbnail preview on hover
- [ ] Playlist support
- [ ] Chromecast support
- [ ] AirPlay support
- [ ] DASH streaming support
- [ ] Accessibility improvements (ARIA labels)
- [x] Unit tests
- [ ] E2E tests
- [ ] Storybook documentation
## ๐ License
MIT
## ๐ค Author
Alper
---
Built with โค๏ธ using React, TypeScript, and Vite