initial commit

README.md

@@ -1,3 +1,58 @@
 # oembed-graphics
 
-Embed social media posts using Oembed in a  format that's callable from Caspar/OGraf
+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.