# oembed-graphics

Docker-hosted oEmbed graphics for broadcast workflows. It is inspired by
[webrecorder/oembed.link](https://github.com/webrecorder/oembed.link), but runs
as a normal container and exposes graphic URLs that can be loaded by CasparCG,
OBS Browser Source, OGraf, or any HTML-capable character generator.

## Run locally

```sh
npm install
npm start
```

Open `http://localhost:3000`.

## Run with Docker

```sh
docker compose up --build
```

The service listens on `http://localhost:3000`.

## Broadcast URL

Use `/graphic` with a source URL:

```txt
http://localhost:3000/graphic?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&width=1920&height=1080&transparent=1
```

Useful query parameters:

- `url`: required source URL to resolve through oEmbed.
- `width`: stage width, default `1920`.
- `height`: stage height, default `1080`.
- `transparent`: `1` for transparent output, default `1`.
- `chroma`: background color when transparent output is disabled, default `#00ff00`.
- `fit`: `contain` or `cover`, default `contain`.
- `scale`: graphic scale multiplier, default `1`.
- `maxwidth`: sent to the oEmbed provider, default is based on stage width.

The service also supports the oembed.link-style form:

```txt
http://localhost:3000/https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ
```

## API

- `GET /api/oembed?url=...` returns the matched provider and raw oEmbed data.
- `GET /providers` returns the loaded provider patterns.
- `GET /healthz` returns a health check response.

Provider data is loaded from `https://oembed.com/providers.json` and cached in
memory. Override with `PROVIDERS_URL`, `PROVIDERS_TTL_MS`, and
`OEMBED_TIMEOUT_MS` environment variables.