Sign In
Player SDK

Player SDK

Put your stream on your website, with live "now playing" and the recent tracks - one line of configuration.

Preview

The SDK is in preview. The API described here is what we are building against; package names and URLs may still change before the release.

The Player SDK is a small library that plays a sonicast stream on your website and shows what is on air: the current title and artist, live, and the tracks before it. It comes in two flavours that share one core:

  • React - a ready-made <ScPlayer />, and the parts it is made of for your own design (React).
  • HTML - a <sc-player> element for any page, loaded with one script tag (HTML).

Both read the public now playing feed, which you can also use directly from any language.

One line of configuration

A player is configured with the domain your streams are served from - BRAND_KEY.pub.sonicast.io, or the custom domain you have set up for it. The SDK asks that domain for the program's streams and takes everything else from there: the stream to play, and the address of the now playing feed.

React
<ScPlayer options={{ domain: "BRAND_KEY.pub.sonicast.io" }} />
HTML
<sc-player domain="BRAND_KEY.pub.sonicast.io"></sc-player>

Options

OptionDefaultWhat it does
domainrequiredThe host your streams are served from: BRAND_KEY.pub.sonicast.io, or your custom domain.
programthe brand's default programThe program key, as shown on the program page in the dashboard.
formatthe best availableThe stream to play: aac-64, mp3-128, hls, … - the formats of your program as listed on its page. Without it the SDK takes aac, then mp3, then hls.
history5How many recent tracks are loaded and shown below the current one. 0 turns the history off, including the request for it.
adsoff{ preRoll: true } plays an ad before the stream, from sonicast's ad delivery - see Ads. React only for now.

In React the options are one object (ScPlayerOptions); in HTML they are the element's attributes.

What it does for you

  • Playback on a plain audio element: aac and mp3 straight away, HLS natively in Safari and through hls.js elsewhere, loaded only when an HLS stream is actually played.
  • Now playing, live. The player holds one connection to the feed and updates the moment your playout or encoder changes the title. If the connection drops, it reconnects on its own and catches up on what it missed.
  • Recent tracks. The last items that were on air, newest first, kept up to date from the live updates.
  • Ads, in the player. With ads: { preRoll: true } the player plays an ad before the stream and reports it - from the same ad delivery that serves your other listeners, so a listener hears one ad, not two.
  • Your design. The default player is themed with a few CSS variables. In React, the parts it is made of - the play button, the title, the history - are available on their own, unstyled, so you can build the player that fits your site.

Browser support

Current versions of Chrome, Firefox, Safari and Edge, on desktop and mobile. The SDK uses EventSource for the live updates and the standard <audio> element for playback; HLS playback outside Safari needs Media Source Extensions, which every current browser has.

In questa pagina

Player SDK