DCAST in Lovable apps

Lovable builds the app; DCAST hosts, transcodes and delivers its video. Viewers get adaptive streaming on any device, authors can broadcast live, and the DCAST player can sell access to a video or a broadcast. Lovable writes the integration code itself from the knowledge text on this page: you describe the feature in the chat instead of writing the calls by hand.

What you need

• A DCAST account: sign up at dcast.pro. Every plan works through the API, including the free one; storage, streaming hours and paid features follow your plan exactly as on the website.
• A DCAST API key (it starts with pk_), created in your DCAST cabinet. See Authentication.
• A Lovable project with its built-in backend (Lovable Cloud) or a connected Supabase project, so that the key stays on the server.

Connect DCAST to your project

The published app can call DCAST in two ways, and both keep the key out of the browser. Choose the custom connector if you are a workspace admin or owner in Lovable; otherwise use the direct integration. The DCAST MCP server can be added to either one for help while you build.

Option 1: a DCAST custom connector

Lovable can turn any REST API into a connector of your workspace. Creating one needs the workspace admin or owner role in Lovable.

1. In Lovable open Connectors, choose Add custom, then Custom connector.
2. Under Details: display name DCAST, category Other, documentation URL https://dcast.pro/docs.
3. Under Authentication: choose Bearer token and set the API base URL to https://api.dcast.pro/api/v1.
4. For the test request choose GET and the path /me: it answers with your account when the key is right.
5. Under Agent knowledge, add a knowledge file and paste the knowledge text below as its content.
6. Choose Create, connect the new DCAST connector in your project and paste your API key when Lovable asks for the token.

Option 2: direct integration with a secret

1. In the project open More → Settings → Secrets and add the secret DCAST_API_KEY with your API key. Do not paste the key into the chat.
2. Open Project settings → Knowledge and paste the knowledge text below. It is well under the 10,000-character limit of Lovable knowledge.
3. Ask for the feature in the chat (examples below). Lovable writes the server-side code that reads the secret: an Edge Function in React + Vite apps, a server function in TanStack Start apps.

While you build: the DCAST MCP server

In Connectors → Add custom → MCP server enter https://api.dcast.pro/mcp and choose bearer-token authentication with your API key. Lovable can then search the DCAST documentation and recipes and work with your account from the chat, asking before it changes anything. This is a chat connection: Lovable does not include it in the published app, so the app still needs option 1 or 2. The same server is described on the Claude connector page.

Knowledge text

Copy the whole block. It tells Lovable which DCAST calls to use for upload, playback, live streams, paid access and webhooks, and where the key may and may not go.

# DCAST video API: how this app hosts video, live streams and paid access

DCAST (dcast.pro) hosts, transcodes and delivers this app's videos and live streams, and runs the player with its paywall. Use DCAST for every video feature; do not store video files in the app's own storage and do not build a video player.

## Rules
- API base URL: `https://api.dcast.pro/api/v1`. Paths below are relative to it.
- Auth: `Authorization: Bearer <DCAST API key>`. The key starts with `pk_`. If the DCAST connector is connected, it attaches the key; otherwise the key is the secret `DCAST_API_KEY` and only server-side code (an Edge Function, or a server function in TanStack Start apps) reads it. Never put the key in browser code, in a `VITE_` variable or in the database.
- Answers are `{ "success": true, "data": ... }` or `{ "success": false, "error": { "code", "message" } }`. Show `error.message` to the user when a call is refused (plan limits such as `QUOTA_EXCEEDED` arrive this way). Do not retry a plan-limit refusal.
- Never write embed HTML or player URLs by hand: take them from the API answers named below.
- Only these calls are needed. Full reference: https://dcast.pro/docs and https://api.dcast.pro/api/v1/docs/openapi.json. Do not invent endpoints or fields.

## 1. Upload a video (files of any size go straight from the browser to DCAST)
Step 1, on the server (needs a signed-in user):
```
POST /videos/upload
{ "title": "Lesson 1", "fileName": "lesson-1.mp4", "fileSize": 734003200, "visibility": "PRIVATE" }
```
`fileSize` is the exact byte count of the file. `visibility` is one of PUBLIC, LINK_ONLY, PRIVATE, REGISTERED (default PRIVATE). Return to the browser only `data.video.id` and `data.upload.url`. `data.upload.url` is a signed, single-use URL that carries its own credential; it is not the API key.

Step 2, in the browser: load `<script src="https://dcast.tv/embed/dcast.js"></script>` once (in index.html) and call
```js
const result = await window.DcastStudio.upload({
  uploadUrl, file,
  onProgress: (p) => setProgress(p.percent),
});
```
It uploads with the resumable TUS 1.0 protocol and continues after a dropped connection. Do not upload the file to Supabase storage first.

Step 3: wait for processing. On the server, `GET /videos/{id}/status` every 10-30 seconds until `data.status` is `READY` or `FAILED`, or receive the `video.processing.completed` webhook (section 5).

Save the DCAST video id in the app's own table (for example `lessons.dcast_video_id`).

## 2. Show a video
On the server: `GET /videos/{id}/embed`. Render `data.responsive` (fills its container at the video's ratio) or `data.iframe` (fixed size) exactly as returned, for example with `dangerouslySetInnerHTML` in a wrapper div. `data.url` is the bare player address. The same player plays private, paid and password-protected videos and asks the viewer for payment or the password itself.

## 3. Live stream
Admin only (the app owner or course author), on the server:
```
POST /streams
{ "title": "Friday class", "visibility": "PUBLIC" }
```
Send an `Idempotency-Key` header so a retry does not create a second stream. The answer has `data.id`, `data.ingest.rtmp`, `data.ingest.srt`, `data.ingest.whip` and `data.playback.embed`. The ingest URLs contain the stream key: show them only to the admin (OBS uses `ingest.rtmp` or `ingest.srt`; a browser encoder uses `ingest.whip`) and never send them to viewers.

Viewers: put `data.playback.embed` as the `src` of an iframe with `allow="autoplay; fullscreen; encrypted-media; picture-in-picture; payment"` and `allowfullscreen`. Do not change the address.

Going on air: after the encoder is sending (`GET /streams/{id}` shows `data.hasSignal: true`), call `POST /streams/{id}/start` (no body). To end, `POST /streams/{id}/stop`. The stream card and its key stay, so the same stream and the same player are reused for the next class. `GET /streams/{id}` returns `data.status` LIVE or OFFLINE.

## 4. Paid access (the DCAST player takes the payment)
Admin only, on the server:
```
PATCH /videos/{id}      { "isPaid": true, "price": 19 }
PATCH /streams/{id}     { "isPaid": true, "price": 9.99 }
```
`price` is in US dollars (0 to 9999); `{ "isPaid": false }` makes it free again. The DCAST player then shows the price, takes the payment (card and other methods) and opens the video for the buyer; the app does not build a checkout and does not need Stripe for this. If the answer is `NO_PAYOUT_GATEWAY`, the DCAST account owner must first connect a payout method in the DCAST cabinet (dcast.pro).

## 5. Webhooks (DCAST tells the app what happened)
Register once (server, admin):
```
POST /me/webhooks
{ "url": "https://<project>.supabase.co/functions/v1/dcast-webhook",
  "events": ["video.processing.completed", "video.processing.failed", "stream.broadcast_started", "stream.broadcast_stopped", "purchase.completed", "purchase.refunded"] }
```
The answer's `signingSecret` (starts with `whsec_`) is shown only once: store it as the secret `DCAST_WEBHOOK_SECRET`.

Each delivery is a POST with body `{ id, type, created, data }` and header `Dcast-Signature: t=<unix seconds>,v1=<hex>`. Verify before trusting it: compute HMAC-SHA256 of `${t}.${rawBody}` with the whole `whsec_...` secret as the key, compare with `v1` in constant time, and reject if `t` is more than 300 seconds from now. The receiving function must accept calls without a Supabase user token (turn off JWT verification for it) because DCAST, not a signed-in user, calls it.

`purchase.completed` data: `orderId`, `kind` (video, stream, course, booking, tip), `sourceId` (the video or stream id), `buyerId` (DCAST user id or null for a guest), `priceCents`, `grossCents`, `currency`, `completedAt`. It carries no buyer email, so it cannot be matched to an app user; use it for the app's sales records. Access itself is enforced by the DCAST player, not by the app.

## 6. Embedding allowed sites
`GET /me` returns `data.embedAllowlist`. An empty list means the player may appear on every site. If it is not empty, add this app's domain (`<app>.lovable.app` and any custom domain) with `PATCH /me/embed-allowlist { "domains": [ ...current entries, "<app>.lovable.app" ] }`; this call replaces the whole list, so always send the current entries too.

## Account
No DCAST account yet: https://dcast.pro/signup?utm_source=lovable&utm_medium=integration&utm_campaign=knowledge . The API key is created in the DCAST cabinet. Plan limits (storage, streaming hours, paid features) are the same in the API and in the cabinet.

What Lovable builds with it

Example requests to Lovable

• “Add a lessons page: the admin uploads a video for each lesson to DCAST and students watch it in the DCAST player.”
• “Add a live class: the admin creates a DCAST stream and sees the OBS address, students see the player on the class page.”
• “Make lesson 3 paid at $19 through DCAST and record every completed DCAST purchase in a sales table.”

What stays on the server

• The API key is read only by server-side code or by the connector. Lovable treats anything prefixed with VITE_ as visible in the browser, so never store the key that way.
• The ingest addresses returned by POST /streams contain the stream key. Show them to the author only, never to viewers.
• Check the Dcast-Signature header of every webhook before trusting it, as described in Webhooks.

Support

Write to [email protected]. Plan limits and error codes are the same in the API and in the cabinet (see Errors and limits).