Radioplayer Cloud


DAB EPG Spec



Migration Guide

 

 

Introduction

Radioplayer Cloud allows you to submit your Station and Programme updates using the latest version of the DAB EPG spec. This version contains many updates that have renders the extensions implemented by Radioplayer to the old spec largely redundant. We have adopted the latest standard so that it makes it possible for broadcasters to generate a single XML file that could be used in other parts of their business without any special customizations.


The purpose of this document is to describe the differences between the old specification and the new one, and how to adapt ingest files that you send to us to maintain your station information.


Service Information

Ensemble element

The SPI XML definition no longer contains an element to represent the ensemble.

We only required this field to be completed to conform to the previous specification and had no functional use, so can be dropped with no impact.


Service Id

The serviceId element is no longer part of the DAB EPG spec and is not necessary to complete.

Defining the Radioplayer ID

There is still no ideal mechanism to specify the Radioplayer Station ID within any existing elements in the specification, so have extended the specification to all you to send it to us.


The Radioplayer universal station identifier needs to be added into the XML document; we will provide you the identifier but the pattern will be  <ISO country code><StationID>  to make all stations unique across all territories.


The Radioplayer ID should be added as follows:

<radioplayer:radioplayerId rpuid="8261004"/>


The 3.1 specification is lax in as much as it allows any elements to be added; however they must be added to the end of the service definition. Therefore this element should be added after the geolocation or serviceGroupMember elements (if you have one).


Defining Live Streams

The DAB EPG spec has been enhanced to support all the extensions added by Radioplayer to define live streams, so the listenLiveGroup element is no longer necessary.


Streams are now defined using the bearer element inside a service definition, as it supports all the fields we need to define a stream.


A bearer element supports the following attributes:

Attribute

Description

Type

Status

id

A URI describing the bearer details [18]

bearerURI type

Required

cost

An indication of a relative 'cost' of acquiring the service from the service provider. This may be used by a device as a means of selecting an appropriate bearer to use, see Annex E

xs:nonNegativeInteger

Required

mimeValue

Indicates the MIME type (IETF RFC 2045 [5]) of the audio carried by the bearer.

MIME type

Dependant on the bearer

bitrate

Bitrate of the audio carried by the bearer, in kilobits per second (kbps)

xs:nonNegativeInteger

Dependant on the bearer

offset

An indication of the offset given to the audio on this bearer by the service provider, in milliseconds relative to other bearers in the same document

xs:nonNegativeInteger

Optional, defaults to zero

 

The bearer element can also contain a child geolocation element that can be used to define restrictions on a particular stream. We support restrictions defined by country, as follows:


<bearer cost="110" bitrate="48" id="http://britishbroadcaster.com/uk_stream">
   <geolocation allow = "false" />
   <geolocation allow = "true">
    <country>GB</country>
  </geolocation>
</bearer>


We no longer support RTMP streams which have fallen out of use.


The audioFormat element is no longer necessary; the format is inferred from the MIME type.


We also allow you to define specific platforms that a stream can be played on - for instance if you have a high quality stream that is specific to a Sonos device.


We have extended our processing of data sent to us in XML files using the radioplayer namespaced attribute `allowedPlatforms` as below. Note that specification allows us to attach additional attributes to the bearer element without modifying the XML specification itself:

<bearer cost="110" bitrate="48" 
id="http://britishbroadcaster.com/uk_stream"
radioplayer:allowedPlatforms=”sonos,bose”> 
</bearer>

 

The attribute value is a comma separated list of strings. The list of strings can be extended by your country manager, but the minimum set is listed below. Note this list is capitalised for readability, but the values themselves are case insensitive.

  • iOS
  • Android
  • Web
  • Bose
  • Sonos
  • Echo
  • GoogleHome
  • Auto

 

Defining player URL

We only ever supported one console per station so this element is no longer defined in the serviceGroup. This has been moved to the link element of a service.


The ‘type’ attribute was removed from an earlier version of the specification, but we need it so that you can differentiate between the different types of link you will send to us. We have therefore restored the type attribute in the radioplayer namespace.


The description attribute can still be used to provide some human readable text that describes what the link is for; we do not do anything with this text. 


The web console player URL is identified by setting the ‘type’ attribute to “rp-web-player”.


Service Footprint

A service footprint can be defined using the geolocation element within a service. This is the same element that can be used to limit streams.


Service footprints should be defined using the polygon type. An example is shown below:

<geolocation>
 <polygon>
 51.524124 -2.709503 51.572803 -2.668304 51.616310 -2.572174
 51.575363 -2.412872 51.504471 -2.379913 51.426613 -2.471924
 51.400063 -2.460937 51.387211 -2.511749 51.328896 -2.708130
 51.273087 -2.772675 51.238705 -2.938843 51.258476 -3.036346
 51.376068 -3.026733 51.472401 -2.859879 51.524124 -2.709503
 </polygon>
</geolocation> 


The polygon is strictly defined as a list of doubles, and is a space separated list of points (lat / long). The polygon should be closed.

Genres

We have adopted the TVAnytime standard to specify station genres. We will have identified within each territory the TVA genres that can be attached to stations to specify their live content, and their output that is available on demand.

Each territory will also have identified the region specific text(s) that will be displayed for this genre, in any languages used within that territory.


Any genres that are not supported in the territory will be stripped out of the station information as it is processed and stored in our search index.

Service Groups

Service Groups can be specified in the new standard, but are not currently supported. Groups/brands of stations are managed within the Radioplayer Cloud CMS to manage search results and stations that are from the same broadcaster.

We may allow these rules to be managed by broadcasters in future versions of the platform.

Links

As noted earlier, we support the type attribute on a link element to help us identify what the link is for. We currently support the following types in our Ingest processor:

homepage

Define the radio station’s home page

rp-web-player

The location of the station’s web console

rp-handheld-station-view

The webview to display in the mobile app

twitter

The station’s twitter handle

 

We perform specific processing when we see the above links (e.g. attaching the Twitter handle in station responses). Any other values will be attached to the station as plain text and returned in metadata API responses for the client to utilise as they see fit.

Social Identifiers

We support ingesting a station’s Twitter handle using the link element with the type set to “twitter”, for example:

<link mimeValue="text/html" radioplayer:type=”twitter” uri="bbcr1"/>


Note, the mimeValue is not used.

Programme Information

Attaching a programme to a service

Please first note that according to DEB EPG spec 3.1: 


“A "linear schedule" describes programmes for a linear service (radio station) over a defined time interval, typically around a 24-hour period from midnight to midnight. Individual programmes may also include programme events, signifying events within the programme. A linear schedule may also indicate that the programme or programme event is available on-demand.”


That is to say, a schedule should contain programme information for one radio station.


We have applied the spirit of this rule in our PI processing. The previous specification was extended to allow you to indicate the station that the schedule was linked to using the bearer child element of the location element.


The latest version of the DAB EPG spec does not permit us to alter the bearer element without altering the schema itself, and also a PI file should only contain schedule information for a single station, so we do not support this any longer. 


Instead we have provided a number of ways to let you link a schedule to a station:

  1. You can POST the PI file to https://core-ingest.radioplayer.cloud/latest/pi/{rpuid} (include the RPUID in the path). This lets you submit unadulterated PI files to us and we will attach all programmes in the schedule to that station.

  2. You can add a <radioplayer:radioplayerId> element into the <scope> element to define the Radioplayer station id (the spec allows us to add namespaced elements to the scope.

For example:

<schedule creationTime="2014-04-11T01:20:00+01:00" originator="Global Radio">
<scope startTime="2014-04-25T06:00:00+01:00" stopTime="2014-04-25T13:00:00+01:00">
 <serviceScope id="dab:ce1.c185.c479.0" />
 <serviceScope id="fm:ce1.c479.09580" />
 <serviceScope id="http://media-ice.musicradio.com/Capital" />
 <serviceScope id="http://media-ice.musicradio.com/CapitalMP3Low" />
 <radioplayer:radioplayerId>8261234</radioplayer:radioplayerId>
</scope>

On Demand Audio

The latest specification allows you to add OnDemand elements to the programme directly. This is via the onDemand element which should be inserted after the location element.


A sample is shown below:

<onDemand>
  <presentationTime start="2014-02-15T15:30:00Z" end="2014-02-22T14:59:59Z" duration="PT28M" />
  <bearer id="http://downloads.bbc.co.uk/podcasts/radio4/makinghistory/makinghistory20140215-1530a.mp4a" mimeValue="audio/aacp" cost="70" bitrate="48" />
  <bearer id="dab:ce1.ce15.e1cf11ec.0.00d" cost="20" mimeValue="audio/aacp" />
</onDemand>


The presentationTime element is used to indicate how long this item will be available for. The ondemand item will not be available after the date specified in the end attribute.


We do not support the acquisitionTime element.


Not that the bearer element (the same element as on a station) is used to describe the stream url.


Short IDs and CRIDS

As with the previous version of the specification, you should use the id attribute of a programme to uniquely identify each individual scheduled item. Even though the shortId attribute is required, we do not use it.

We store a programmes in our search index using a combination of:

  • The station id
  • The programme id
  • The programme broadcast start time


This could be used to correct an existing programme record; if you resubmit a schedule using the same station/programme/start time the information attached to the programme (e.g. description or imagery) will be updated accordingly.


Series Linking

You can include a single 'memberOf' element in your PI and OD files to allow you to identify which of your programmes belong to a series, and which series they belong to.


Although the DAB specification allows multiple memberOf elements per programme, Radioplayer will process only the first memberOf element.


It is therefore essential that, should you already be generating memberOf elements in your PI files, you ensure that the first memberOf is always the one that signifies the programme's series membership as far as Radioplayer is concerned.


All memberOf elements that appear after the first within a given programme will be ignored.

Programme Events

Programme events can still be used to break the programme into small parts (e.g. news, traffic updates etc.) or identify now playing (music). The old platform supported defining rich information in the media credit (such as composer, producer) but this was not used so we have simplified the processing.


For a given programme event we extract:

  • All name information (i.e. short, medium and long names and descriptions)
  • All imagery

And attach this information to the programme event.

If the programme event contains the <mediaCredit> element then the element text is used as the artist name, and the event is marked as a song.

Special Processing

It is possible to delete all programmes in a given scope by submitting a schedule that contains no programmes. For example the following XML submission:

<?xml version="1.0" encoding="UTF-8"?>
<epg xmlns="http://www.worlddab.org/schemas/spi/33"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xml="http://www.w3.org/XML/1998/namespace"
 xsi:schemaLocation="http://www.worlddab.org/schemas/spi/33
http://www.worlddab.org/schemas/spi/33/spi_33.xsd">
 <schedule creationTime="2021-07-11T01:20:00+01:00" originator="Global Radio">
 <scope startTime="2021-07-01T00:00:00" stopTime="2021-07-01T23:59:00">
 <serviceScope id="dab:ce1.c185.c479.0" />
 </schedule>
</epg>


The above will delete all programmes with a start time sometime on the 1st July 2021.