Player SDK for Embedded Video Control

The Vidinfra Player SDK is a lightweight, type safe JavaScript library for controlling embedded video players inside iframes. It uses the postMessage API for secure, real time communication, making custom player integration simple and efficient.

Key Features

Unified API: One class manages both controlling existing iframes and embedding new players.
Type-safe: Full TypeScript support with comprehensive type definitions for a reliable development - experience.
Framework-agnostic: Works seamlessly with any JavaScript framework or plain JavaScript.
Secure: Built-in origin validation for postMessage communication to ensure safe interactions.
Event-driven: Listen to real-time player events such as play, pause, and time updates.
Lightweight: The SDK is approximately 15KB when minified, making it efficient and easy to use.

Installation

NPM Installation

To install the Vidinfra Player SDK via npm, run the following command:

npm install @vidinfra/player

CDN Installation

Alternatively, you can load the SDK via a CDN:

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

This method allows you to use the SDK without needing to install it locally, making it easy to integrate into static or non-Node.js projects.

Quick Start

The Player SDK allows you to control existing iframe players and create embedded players on the fly. Below are the basic instructions for both use cases.

Control an Existing Iframe

If you already have an iframe on your page and want to control the video player inside it, you can easily use the Player class. With just a few lines of code, you can target an existing iframe, wait for it to be ready, and start playing the video.

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

const player = new Player("iframe");

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

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

Creating an Embedded Player

If you want to embed a video player directly into your page, Vidinfra can automatically create and inject an iframe for you. You can configure the player with your desired settings like autoplay, volume, and aspect ratio.

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

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

player.setVolume(0.5);

To learn how to copy a video ID, check the Quickstart Guide in the Vidinfra section.

Usage

Controlling an Existing Iframe

If you already have an iframe in your HTML, you can control it by passing the iframe element or a CSS selector.

Javascript

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

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

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

CDN

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe
  id="vidinfra-iframe-player"
    src="https://player.vidinfra.com/{librayID}/default/{videoID}?autoplay=false&loop=false&muted=false&controls=true&preload=true"
    loading="lazy"
    style="border: none; position: absolute; top: 0; height: 100%; width: 100%;"
    allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
    allowfullscreen="true">
  </iframe>
</div>

Creating an Embedded Player

You can dynamically create an embedded player by specifying a target element for the player:

Javascript

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

const player = new Player("vidinfra-player", {
  libraryId: default,
  videoId: default,
  playerId: default,
  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: default,
    videoId: default,
    playerId: default,
    autoplay: false,
    loop: false,
    muted: false,
    controls: true,
    preload: true,
    aspectRatio: "16:9"
  });
</script>

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

The PlayerOptions defines all the customizable settings for configuring a Vidinfra player. Here, you specify key details about the video and player behavior. You can set the video’s library ID, video ID, and the player’s size, playback options, and more.

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

These methods control the basic playback behavior of the video. They include actions like starting, pausing, seeking, and changing playback speed. Start video playback.

play(): Promise<void>

Pause video playback.

pause(): Promise<void>

Toggle between play and pause states.

togglePlay(): Promise<void>

Seek to a specific time in seconds.

seek(time: number): Promise<void>

Set playback speed (e.g., 0.5, 1.0, 2.0).

setPlaybackRate(rate: number): Promise<void>

Get current playback rate.

getPlaybackRate(): Promise<number>

Get current playback position in seconds.

getCurrentTime(): Promise<number>

Get total video duration in seconds.

getDuration(): Promise<number>

Check if video is currently paused.

getPaused(): Promise<boolean>

Volume Methods

These methods manage the audio settings for the player. You can adjust the volume, mute, or check the current audio state. Set volume level (0-1).

setVolume(volume: number): Promise<void>

Get current volume level.

getVolume(): Promise<number>

Mute audio.

mute(): Promise<void>

Unmute audio.

unmute(): Promise<void>

Set muted state.

setMuted(muted: boolean): Promise<void>

Get current muted state.

getMuted(): Promise<boolean>

Display Methods

These methods manage the visual behavior of the player, including fullscreen and control visibility. Toggle fullscreen mode.

toggleFullscreen(): Promise<void>

Enter fullscreen mode.

requestFullscreen(): Promise<void>

Exit fullscreen mode.

exitFullscreen(): Promise<void>

Show player controls.

showControls(): Promise<void>

Hide player controls.

hideControls(): Promise<void>

Set controls visibility.

setControlsVisible(visible: boolean): Promise<void>

Watermark Methods

These methods add a watermark to your video, which can be customized with text and styling options. Add a watermark overlay to the video.

addWatermark(config: WatermarkConfig): Promise<void>

WatermarkConfig:

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

Utility Methods

These methods help you interact with the player’s internal state and configuration. Check if player is ready to receive commands.

isReady(): boolean

Returns a promise that resolves when the player is ready.

whenReady(): Promise<void>

Get the iframe element.

getIframe(): HTMLIFrameElement

Get the wrapper element (only available for embedded players).

getWrapper(): HTMLElement | null

Get the iframe source URL.

getSrc(): string

Update player options (only available for embedded players).

update(options: Partial<PlayerOptions>): void

Clean up event listeners and remove the player.

destroy(): void

Event Methods

These methods allow you to listen for events like play, pause, and custom player events. Register an event listener.

on(event: string, callback: Function): this

Remove an event listener.

off(event: string, callback?: Function): this

once(event: string, callback: Function): this

Events

The player emits the following events:

Event	Description
`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: default,
  videoId: default,
  playerId: default,
  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: default,
  videoId: default,
  playerId: default,
  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";

Home

Account & Organization

Vidinfra

Live Streaming

CDN

Cloud

Key Features

Installation

NPM Installation

CDN Installation

Quick Start

Control an Existing Iframe

Creating an Embedded Player

Usage

Controlling an Existing Iframe

Javascript

CDN

Creating an Embedded Player

Javascript

CDN

API Reference

Constructor

Parameters

PlayerOptions

Playback Methods

Volume Methods

Display Methods

Watermark Methods

Utility Methods

Event Methods

Events

Examples

Basic Playback Control

Volume Control

Creating and Controlling an Embed

TypeScript Example

Security

Browser Support

TypeScript

​Key Features

​Installation

​NPM Installation

​CDN Installation

​Quick Start

​Control an Existing Iframe

​Creating an Embedded Player

​Usage

​Controlling an Existing Iframe

​Javascript

​CDN

​Creating an Embedded Player

​Javascript

​CDN

​API Reference

​Constructor

​Parameters

​PlayerOptions

​Playback Methods

​Volume Methods

​Display Methods

​Watermark Methods

​Utility Methods

​Event Methods

​Events

​Examples

​Basic Playback Control

​Volume Control

​Creating and Controlling an Embed

​TypeScript Example

​Security

​Browser Support

​TypeScript

Key Features

Installation

NPM Installation

CDN Installation

Quick Start

Control an Existing Iframe

Creating an Embedded Player

Usage

Controlling an Existing Iframe

Javascript

CDN

Creating an Embedded Player

Javascript

CDN

API Reference

Constructor

Parameters

PlayerOptions

Playback Methods

Volume Methods

Display Methods

Watermark Methods

Utility Methods

Event Methods

Events

Examples

Basic Playback Control

Volume Control

Creating and Controlling an Embed

TypeScript Example

Security

Browser Support

TypeScript