Sign In
Player SDK

React

The ScPlayer component, its parts for your own design, and the hooks behind them.

Preview

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.

The default player
import { ScPlayer } from "@sonicast/sdk/react";export function Listen() {  return <ScPlayer options={{ domain: "BRAND_KEY.pub.sonicast.io" }} />;}
A program and a format
<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:

Theming with CSS variables
<ScPlayer  options={{ domain: "BRAND_KEY.pub.sonicast.io" }}  style={{ "--sc-accent": "#dc2626", "--sc-radius": "0" }}/>
VariableDefaultUsed for
--sc-font14px/1.4 system-ui, sans-serifthe font
--sc-fg#18181btext
--sc-muted#71717athe status line and the history
--sc-border#d4d4d8the frame and the separator
--sc-accent#2563ebthe play button
--sc-accent-fg#fffthe play button's icon
--sc-radius8pxthe 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.

Your own layout
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; }
PartRendersState
ScPlayer.Rootnothing - the player and its context-
ScPlayer.PlayButtona button that plays and stopsdata-status: idle, loading, ad, playing, error
ScPlayer.Titlea span with the title (else the stream text); the ad's title while one playsdata-status as above
ScPlayer.Artista span with the artist, nothing without one; the advertiser while an ad playsdata-status as above
ScPlayer.Statusa span with the feed and player statusdata-feed: resolving, connecting, live, reconnecting, error; data-status as above
ScPlayer.Companionan a with the ad's companion image, nothing without one - see Ads-
ScPlayer.Historyan ol of the recent tracks, newest firstlimit (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:

asChild
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.

A pre-roll
<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.

The companion image
<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.

useScPlayer
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>  );}
FieldWhat it is
statusthe playback: idle, loading, ad, playing, error
adthe ad playing before the stream (id, title, advertiser, duration_ms, companion), null otherwise
feedthe live connection: resolving, connecting, live, reconnecting, error
nowPlayingthe current state of the program, null until the first update - the feed's JSON
historythe recent tracks, newest first, the current one included
targetwhat 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.

Sur cette page

React