Developer:Davaar:RadioService

Architecture Overview

Cara 6 introduces a new source of type 'Radio'. In Cara 6 and later, if a Product Service reports a source of type 'Radio', then the UPnP device that bears that Product Service also bears the Radio Service. The Radio Service provides the means for controlling the Radio Source.

The heart of the Radio Service is the SetChannel action. Call SetChannel with a particular Uri and Metadata, then call Play and the media at the given Uri is played. If the media is an internet radio stream, it will play forever. If it is of finite length, it will play to the end and then stop.

Call the Channel action to report the Uri and Metadata of the current Channel.

The Radio Source also stores a list of Channel Presets. These can be presented to the user as a list of numbered Channels that can easily be selected and played.

This array of Channel Presets is accessed using the Id Array mechanism previously developed for the Playlist Service. The only difference is that the Radio Source Id Array is of a constant length and may contain entries that are zero, which represent empty presets.

The Radio Source reports technical information concerning the currently playing Channel through the Info Service and time information through the Time Service

Channel

Report the Uri and Metadata of the current Channel.

Set Channel

Set the Uri and Metadata of the current Channel.

IdArray

Report the current Id Array. The Cara 6 Id Array contains 100 presets, but this may change (see IdsMax).

The IdArray is an ordered, constant length, array of Ids. The first element contains the Id for Channel Preset 1, the second element contains the Id for Channel Preset 2, etc. If an element is set to zero, then the corresponding Channel Preset is empty.

This action also reports an IdArrayToken, which can be used to quickly detect if the IdArray has changed since it was last read (see IdArrayChanged).

IdArrayChanged

Check to see if the IdArray has changed since gathering the specified IdArrayToken. This IdArrayToken must have been previously collected from the IdArray action.

This mechanism is provided specifically for clients unable to partake in Upnp eventing.

SetId

The the current Channel using the Channel Preset represented by the given Id, and using the provided Uri.

It is usual for a Control Point to inspect the res elements of the Channel Metadata and select the appropriate Uri by matching to the renderer's ProtocolInfo.

Id

Report the Id of the current Channel if it is in the Channel Preset list. If the current Channel is not a Channel Preset, the Id reported is zero.

ProtocolInfo

Report the Radio Source Protocol Info.

Read

Given a Channel Preset Id, report its associated Metadata.

ReadList

Given a comma separated list of Channel Preset Ids, report on their associated Metadata.

TransportState

Report the current TransportState, which can be: 'Playing', 'Paused', 'Stopped', or 'Buffering'.

Play

Play the current Channel

Pause

Pause the current Channel. This will be converted to Stop if the Channel cannot be paused e.g. internet radio.

Stop

Stop the current Channel

SeekSecondsAbsolute

Seek to an absolute second within the current media. This is only available if the current media has a finite length.

SeekSecondsRelative

Seek to a relative second within the current media. This is only available if the current media has a finite length.

API Reference

Radio Service Description (XML)

Migration Guide

None.

Upnp Action Name Changes

None.

Obsolete Functions

None.