Embed

Embed parameters

Every option is a query parameter of /embed/ and an attribute of <vid2context-embed> with the same name. Leave a parameter out to use its default. The widget checks every value: a bad one shows an error in the widget (code bad_param) instead of being ignored silently.

All parameters

Parameter Values Default What it does
url URL none Any video link vid2context understands. The widget fetches its context from the API when it loads.
sample zoo, gwagon none A recorded context served by the site (zoo or gwagon). Needs no API call; good for trying layouts.
src URL none A VideoContext JSON file you host (for example from vid2context get <url> --format json). The host must allow CORS.
api URL none Base URL of another vid2context server, for example your own deployment. Empty means the server that serves the widget.
lang language code none BCP-47 code of the transcript to prefer, for example en or pt-BR.
mode auto, captions, stt, video auto auto: captions first, then speech-to-text. captions, stt and video force one path.
view transcript, chapters, quote, card, input transcript transcript: searchable timed transcript. chapters: the chapter list. quote: the lines between start and end. card: title, thumbnail and chapters. input: a link box that opens the vid2context app.
theme auto, light, dark auto auto follows the reader’s system setting.
accent hex none Hex color for highlights and buttons, without the #, for example 3b82f6.
compact 1 or 0 off (0) Tighter spacing and smaller text.
header 1 or 0 on (1) Show the title, channel and length.
player 1 or 0 off (0) YouTube only: show the video (youtube-nocookie.com) above the transcript, keep the current line in sync and seek on click. Off by default because it loads YouTube.
timestamps 1 or 0 on (1) Show a timestamp before each line.
search 1 or 0 on (1) Filter the transcript as the reader types.
tools 1 or 0 on (1) Copy the transcript, download it as text, SRT or JSON, or open the video in the vid2context app.
branding 1 or 0 on (1) A small "Context by vid2context" link in the footer.
start seconds, m:ss or 1m15s none Show only lines from this time on. Also the start of a quote. Accepts 75, 1:15 or 1m15s.
end seconds, m:ss or 1m15s none Show only lines up to this time.

Where the context comes from

Give exactly one source. When more than one is set, sample wins, then src, then url.

  • url: the widget calls GET /api/v1/context?url=... on the server that serves it, or on api when set. lang and mode are passed along.

  • sample: a recorded context served by this site. No API call, so it is the quickest way to try a layout. The samples:

  • src: any URL that returns a VideoContext JSON, for example a file you saved with vid2context <url> --format json and host next to your page. The host must send Access-Control-Allow-Origin for the widget's origin (or *).

Examples

A searchable transcript in a light theme with a blue accent:

text
https://vid2context.com/embed/?url=https://www.youtube.com/watch?v=jNQXAC9IVRw&theme=light&accent=3b82f6

The video above its transcript, with the current line highlighted as it plays:

text
https://vid2context.com/embed/?url=https://www.youtube.com/watch?v=jNQXAC9IVRw&player=1

A quote of the lines between 0:05 and 0:13, with a link to that moment:

text
https://vid2context.com/embed/?sample=zoo&view=quote&start=0:05&end=0:13

Only the first two minutes of a long video, without the header or the credit line:

text
https://vid2context.com/embed/?url=https://www.youtube.com/watch?v=cCPsdFdlshc&end=2m&header=0&branding=0

A widget that reads a context file you host:

text
https://vid2context.com/embed/?src=https://example.org/contexts/talk.json

Try any of them in the builder, which writes the address for you.

Sizing

An iframe has the height you give it. The transcript and chapters views scroll inside that height, and the quote, card and link box views are as tall as their content. The builder's snippets use a height that fits the view. The web component sizes the iframe for you: up to max-height (default 640) for the views that scroll, and exactly to the content for the others. Set height on the element to fix it instead.