VpOutstreamPlayer

VpOutstreamPlayer is a lightweight, customizable outstream video‑ad player built on the Google IMA SDK. It supports:

• Smooth VAST ad playback with waterfall fallbacks
• Viewability tracking (auto‑pause / auto‑play on scroll)
• Custom controls (play, mute, skip, fullscreen, hover volume)
• Rich lifecycle callbacks (request → load → start → timeupdate → complete / error / pause / resume)
• Ad‑block detection and graceful fallback
• Optional responsive sizing

Repository

https://github.com/lumdukaj/vpOutstreamPlayer

Installation

npm (recommended)

npm install vp-outstream-player

or

yarn add vp-outstream-player

💡 Note: The player automatically injects
https://imasdk.googleapis.com/js/sdkloader/ima3.js
if it's not already loaded.
You can include it manually to avoid first‑time latency.

GitHub (development)

git clone https://github.com/lumdukaj/vpOutstreamPlayer.git
cd vpOutstreamPlayer
npm install
npm run build

Usage

ES modules (with bundler like Vite, Rollup, Webpack)

import vpOutstreamPlayer from "vp-outstream-player";

vpOutstreamPlayer("player").setup({
	adBreaks: [{ adTagUrl: ["https://example.com/vast.xml"] }],
	responsive: true,
	startMuted: true,
	controls: { play: true, mute: true, volume: true },
	debug: false,
});

Plain HTML (UMD bundle, no bundler required)

<!-- Optional: pre-load IMA SDK -->
<script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

<!-- Use local build from dist or node_modules -->
<script src="dist/vpOutstreamPlayer.umd.js"></script>

<div id="player"></div>
<script>
	vpOutstreamPlayer("player").setup({
		adBreaks: [{ adTagUrl: ["https://example.com/vast.xml"] }],
		size: { width: 640, height: 360 },
	});
</script>

Configuration

| Key | Type | Default | Description | | --------------------- | ------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | adBreaks | AdBreakConfig[] | [] | List of ad breaks; each includes one or more VAST tag URLs (as waterfall). | | responsive | boolean | false | If true, player stretches to 100% of its container. Overrides size. | | size | { width:number; height:number } | 640×360 | Fixed dimensions when responsive is disabled. | | startMuted | boolean | true | Whether to start the first ad muted when the user hasn't interacted. | | controls | { play:boolean; mute:boolean; volume:boolean } | all true | Toggle visibility of control buttons. | | autopauseOnViewable | { state: boolean } | false | Pause ad when player is no longer in view. | | autostartOnViewable | { state: boolean } | true | Resume ad when player comes back into view. | | adCycleDelayMs | number | 3000 | Delay before starting the next ad after a completed one. | | adRetryLimit | number | 2 | How many times to retry the same ad before skipping. | | adCycleRestartMs | number \| null | -1 | Time before restarting ad cycle from the beginning. Set to -1 or null to disable restart. | | debug | boolean | false | Logs lifecycle events and state changes to console. | | Callbacks | function | — | Lifecycle hooks: onAdRequested, onAdLoaded, onAdStarted, onAdTimeUpdate, onAdSkipped, onAdComplete, onAdError, onAdPause, onAdResume |

export interface AdBreakConfig {
	/** One or more VAST tag URLs (in fallback order) */
	adTagUrl: string[];
}

Programmatic API

You can interact with the player via methods and properties:

Methods

• play() — Start or resume ad playback.
• pause() — Pause the ad.
• mute() / unmute() — Toggle mute state.
• setVolume(number) — Set volume (0 to 1).
• skipAd() — Skip the current ad.
• getState() — Returns player state (e.g. isMuted, isPlaying, etc).

Properties

• isPlaying — Whether the ad is playing.
• isMuted — Whether the player is muted.
• volume — Current volume level.

Development

npm run build        # Rollup UMD + CJS + ESM
npm run dev          # Rollup watch mode
npm run type-check   # TypeScript type-check only
npm run watch        # tsc --watch