Open Source Projects Europe

Upmpdcli implements an OpenHome Radio service which allows selecting and

listening to internet radio stations when using an OpenHome-compatible

Control Point (e.g. Kazoo, Lumin, Bubble UPnP, etc.).

Radio channels can be accessed by using the Control Point application to

select the _Radio_ OpenHome source.

An example of a simple radio station definition follows. The only mandatory

value is the +url+ one, which should point to the actual audio stream or to

the station playlist link which will redirect to it (more detail in the

<<RADIO-SCRIPTS,radio scripts section>>. +artUrl+ points to a

static logo image for the station.

Radio definitions may also include paths to scripts to be executed for

retrieving the metadata and album art for the currently playing song. See

the <<RADIO-SCRIPTS,radio scripts section>> for more detail.

[[RADIO-SCRIPTS]]

== Annex: the radio scripts

=== The radio URL script

The +url+ field inside the radio definition can be a direct audio link or a

link to the radio station playlist. This link will be interpreted by the

'fetchstream.py' ('rdpltostream' directory inside the source tree, or see

'/usr/share/upmpdcli/rdpl2stream'). The Python code knows about the various

playlist formats used by the stations.

=== The dynamic album art script

If set, +artScript+ is the path to an executable script which can retrieve

the image URL for the currently playing title. It can also be a simple

script name if this is located in the PATH or in the 'radio_scripts'

directory inside the upmpdcli directory (typically '/usr/share/upmpdcli').

Some radios (e.g.  link:https://www.radioparadise.com/rp_2.php?#[Radio

Paradise]) publish the album art for the currently playing title. The

details vary. The +artScript+ parameter, if set, should point to an

executable script which prints this dynamic art Uri to stdout. The image

will supercede the radio logo, to be displayed by control points. Beware

that the path to the script must be accessible by the _upmpdcli_ user,

which may not be the case for your home. +/usr/local/bin+ is your

friend. The Upmpdcli installation has a very small set of scripts inside

the '/usr/share/upmpdcli/radio_scripts' directory. This includes a very

rough example for retrieving the Radio Paradise art URI,

'radio-paradise-get-art.sh' 

The art script is executed each time the stream metadata changes (the data

is obtained by mpd from Icy metadata in the stream).

Upmpdcli does not set a timeout for the +artScript+ execution. A reasonable

value should be used inside the script, to avoid freezing upmpdcli forever.

There is no reason to have an +artScript+ if +metaScript+ exists for the

radio. +metaScript+ can also return the image URL.

=== The dynamic metadata script

If set, +metaScript+ is the path to an executable script which can retrieve

the metadata (possibly including art Url) for the currently playing

title. It can also be a simple script name if this is located in the PATH

or in the 'radio_scripts' directory inside the upmpdcli directory

(typically '/usr/share/upmpdcli').

The script should output the metadata in JSON format. An example output

follows (the newlines and whitespace are just here for readability, any

valid JSON will do):

----

{

    "title" : "The title of the current track",

    "artist" : "The artist playing",

    "album": "The album name",

    "artUrl" : "https://www.somesite.com/path/to/image.jpg",

    "audioUrl" : "http://some url",

    "reload" : 103

}

----

The +reload+ value gives the number of seconds after which the script

should be re-executed (the clever radio sets this to the remaining song

time). By default, the script is executed every 10 S.

Any value not present will simply not be used (not an error). +audioUrl+ is

generally not set. If it is set, it's the next audio Url to queue after the

current one (this is used for radio streams which are a sequences of URLs

rather than a continuous stream, for example the Radio Paradise FLAC

station).

The 'radio_scripts' directory has two examples of radio metadata scripts, a

simple one ('fip-meta.py'), and a quite complicated one

('radio-paradise-get-flac.py').