Integration & API Reference

Complete technical guide for embedding VidEmbed Player on external websites, CMS systems, and web applications using URL parameters or the JavaScript SDK.

1. URL Parameter Type Integration

The simplest way to embed VidEmbed Player is using a standard HTML <iframe> pointing to /embed with query parameters.

<iframe src="https://your-domain.com/embed?url=https://lorem.video/720p.mp4&title=Sample+Video&autoplay=1&muted=1" style="width: 100%; aspect-ratio: 16/9; border: none; border-radius: 12px;" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowfullscreen> </iframe>
Parameter Type Default Description
url / src string none Direct link to the video media (MP4, MKV, AVI, WebM, HLS, DASH, TS).
title string none Display title shown in the top control bar and media session.
poster string none Preview image URL displayed before the video begins playback.
autoplay 1 | 0 0 Automatically starts playback on page load (starts muted per browser autoplay policy).
muted 1 | 0 0 Sets audio playback to muted initially.
controls 1 | 0 1 Toggles display of the player overlay controls.
loop 1 | 0 0 Automatically restarts video from the beginning upon completion.
theme string "dark" Player UI theme: dark, light, cyberpunk, or midnight.
accent hex color #6366f1 Custom accent color for seek bars, highlights, and active buttons (e.g. %2306b6d4).
ambient 1 | 0 0 Enables reactive canvas ambient glow behind the player canvas.
starttime number 0 Playback start time offset in seconds (e.g. starttime=45).
data base64 string none Base64-encoded JSON payload containing all parameters in a single parameter string.

2. API Type: JavaScript Embed SDK

For dynamic applications, the vidembed.js client SDK allows mounting and controlling the player programmatically.

<script src="https://your-domain.com/vidembed.js"></script> <div id="my-video-container"></div> <script> const player = VidEmbed.create('#my-video-container', { src: 'https://lorem.video/cat.mp4', title: 'Cat Playing [1080p]', autoplay: false, muted: false, controls: true, theme: 'dark' }); player.on('play', () => console.log('Video started playing')); player.on('timeupdate', (payload) => console.log('Current time:', payload.currentTime)); player.seek(30); player.setVolume(0.8); </script>

3. API Type: Two-Way postMessage Protocol

When embedding via <iframe>, the parent document can send commands to the iframe and receive real-time playback events.

Host to Iframe Command: iframe.contentWindow.postMessage({ source: 'vidembed-host', action: 'play' }, '*')
Action Value Type Example
play none { source: 'vidembed-host', action: 'play' }
pause none { source: 'vidembed-host', action: 'pause' }
seek number (seconds) { source: 'vidembed-host', action: 'seek', value: 45 }
setVolume number (0.0 to 1.0) { source: 'vidembed-host', action: 'setVolume', value: 0.75 }
setMuted boolean { source: 'vidembed-host', action: 'setMuted', value: true }
setSpeed number (playbackRate) { source: 'vidembed-host', action: 'setSpeed', value: 1.5 }
loadSource string (new URL) { source: 'vidembed-host', action: 'loadSource', value: 'https://lorem.video/720p.mp4', title: 'New Stream' }