React
The ScPlayer component, its parts for your own design, and the hooks behind them.
The package is not published yet. The examples show the API as it will be
imported from @sonicast/sdk/react.
The default player
ScPlayer renders a complete player: play button, the current title and
artist, the feed status, and the recent tracks below. Everything is
configured through one options object, see Options.
import { ScPlayer } from "@sonicast/sdk/react";export function Listen() { return <ScPlayer options={{ domain: "BRAND_KEY.pub.sonicast.io" }} />;}<ScPlayer options={{ domain: "BRAND_KEY.pub.sonicast.io", program: "PROGRAM_KEY", format: "aac-64", history: 10, }}/>Theming
The default player takes its colours and shapes from CSS variables. Set them
on the player (style, or a class) or anywhere above it:
<ScPlayer options={{ domain: "BRAND_KEY.pub.sonicast.io" }} style={{ "--sc-accent": "#dc2626", "--sc-radius": "0" }}/>| Variable | Default | Used for |
|---|---|---|
--sc-font | 14px/1.4 system-ui, sans-serif | the font |
--sc-fg | #18181b | text |
--sc-muted | #71717a | the status line and the history |
--sc-border | #d4d4d8 | the frame and the separator |
--sc-accent | #2563eb | the play button |
--sc-accent-fg | #fff | the play button's icon |
--sc-radius | 8px | the frame's corners |
className and style go to the player's outer element.
Your own player from the parts
When the default layout is not what your site needs, build the player from
its parts. They are unstyled: each renders one plain element with the
behaviour attached, and the state as data attributes for your CSS. Root
holds the player; everything inside it reads from that player.
import { ScPlayer } from "@sonicast/sdk/react";export function Listen() { return ( <ScPlayer.Root options={{ domain: "BRAND_KEY.pub.sonicast.io" }}> <ScPlayer.PlayButton className="play" /> <ScPlayer.Title className="title" /> <ScPlayer.Artist className="artist" /> <ScPlayer.History limit={3} className="recent" /> </ScPlayer.Root> );}.play[data-status="playing"] { background: crimson; }
.play[data-status="loading"] { opacity: 0.5; }| Part | Renders | State |
|---|---|---|
ScPlayer.Root | nothing - the player and its context | - |
ScPlayer.PlayButton | a button that plays and stops | data-status: idle, loading, ad, playing, error |
ScPlayer.Title | a span with the title (else the stream text); the ad's title while one plays | data-status as above |
ScPlayer.Artist | a span with the artist, nothing without one; the advertiser while an ad plays | data-status as above |
ScPlayer.Status | a span with the feed and player status | data-feed: resolving, connecting, live, reconnecting, error; data-status as above |
ScPlayer.Companion | an a with the ad's companion image, nothing without one - see Ads | - |
ScPlayer.History | an ol of the recent tracks, newest first | limit (entries), render (your own entry) |
All other props are passed to the element: className, style, aria-*,
onClick and so on.
Your own elements with asChild
Every part accepts asChild. The part then renders your element
instead of its own and merges its behaviour into it - class names are
joined, event handlers run both. That is how the play button becomes a
button from your design system:
import { Button } from "@/components/ui/button";<ScPlayer.PlayButton asChild> <Button variant="ghost">Listen</Button></ScPlayer.PlayButton>With asChild the content is yours too; the part does not add a label. Read
the state from the hook below when the label should follow it.
Ads
With ads: { preRoll: true } the player asks sonicast for an ad when the
listener presses play, plays it before the stream and reports the playback -
to the same ad delivery that serves your other listeners. The stream itself
is then requested without a server-side ad, so a listener hears one ad, not
two. No ad available means the stream starts right away.
<ScPlayer options={{ domain: "BRAND_KEY.pub.sonicast.io", ads: { preRoll: true } }} />While the ad plays, status is ad, Title shows the ad's title (or
"Advertisement") and Artist the advertiser, so the default player and a
player built from the parts both make it visible. The play button stops the
ad like the stream.
Some ads come with a companion: an image to show next to the audio, with
a link. ScPlayer.Companion renders it (an a around an img) while such
an ad plays, and nothing otherwise - place it where the image should appear.
It reports the view and the click for you.
<ScPlayer.Root options={{ domain: "BRAND_KEY.pub.sonicast.io", ads: { preRoll: true } }}> <ScPlayer.PlayButton /> <ScPlayer.Title /> <ScPlayer.Companion className="companion" /></ScPlayer.Root>Which programs serve ads, and from which provider, is configured on the program's advertising page in the dashboard - the player needs nothing else. Ads need the program's ad delivery to be enabled; without it the option has no effect.
Hooks
useScPlayer() inside a Root returns that player's state and actions; with
options it creates a player of its own, for a UI without any of the parts.
import { ScPlayer, useScPlayer } from "@sonicast/sdk/react";function Controls() { const { status, nowPlaying, history, toggle } = useScPlayer(); return ( <button type="button" onClick={toggle}> {status === "playing" ? "Stop" : "Listen"} - {nowPlaying?.item?.title} </button> );}export function Listen() { return ( <ScPlayer.Root options={{ domain: "BRAND_KEY.pub.sonicast.io" }}> <Controls /> </ScPlayer.Root> );}| Field | What it is |
|---|---|
status | the playback: idle, loading, ad, playing, error |
ad | the ad playing before the stream (id, title, advertiser, duration_ms, companion), null otherwise |
feed | the live connection: resolving, connecting, live, reconnecting, error |
nowPlaying | the current state of the program, null until the first update - the feed's JSON |
history | the recent tracks, newest first, the current one included |
target | what the domain resolved to: the program's streams and the one being played |
play(), pause(), toggle() | the actions |
useNowPlaying(options) and useNowPlayingHistory(options, limit) return
only the state or the history, for pages that show what is on air without a
player.
TypeScript
The package ships its types. ScPlayerOptions is the options object,
State, Item, Show and HistoryEntry are the feed's payloads - the same
shapes as the feed returns; Opportunity and Companion are
the ad's.