Ingesting with v3.1 of the DAB EPG specification
Introduction
Radioplayer Cloud allows you to submit your Station and Programme updates using this version of the DAB EPG spec. This version contains many updates that have rendered the extensions implemented by Radioplayer to the old spec largely redundant. We have adopted this 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 customisations.
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.
XML Version and Namespace
Please specify the XML schema version as follows in the ‘root’ of your XML document
SI files
<serviceInformation
xmlns="http://www.worlddab.org/schemas/spi/31"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.worlddab.org/schemas/spi/31 http://www.worlddab.org/schemas/spi/31/spi_31.xsd"
xmlns:radioplayer="http://www.assets.radioplayer.org/schemas/spi/extension/31"
creationTime="2014-04-25T00:05:31+01:00" originator="you" xml:lang="en">
<services>
<service>
<!-- Your service information -->
</service>
</services>
</serviceInformation>
PI files
<epg xmlns="http://www.worlddab.org/schemas/spi/31"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.worlddab.org/schemas/spi/31 http://www.worlddab.org/schemas/spi/31/spi_31.xsd"
xmlns:radioplayer="http://www.assets.radioplayer.org/schemas/spi/extension/31"
xml:lang="en">
<!-- Insert all your PI elements -->
</epg>This tells us that you are sending data in the new format.
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 allow 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 lenient 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:
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. Please 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”. See below for a full list of currently supported ‘type’ values.
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:
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
See Station, Programme and On Demand genres
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, Radioplayer supports the type attribute on a link element to help us identify what the link is for. For example:
<link mimeValue="text/html" radioplayer:type="rp-web-player" uri="https://my.site.com/rp-web-player/index.html"/>
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 |
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.”
I.e. 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.
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
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:
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
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 smaller segments (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 wasn’t 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
Will delete all programmes with a start time sometime on the 1st July 2021.
Sample Files