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 callsGET /api/v1/context?url=...on the server that serves it, or onapiwhen set.langandmodeare 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 withvid2context <url> --format jsonand host next to your page. The host must sendAccess-Control-Allow-Originfor the widget's origin (or*).
Examples
A searchable transcript in a light theme with a blue accent:
https://vid2context.com/embed/?url=https://www.youtube.com/watch?v=jNQXAC9IVRw&theme=light&accent=3b82f6The video above its transcript, with the current line highlighted as it plays:
https://vid2context.com/embed/?url=https://www.youtube.com/watch?v=jNQXAC9IVRw&player=1A quote of the lines between 0:05 and 0:13, with a link to that moment:
https://vid2context.com/embed/?sample=zoo&view=quote&start=0:05&end=0:13Only the first two minutes of a long video, without the header or the credit line:
https://vid2context.com/embed/?url=https://www.youtube.com/watch?v=cCPsdFdlshc&end=2m&header=0&branding=0A widget that reads a context file you host:
https://vid2context.com/embed/?src=https://example.org/contexts/talk.jsonTry 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.