Sign In
Player SDK

HTML

The sc-player element for any website, loaded with one script tag.

Preview

The script is not published yet. The examples show the URL it will be served from.

The element

Load the script once, then place the player where it should appear. The attributes are the options - except ads, which the element does not support yet.

A player on any page
<script src="https://sonicast.io/pkg/sc.vanilla.js"></script><sc-player domain="BRAND_KEY.pub.sonicast.io"></sc-player>
A program and a format
<sc-player  domain="BRAND_KEY.pub.sonicast.io"  program="PROGRAM_KEY"  format="aac-64"  history="10"></sc-player>

The script is versioned: sc.vanilla.js is always the latest release, sc.v2026.11.11.vanilla.js a fixed one. Pin a version when your page must not change without you.

Styling

The element renders in a shadow root, so your page's CSS does not leak in and the player's does not leak out. Its parts are exposed for styling with ::part():

sc-player::part(button) { background: crimson; border-radius: 4px; }
sc-player::part(title) { font-family: Georgia, serif; }
sc-player::part(meta) { display: none; }
sc-player::part(history) { font-size: 12px; }
PartWhat it is
buttonthe play button
titlethe current title
metathe status line (artist, feed and player status)
historythe list of recent tracks

Events and properties

The element fires now-playing whenever the feed updates; event.detail is the program's state, the feed's JSON.

React to updates
<sc-player id="player" domain="BRAND_KEY.pub.sonicast.io"></sc-player><script>  const player = document.getElementById("player");  player.addEventListener("now-playing", (event) => {    document.title = event.detail.item?.title ?? "Radio";  });</script>
PropertyWhat it is
player.statethe last state from the feed, null before the first update
player.historythe recent tracks, newest first
player.targetwhat the domain resolved to: the program's streams (mounts) and the one being played (mount)
player.toggle()play / stop

Changing an attribute (domain, program, format, history) reconnects the player to the new program.

Without the element

The script also exposes the building blocks as window.Sonicast - createScPlayer(options) returns the same player the element uses, with getState(), subscribe(), play(), pause() and toggle(), for a player drawn entirely by your own code.

On this page

HTML