npm package: @peaseernest/videoplayer
Description: A unified video player library with HLS streaming support, built on video.js and hls.js
Author: Pease Ernest
Latest version: 1.0.0

# @peaseernest/videoplayer

A unified, easy-to-use video player library with HLS streaming support. Built on top of **video.js** and **hls.js**, this library abstracts away all complexity and provides a simple configuration API.

## Features

✨ **Simple Configuration** - One config object controls everything  
🎬 **HLS Streaming** - Adaptive bitrate streaming with hls.js  
🎨 **Video.js UI** - Professional, customizable player controls  
📱 **Picture-in-Picture** - Built-in PIP support  
📝 **Captions** - WebVTT subtitle support  
⚡ **Buffer Control** - Configurable buffering settings  
🔊 **Volume Controls** - Volume slider with keyboard shortcuts  
☀️ **Brightness Control** - Adjust video brightness  
🎭 **Theater Mode** - Widescreen viewing mode  
⌨️ **Keyboard Shortcuts** - Full keyboard navigation  
🖱️ **Context Menu** - Right-click menu with advanced options  
🔁 **Loop Control** - Loop video playback  
⚙️ **Quality Selector** - Manual quality selection for HLS  
⏩ **Playback Speed** - 0.5x to 2x speed control  
📊 **Stats Display** - Technical video information  

## Installation

```bash
npm install @peaseernest/videoplayer
```

Or with yarn:

```bash
yarn add @peaseernest/videoplayer
```

## Usage

### 1. HTML Setup

Add a container div with the `data-videoplayer` attribute:

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/@peaseernest/videoplayer/dist/videoplayer.css">
</head>
<body>
  <div data-videoplayer="main-video"></div>
  
  <script src="node_modules/@peaseernest/videoplayer/dist/videoplayer.min.js"></script>
  <script src="app.js"></script>
</body>
</html>
```

### 2. JavaScript Configuration

```javascript
// Import the library
import videoplayer from '@peaseernest/videoplayer';

// Configure your player
const config = {
  sourceUrl: 'https://example.com/video/stream.m3u8',
  stream: true,              // Enable HLS streaming
  volume: true,              // Show volume controls
  pip: true,                 // Enable Picture-in-Picture
  buffering: 60,             // Buffer size in MB
  captions: true,            // Enable captions
  captionLink: 'https://example.com/captions/english.vtt'
};

// Initialize the player
videoplayer.init(config);
```

### ES6 Module

```javascript
import videoplayer from '@peaseernest/videoplayer';
import '@peaseernest/videoplayer/dist/videoplayer.css';

videoplayer.init({
  sourceUrl: 'https://example.com/video.m3u8',
  stream: true,
  volume: true,
  pip: true,
  buffering: 100,
  captions: true,
  captionLink: 'https://example.com/subtitles.vtt'
});
```

### CommonJS

```javascript
const videoplayer = require('@peaseernest/videoplayer');

videoplayer.init({ /* config */ });
```

### CDN Usage

```html
<link rel="stylesheet" href="https://unpkg.com/@peaseernest/videoplayer/dist/videoplayer.css">
<script src="https://unpkg.com/@peaseernest/videoplayer/dist/videoplayer.min.js"></script>

<div data-videoplayer="my-video"></div>

<script>
  PeaseErnestPlayer.init({
    sourceUrl: 'https://example.com/video.m3u8',
    stream: true
  });
</script>
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `sourceUrl` | `string` | **required** | URL to your video file (MP4 or M3U8) |
| `stream` | `boolean` | `false` | Enable HLS streaming for M3U8 files |
| `volume` | `boolean` | `true` | Show volume controls |
| `pip` | `boolean` | `true` | Enable Picture-in-Picture button |
| `buffering` | `number` | `60` | Buffer size in megabytes |
| `captions` | `boolean` | `false` | Enable subtitle support |
| `captionLink` | `string` | `null` | URL to WebVTT caption file |
| `autoplay` | `boolean` | `false` | Auto-play video on load |
| `shortcuts` | `object` | see below | Keyboard shortcut configuration |

### Keyboard Shortcuts Configuration

```javascript
shortcuts: {
  playPause: ' ',           // Space bar - Play/Pause
  seekForward: 'ArrowRight', // Seek forward
  seekBackward: 'ArrowLeft', // Seek backward
  volumeUp: 'ArrowUp',      // Increase volume
  volumeDown: 'ArrowDown',   // Decrease volume
  mute: 'm',                // Mute/Unmute
  fullscreen: 'f',          // Toggle fullscreen
  theater: 't',             // Toggle theater mode
  seekForwardAmount: 10,    // Seconds to seek forward
  seekBackwardAmount: 10    // Seconds to seek backward
}
```

### Default Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Space` / `K` | Play/Pause |
| `→` / `L` | Skip forward 10 seconds |
| `←` / `J` | Skip backward 10 seconds |
| `↑` | Volume up |
| `↓` | Volume down |
| `M` | Mute/Unmute |
| `F` | Fullscreen |
| `T` | Theater mode |
| `0-9` | Jump to 0%-90% of video |

## Multiple Players

You can have multiple players on the same page:

```html
<div data-videoplayer="video1"></div>
<div data-videoplayer="video2"></div>
```

```javascript
// All containers with data-videoplayer will use the same config
videoplayer.init({
  sourceUrl: 'https://example.com/video.m3u8',
  stream: true
});
```

## API Methods

### `init(config)`

Initialize all video players on the page.

```javascript
videoplayer.init({
  sourceUrl: 'https://example.com/video.m3u8',
  stream: true
});
```

### `getPlayer(playerId)`

Get a specific player instance by ID.

```javascript
const player = videoplayer.getPlayer('peaseernest-main-video-1234567890');
player.play();
player.pause();
player.currentTime(30); // Seek to 30 seconds
player.volume(0.5); // Set volume to 50%
```

### `destroy()`

Destroy all players and clean up resources.

```javascript
videoplayer.destroy();
```

## Custom Controls

### Built-in UI Controls

- **Play/Pause** - Click or use spacebar
- **Volume Slider** - Drag or use arrow keys
- **Progress Bar** - Click to seek, drag for scrubbing
- **Brightness** - Click sun icon to adjust (0-200%)
- **Theater Mode** - Click film icon or press 'T'
- **Loop** - Click loop icon to enable/disable
- **Playback Speed** - Select from 0.5x to 2x
- **Quality** - Auto-select or manual for HLS streams
- **Fullscreen** - Click or press 'F'
- **Picture-in-Picture** - Click PIP icon

### Right-Click Context Menu

Right-click on the video to access:
- **Loop** - Enable/disable video loop
- **Speed** - Change playback speed
- **Copy Video URL** - Copy source URL to clipboard
- **Copy Current Time** - Copy current timestamp
- **Stats for Nerds** - View technical details
- **About** - Library version info

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+
- iOS Safari 11+
- Android Chrome 60+

## HLS Streaming

The library automatically detects HLS support:
- Uses native HLS in Safari
- Uses hls.js for other browsers
- Falls back gracefully if streaming is not supported

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Watch mode for development
npm run dev
```

## Project Structure

```
@peaseernest/videoplayer/
├── src/
│   └── index.js          # Main library code
├── dist/                 # Built files (generated)
│   ├── videoplayer.js    # UMD bundle
│   ├── videoplayer.min.js
│   ├── videoplayer.esm.js
│   ├── videoplayer.cjs.js
│   └── videoplayer.css
├── package.json
├── rollup.config.js
└── README.md
```

## License

MIT © Pease Ernest

## Credits

Built with:
- [video.js](https://videojs.com/) - HTML5 video player
- [hls.js](https://github.com/video-dev/hls.js/) - HLS streaming library