Initial commit: modern React video player library
Add all source files for a feature-rich, reusable video player built with React, TypeScript, and Vite. Includes core components, context, hooks, utilities, styles, demo app, and configuration files.
This commit is contained in:
hibna
@@ -0,0 +1,355 @@
|
||||
# 🎬 Modern Video Player
|
||||
|
||||
A feature-rich, modern video player library built with React, TypeScript, and Vite. Designed for reusability across multiple projects with zero runtime dependencies.
|
||||
|
||||
## ✨ 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
|
||||
|
||||
### 📱 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
|
||||
- **HTTP Range Request** - Progressive download for large MP4 files
|
||||
- **Subtitles** - WebVTT and SRT support
|
||||
- **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 is a local library project. To use it in your projects:
|
||||
|
||||
### Option 1: Copy the library
|
||||
```bash
|
||||
# Copy the src folder to your project
|
||||
cp -r src/components your-project/src/
|
||||
cp -r src/contexts your-project/src/
|
||||
cp -r src/hooks your-project/src/
|
||||
cp -r src/utils your-project/src/
|
||||
cp -r src/types your-project/src/
|
||||
cp -r src/icons your-project/src/
|
||||
cp -r src/styles your-project/src/
|
||||
```
|
||||
|
||||
### Option 2: Build as library and link
|
||||
```bash
|
||||
# In this project
|
||||
npm run build:lib
|
||||
npm link
|
||||
|
||||
# In your other project
|
||||
npm link @alper/video-player
|
||||
```
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```tsx
|
||||
import { VideoPlayer } from '@alper/video-player'
|
||||
import '@alper/video-player/styles.css'
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<VideoPlayer
|
||||
src="https://example.com/video.mp4"
|
||||
poster="https://example.com/poster.jpg"
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### With Subtitles
|
||||
|
||||
```tsx
|
||||
<VideoPlayer
|
||||
src="https://example.com/video.mp4"
|
||||
subtitles={[
|
||||
{ src: '/subtitles/en.vtt', lang: 'en', label: 'English', default: true },
|
||||
{ src: '/subtitles/tr.srt', lang: 'tr', label: 'Türkçe' },
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
### HLS Streaming
|
||||
|
||||
```tsx
|
||||
<VideoPlayer
|
||||
src="https://example.com/stream/playlist.m3u8"
|
||||
autoplay={false}
|
||||
/>
|
||||
```
|
||||
|
||||
### Custom Theme
|
||||
|
||||
```tsx
|
||||
<VideoPlayer
|
||||
src="https://example.com/video.mp4"
|
||||
theme={{
|
||||
primaryColor: '#ef4444',
|
||||
accentColor: '#dc2626',
|
||||
backgroundColor: '#000000',
|
||||
textColor: '#ffffff',
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
### With Event Handlers
|
||||
|
||||
```tsx
|
||||
<VideoPlayer
|
||||
src="https://example.com/video.mp4"
|
||||
onPlay={() => console.log('Video started playing')}
|
||||
onPause={() => console.log('Video paused')}
|
||||
onEnded={() => console.log('Video ended')}
|
||||
onTimeUpdate={(time) => console.log('Current time:', time)}
|
||||
onError={(error) => console.error('Video error:', error)}
|
||||
/>
|
||||
```
|
||||
|
||||
### Feature Detection & Polyfills
|
||||
|
||||
```tsx
|
||||
import { features, initializePolyfills } from '@alper/video-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
|
||||
<VideoPlayer
|
||||
src="video.mp4"
|
||||
pictureInPicture={features.hasPIP()}
|
||||
/>
|
||||
```
|
||||
|
||||
### CORS Error Handling
|
||||
|
||||
```tsx
|
||||
import { validateVideoURL, checkVideoCORS } from '@alper/video-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
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `src` | `string` | **required** | Video source URL (MP4, WebM, HLS) |
|
||||
| `poster` | `string` | - | Poster image URL |
|
||||
| `autoplay` | `boolean` | `false` | Auto-play video on load |
|
||||
| `loop` | `boolean` | `false` | Loop video playback |
|
||||
| `muted` | `boolean` | `false` | Start muted |
|
||||
| `controls` | `boolean` | `true` | Show player controls |
|
||||
| `subtitles` | `SubtitleTrack[]` | `[]` | Subtitle tracks |
|
||||
| `audioTracks` | `AudioTrack[]` | `[]` | Audio tracks |
|
||||
| `theme` | `PlayerTheme` | - | Custom theme colors |
|
||||
| `keyboardShortcuts` | `boolean` | `true` | Enable keyboard shortcuts |
|
||||
| `pictureInPicture` | `boolean` | `true` | Enable PIP button |
|
||||
| `className` | `string` | - | Custom CSS class |
|
||||
| `style` | `CSSProperties` | - | Inline styles |
|
||||
| `onPlay` | `() => void` | - | Play event handler |
|
||||
| `onPause` | `() => void` | - | Pause event handler |
|
||||
| `onEnded` | `() => void` | - | Ended event handler |
|
||||
| `onTimeUpdate` | `(time: number) => void` | - | Time update handler |
|
||||
| `onVolumeChange` | `(volume: number) => void` | - | Volume change handler |
|
||||
| `onError` | `(error: Error) => void` | - | Error handler |
|
||||
|
||||
### 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
|
||||
}
|
||||
```
|
||||
|
||||
### 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 library: **~8KB** (gzipped)
|
||||
- HLS.js (optional, lazy-loaded): **~200KB** (only when using HLS streams)
|
||||
- Zero runtime dependencies (React is peer dependency)
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
### Native Browser APIs Used
|
||||
- HTML5 Video API
|
||||
- Fullscreen API
|
||||
- Picture-in-Picture API
|
||||
- Media Session API
|
||||
- Fetch API (Range Requests)
|
||||
- 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
|
||||
|
||||
- [ ] Multiple audio track UI and switching
|
||||
- [ ] Quality selector for HLS streams
|
||||
- [ ] Playback speed menu
|
||||
- [ ] Settings panel
|
||||
- [ ] Chapters/markers support
|
||||
- [ ] Thumbnail preview on hover
|
||||
- [ ] Playlist support
|
||||
- [ ] Chromecast support
|
||||
- [ ] AirPlay support
|
||||
- [ ] DASH streaming support
|
||||
- [ ] Accessibility improvements (ARIA labels)
|
||||
- [ ] Unit tests
|
||||
- [ ] E2E tests
|
||||
- [ ] Storybook documentation
|
||||
|
||||
## 📝 License
|
||||
|
||||
MIT
|
||||
|
||||
## 👤 Author
|
||||
|
||||
Alper
|
||||
|
||||
---
|
||||
|
||||
Built with ❤️ using React, TypeScript, and Vite
|
||||
Reference in New Issue
Block a user