Playout integrations
Send now playing information from playout systems to sonicast.
These endpoints feed the same now playing state as the native API. See Metadata for how items, shows and the stream text work.
Many playout systems cannot send JSON with custom headers. They can only call a
URL template with placeholders for title, artist and so on. For these, sonicast
has adapters at /now-playing/{format}/, which accept the format of the
playout and translate it into the state described above.
Adapter endpoints also accept the API key as a ?key= query parameter, as
playouts usually can't set an Authorization header.
Programs are addressed as BRAND_KEY:PROGRAM_KEY. The permanent program uid
works in its place as well (see Metadata).
Durations can be given as seconds (210), mm:ss (03:30) or hh:mm:ss
(00:03:30). Values that can't be understood are rejected with 400 rather
than silently ignored. An unknown format returns 404.
Generic
generic is meant for playouts that call a URL template, like mAirList,
RadioDJ, RadioBOSS or SAM Broadcaster. It takes flat parameters: title, artist,
type, duration, started_at and image_url.
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/generic/?key=$SONICAST_API_KEY&title=Enjoy%20the%20Silence&artist=Depeche%20Mode"type accepts the words playouts commonly use (song, spot, commercial,
station id, ...) and maps them to the native types. Older playouts often send
latin-1 instead of UTF-8. With charset=latin1, characters like "ö" are decoded
correctly:
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/generic/?key=$SONICAST_API_KEY&charset=latin1&title=Army%20of%20Me&artist=Bj%F6rk&duration=03:54&type=Song"Playouts sending a form body instead of query parameters can POST the same
fields as application/x-www-form-urlencoded:
curl \ -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Accept: application/json" \ --data-urlencode "title=Personal Jesus" \ --data-urlencode "artist=Depeche Mode" \ --data-urlencode "duration=00:03:44" \ --data-urlencode "type=music" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/generic/?key=$SONICAST_API_KEY"Non-music elements are stored as well, but don't replace the stream text with their title. During a station ID, listeners see the show or program name instead:
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/generic/?key=$SONICAST_API_KEY&title=Station%20ID&type=Station%20ID&duration=8"Quantumcast
The quantumcast adapter understands the Quantumcast / Audalaxy MetaPort
parameters (song, artist, duration, time, etype, tracktype,
cover). When switching from Quantumcast, changing the base URL in the playout
is usually all that is needed.
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/quantumcast/?key=$SONICAST_API_KEY&song=Anxious&artist=Dennis+Lloyd&duration=174&etype=1001&separator=+-+"The same fields can be sent as JSON:
curl \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "song": "Just Can'"'"'t Get Enough", "artist": "Depeche Mode", "duration": 221, "cover": "https://example.com/cover.jpg", "etype": 1001, "tracktype": "now" }' \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/quantumcast/?key=$SONICAST_API_KEY"Windows (latin-1) encoded text is decoded with encoding=windows:
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/quantumcast/?key=$SONICAST_API_KEY&song=D%E9j%E0%20vu&artist=Beyonc%E9&duration=240&encoding=windows"Ad break markers (ADBREAK_LENGTH_<ms> and InStreamAd [N:x] [L:x]) are
turned into an ad item with the given length. This example marks a 30-second
break:
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/quantumcast/?key=$SONICAST_API_KEY&song=ADBREAK_LENGTH_30000&artist="Announcements of the upcoming track (tracktype=next) are ignored. The request
succeeds and returns the unchanged current state:
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/quantumcast/?key=$SONICAST_API_KEY&song=Policy%20of%20Truth&artist=Depeche%20Mode&tracktype=next"DTS AutoStage
The dts adapter accepts the DTS AutoStage JSON format, so sonicast and DTS
can be fed from the same playout configuration. Entries in nowPlaying
become the item:
curl \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "nowPlaying": [ { "title": "Land Down Under", "artist": "Pennywise", "duration": "00:02:28", "imageUrl": "", "status": "playing", "type": "song" } ] }' \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/dts/?key=$SONICAST_API_KEY"Entries in onAir become the show. Only entries with status: playing are
used. A show can have a duration instead of an endTime:
curl \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "onAir": [ { "title": "The news at 6.00 PM", "description": "This is the news bulletin", "imageUrl": "", "status": "playing", "duration": "00:15:00", "type": "show" } ] }' \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/dts/?key=$SONICAST_API_KEY"For simple setups, dts also takes title, artist and duration as query
parameters:
curl \ -H "Accept: application/json" \ "https://sonicast.io/api/v1/programs/BRAND_KEY:PROGRAM_KEY/now-playing/dts/?key=$SONICAST_API_KEY&title=Jump&artist=Madonna&duration=00:03:30"Other playouts
Most systems that can call a URL work with generic. Adapters for structured
formats (e.g. Zetta, WideOrbit or Myriad) are added on request, based on a
sample payload.