The web component and postMessage API
/embed.js defines a <vid2context-embed> element. It puts the widget in an iframe from the same server the script came from, resizes it to its content, and turns the widget's messages into DOM events. It is a single small script with no dependencies.
Try it
This is the element running on this page. The buttons call its methods, and every event it fires is logged under it.
The element appears here once /embed.js loads.
DOM events
<script src="https://vid2context.com/embed.js" async></script>
<vid2context-embed id="demo" sample="gwagon" max-height="420"></vid2context-embed>
<script>
const demo = document.getElementById('demo');
demo.addEventListener('vid2context:loaded', (e) => console.log(e.detail.title, e.detail.segments));
demo.addEventListener('vid2context:segment', (e) => console.log(e.detail.startSec, e.detail.text));
demo.seek('2:30'); // scroll to 2:30
demo.search('engine'); // filter the transcript
demo.setAttribute('theme', 'light');
</script>Attributes
Every embed parameter is an attribute with the same name, plus three that only the element has:
height: a fixed height in pixels. Without it the element follows the widget's size.max-height: the tallest the element grows for the transcript and chapters views, which scroll inside it. Default 640.loading:lazy(the default) waits until the element is near the screen;eagerloads at once.
Changing an attribute reloads the widget with the new options, except theme, which switches in place.
Events
The element fires these as CustomEvents that bubble, with the fields in event.detail:
Message type |
DOM event | Fields | When |
|---|---|---|---|
ready |
vid2context:ready |
{ version } |
The widget started and is loading its context. |
loaded |
vid2context:loaded |
{ title, url, durationSec, segments, chapters, language, origin } |
The context is shown. |
resize |
vid2context:resize |
{ height } |
The content height changed. The loader uses it to size the iframe. |
segment |
vid2context:segment |
{ startSec, endSec, text } |
The reader clicked a line or a chapter. |
seek |
vid2context:seek |
{ sec, index } |
With the player on, playback reached a new line. |
search |
vid2context:search |
{ query, matches } |
The search box changed. |
error |
vid2context:error |
{ code, message, hint } |
The context could not be loaded or a parameter was wrong. |
const el = document.querySelector('vid2context-embed');
el.addEventListener('vid2context:loaded', (e) => {
console.log(`${e.detail.title}: ${e.detail.segments} lines, ${e.detail.chapters} chapters`);
});
el.addEventListener('vid2context:segment', (e) => {
// The reader clicked a line: send it to your own player, notes or chat box.
console.log(e.detail.startSec, e.detail.text);
});
el.addEventListener('vid2context:error', (e) => console.warn(e.detail.code, e.detail.hint));Methods
el.seek(sec): scroll to the line at this time and highlight it. Takes seconds or a string like"2:30". Withplayer="1", the video seeks too.el.search(query): set the search box. An empty string clears it.el.setTheme('auto' | 'light' | 'dark'): same as setting thethemeattribute.el.load({ url }),el.load({ sample })orel.load({ src }): show another video without rebuilding the element.
From JavaScript
Vid2Context.embed(target, options) creates the element inside target (an element or a CSS selector) and returns it. Option names are the parameters; camelCase names become kebab-case attributes (maxHeight becomes max-height), and true and false become 1 and 0.
<div id="talk"></div>
<script src="https://vid2context.com/embed.js"></script>
<script>
const widget = Vid2Context.embed('#talk', {
url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
theme: 'light',
player: true,
maxHeight: 520,
});
widget.addEventListener('vid2context:loaded', (e) => console.log(e.detail.title));
</script>Vid2Context.origin is the server the script came from, and Vid2Context.params lists every parameter name.
Without the script: postMessage
A plain iframe speaks the same protocol. The widget posts every event to its parent as an object with source: "vid2context" and a type; the fields are the ones in the table above.
const frame = document.querySelector('iframe[src*="/embed/"]');
window.addEventListener('message', (e) => {
if (e.source !== frame.contentWindow || e.origin !== 'https://vid2context.com') return;
if (e.data?.source !== 'vid2context') return;
if (e.data.type === 'resize') frame.style.height = `${Math.min(e.data.height, 640)}px`;
if (e.data.type === 'segment') console.log(e.data.startSec, e.data.text);
});To send a command, post an object with target: "vid2context" to the iframe:
type |
Fields | What it does |
|---|---|---|
seek |
{ sec } |
Scroll to the line at this time (and seek the player when it is on). |
search |
{ query } |
Set the search box. |
theme |
{ theme: "auto" | "light" | "dark" } |
Switch theme without reloading. |
load |
{ url }, { sample } or { src } |
Load another video, sample or JSON file. |
frame.contentWindow.postMessage({ target: 'vid2context', type: 'seek', sec: 75 }, 'https://vid2context.com');
frame.contentWindow.postMessage({ target: 'vid2context', type: 'search', query: 'engine' }, 'https://vid2context.com');The widget only accepts commands from the page that embeds it (its window.parent), and it posts nothing it does not show: the messages carry the same public transcript the widget displays.