@vidtreo/player-wc

Web component package for playing Vidtreo-recorded videos. This package provides a ready-to-use custom element (<vidtreo-player>) that can be embedded in any HTML page without a framework.

Installation

npm install @vidtreo/player-wc

Quick Start

Using the Component

<script type="module" src="node_modules/@vidtreo/player-wc/dist/vidtreo-player.js"></script>

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
></vidtreo-player>

Via CDN (jsDelivr)

Specific Version (Recommended for Production)

<script type="module" src="https://cdn.jsdelivr.net/npm/@vidtreo/[email protected]/dist/vidtreo-player.js"></script>

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
></vidtreo-player>

Latest Version (Use with Caution)

<script type="module" src="https://cdn.jsdelivr.net/npm/@vidtreo/player-wc@latest/dist/vidtreo-player.js"></script>

Component API

Attributes

All attributes are optional except where noted. Attributes use kebab-case.

| Attribute | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | src | string | No | - | Direct video URL. When set, video-id and api-key are ignored and no backend request is made | | video-id | string | Yes unless src is set | - | The ID of the video to play | | api-key | string | Yes unless src is set | - | API key for authentication | | backend-url | string | No | https://core.vidtreo.com | Backend API URL | | theme-color | string | No | #00ff00 | Player theme color (hex or rgb) | | screenshot | boolean | No | false | Enable screenshot button | | setting | boolean | No | false | Enable settings panel button | | pip | boolean | No | false | Enable picture-in-picture button | | fullscreen-web | boolean | No | false | Enable web fullscreen button | | fullscreen | boolean | No | false | Enable fullscreen button | | playback-rate | boolean | No | Enabled if setting=true | Enable playback speed control in settings | | aspect-ratio | boolean | No | Enabled if setting=true | Enable aspect ratio control in settings | | flip | boolean | No | Enabled if setting=true | Enable video flip control in settings |

Note: Boolean attributes work as follows:

• Present without value or with any value except "false" = enabled
• Not present or set to "false" = disabled

Custom Events

The component dispatches custom events that can be listened to:

| Event | Detail | Description | |-------|--------|-------------| | player-ready | - | Dispatched when video is loaded and ready to play | | player-error | { error: string } | Dispatched when an error occurs |

Examples

Basic Usage

<script type="module" src="node_modules/@vidtreo/player-wc/dist/vidtreo-player.js"></script>

<vidtreo-player
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
></vidtreo-player>

Direct Source Playback

Play a video from a URL you already have, skipping the backend entirely:

<vidtreo-player
  src="https://cdn.example.com/videos/video.mp4"
></vidtreo-player>

With Custom Theme and Screenshot

<vidtreo-player
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
  theme-color="#ff6b6b"
  screenshot
></vidtreo-player>

With All Controls Enabled

<vidtreo-player
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
  screenshot
  setting
  pip
  fullscreen-web
  fullscreen
></vidtreo-player>

With Settings Panel and Custom Options

<vidtreo-player
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
  setting
  playback-rate
  aspect-ratio
  flip
></vidtreo-player>

With Custom Backend URL

<vidtreo-player
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
  backend-url="https://custom-api.example.com"
></vidtreo-player>

Minimal Configuration (Basic Playback Only)

<vidtreo-player
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
></vidtreo-player>

Programmatic Access

The web component exposes custom events that can be listened to via JavaScript.

Getting the Component Instance

const player = document.querySelector('vidtreo-player');

Listening to Events

<vidtreo-player
  id="my-player"
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
></vidtreo-player>

<script type="module">
  import './node_modules/@vidtreo/player-wc/dist/vidtreo-player.js';

  const player = document.getElementById('my-player');

  player.addEventListener('player-ready', () => {
    console.log('Player is ready');
  });

  player.addEventListener('player-error', (event) => {
    console.error('Player error:', event.detail.error);
  });
</script>

Dynamic Attribute Changes

Attributes can be changed dynamically, which will trigger a component re-initialization:

const player = document.querySelector('vidtreo-player');

player.setAttribute('video-id', 'new-video-id');
player.setAttribute('theme-color', '#3498db');
player.setAttribute('screenshot', 'true');

Features

Video Playback Controls

The player provides standard video controls:

• Play/Pause
• Progress bar with seek
• Volume control
• Current time / Duration display

Screenshot

Enable the screenshot feature to allow users to capture the current video frame:

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  screenshot
></vidtreo-player>

Settings Panel

Enable the settings panel to provide users with playback customization options:

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  setting
></vidtreo-player>

When setting is enabled, the following options are automatically included:

• Playback Rate: Control video playback speed (0.5x, 0.75x, 1x, 1.25x, 1.5x, 2x)
• Aspect Ratio: Adjust video aspect ratio (Default, 4:3, 16:9)
• Flip: Flip video horizontally or vertically

To disable specific settings options:

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  setting
  playback-rate="false"
  aspect-ratio="false"
></vidtreo-player>

Picture-in-Picture

Enable picture-in-picture mode to allow videos to play in a floating window:

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  pip
></vidtreo-player>

Fullscreen Modes

Two fullscreen modes are available:

Web Fullscreen: Expands the player to fill the browser window

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  fullscreen-web
></vidtreo-player>

Standard Fullscreen: Uses native browser fullscreen API

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  fullscreen
></vidtreo-player>

Theme Customization

Customize the player theme color:

<vidtreo-player
  video-id="your-video-id"
  api-key="your-api-key"
  theme-color="#ff6b6b"
></vidtreo-player>

Supports hex colors and rgb/rgba values:

• #ff6b6b
• #3498db
• rgb(52, 152, 219)
• rgba(52, 152, 219, 0.8)

Usage Patterns

Single Video Player

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Video Player</title>
</head>
<body>
  <script type="module" src="https://cdn.jsdelivr.net/npm/@vidtreo/[email protected]/dist/vidtreo-player.js"></script>

  <vidtreo-player
    video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
    api-key="your-api-key"
    screenshot
    setting
    fullscreen
  ></vidtreo-player>
</body>
</html>

Multiple Players

<script type="module" src="https://cdn.jsdelivr.net/npm/@vidtreo/[email protected]/dist/vidtreo-player.js"></script>

<vidtreo-player
  video-id="video-1-id"
  api-key="your-api-key"
></vidtreo-player>

<vidtreo-player
  video-id="video-2-id"
  api-key="your-api-key"
></vidtreo-player>

<vidtreo-player
  video-id="video-3-id"
  api-key="your-api-key"
></vidtreo-player>

With Event Listeners

<vidtreo-player
  id="tracked-player"
  video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
  api-key="your-api-key"
></vidtreo-player>

<div id="status"></div>

<script type="module">
  import './node_modules/@vidtreo/player-wc/dist/vidtreo-player.js';

  const player = document.getElementById('tracked-player');
  const status = document.getElementById('status');

  player.addEventListener('player-ready', () => {
    status.textContent = 'Player ready - Video loaded';
    console.log('Video is ready to play');
  });

  player.addEventListener('player-error', (event) => {
    status.textContent = `Error: ${event.detail.error}`;
    console.error('Player error:', event.detail.error);
  });
</script>

Responsive Player

<style>
  .player-container {
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
  }

  vidtreo-player {
    display: block;
    width: 100%;
  }
</style>

<div class="player-container">
  <vidtreo-player
    video-id="dfc591f2-158e-4f83-885f-6fe34452ce11"
    api-key="your-api-key"
    screenshot
    setting
    fullscreen
  ></vidtreo-player>
</div>

Browser Compatibility

This package requires modern browser APIs for video playback.

Full Support

• Chrome 94+
• Edge (Chromium) 94+
• Firefox 130+
• Safari 16.4+
• Opera 80+

Required Browser APIs

• Web Components (Custom Elements v1)
• ES Modules
• Fetch API
• Blob API
• URL.createObjectURL

Important Notes

1. HTTPS Required: The component must be served over HTTPS (or localhost) for proper operation
2. Cross-Origin Videos: Screenshot functionality may be limited for cross-origin videos due to browser security policies
3. Modern Browsers Only: This component requires ES2022+ support and does not include polyfills

Error Handling

The component displays error messages in the player area when issues occur:

Common Errors

Missing Required Attributes

These errors only apply when src is not set:

video-id attribute is required
api-key attribute is required

Authentication Errors

Failed to fetch video: 401 Unauthorized
Failed to fetch video: 403 Forbidden

Video Not Found

Failed to fetch video: 404 Not Found

Network Errors

Failed to fetch video: Network error

Handling Errors Programmatically

const player = document.querySelector('vidtreo-player');

player.addEventListener('player-error', (event) => {
  const error = event.detail.error;

  if (error.includes('401') || error.includes('403')) {
    console.error('Authentication error - check your API key');
  } else if (error.includes('404')) {
    console.error('Video not found - check your video ID');
  } else if (error.includes('Network')) {
    console.error('Network error - check your connection');
  } else {
    console.error('Unknown error:', error);
  }
});

Styling

The component uses CSS variables for internal styling with a --vidtreo-player- prefix. The player adapts to its container size and maintains a 16:9 aspect ratio by default.

Container Styling

vidtreo-player {
  display: block;
  width: 100%;
  max-width: 1280px;
  margin: 0 auto;
}

Responsive Design

.video-wrapper {
  width: 100%;
  max-width: 100%;
}

vidtreo-player {
  width: 100%;
  height: auto;
}

@media (max-width: 768px) {
  vidtreo-player {
    max-width: 100%;
  }
}

API Reference

Backend API Endpoint

The component fetches videos from:

{backend-url}/api/v1/videos/{video-id}/file

Authentication: Bearer token via Authorization header

Response Types:

• application/json - Returns JSON with url field containing video URL
• video/* - Returns video file directly as blob

Example Request:

GET /api/v1/videos/{video-id}/file HTTP/1.1
Host: core.vidtreo.com
Authorization: Bearer your-api-key

Example JSON Response:

{
  "url": "https://cdn.example.com/videos/video.mp4"
}

Bundle Information

• Format: IIFE (Immediately Invoked Function Expression)
• Size: ~165 KB (uncompressed), ~42 KB (gzipped)
• Includes: ArtPlayer library bundled
• Target: ES2022
• Browser Support: Modern browsers only

Development

Building from Source

# Clone repository
git clone https://github.com/your-org/vidtreo-sdk.git
cd vidtreo-sdk/packages/player-wc

# Install dependencies
bun install

# Build package
bun run build

# Start demo server
bun run dev

Demo Application

A demo application is included for testing:

bun run demo

Visit http://localhost:5177 to see the demo.

License

MIT