Package: android.hardware.broadcastradio@2.0

types

Properties

Constants

enum Constants: int32_t

Constants used by broadcast radio HAL.

Details
Members
INVALID_IMAGE = 0
Invalid identifier for IBroadcastRadio::getImage.
ANTENNA_DISCONNECTED_TIMEOUT_MS = 100
If the antenna is disconnected from the beginning, the onAntennaStateChange callback must be called within this time.
LIST_COMPLETE_TIMEOUT_MS = 300000

Result

enum Result: int32_t
Details
Members
OK
UNKNOWN_ERROR
INTERNAL_ERROR
INVALID_ARGUMENTS
INVALID_STATE
NOT_SUPPORTED
TIMEOUT

ConfigFlag

enum ConfigFlag: uint32_t

Configuration flags to be used with isConfigFlagSet and setConfigFlag methods of ITunerSession.

Details
Members
FORCE_MONO = 1
Forces mono audio stream reception.
Analog broadcasts can recover poor reception conditions by jointing stereo channels into one.Mainly for, but not limited to AM/FM.
FORCE_ANALOG
Forces the analog playback for the supporting radio technology.
User may disable digital playback for FM HD Radio or hybrid FM/DAB with this option.This is purely user choice, ie.does not reflect digital- analog handover state managed from the HAL implementation side.
Some radio technologies may not support this, ie.DAB.
FORCE_DIGITAL
Forces the digital playback for the supporting radio technology.
User may disable digital-analog handover that happens with poor reception conditions.With digital forced, the radio will remain silent instead of switching to analog channel if it's available.This is purely user choice, it does not reflect the actual state of handover.
RDS_AF
RDS Alternative Frequencies.
If set and the currently tuned RDS station broadcasts on multiple channels, radio tuner automatically switches to the best available alternative.
RDS_REG
RDS region-specific program lock-down.
Allows user to lock to the current region as they move into the other region.
DAB_DAB_LINKING
Enables DAB-DAB hard- and implicit-linking(the same content).
DAB_FM_LINKING
Enables DAB-FM hard- and implicit-linking(the same content).
DAB_DAB_SOFT_LINKING
Enables DAB-DAB soft-linking(related content).
DAB_FM_SOFT_LINKING
Enables DAB-FM soft-linking(related content).

Rds

enum Rds: uint8_t

A supported or configured RDS variant.

Both might be set for hardware capabilities check(with full=true when calling getAmFmRegionConfig), but only one(or none)for specific region settings.

Details
Members
RDS = 1 << 0
Standard variant, used everywhere except North America.
RBDS = 1 << 1
Variant used in North America.

Deemphasis

enum Deemphasis: uint8_t

FM de-emphasis filter supported or configured.

Both might be set for hardware capabilities check(with full=true when calling getAmFmRegionConfig), but exactly one for specific region settings.

Details
Members
D50 = 1 << 0
D75 = 1 << 1

ProgramInfoFlags

enum ProgramInfoFlags: uint32_t
Details
Members
LIVE = 1 << 0
Set when the program is currently playing live stream.This may result in a slightly altered reception parameters, usually targetted at reduced latency.
MUTED = 1 << 1
Radio stream is not playing, ie.due to bad reception conditions or buffering.In this state volume knob MAY be disabled to prevent user increasing volume too much.
TRAFFIC_PROGRAM = 1 << 2
Station broadcasts traffic information regularly, but not necessarily right now.
TRAFFIC_ANNOUNCEMENT = 1 << 3
Station is broadcasting traffic information at the very moment.
TUNED = 1 << 4
Tuned to a program(not playing static).
It's the same condition that would stop a seek operation(ie:ITunerSession::scan()).
By definition, this flag must be set for all items on the program list.
STEREO = 1 << 5
Audio stream is MONO if this bit is not set.

IdentifierType

enum IdentifierType: uint32_t

Type of program identifier component.

Each identifier type corresponds to exactly one radio technology, i.e.DAB_ENSEMBLE is specifically for DAB.

VENDOR identifier types must be opaque to the framework.

The value format for each(but VENDOR_*)identifier is strictly defined to maintain interoperability between devices made by different vendors.

All other values are reserved for future use.Values not matching any enumerated constant must be ignored.

Details
Members
VENDOR_START = 1000
Primary/secondary identifier for vendor-specific radio technology.The value format is determined by a vendor.
The vendor identifiers have limited serialization capabilities - see ProgramSelector description.
VENDOR_END = 1999
See VENDOR_START
INVALID = 0
AMFM_FREQUENCY
Primary identifier for analogue(without RDS)AM/FM stations:frequency in kHz.
This identifier also contains band information:-<500kHz:AM LW;- 500kHz - 1705kHz:AM MW;- 1.71MHz - 30MHz:AM SW;->60MHz:FM.
RDS_PI
16bit primary identifier for FM RDS station.
HD_STATION_ID_EXT
64bit compound primary identifier for HD Radio.
Consists of(from the LSB): - 32bit:Station ID number;- 4bit:HD Radio subchannel;- 18bit:AMFM_FREQUENCY.
While station ID number should be unique globally, it sometimes get abused by broadcasters(i.e.not being set at all). To ensure local uniqueness, AMFM_FREQUENCY was added here.Global uniqueness is a best-effort - see HD_STATION_NAME.
HD Radio subchannel is a value in range 0-7.This index is 0-based(where 0 is MPS and 1.. 7 are SPS), as opposed to HD Radio standard(where it's 1-based).
The remaining bits should be set to zeros when writing on the chip side and ignored when read.
HD_STATION_NAME
64bit additional identifier for HD Radio.
Due to Station ID abuse, some HD_STATION_ID_EXT identifiers may be not globally unique.To provide a best-effort solution, a short version of station name may be carried as additional identifier and may be used by the tuner hardware to double-check tuning.
The name is limited to the first 8 A-Z0-9 characters(lowercase letters must be converted to uppercase). Encoded in little-endian ASCII:the first character of the name is the LSB.
For example:"Abc" is encoded as 0x434241.
DAB_SID_EXT
28bit compound primary identifier for Digital Audio Broadcasting.
Consists of(from the LSB): - 16bit:SId;- 8bit:ECC code;- 4bit:SCIdS.
SCIdS(Service Component Identifier within the Service)value of 0 represents the main service, while 1 and above represents secondary services.
The remaining bits should be set to zeros when writing on the chip side and ignored when read.
DAB_ENSEMBLE
16bit
DAB_SCID
12bit
DAB_FREQUENCY
kHz(see AMFM_FREQUENCY )
DRMO_SERVICE_ID
24bit primary identifier for Digital Radio Mondiale.
DRMO_FREQUENCY
kHz(see AMFM_FREQUENCY )
SXM_SERVICE_ID = DRMO_FREQUENCY + 2
32bit primary identifier for SiriusXM Satellite Radio.
SXM_CHANNEL
0-999 range

MetadataKey

enum MetadataKey: int32_t
Details
Members
RDS_PS = 1
RDS PS(string )
RDS_PTY
RDS PTY(uint8_t )
RBDS_PTY
RBDS PTY(uint8_t )
RDS_RT
RDS RT(string )
SONG_TITLE
Song title(string )
SONG_ARTIST
Artist name(string )
SONG_ALBUM
Album name(string )
STATION_ICON
Station icon(uint32_t, see IBroadcastRadio::getImage )
ALBUM_ART
Album art(uint32_t, see IBroadcastRadio::getImage )
PROGRAM_NAME
Station name.
This is a generic field to cover any radio technology.
If the PROGRAM_NAME has the same content as DAB_*_NAME or RDS_PS, it may not be present, to preserve space - framework must repopulate it on the client side.
DAB_ENSEMBLE_NAME
DAB ensemble name(string )
DAB_ENSEMBLE_NAME_SHORT
DAB ensemble name abbreviated(string).
The string must be up to 8 characters long.
If the short variant is present, the long(DAB_ENSEMBLE_NAME)one must be present as well.
DAB_SERVICE_NAME
DAB service name(string )
DAB_SERVICE_NAME_SHORT
DAB service name abbreviated(see DAB_ENSEMBLE_NAME_SHORT )(string )
DAB_COMPONENT_NAME
DAB component name(string )
DAB_COMPONENT_NAME_SHORT
DAB component name abbreviated(see DAB_ENSEMBLE_NAME_SHORT )(string )

AnnouncementType

enum AnnouncementType: uint8_t

Type of an announcement.

It maps to different announcement types per each radio technology.

Details
Members
EMERGENCY = 1
DAB alarm, RDS emergency program type(PTY 31).
WARNING
DAB warning.
TRAFFIC
DAB road traffic, RDS TA, HD Radio transportation.
WEATHER
Weather.
NEWS
News.
EVENT
DAB event, special event.
SPORT
DAB sport report, RDS sports.
MISC
All others.

VendorKeyValue

struct VendorKeyValue {string key; string value}

A key-value pair for vendor-specific information to be passed as-is through Android framework to the front-end application.

Details
Members
key
Key must start with unique vendor Java-style namespace, eg.'com.somecompany.parameter1'.
value
Value must be passed through the framework without any changes.Format of this string can vary across vendors.

AmFmRegionConfig

struct AmFmRegionConfig {vec ranges; bitfield fmDeemphasis; bitfield fmRds}

Regional configuration for AM/FM.

For hardware capabilities check(with full=true when calling getAmFmRegionConfig), HAL implementation fills entire supported range of frequencies and features.

When checking current configuration, at most one bit in each bitfield can be set.

Details
Members
ranges
All supported or configured AM/FM bands.
AM/FM bands are identified by frequency value(see IdentifierType::AMFM_FREQUENCY).
With typical configuration, it's expected to have two frequency ranges for capabilities check(AM and FM)and four ranges for specific region configuration(AM LW, AM MW, AM SW, FM).
fmDeemphasis
De-emphasis filter supported/configured.
fmRds
RDS/RBDS variant supported/configured.

AmFmBandRange

struct AmFmBandRange {uint32_t lowerBound; uint32_t upperBound; uint32_t spacing; uint32_t scanSpacing}

AM/FM band range for region configuration.

Defines channel grid:each possible channel is set at lowerBound + channelNumber * spacing, up to upperBound.

Details
Members
lowerBound
The frequency(in kHz)of the first channel within the range.
upperBound
The frequency(in kHz)of the last channel within the range.
spacing
Channel grid resolution(in kHz), how far apart are the channels.
scanSpacing
Channel spacing(in kHz)used to speed up seeking to the next station via the ITunerSession::scan() operation.
It must be a multiple of channel grid resolution.
Tuner may first quickly check every n-th channel and if it detects echo from a station, it fine-tunes to find the exact frequency.
It's ignored for capabilities check(with full=true when calling getAmFmRegionConfig).

DabTableEntry

struct DabTableEntry {string label; uint32_t frequency}

An entry in regional configuration for DAB.

Defines a frequency table row for ensembles.

Details
Members
label
Channel name, i.e.5A, 7B.
It must match the following regular expression:/^[A-Z0-9 ][A-Z0-9 ]{0, 5}[ A-Z0-9]$/(2-7 uppercase alphanumeric characters without spaces allowed at the beginning nor end).
frequency
Frequency, in kHz.

Properties

struct Properties {string maker; string product; string version; string serial; vec supportedIdentifierTypes; vec vendorInfo}

Properties of a given broadcast radio module.

Details
Members
maker
A company name who made the radio module.Must be a valid, registered name of the company itself.
It must be opaque to the Android framework.
product
A product name.Must be unique within the company.
It must be opaque to the Android framework.
version
Version of the hardware module.
It must be opaque to the Android framework.
serial
Hardware serial number(for subscription services).
It must be opaque to the Android framework.
supportedIdentifierTypes
A list of supported IdentifierType values.
If an identifier is supported by radio module, it means it can use it for tuning to ProgramSelector with either primary or secondary Identifier of a given type.
Support for VENDOR identifier type does not guarantee compatibility, as other module properties(implementor, product, version)must be checked.
vendorInfo
Vendor-specific information.
It may be used for extra features, not supported by the platform, for example:com.me.preset-slots=6;com.me.ultra-hd-capable=false.

ProgramInfo

struct ProgramInfo {ProgramSelector selector; ProgramIdentifier logicallyTunedTo; ProgramIdentifier physicallyTunedTo; vec relatedContent; bitfield infoFlags; uint32_t signalQuality; vec metadata; vec vendorInfo}

Program(channel, station)information.

Carries both user-visible information(like station name)and technical details(tuning selector).

Details
Members
selector
An identifier used to point at the program(primarily to tune to it).
This field is required - its type field must not be set to IdentifierType::INVALID.
logicallyTunedTo
Identifier currently used for program selection.
It allows to determine which technology is currently used for reception.
Some program selectors contain tuning information for different radio technologies(i.e.FM RDS and DAB). For example, user may tune using a ProgramSelector with RDS_PI primary identifier, but the tuner hardware may choose to use DAB technology to make actual tuning.This identifier must reflect that.
This field is required for currently tuned program only.For all other items on the program list, its type field must be initialized to IdentifierType::INVALID.
Only primary identifiers for a given radio technology are valid:- AMFM_FREQUENCY for analog AM/FM;- RDS_PI for FM RDS;- HD_STATION_ID_EXT;- DAB_SID_EXT;- DRMO_SERVICE_ID;- SXM_SERVICE_ID;- VENDOR_*;- more might come in next minor versions of this HAL.
physicallyTunedTo
Identifier currently used by hardware to physically tune to a channel.
Some radio technologies broadcast the same program on multiple channels, i.e.with RDS AF the same program may be broadcasted on multiple alternative frequencies;the same DAB program may be broadcast on multiple ensembles.This identifier points to the channel to which the radio hardware is physically tuned to.
This field is required for currently tuned program only.For all other items on the program list, its type field must be initialized to IdentifierType::INVALID.
Only physical identifiers are valid:- AMFM_FREQUENCY;- DAB_ENSEMBLE;- DRMO_FREQUENCY;- SXM_CHANNEL;- VENDOR_*;- more might come in next minor versions of this HAL.
relatedContent
Primary identifiers of related contents.
Some radio technologies provide pointers to other programs that carry related content(i.e.DAB soft-links). This field is a list of pointers to other programs on the program list.
This is not a list of programs that carry the same content(i.e.DAB hard-links, RDS AF). Switching to programs from this list usually require user action.
Please note, that these identifiers do not have to exist on the program list - i.e.DAB tuner may provide information on FM RDS alternatives despite not supporting FM RDS.If the system has multiple tuners, another one may have it on its list.
This field is optional(can be empty).
infoFlags
signalQuality
Signal quality measured in 0% to 100% range to be shown in the UI.
The purpose of this field is primarily informative, must not be used to determine to which frequency should it tune to.
metadata
Program metadata(station name, PTY, song title).
vendorInfo
Vendor-specific information.
It may be used for extra features, not supported by the platform, for example:paid-service=true;bitrate=320kbps.

ProgramIdentifier

struct ProgramIdentifier {uint32_t type; uint64_t value}

A single program identifier component, i.e.frequency or channel ID.

Details
Members
type
Maps to IdentifierType enum.The enum may be extended in future versions of the HAL.Values out of the enum range must not be used when writing and ignored when reading.
value
The uint64_t value field holds the value in format described in comments for IdentifierType enum.

ProgramSelector

struct ProgramSelector {ProgramIdentifier primaryId; vec secondaryIds}

A set of identifiers necessary to tune to a given station.

This can hold a combination of various identifiers, like:- AM/FM frequency, - HD Radio subchannel, - DAB service ID.

The type of radio technology is determined by the primary identifier - if the primary identifier is for DAB, the program is DAB.However, a program of a specific radio technology may have additional secondary identifiers for other technologies, i.e.a satellite program may have FM fallback frequency, if a station broadcasts both via satellite and FM.

The identifiers from VENDOR_START.. VENDOR_END range have limited serialization capabilities:they are serialized locally, but ignored by the cloud services.If a program has primary id from vendor range, it's not synchronized with other devices at all.

Details
Members
primaryId
Primary program identifier.
This identifier uniquely identifies a station and can be used for equality check.
It can hold only a subset of identifier types, one per each radio technology:- analogue AM/FM:AMFM_FREQUENCY;- FM RDS:RDS_PI;- HD Radio:HD_STATION_ID_EXT;- DAB:DAB_SID_EXT;- Digital Radio Mondiale:DRMO_SERVICE_ID;- SiriusXM:SXM_SERVICE_ID;- vendor-specific:VENDOR_START.. VENDOR_END.
The list may change in future versions, so the implementation must obey, but not rely on it.
secondaryIds
Secondary program identifiers.
These identifiers are supplementary and can speed up tuning process, but the primary ID must be sufficient(i.e.RDS PI is enough to select a station from the list after a full band scan).
Two selectors with different secondary IDs, but the same primary ID are considered equal.In particular, secondary IDs vector may get updated for an entry on the program list(ie.when a better frequency for a given station is found).

Metadata

struct Metadata {uint32_t key; int64_t intValue; string stringValue}

An element of metadata vector.

Contains one of the entries explained in MetadataKey.

Depending on a type described in the comment for a specific key, either the intValue or stringValue field must be populated.

Details
Members
key
Maps to MetadataKey enum.The enum may be extended in future versions of the HAL.Values out of the enum range must not be used when writing and ignored when reading.
intValue
stringValue

ProgramListChunk

struct ProgramListChunk {bool purge; bool complete; vec modified; vec removed}

An update packet of the program list.

The order of entries in the vectors is unspecified.

Details
Members
purge
Treats all previously added entries as removed.
This is meant to save binder transaction bandwidth on 'removed' vector and provide a clear empty state.
If set, 'removed' vector must be empty.
The client may wait with taking action on this until it received the chunk with complete flag set(to avoid part of stations temporarily disappearing from the list).
complete
If false, it means there are still programs not transmitted, due for transmission in following updates.
Used by UIs that wait for complete list instead of displaying programs while scanning.
After the whole channel range was scanned and all discovered programs were transmitted, the last chunk must have set this flag to true.This must happen within Constants::LIST_COMPLETE_TIMEOUT_MS from the startProgramListUpdates call.If it doesn't, client may assume the tuner came into a bad state and display error message.
modified
Added or modified program list entries.
Two entries with the same primaryId(ProgramSelector member)are considered the same.
removed
Removed program list entries.
Contains primaryId(ProgramSelector member)of a program to remove.

ProgramFilter

struct ProgramFilter {vec identifierTypes; vec identifiers; bool includeCategories; bool excludeModifications}

Large-grain filter to the program list.

This is meant to reduce binder transaction bandwidth, not for fine-grained filtering user might expect.

The filter is designed as conjunctive normal form:the entry that passes the filter must satisfy all the clauses(members of this struct). Vector clauses are disjunctions of literals.In other words, there is AND between each high-level group and OR inside it.

Details
Members
identifierTypes
List of identifier types that satisfy the filter.
If the program list entry contains at least one identifier of the type listed, it satisfies this condition.
Empty list means no filtering on identifier type.
identifiers
List of identifiers that satisfy the filter.
If the program list entry contains at least one listed identifier, it satisfies this condition.
Empty list means no filtering on identifier.
includeCategories
Includes non-tunable entries that define tree structure on the program list(i.e.DAB ensembles).
excludeModifications
Disable updates on entry modifications.
If true, 'modified' vector of ProgramListChunk must contain list additions only.Once the program is added to the list, it's not updated anymore.

Announcement

struct Announcement {ProgramSelector selector; AnnouncementType type; vec vendorInfo}

A pointer to a station broadcasting active announcement.

Details
Members
selector
Program selector to tune to the announcement.
type
Announcement type.
vendorInfo
Vendor-specific information.
It may be used for extra features, not supported by the platform, for example:com.me.hdradio.urgency=100;com.me.hdradio.certainity=50.