@vidinfra/player

A lightweight, type-safe JavaScript library for controlling video players inside iframes using the postMessage API.

Installation

npm install @vidinfra/player

CDN

<script src="https://unpkg.com/@vidinfra/player/dist/player.global.js"></script>

Features

• Unified API - Single class handles both iframe control and embed creation
• Type-safe - Full TypeScript support with comprehensive type definitions
• Framework-agnostic - Works with any JavaScript framework or vanilla JS
• Secure - Built-in origin validation for postMessage communication
• Event-driven - Real-time player state updates via event listeners
• Lightweight - ~15KB minified

Quick Start

Control an Existing Iframe

import { Player } from "@vidinfra/player";

const player = new Player("iframe");

player.on("play", () => {
  console.log("Video started playing");
});

await player.whenReady();
await player.play();

Create an Embedded Player

import { Player } from "@vidinfra/player";

const player = new Player("vidinfra-player", {
  libraryId: 1234567,
  videoId: 59777392,
  playerId: 27282929,
  autoplay: false,
  loop: false,
  muted: false,
  controls: true,
  preload: true,
  aspectRatio: "16:9"
});

player.setVolume(0.5);

Usage

Controlling an Existing Iframe

If you already have an iframe on your page, pass the element or a CSS selector to control it.

JavaScript

import { Player } from "@vidinfra/player";

const player = new Player("#player-iframe");

await player.whenReady();
await player.play();

CDN

<iframe id="player-iframe" src="https://player.example.com/video/123"></iframe>

<script src="https://unpkg.com/@vidinfra/player/dist/player.global.js"></script>
<script>
  const player = new Vidinfra.Player("#player-iframe");
  
  player.whenReady().then(() => {
    player.play();
  });
</script>

Creating an Embedded Player

The library can automatically create and inject a Vidinfra player iframe into your page.

JavaScript

import { Player } from "@vidinfra/player";

const player = new Player("vidinfra-player", {
  libraryId: 1234567,
  videoId: 59777392,
  playerId: 27282929,
  autoplay: false,
  loop: false,
  muted: false,
  controls: true,
  preload: true,
  aspectRatio: "16:9"
});

CDN

<div id="vidinfra-player"></div>

<script src="https://unpkg.com/@vidinfra/player/dist/player.global.js"></script>
<script>
  const player = new Vidinfra.Player("vidinfra-player", {
    libraryId: 1234567,
    videoId: 59777392,
    playerId: 27282929,
    autoplay: false,
    loop: false,
    muted: false,
    controls: true,
    preload: true,
    aspectRatio: "16:9"
  });
</script>

Integration with TenbytePlayer

This library is designed to work with tenbyte-player-sdk. To enable external control, initialize the bridge inside your iframe.

Inside the Iframe

import { TenbytePlayer, enablePlayerBridge } from "tenbyte-player-sdk";

const player = new TenbytePlayer({
  target: "#player",
  source: {
    manifestUri: "https://example.com/video.mpd"
  },
  autoplay: true
});

enablePlayerBridge(player, {
  allowedOrigin: "https://parent-site.com"
});

From the Parent Page

import { Player } from "@vidinfra/player";

const player = new Player("#player-iframe");
await player.whenReady();
await player.play();

API Reference

Constructor

new Player(element: HTMLIFrameElement | HTMLElement | string)
new Player(element: HTMLElement | string, options: PlayerOptions)

Parameters

• element - An iframe element, CSS selector for an iframe, or a container element for embedding
• options - Configuration options for creating an embedded player (required when creating an embed)

PlayerOptions

interface PlayerOptions {
  // Vidinfra player (required)
  libraryId: string | number;
  videoId: string | number;
  playerId?: string | number; // Optional, defaults to 'default'

  // Display options
  width?: number | string;
  height?: number | string;
  aspectRatio?: string; // e.g., "16:9", "4:3"

  // Playback options
  autoplay?: boolean;
  loop?: boolean;
  muted?: boolean;
  controls?: boolean;
  preload?: boolean;

  // Advanced options
  loading?: "lazy" | "eager";
  allow?: string;
  className?: string;
  baseUrl?: string;
}

Playback Methods

play(): Promise<void>
Start video playback.

pause(): Promise<void>
Pause video playback.

togglePlay(): Promise<void>
Toggle between play and pause states.

seek(time: number): Promise<void>
Seek to a specific time in seconds.

setPlaybackRate(rate: number): Promise<void>
Set playback speed (e.g., 0.5, 1.0, 2.0).

getPlaybackRate(): Promise<number>
Get current playback rate.

getCurrentTime(): Promise<number>
Get current playback position in seconds.

getDuration(): Promise<number>
Get total video duration in seconds.

getPaused(): Promise<boolean>
Check if video is currently paused.

Volume Methods

setVolume(volume: number): Promise<void>
Set volume level (0-1).

getVolume(): Promise<number>
Get current volume level.

mute(): Promise<void>
Mute audio.

unmute(): Promise<void>
Unmute audio.

setMuted(muted: boolean): Promise<void>
Set muted state.

getMuted(): Promise<boolean>
Get current muted state.

Display Methods

toggleFullscreen(): Promise<void>
Toggle fullscreen mode.

requestFullscreen(): Promise<void>
Enter fullscreen mode.

exitFullscreen(): Promise<void>
Exit fullscreen mode.

showControls(): Promise<void>
Show player controls.

hideControls(): Promise<void>
Hide player controls.

setControlsVisible(visible: boolean): Promise<void>
Set controls visibility.

Watermark Methods

addWatermark(config: WatermarkConfig): Promise<void>
Add a watermark overlay to the video.

interface WatermarkConfig {
  text: string;
  color?: string;
  opacity?: number;
  fontSize?: number;
}

Utility Methods

isReady(): boolean
Check if player is ready to receive commands.

whenReady(): Promise<void>
Returns a promise that resolves when the player is ready.

getIframe(): HTMLIFrameElement
Get the iframe element.

getWrapper(): HTMLElement | null
Get the wrapper element (only available for embedded players).

getSrc(): string
Get the iframe source URL.

update(options: Partial<PlayerOptions>): void
Update player options (only available for embedded players).

destroy(): void
Clean up event listeners and remove the player.

Event Methods

on(event: string, callback: Function): this
Register an event listener.

off(event: string, callback?: Function): this
Remove an event listener.

once(event: string, callback: Function): this
Register a one-time event listener.

Events

The player emits the following events:

• ready - Player is ready to receive commands
• play - Playback has started
• playing - Playback is playing
• pause - Playback has paused
• ended - Playback has ended
• timeupdate - Playback position changed
• volumechange - Volume or muted state changed
• seeking - Seeking started
• seeked - Seeking completed
• waiting - Waiting for data
• canplay - Enough data to play
• canplaythrough - Can play through without buffering
• loadedmetadata - Metadata loaded
• loadeddata - Frame data loaded
• durationchange - Duration changed
• ratechange - Playback rate changed
• fullscreenchange - Fullscreen state changed
• error - Playback error occurred

Examples

Basic Playback Control

import { Player } from "@vidinfra/player";

const player = new Player("#player-iframe");

await player.whenReady();

document.getElementById("play-btn").addEventListener("click", () => {
  player.play();
});

document.getElementById("pause-btn").addEventListener("click", () => {
  player.pause();
});

player.on("timeupdate", (state) => {
  const currentTime = Math.floor(state.currentTime);
  const duration = Math.floor(state.duration);
  console.log(`${currentTime}s / ${duration}s`);
});

Volume Control

import { Player } from "@vidinfra/player";

const player = new Player("#player-iframe");

await player.whenReady();

const volumeSlider = document.getElementById("volume");
volumeSlider.addEventListener("input", (e) => {
  const volume = e.target.value / 100;
  player.setVolume(volume);
});

const muteBtn = document.getElementById("mute");
muteBtn.addEventListener("click", async () => {
  const isMuted = await player.getMuted();
  player.setMuted(!isMuted);
});

Creating and Controlling an Embed

import { Player } from "@vidinfra/player";

const player = new Player("vidinfra-player", {
  libraryId: 1234567,
  videoId: 59777392,
  playerId: 27282929,
  autoplay: false,
  loop: false,
  muted: false,
  controls: true,
  preload: true,
  aspectRatio: "16:9"
});

player.on("ready", () => {
  console.log("Player created and ready");
});

player.on("play", () => {
  console.log("Video playing");
});

setTimeout(() => {
  player.update({ loop: true });
}, 5000);

TypeScript Example

import { Player, PlayerOptions, WatermarkConfig } from "@vidinfra/player";

const options: PlayerOptions = {
  libraryId: 1234567,
  videoId: 59777392,
  playerId: 27282929,
  autoplay: false,
  loop: false,
  muted: false,
  controls: true,
  preload: true,
  aspectRatio: "16:9"
};

const player = new Player("vidinfra-player", options);

await player.whenReady();

const volume: number = await player.getVolume();
const duration: number = await player.getDuration();

const watermark: WatermarkConfig = {
  text: "Confidential",
  color: "#ffffff",
  opacity: 0.3,
  fontSize: 24
};

await player.addWatermark(watermark);

Security

The Player automatically validates the origin of postMessage communications based on the iframe's source URL. For iframe-side implementations, you should also validate the origin of incoming messages:

window.addEventListener("message", (event) => {
  const allowedOrigin = "https://trusted-parent.com";
  if (event.origin !== allowedOrigin) return;
  
  // Handle message
});

Browser Support

• Modern browsers with ES6+ support
• Requires postMessage API
• Fullscreen API support varies by browser

TypeScript

Full TypeScript definitions are included with the package:

import { Player, PlayerOptions, WatermarkConfig, WatermarkOptions } from "@vidinfra/player";

License

MIT