Appearance
Widgets
Playout Widgets are embeddable web components that let you integrate live streaming and replay functionality directly into your own website — no framework required. Drop a script tag on your page and you have a live video player, streaming status banner, program display, and replay archive, all connected to your Playout tenant in real time.
INFO
Widgets connect to the same Playout backend as the operator interface. To embed live stream or replay content, your tenant must have Streaming enabled. Contact contact@playout.studio to get access.
Quick Start
1. Include the widget scripts
Add the scripts for the widgets you want to use. Each widget is a self-contained ES module served from the Playout CDN.
html
<!-- Required for all widgets -->
<script type="module" src="https://widgets.playout.studio/playout-login.js"></script>
<!-- Add only the widgets you need -->
<script type="module" src="https://widgets.playout.studio/playout-streaming-status.js"></script>
<script type="module" src="https://widgets.playout.studio/playout-live-video-player.js"></script>
<script type="module" src="https://widgets.playout.studio/playout-replay-list.js"></script>
<script type="module" src="https://widgets.playout.studio/playout-replay.js"></script>
<script type="module" src="https://widgets.playout.studio/playout-upcoming-events.js"></script>2. Add playout-login
Every page that uses Playout Widgets must include exactly one <playout-login> element. It handles authentication silently in the background — it renders nothing visible.
Option A — inline token (simplest, when the token is already available in the page):
html
<playout-login
tenant="your-tenant-id"
token="SSO_TOKEN_HERE"
></playout-login>Option B — server-fetched token (recommended for production, keeps the token out of the HTML source):
html
<playout-login
tenant="your-tenant-id"
token_location="/api/playout-token"
></playout-login>Replace your-tenant-id with your Playout tenant identifier.
3. Add a widget
Place any widget element anywhere on the page. It will activate automatically once playout-login has authenticated.
html
<playout-streaming-status live_location="/live"></playout-streaming-status>Complete example
html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My website</title>
<script type="module" src="https://widgets.playout.studio/playout-login.js"></script>
<script type="module" src="https://widgets.playout.studio/playout-streaming-status.js"></script>
<script type="module" src="https://widgets.playout.studio/playout-live-video-player.js"></script>
</head>
<body>
<playout-login tenant="your-tenant-id" token="SSO_TOKEN_HERE"></playout-login>
<!-- Shows a "Live now" banner when a stream is active -->
<playout-streaming-status live_location="/live"></playout-streaming-status>
<!-- On your /live page: the video player -->
<playout-live-video-player lang="en"></playout-live-video-player>
</body>
</html>How Authentication Works
Playout Widgets use a two-step authentication flow:
- SSO token exchange —
playout-loginsends your SSO token to the Playout API and receives a short-lived Firebase token in return. - Firebase sign-in — The widget signs into Firebase with that token, gaining access to your tenant's real-time data.
Once signed in, playout-login broadcasts a playout-logged-in event. All other widgets on the page listen for this event and start up automatically. This means:
playout-loginmust be present on every page that uses widgets.- Other widgets can be placed anywhere in the document — they will wait for the login event.
- You only need one
playout-loginper page, regardless of how many widgets you use.
Providing the token
There are two ways to supply the SSO token:
token — inline
Pass the token directly as an attribute. Straightforward, but exposes the token in the HTML source. Suitable when the token is short-lived and already present in a server-rendered page.
html
<playout-login tenant="your-tenant-id" token="SSO_TOKEN_HERE"></playout-login>token_location — server endpoint (recommended)
Pass a URL instead. playout-login fetches the token from that endpoint at runtime using a credentialed request, so the token is never embedded in your HTML.
html
<playout-login tenant="your-tenant-id" token_location="/api/playout-token"></playout-login>Your endpoint must:
- Return the raw SSO token string as the response body (plain text, not JSON).
- Accept credentialed requests — set
Access-Control-Allow-Credentials: trueand an appropriateAccess-Control-Allow-Originheader if the endpoint is on a different origin. - Authenticate the caller via session cookie or similar server-side mechanism.
BCC Signon WordPress plugin
If your site uses the BCC Signon WordPress plugin, the token endpoint is already provided for you. Set token_location to /?bcc-login=access-token:
html
<playout-login
tenant="your-tenant-id"
token_location="/?bcc-login=access-token"
></playout-login>Which production unit is used?
Each Playout tenant can have multiple production units — independent stream endpoints, each of which can be assigned to an event. Widgets derive which event to display by reading the currentEvent assigned to their production unit.
By default playout-login targets the production unit named default. If your tenant uses a different unit, or you run multiple streams simultaneously on separate pages, specify the unit explicitly:
html
<playout-login
tenant="your-tenant-id"
token_location="/api/playout-token"
production_unit="main-stage"
></playout-login>All widgets on the same page follow the production unit set on playout-login. To display two independent streams on the same page, you would need two separate pages — one per production unit.
Widget Reference
playout-login
Handles authentication and bootstraps all other widgets on the page. Renders nothing visible.
| Attribute | Type | Required | Description |
|---|---|---|---|
tenant | string | Yes | Your Playout tenant identifier |
token | string | One of token or token_location | SSO token from your identity provider, provided inline |
token_location | string | One of token or token_location | URL of an endpoint that returns the SSO token as plain text. Fetched with withCredentials |
production_unit | string | No | ID of the production unit whose current event the widgets will display. Defaults to default |
html
<!-- Inline token -->
<playout-login
tenant="your-tenant-id"
token="SSO_TOKEN_HERE"
></playout-login>
<!-- Server-fetched token, non-default production unit -->
<playout-login
tenant="your-tenant-id"
token_location="/api/playout-token"
production_unit="main-stage"
></playout-login>playout-streaming-status
Displays a compact "Live now" banner when a stream is active on the current event. Renders nothing when there is no active stream.
| Attribute | Type | Required | Description |
|---|---|---|---|
live_location | string | Yes | URL the banner links to (e.g. your live page) |
lang | string | No | Locale code for translated labels. See Localization |
html
<playout-streaming-status
live_location="/live"
lang="en"
></playout-streaming-status>playout-live-video-player
Embeds the live video player for the current event. Shows a loading state while the event is resolving, a "no stream available" message when the event is not live, and the Mux video player with the stream title and description when a broadcast is active.
| Attribute | Type | Required | Description |
|---|---|---|---|
lang | string | No | Locale code for translated labels. See Localization |
html
<playout-live-video-player lang="en"></playout-live-video-player>INFO
This widget registers a viewer connection with Playout while it is on the page. The operator interface shows the number of active connections in real time. Connections are refreshed every 30 seconds and cleaned up when the widget is unmounted.
playout-replay-list
Shows a paginated list of past events available for replay. Each row displays the event name and date, with a link to the replay page. The list hides itself automatically when the current URL already contains an eventId query parameter (i.e. when a replay is already selected).
| Attribute | Type | Required | Description |
|---|---|---|---|
replay_location | string | Yes | Base URL for replay pages. The widget appends ?eventId=<id> to build each link |
lang | string | No | Locale code for translated labels. See Localization |
html
<playout-replay-list
replay_location="/replay"
lang="en"
></playout-replay-list>A visitor clicking "Watch replay" is sent to /replay?eventId=abc123. Place playout-replay on that destination page to play back the recording.
playout-replay
Plays back a recorded event. Reads the eventId query parameter from the current URL to determine which recording to load, then shows the Mux video player in on-demand mode.
This widget has no configurable attributes — it reads eventId from the URL automatically.
html
<playout-replay></playout-replay>Typical setup across two pages:
| Page | Widget(s) |
|---|---|
/replays | playout-replay-list |
/replay?eventId=abc123 | playout-replay |
playout-upcoming-events
Displays a list of upcoming scheduled events for your tenant. Use this to show visitors what is coming up next on your website — for example, on a home page or events landing page.
The widget reads upcoming events from your tenant in real time and renders them in chronological order. It hides itself automatically when there are no upcoming events.
| Attribute | Type | Required | Description |
|---|---|---|---|
lang | string | No | Locale code for translated labels. See Localization |
html
<script type="module" src="https://widgets.playout.studio/playout-upcoming-events.js"></script>
<playout-login tenant="your-tenant-id" token_location="/api/playout-token"></playout-login>
<playout-upcoming-events lang="en"></playout-upcoming-events>INFO
playout-login is required on the same page for the widget to authenticate and read your tenant's event schedule.
Localization
Widgets that display text to visitors accept a lang attribute. Set it to the locale code that matches your website's language.
html
<playout-live-video-player lang="fr"></playout-live-video-player>Supported locales:
| Code | Language |
|---|---|
en | English (default) |
fr | French |
If lang is omitted or set to an unsupported value, widgets fall back to English.
Styling
Widgets expose their internal elements via predictable CSS class names using the playout- prefix. You can override these classes from your own stylesheet.
| Widget | Key CSS classes |
|---|---|
playout-streaming-status | .playout-streaming-status__container, .playout-streaming-status__title, .playout-streaming-status__subtitle |
playout-live-video-player | .playout-live-player__loading, .playout-live-player__title, .playout-live-player__description, .playout-live-player__text |
playout-live-program | .playout-program__container, .playout-program__item, .playout-program__item-current |
playout-replay-list | .playout-replay-list__container, .playout-replay-list__element, .playout-replay-list__title, .playout-replay-list__date, .playout-replay-list__link |
playout-upcoming-events | .playout-upcoming-events__container, .playout-upcoming-events__item, .playout-upcoming-events__title, .playout-upcoming-events__date |
WARNING
playout-live-video-player renders in the light DOM, so its classes are directly accessible from your stylesheet. The other widgets render in the shadow DOM — use ::part() or CSS custom properties if you need deeper customisation, or contact the Playout team for guidance.