# 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:

  - `zoo`: [Me at the zoo (0:19, three chapters)](https://www.youtube.com/watch?v=jNQXAC9IVRw)
  - `gwagon`: [G-Wagon buyer guide (18 min)](https://www.youtube.com/watch?v=cCPsdFdlshc)

- `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](https://vid2context.com/docs/embed.md), 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.
