npm package: @lidemo/angular-video-player
Description: A feature-rich, Tailwind-based video player component for Angular applications with support for HLS streaming, multi-part videos, custom themes, and comprehensive keyboard controls
Author: lidemo
Latest version: 1.0.0

# Angular Video Player

A customizable Tailwind based video player component for Angular applications with support for HLS streaming, multi-part videos, custom themes, and comprehensive keyboard controls. 

## Features

- **Multiple Video Formats**: MP4, WebM, OGG, HLS streaming support
- **Built-in Controls**: Play/pause, volume, seek, fullscreen, picture-in-picture, multipart-selection, playback speeds
- **Theming Options**: Customizable colors, borders, and styling
- **Keyboard Controls**: Keyboard navigation and shortcuts
- **Multi-Part Videos**: Support for video series with parts/chapters
- **Playback Speed Control**: Variable speed playback (0.25x to 2x)
- **Theatre Mode**: Expandable viewing experience (YouTube-like full width page player)
- **Picture-in-Picture**: Mini player functionality
- **Accessibility**: WCAG compliant with proper ARIA labels
- **Performance**: Optimized bundle size and runtime performance

## Installation

```bash
npm install angular-video-player
```

### Requirements

**Tailwind CSS 3.0+** is required as a dependency:

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init
```

Add to your `styles.css`:
```css
@tailwind base;
@tailwind components;  
@tailwind utilities;
```

## Basic Usage

### Standalone Component (Recommended)

```typescript
import { Component } from '@angular/core';
import { VideoPlayerComponent, VideoPlayerConfig } from 'angular-video-player';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [VideoPlayerComponent],
  template: `
    <avp-video-player 
      [config]="videoConfig"
      (play)="onPlay()"
      (pause)="onPause()"
      (timeUpdate)="onTimeUpdate($event)">
    </avp-video-player>
  `
})
export class ExampleComponent {
  videoConfig: VideoPlayerConfig = {
    src: 'https://example.com/video.mp4',
    poster: 'https://example.com/poster.jpg',
    type: 'mp4'
  };

  onPlay() {
    console.log('Video started playing');
  }

  onPause() {
    console.log('Video paused');
  }

  onTimeUpdate(currentTime: number) {
    console.log('Current time:', currentTime);
  }
}
```

### Module-based Usage

```typescript
import { NgModule } from '@angular/core';
import { AngularVideoPlayerModule } from 'angular-video-player';

@NgModule({
  imports: [AngularVideoPlayerModule],
  // ... other module configuration
})
export class AppModule { }
```

## Configuration Options

### VideoPlayerConfig Interface

```typescript
interface VideoPlayerConfig {
  src: string | VideoPlayerPart[];     // Video source(s)
  poster?: string;                     // Poster image URL
  type?: 'hls' | 'dash' | 'mp4' | 'webm' | 'ogg'; // Video type
  autoplay?: boolean;                  // Auto-start playback
  muted?: boolean;                     // Start muted
  controls?: VideoPlayerControlsConfig; // Control visibility
  tailwindTheme?: VideoPlayerTailwindTheme; // Tailwind class customization
  responsive?: boolean;                // Responsive behavior
  fluid?: boolean;                     // Fluid aspect ratio
}
```

### Controls Configuration

```typescript
interface VideoPlayerControlsConfig {
  play?: boolean;           // Show play/pause button
  volume?: boolean;         // Show volume control
  progress?: boolean;       // Show progress bar
  fullscreen?: boolean;     // Show fullscreen button
  pictureInPicture?: boolean; // Show PiP button
  theatreMode?: boolean;    // Show theatre mode button
  playbackSpeed?: boolean;  // Show speed control
  parts?: boolean;          // Show parts dropdown (for multi-part videos)
  keyboard?: boolean;       // Enable keyboard controls
}
```

### Tailwind Theme Configuration

```typescript
interface VideoPlayerTailwindTheme {
  wrapper?: string;          // Container classes (e.g., 'max-h-[90vh] bg-gray-900')
  video?: string;            // Video element classes
  overlay?: string;          // Overlay gradient classes
  controls?: string;         // Controls bar classes
  button?: string;           // Button base classes
  buttonHover?: string;      // Button hover classes  
  progressBar?: string;      // Progress bar background
  progressFilled?: string;   // Progress bar filled portion
  dropdown?: string;         // Dropdown menu classes
  dropdownItem?: string;     // Dropdown item classes
  text?: string;             // Text color classes
  volumeSlider?: string;     // Volume slider classes
}
```

## Advanced Examples

### HLS Streaming Video

```typescript
videoConfig: VideoPlayerConfig = {
  src: 'https://example.com/stream.m3u8',
  type: 'hls',
  autoplay: false,
  muted: true,
  tailwindTheme: {
    controls: 'bg-black bg-opacity-80',
    progressFilled: 'bg-orange-500',
    button: 'px-2 py-2 text-orange-100 transition-all opacity-80',
    buttonHover: 'hover:bg-orange-700 hover:opacity-100'
  }
};
```

### Multi-Part Video Series

```typescript
videoConfig: VideoPlayerConfig = {
  src: [
    {
      src: 'https://example.com/part1.mp4',
      poster: 'https://example.com/poster1.jpg',
      title: 'Episode 1',
      part: 1
    },
    {
      src: 'https://example.com/part2.mp4', 
      poster: 'https://example.com/poster2.jpg',
      title: 'Episode 2',
      part: 2
    }
  ],
  type: 'mp4',
  controls: {
    parts: true,
    playbackSpeed: true
  }
};
```

### Custom Tailwind Themed Player

```typescript
videoConfig: VideoPlayerConfig = {
  src: 'https://example.com/video.mp4',
  tailwindTheme: {
    wrapper: 'max-h-[90vh] rounded-xl shadow-2xl',
    controls: 'bg-purple-900 bg-opacity-80',
    button: 'px-3 py-3 text-purple-100 transition-all opacity-90',
    buttonHover: 'hover:bg-purple-700 hover:opacity-100',
    progressFilled: 'bg-purple-400',
    progressBar: 'bg-purple-200 bg-opacity-30',
    dropdown: 'bg-purple-800 shadow-xl border border-purple-600',
    dropdownItem: 'hover:bg-purple-700',
    text: 'text-purple-100'
  }
};
```


## Events

The video player emits the following events:

```typescript
<avp-video-player 
  [config]="config"
  (play)="onPlay()"
  (pause)="onPause()"
  (timeUpdate)="onTimeUpdate($event)"
  (ended)="onEnded()"
  (error)="onError($event)"
  (stateChange)="onStateChange($event)"
  (partChange)="onPartChange($event)">
</avp-video-player>
```

### Event Handlers

```typescript
onPlay(): void {
  // Video started playing
}

onPause(): void {
  // Video paused
}

onTimeUpdate(currentTime: number): void {
  // Playback position updated
}

onEnded(): void {
  // Video playback ended
}

onError(error: any): void {
  // Error occurred during playback
}

onStateChange(state: VideoPlayerState): void {
  // Player state changed (includes all player data)
}

onPartChange(event: { partIndex: number; part: VideoPlayerPart }): void {
  // User switched to different video part
}
```

## Keyboard Controls

The video player supports keyboard controls:

- **Space**: Play/pause toggle
- **←/→ Arrow Keys**: Seek backward/forward (5 seconds)
- **↑/↓ Arrow Keys**: Volume up/down
- **F**: Toggle fullscreen
- **M**: Toggle mute
- **Tab**: Navigate through controls

## Styling

### Tailwind Customization

The video player uses **Tailwind CSS** for styling, allowing customization through Tailwind classes:

```typescript
// Custom blue theme
const blueTheme: VideoPlayerTailwindTheme = {
  wrapper: 'max-h-[80vh] rounded-lg shadow-lg',
  controls: 'bg-blue-900 bg-opacity-80',
  button: 'px-2 py-2 text-blue-100 transition-all opacity-80',
  buttonHover: 'hover:bg-blue-700 hover:opacity-100',
  progressFilled: 'bg-blue-400',
  progressBar: 'bg-gray-400 bg-opacity-25',
  dropdown: 'bg-blue-800 shadow-lg',
  dropdownItem: 'hover:bg-blue-600'
};

// Modern glass theme
const glassTheme: VideoPlayerTailwindTheme = {
  wrapper: 'max-h-[90vh] rounded-2xl backdrop-blur-lg',
  controls: 'bg-white bg-opacity-10 backdrop-blur-md border-t border-white border-opacity-20',
  button: 'px-3 py-3 text-white transition-all opacity-70',
  buttonHover: 'hover:bg-white hover:bg-opacity-20 hover:opacity-100',
  progressFilled: 'bg-gradient-to-r from-pink-500 to-violet-500',
  dropdown: 'bg-black bg-opacity-60 backdrop-blur-md rounded-xl border border-white border-opacity-10'
};
```


### Tailwind Configuration

Make sure your `tailwind.config.js` includes the video player files:

```javascript
module.exports = {
  content: [
    "./src/**/*.{html,ts}",
    "./node_modules/angular-video-player/**/*.{html,js}"
  ],
  // ... rest of config
};
```

## Browser Support

- **Chrome/Chromium**: 90+
- **Firefox**: 88+
- **Safari**: 14+
- **Edge**: 90+

### HLS Support
- HLS.js

## Performance

- **Bundle Size**: ~45KB gzipped (including HLS.js)
- **Tree Shaking**: Fully supported
- **Lazy Loading**: Component supports lazy loading
- **Memory Management**: Automatic cleanup on component destroy

## Development

### Building the Library

```bash
# Clone the repository
git clone https://github.com/your-repo/angular-video-player
cd angular-video-player

# Install dependencies
npm install

# Build the library
ng build angular-video-player

# Run demo application
ng serve demo
```
## License

MIT License - see the [LICENSE](LICENSE) file for details.