oembed-graphics/README.md

oembed-graphics

Docker-hosted oEmbed graphics for broadcast workflows. It is inspired by 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

npm install
npm start

Open http://localhost:3000.

Run with Docker

docker compose up --build

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

Broadcast URL

Use /graphic with a source URL:

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:

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.