HTML
The sc-player element for any website, loaded with one script tag.
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.
<script src="https://sonicast.io/pkg/sc.vanilla.js"></script><sc-player domain="BRAND_KEY.pub.sonicast.io"></sc-player><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; }| Part | What it is |
|---|---|
button | the play button |
title | the current title |
meta | the status line (artist, feed and player status) |
history | the 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.
<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>| Property | What it is |
|---|---|
player.state | the last state from the feed, null before the first update |
player.history | the recent tracks, newest first |
player.target | what 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.