|
TECHNICAL SPECIFICATION
Digital Audio Broadcasting (DAB);
Open Mobile Radio Interface (OMRI);
Application Programming Interface (API)
---------------------- Page: 1 ----------------------
2 ETSI TS 103 632 V1.1.1 (2018-10)
Reference
DTS/JTC-DAB-91
Keywords
application, audio, broadcasting, digital, interface,
radio
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88
Important notice
The present document can be downloaded from:
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the only prevailing document is the
print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
If you find errors in the present document, please send your comment to one of the following services:
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© ETSI 2018.
© European Broadcasting Union 2018.
All rights reserved.
TM TM TM
DECT , PLUGTESTS , UMTS and the ETSI logo are trademarks of ETSI registered for the benefit of its Members.
TM TM
3GPP and LTE are trademarks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
oneM2M logo is a trademark of ETSI registered for the benefit of its Members and
of the oneM2M Partners
GSM and the GSM logo are trademarks registered and owned by the GSM Association.
ETSI
---------------------- Page: 2 ----------------------
3 ETSI TS 103 632 V1.1.1 (2018-10)
Contents
Intellectual Property Rights . 5
Foreword . 5
Modal verbs terminology . 5
Introduction . 6
1 Scope . 7
2 References . 7
2.1 Normative references . 7
2.2 Informative references . 7
3 Definition of terms and abbreviations . 8
3.1 Terms . 8
3.2 Abbreviations . 8
4 API Architecture . 9
4.1 Introduction . 9
4.2 System overview . 9
4.3 API overview . 10
4.3.1 OMRI packages . 10
4.3.2 OMRI Object diagram . 10
4.3.3 Radio state model . 11
4.3.4 Tuner state model . 12
5 Examples of use of OMRI API . . 13
5.1 Developer experience . 13
5.2 Getting a Radio instance and initializing and registering the minimum listeners . 13
5.3 Implementing a TunerListener . 14
5.4 Implementing a VisualMetadataListener . 16
5.5 Implementing a TextualMetadataListener . 16
Annex A (normative): Java API Interface and Class definitions . 18
A.1 Introduction . 18
A.2 Package org.omri.radio. 18
A.2.1 Radio . 18
A.2.2 RadioErrorCode . 20
A.2.3 RadioListener . 21
A.2.4 RadioStatus. 21
A.2.5 RadioStatusListener. 22
A.3 Package org.omri.radioservice . 22
A.3.1 RadioService . 22
A.3.2 RadioServiceAudiodataListener . 24
A.3.3 RadioServiceDab . 24
A.3.4 RadioServiceDabComponent . 25
A.3.5 RadioServiceDabComponentListener . 27
A.3.6 RadioServiceDabUserApplication . 28
A.3.7 RadioServiceFm . 28
A.3.8 RadioServiceFmPty . 29
A.3.9 RadioServiceIp . 29
A.3.10 RadioServiceIpStream . 30
A.3.11 RadioServiceListener . 30
A.3.12 RadioServiceMimeType . 31
A.3.13 RadioServiceRawAudiodataListener. 32
A.3.14 RadioServiceType . 32
A.4 Sub-package org.omri.radioservice.metadata . 33
A.4.1 Group . 33
ETSI
---------------------- Page: 3 ----------------------
4 ETSI TS 103 632 V1.1.1 (2018-10)
A.4.2 Location . 34
A.4.3 ProgrammeInformation . 34
A.4.4 ProgrammeInformationType . 35
A.4.5 ProgrammeServiceMetadataListener. 35
A.4.6 ServiceInformation . 36
A.4.7 SpiProgrammeInformation . 36
A.4.8 TermId . 36
A.4.9 Textual . 37
A.4.10 TextualDabDynamicLabel . 37
A.4.11 TextualDabDynamicLabelPlusContentType . 38
A.4.12 TextualDabDynamicLabelPlusItem . 39
A.4.13 TextualFmRdsRadioText . 40
A.4.14 TextualIpRdnsRadioVis . 40
A.4.15 TextualMetadataListener . 41
A.4.16 TextualType . 41
A.4.17 Visual . 42
A.4.18 VisualDabSlideShow. 42
A.4.19 VisualIpRdnsRadioVis . 44
A.4.20 VisualMetadataListener . 44
A.4.21 VisualMimeType . 45
A.4.22 VisualType . 45
A.5 Package org.omri.tuner. 46
A.5.1 ReceptionQuality . 46
A.5.2 Tuner . 46
A.5.3 TunerListener . 48
A.5.4 TunerStatus. 49
A.5.5 TunerType . 49
Annex B (informative): Package org.omri.radio.impl . 51
B.1 Introduction . 51
B.2 public class RadioImpl extends Radio . 51
Annex C (informative): OMRI sample application . 53
C.1 Introduction . 53
C.2 MainActiviy.java . 53
C.3 RadioServiceArrayAdapter.java . 57
C.4 RadioServiceListFragment.java . 58
History . 60
ETSI
---------------------- Page: 4 ----------------------
5 ETSI TS 103 632 V1.1.1 (2018-10)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (https://ipr.etsi.org/).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
Foreword
This Technical Specification (TS) has been produced by Joint Technical Committee (JTC) Broadcast of the European
Broadcasting Union (EBU), Comité Européen de Normalisation ELECtrotechnique (CENELEC) and the European
Telecommunications Standards Institute (ETSI).
NOTE 1: The EBU/ETSI JTC Broadcast was established in 1990 to co-ordinate the drafting of standards in the
specific field of broadcasting and related fields. Since 1995 the JTC Broadcast became a tripartite body
by including in the Memorandum of Understanding also CENELEC, which is responsible for the
standardization of radio and television receivers. The EBU is a professional association of broadcasting
organizations whose work includes the co-ordination of its members' activities in the technical, legal,
programme-making and programme-exchange domains. The EBU has active members in about
60 countries in the European broadcasting area; its headquarters is in Geneva.
European Broadcasting Union
CH-1218 GRAND SACONNEX (Geneva)
Switzerland
Tel: +41 22 717 21 11
Fax: +41 22 717 24 81
The Eureka Project 147 was established in 1987, with funding from the European Commission, to develop a system for
the broadcasting of audio and data to fixed, portable or mobile receivers. Their work resulted in the publication of
European Standard, ETSI EN 300 401 [i.1], for DAB (see note 2) which now has worldwide acceptance.
NOTE 2: DAB is a registered trademark owned by one of the Eureka Project 147 partners.
The DAB family of standards is supported by WorldDAB, an organization with members drawn from broadcasting
organizations and telecommunication providers together with companies from the professional and consumer
electronics industry.
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
---------------------- Page: 5 ----------------------
6 ETSI TS 103 632 V1.1.1 (2018-10)
Introduction
The OMRI API is designed to allow developers to gain access to broadcast radio tuners in consumer electronic devices
such as smartphones, tablets and/or other devices, and allows the execution of program code often referred to as apps.
Device manufacturers, who embed tuner hardware in their devices, should implement the OMRI API and enable the
development of individual, rich and sophisticated radio applications. The Java programming language was selected
because of its clear and well known syntax, its implementation of all necessary programming paradigms (e.g. Object
Orientated, Generics, Data encapsulation) and its use in the main target platform of possible devices, the Android™
platform.
NOTE: Oracle and Java are registered trademarks of Oracle and/or its affiliates. Android is a trademark of Google
LLC.
ETSI
---------------------- Page: 6 ----------------------
7 ETSI TS 103 632 V1.1.1 (2018-10)
1 Scope
The present document specifies an Application Programming Interface (API) for the Open Mobile Radio Interface
(OMRI) which can be used by application developers to gain access to broadcast radio tuners in consumer electronic
devices such as smartphones, tablets and/or other devices, and which allows the execution of program code often
referred to as apps.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
Not applicable.
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area.
[i.1] ETSI EN 300 401: "Radio Broadcasting Systems; Digital Audio Broadcasting (DAB) to mobile,
portable and fixed receivers".
[i.2] ETSI TS 101 499: "Hybrid Digital Radio (DAB, DRM, RadioDNS); SlideShow; User Application
Specification".
[i.3] ETSI TS 102 818: "Hybrid Digital Radio (DAB, DRM, RadioDNS); XML Specification for
Service and Programme Information (SPI)".
[i.4] ETSI TS 103 270: "RadioDNS Hybrid Radio; Hybrid lookup for radio services".
[i.5] ETSI TS 102 980: "Digital Audio Broadcasting (DAB); Dynamic Label Plus (DL Plus);
Application specification".
[i.6] ISO EN 62106: "Specification of the radio data system (RDS) for VHF/FM sound broadcasting in
the frequency range from 87,5 MHz to 108,0 MHz".
ETSI
---------------------- Page: 7 ----------------------
8 ETSI TS 103 632 V1.1.1 (2018-10)
3 Definition of terms and abbreviations
3.1 Terms
For the purposes of the present document, the following terms apply:
app: small software program providing a dedicated function typically found on a smart device
3.2 Abbreviations
For the purposes of the present document, the following abbreviations apply:
AAC Advanced Audio Coding
ADTS Audio Data Transport Stream
API Application Programming Interface
CRID Content Reference IDentifier
DAB Digital Audio Broadcasting
DL Dynamic Label
DLS Dynamic Label Segment
EPG Electronic Programme Guide
FIC Fast Information Channel
FM Frequency Modulation
ICY I Can Yell
IP Internet Protocol
MMS Multimedia Message Service
MOT Multimedia Object Transfer
MPEG Moving Picture Experts Group
MSC Main Service Channel
OMRI Open Mobile Radio Interface
OS Operating System
POSIX Portable Operating System Interface
PTY Programme TYpe
RDS Radio Data Service
RF Radio Frequency
SBR Spectral Band Replication
SI Service Information
SLS SLideShow
SMS Simple Message Service
SPI Service and Programme Information
UI User Interface
URI Uniform Resource Identifier
URL Universal Resource Locator
UX User eXperience
XSI eXtended Service Information
ETSI
---------------------- Page: 8 ----------------------
9 ETSI TS 103 632 V1.1.1 (2018-10)
4 API Architecture
4.1 Introduction
In recent years, the class of so called smart devices has shown an impressive growth in market share. Initially designed
primarily as mobile phones (cell phones) and for accessing internet services such as e-mail and the World Wide Web,
the versatility of these devices has provided developers with the ability to implement small software programs called
apps for a huge amount of different use cases and services. The present document addresses such apps which want to
make use of built-in broadcast radio tuners.
4.2 System overview
Normally mobile devices have the capability to connect to IP based networks either over integrated wifi or mobile
communications systems. This connectivity, however, only allows for point-to-point connectivity. Access to broadcast
services such as DAB or FM for radio is often not possible. Even if mobile devices are equipped with broadcast
receivers, app developers do not have access to the hardware tuner resources and therefore they cannot enhance their
media centric Apps with access to broadcast services.
Technologies such as IP audio streaming and podcasts have enabled service offerings for on-demand experiences in
radio consumption. Specifications such a RadioDNS [i.4] allow a combination of broadcast and IP based services,
known as hybrid radio. In order to utilize this potential, it is important to combine broadcast media with individually
accessed on-demand content in a seamless user experience.
Figure 1 depicts a system overview of mobile devices accessing radio and hybrid services using RadioDNS as the
"pathfinder" between them.
Figure 1: System overview
While App developers understand very well how to access and implement IP based services on target mobile platforms,
such easy access has not been possible for broadcast media. The OMRI API closes this gap, by providing a
standardized, technology agnostic API for App developers to develop hybrid radio Apps.
ETSI
---------------------- Page: 9 ----------------------
10 ETSI TS 103 632 V1.1.1 (2018-10)
The device receives broadcast data via the tuner hardware which includes the audio services as well as additional
metadata such as dynamic label [i.1], SlideShow [i.2], Service and Programme Information (SPI) [i.3], and other
information. The tuner hardware is usually integrated into the OS of the device via a driver software generally provided
by the manufacturer of the tuner hardware itself. A middleware software layer uses the data provided by the driver
software to perform a range of tasks to extract the audio and metadata for presentation to an App. Such tasks can
include demodulation, demultiplexing and decoding of the different service components. Currently different
manufacturers provide custom APIs for access to their tuner hardware and middleware software and consequently the
user app has to be adapted to conform to individual tuner solutions. The OMRI API standardizes the access to tuner
solutions and enables the development of comprehensive radio apps.
4.3 API overview
4.3.1 OMRI packages
The OMRI API currently consists of three main packages:
org.omri.radio:
The radio package acts as the entry point into the API for the developer. The main class in org.omri.radio is the Radio
class which is designed as a singleton and provides a simple getInstance method for the app developer to obtain the
Radio instance for further usage. Additionally in the org.omri.radio package enumerations for error and status codes are
defined. The access to broadcast data is highly asynchronous, therefore the org.omri.radio package defines the base
class of all further interfaces of listeners in the OMRI API.
org.omri.radioservice:
The org.omri.radioservice package contains all the necessary definitions for app developers to access radioservice
information such as service labels, descriptions, logos, and many more. While the general radio service model in OMRI
is agnostic to the underlying broadcasting technology, the org.omri.radioservice package contains the necessary sub-
interfaces derived from the org.omri.radioservice. The RadioService interface reveals broadcast system specific
information and metadata to the developer. Derived from the RadioListener interface, org.omri.radioservice and its
sub-package metadata define specific listener interface definitions for service data components such as dynamic label
[i.1] and DL Plus [i.5], SlideShow [i.2] and programme information (SPI) [i.3].
org.omri.tuner:
The org.omri.tuner package defines the abstract Tuner interface which enables the developer to access radio
functionalities such as service scan. The OMRI API is designed to be able to handle devices which include multiple
tuners even for different transmission technolo
...