V360 Player

A lightweight, customizable HLS video player web component with built-in controls. Available for both modern bundlers and direct browser usage.

Features

• HLS (HTTP Live Streaming) video playback
• Built-in controls with optimized icons
• Responsive design with aspect ratio support
• Dynamic controls handling based on video background color (dark or light)
• Customizable playback speeds
• Time display options
• Progress bar with seek functionality
• Fullscreen support
• Cross-browser compatibility with native HLS fallback for Safari

Installation & Usage

For Modern Bundlers (Vite, Webpack, etc.)

# Install the package and its peer dependencies
npm install @v360-tech/v360-player hls.js jquery

// Import in your TypeScript/JavaScript file
import "@v360-tech/v360-player";

<!-- Use in your HTML -->
<v360-player
  video-src="path/to/video.m3u8"
  poster-src="path/to/poster.jpg"
  show-time-display
  show-speed-control
>
</v360-player>

For Direct Browser Usage

<!-- Include from CDN (all dependencies bundled) -->
<script src="https://unpkg.com/@v360-tech/[email protected]/dist/v360-player.browser.js"></script>
<!-- OR -->
<script src="https://cdn.jsdelivr.net/npm/@v360-tech/[email protected]/dist/v360-player.browser.js"></script>

<!-- Use immediately -->
<v360-player
  video-src="path/to/video.m3u8"
  poster-src="path/to/poster.jpg"
  show-time-display
  show-speed-control
>
</v360-player>

Advanced Usage Example

<!-- Full-featured player -->
<v360-player
  video-src="path/to/video.m3u8"
  poster-src="path/to/poster.jpg"
  width="720px"
  auto-play
  show-time-display
  show-speed-control
  playback-speeds="0.5,1,1.5,2"
  default-speed="1"
  progress-bar-style="DualLayer"
  background="dark"
  aspect-ratio="16:9"
>
</v360-player>

Properties

| Property | Type | Default | Description | Possible Values | | -------------------- | ------- | ------------------------------ | ----------------------------------- | -------------------------------------------------------- | | video-src | string | required | URL to the HLS (.m3u8) video stream | Any valid URL | | poster-src | string | "" | URL to the poster image | Any valid URL | | width | string | "100%" | Width of the video player | CSS width value (e.g., "100%", "800px") | | auto-play | boolean | false | Enable autoplay | true, false | | show-time-display | boolean | false | Show current time and duration | true, false | | show-speed-control | boolean | false | Show playback speed control | true, false | | playback-speeds | string | "0.25,0.5,0.75,1,1.25,1.5,2" | Comma-separated list of speeds | Comma-separated numbers | | default-speed | string | "1" | Default playback speed | One of the values from playback-speeds | | default-quality | string | "-1" | Default HLS quality (-1 for auto) | -1 or positive integer | | progress-bar-style | string | "none" | Progress bar style variant | "none", "dual-layer", "segments", "minimal-wave" | | background | string | dark | Video background | dark, light | | aspect-ratio | string | "16:9" | Aspect ratio of the player | Any valid ratio (e.g., "16:9", "4:3", "1:1") |

Build Types

This package provides two optimized builds:

1. ES Module Build (v360-player.js):

   • For use with modern bundlers (Vite, Webpack, Rollup, etc.)
   • External dependencies (hls.js, jquery) for better tree-shaking
   • Smaller bundle size when used with bundlers

2. Browser Build (v360-player.browser.js):

   • For direct browser usage via CDN
   • All dependencies bundled in
   • No external dependencies required
   • Ready to use with a simple script tag

Examples

Framework Usage Examples

React/Next.js

import { useEffect } from "react";
import "@v360-tech/v360-player";
export default function VideoPlayer() {
  return (
    <v360-player
      video-src="video.m3u8"
      poster-src="poster.jpg"
      show-time-display
      show-speed-control
    />
  );
}

Vue.js

<template>
  <v360-player
    video-src="video.m3u8"
    poster-src="poster.jpg"
    show-time-display
    show-speed-control
  />
</template>

<script setup>
import "@v360-tech/v360-player";
</script>

Svelte

<script>
  import '@v360-tech/v360-player';
</script>

<v360-player
  video-src="video.m3u8"
  poster-src="poster.jpg"
  show-time-display
  show-speed-control
/>

Minimal Player

<v360-player video-src="video.m3u8"></v360-player>

With Time Display

<v360-player video-src="video.m3u8" show-time-display> </v360-player>

Full-Featured Player

<v360-player
  video-src="video.m3u8"
  poster-src="poster.jpg"
  width="800px"
  auto-play
  show-time-display
  show-speed-control
  playback-speeds="0.5,1,1.5,2"
  default-speed="1"
  progress-bar-style="dual-layer"
>
</v360-player>

Progress Bar Styles

The player offers different progress bar styles through the progress-bar-style property:

none (default)

Basic progress bar with simple fill indicator.

<v360-player video-src="video.m3u8" progress-bar-style="none"></v360-player>

dual-layer

Shows buffer progress and includes a draggable handle.

<v360-player
  video-src="video.m3u8"
  progress-bar-style="dual-layer"
></v360-player>

segments

Divides the progress into clickable segments.

<v360-player video-src="video.m3u8" progress-bar-style="segments"></v360-player>

minimal-wave

Clean style with an animated wave indicator.

<v360-player
  video-src="video.m3u8"
  progress-bar-style="minimal-wave"
></v360-player>

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari 14+ (uses native HLS)
• Mobile browsers with HLS support

Development

1. Clone the repository

git clone <repository-url>
cd v360-player

2. Install dependencies

npm install

3. Start development server

npm run dev

4. Build for production

npm run build

Technical Details

The player uses:

• HLS.js for video streaming in browsers without native HLS support
• Web Components with Shadow DOM for style isolation
• TypeScript for type safety
• Optimized icons for controls
• Custom controls with playback speed adjustment
• Progress bar with seek functionality
• Fullscreen mode support
• Dynamic controls handling based on video background color (dark or light)
• Dynamic aspect ratio handling

License

MIT License