From OpenHome

(Difference between revisions)

Latest revision as of 10:58, 2 August 2013

Overview

The Radio service primarily offers the means for controlling radio presets; it also offers an API to allow arbitrary URLs to be played. If a device’s Product service reports a source of type 'Radio', then the device that bears that Product service is guaranteed to also bear the Radio service.

State Variables

ChannelsMax

The maximum number of presets (and so the number of elements in IdArray). Read-only.

Id

The id of the currently selected preset (as set by the last call to SetId). Or 0 if no preset has ever been selected or SetChannel was called more recently than SetId.

IdArray

Base64-encoded array of 32-bit big endian unsigned integers. Will always be (ChannelsMax * 4) bytes long. Each id represents a preset id. A value of 0 implies that no preset is set for that slot.

Metadata

Metadata for the last track to be selected (via a call to either SetChannel or SetId).

ProtocolInfo

Audio formats and networking protocols supported by the device. Will be the same as reported by Playlist and AVTransport if these services are present. Read-only.

TransportState

One of Stopped, Playing, Paused or Buffering.

Uri

The last uri to be set (via a call to either SetChannel or SetId).

Actions

Channel

Return the values of the Uri and Metadata state variables.

ChannelsMax

Return the value of the ChannelsMax state variable.

Id

Report the value of the Id state variable.

IdArray

Return the value of the IdArray state variable.

IdArrayChanged

Check to see if the IdArray state variable has changed since gathering the specified IdArrayToken. This Token must have been previously collected from the IdArray action. This action is provided specifically for clients which do not use UPnP eventing.

Pause

Pause any currently playing radio stream. Should only be called when the Radio source is currently selected.

Play

Play any previously selected track (the last uri to be set via either SetChannel or SetId). Switches source to Radio if that wasn’t already selected.

ProtocolInfo

Return the value of the ProtocolInfo state variable.

Read

Given a channel preset Id, return its associated metadata. The metadata will be of the form

<DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/"
           xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
           xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
    <item id="" parentID="" restricted="True">
        <dc:title>[title]</dc:title>
        <res protocolInfo="*:*:*:*" bitrate="6000">[track url]</res>
        <upnp:albumArtURI>[image url]</upnp:albumArtURI>
        <upnp:class>object.item.audioItem</upnp:class>
    </item>
</DIDL-Lite>

Note that additional elements may be present. The elements listed above are guaranteed to be present. The contents of all elements will be XML escaped.

ReadList

Given a space separated list of channel preset Ids, return their associated metadata. The metadata will be of the form

<ChannelList>
    <Entry>
        <Id>[preset Id]</Id>
        <Metadata>[as for Read]</Metadata>
    </Entry>
    <Entry>
        ....
    </Entry>
</ChannelList>

Note that the content of each metadata will be fully xml escaped (so metadata for a given id won't be byte-for-byte identical to that returned by Read).

SeekSecondAbsolute

Seek to an absolute (seconds) position in the currently playing stream, retaining the existing TransportState. Note that most radio streams are not seekable so this action is probably only applicable to a subset of tracks played via SetChannel that the Info service reports are seekable.

SeekSecondRelative

Seek to an position (in seconds) in the currently playing stream, relative to its current position, retaining the existing TransportState. Note that most radio streams are not seekable so this action is probably only applicable to a subset of tracks played via SetChannel that the Info service reports are seekable

SetChannel

Set the uri and metadata for a new track. Any currently playing track will be stopped. The new track will not play until the Play action is invoked. The Id state variable will be set to 0.

SetId

Set the preset id and uri for a new track. The uri should be parsed from the metadata returned by Read or ReadList. Any currently playing track will be stopped. The new track will not play until the Play action is invoked. The Id state variable will be updated to the newly specified preset id.

Stop

Stop any currently playing radio stream. Should only be called when the Radio source is currently selected

TransportState

Return the value of the TransportState state variable.

Technical Details


   Domain  : av.openhome.org
   Name    : Radio
   Version : 1

Radio Service Description (XML)

<?xml version="1.0"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
    <specVersion>
        <major>1</major>
        <minor>0</minor>
    </specVersion>
    <actionList>
        <action>
            <name>Play</name>
        </action>
        <action>
            <name>Pause</name>
        </action>
        <action>
            <name>Stop</name>
        </action>
        <action>
            <name>SeekSecondAbsolute</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>in</direction>
                    <relatedStateVariable>Absolute</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SeekSecondRelative</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>in</direction>
                    <relatedStateVariable>Relative</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Channel</name>
            <argumentList>
                <argument>
                    <name>Uri</name>
                    <direction>out</direction>
                    <relatedStateVariable>Uri</relatedStateVariable>
                </argument>
                <argument>
                    <name>Metadata</name>
                    <direction>out</direction>
                    <relatedStateVariable>Metadata</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SetChannel</name>
            <argumentList>
                <argument>
                    <name>Uri</name>
                    <direction>in</direction>
                    <relatedStateVariable>Uri</relatedStateVariable>
                </argument>
                <argument>
                    <name>Metadata</name>
                    <direction>in</direction>
                    <relatedStateVariable>Metadata</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>TransportState</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>TransportState</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Id</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>Id</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SetId</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>in</direction>
                    <relatedStateVariable>Id</relatedStateVariable>
                </argument>
                <argument>
                    <name>Uri</name>
                    <direction>in</direction>
                    <relatedStateVariable>Uri</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Read</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>Id</relatedStateVariable>
                </argument>
                <argument>
                    <name>Metadata</name>
                    <direction>out</direction>
                    <relatedStateVariable>Metadata</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>ReadList</name>
            <argumentList>
                <argument>
                    <name>IdList</name>
                    <direction>in</direction>
                    <relatedStateVariable>IdList</relatedStateVariable>
                </argument>
                <argument>
                    <name>ChannelList</name>
                    <direction>out</direction>
                    <relatedStateVariable>ChannelList</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>IdArray</name>
            <argumentList>
                <argument>
                    <name>Token</name>
                    <direction>out</direction>
                    <relatedStateVariable>IdArrayToken</relatedStateVariable>
                </argument>
                <argument>
                    <name>Array</name>
                    <direction>out</direction>
                    <relatedStateVariable>IdArray</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>IdArrayChanged</name>
            <argumentList>
                <argument>
                    <name>Token</name>
                    <direction>in</direction>
                    <relatedStateVariable>IdArrayToken</relatedStateVariable>
                </argument>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>IdArrayChanged</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>ChannelsMax</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>ChannelsMax</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>ProtocolInfo</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>ProtocolInfo</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
    </actionList>
 
    <serviceStateTable>
        <stateVariable sendEvents="yes">
            <name>Uri</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>Metadata</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>TransportState</name>
            <dataType>string</dataType>
            <allowedValueList>
                <allowedValue>Stopped</allowedValue>
                <allowedValue>Playing</allowedValue>
                <allowedValue>Paused</allowedValue>
                <allowedValue>Buffering</allowedValue>
            </allowedValueList>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>Id</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>IdArray</name>
            <dataType>bin.base64</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ChannelsMax</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ProtocolInfo</name>
            <dataType>string</dataType>
        </stateVariable>        
        <stateVariable sendEvents="no">
            <name>Relative</name>
            <dataType>i4</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>Absolute</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>IdArrayToken</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>IdArrayChanged</name>
            <dataType>boolean</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>IdList</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>ChannelList</name>
            <dataType>string</dataType>
        </stateVariable>
    </serviceStateTable>
</scpd>

@@ Line 1: / Line 1: @@
-= Architectural Overview =
+= Overview =
-The Radio service provides the means for controlling a Radio source. If a product's [[Developer:ProductService|Product Service]] reports a source of type 'Radio', then the device that bears that [[Developer:ProductService|Product Service]] is guaranteed to also bear the Radio service.
+The Radio service primarily offers the means for controlling radio presets; it also offers an API to allow arbitrary URLs to be played.
+If a device’s Product service reports a source of type 'Radio', then the device that bears that Product service is guaranteed to also bear the Radio service.
-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.
+= State Variables =
+== ChannelsMax ==
-Call the '''Channel''' action to report the Uri and Metadata of the current Channel.
+The maximum number of presets (and so the number of elements in IdArray).  Read-only.
+== Id ==
-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.
+The id of the currently selected preset (as set by the last call to SetId).  Or 0 if no preset has ever been selected or SetChannel was called more recently than SetId.
+== IdArray ==
-This array of channel presets is accessed using an id array mechanism similar to that used in the [[Developer:PlaylistService|Playlist Service]]. The only difference is that the Radio service's id array is a constant length and may contain entries that are zero, which represent empty presets.
+Base64-encoded array of 32-bit big endian unsigned integers.  Will always be (ChannelsMax * 4) bytes long.  Each id represents a preset id.  A value of 0 implies that no preset is set for that slot.
+== Metadata ==
+Metadata for the last track to be selected (via a call to either SetChannel or SetId).
+== ProtocolInfo ==
+Audio formats and networking protocols supported by the device.  Will be the same as reported by Playlist and AVTransport if these services are present.  Read-only.
+== TransportState ==
+One of Stopped, Playing, Paused or Buffering.
+== Uri ==
+The last uri to be set (via a call to either SetChannel or SetId).
 = Actions =
-==Channel==
+== Channel ==
-Report the Uri and Metadata of the current Channel.
+Return the values of the Uri and Metadata state variables.
-==SetChannel==
-Set the Uri and Metadata of the current Channel.
-==IdArray==
-Report the current id array. The id array contains 100 presets, but this may change (see ChannelsMax).
-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 a Token, which can be used to quickly detect if the id array has changed since it was last read (see IdArrayChanged).
-==IdArrayChanged==
-Check to see if the id array has changed since gathering the specified IdArrayToken.
-This Token must have been previously collected from the IdArray action.
-This mechanism is provided specifically for clients unable to partake in UPnP eventing.
-==ChannelsMax==
-Report the maximum number of entries in the channel preset id array.
-==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 space separated list of channel preset Ids, report their associated Metadata.
-==TransportState==
-Report the current transport state, which can be: 'Playing', 'Paused', 'Stopped', or 'Buffering'.
-==Play==
+== ChannelsMax ==
-Play the current channel
+Return  the value of the ChannelsMax state variable.
+== Id ==
+Report the value of the Id state variable.
+== IdArray ==
+Return the value of the IdArray state variable.
+== IdArrayChanged ==
+Check to see if the IdArray state variable has changed since gathering the specified IdArrayToken. This Token must have been previously collected from the IdArray action.  This action is provided specifically for clients which do not use UPnP eventing.
+== Pause ==
+Pause any currently playing radio stream.  Should only be called when the Radio source is currently selected.
+== Play ==
+Play any previously selected track (the last uri to be set via either SetChannel or SetId).  Switches source to Radio if that wasn’t already selected.
+== ProtocolInfo ==
+Return the value of the ProtocolInfo state variable.
+== Read ==
+Given a channel preset Id, return its associated metadata.  The metadata will be of the form
+<syntaxhighlight lang="xml">
+<DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/"
+           xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
+           xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
+    <item id="" parentID="" restricted="True">
+        <dc:title>[title]</dc:title>
+        <res protocolInfo="*:*:*:*" bitrate="6000">[track url]</res>
+        <upnp:albumArtURI>[image url]</upnp:albumArtURI>
+        <upnp:class>object.item.audioItem</upnp:class>
+    </item>
+</DIDL-Lite>
+</syntaxhighlight>
+Note that additional elements may be present.  The elements listed above are guaranteed to be present.  The contents of all elements will be XML escaped.
-==Pause==
+== ReadList ==
-Pause the current channel. This will be converted to Stop if the channel cannot be paused e.g. internet radio.
+Given a space separated list of channel preset Ids, return their associated metadata.  The metadata will be of the form
+<syntaxhighlight lang="xml">
+<ChannelList>
+    <Entry>
+        <Id>[preset Id]</Id>
+        <Metadata>[as for Read]</Metadata>
+    </Entry>
+    <Entry>
+        ....
+    </Entry>
+</ChannelList>
+</syntaxhighlight>
-==Stop==
+Note that the content of each metadata will be fully xml escaped (so metadata for a given id won't be byte-for-byte identical to that returned by Read).
-Stop the current Channel
-==SeekSecondsAbsolute==
+== SeekSecondAbsolute ==
-Seek to an absolute second within the current media. This is only available if the current media has a finite length.
+Seek to an absolute (seconds) position in the currently playing stream, retaining the existing TransportState.  Note that most radio streams are not seekable so this action is probably only applicable to a subset of tracks played via SetChannel that the Info service reports are seekable.
+== SeekSecondRelative ==
+Seek to an position (in seconds) in the currently playing stream, relative to its current position, retaining the existing TransportState.  Note that most radio streams are not seekable so this action is probably only applicable to a subset of tracks played via SetChannel that the Info service reports are seekable
+== SetChannel ==
+Set the uri and metadata for a new track.  Any currently playing track will be stopped.  The new track will not play until the Play action is invoked.  The Id state variable will be set to 0.
+== SetId ==
+Set the preset id and uri for a new track.  The uri should be parsed from the metadata returned by Read or ReadList.  Any currently playing track will be stopped.  The new track will not play until the Play action is invoked.  The Id state variable will be updated to the newly specified preset id.
-==SeekSecondsRelative==
+== Stop ==
-Seek to a relative second within the current media.  This is only available if the current media has a finite length.
+Stop any currently playing radio stream.  Should only be called when the Radio source is currently selected
+== TransportState ==
+Return the value of the TransportState state variable.
 = Technical Details =

From OpenHome

Latest revision as of 10:58, 2 August 2013

Contents

Overview

State Variables

ChannelsMax

Id

IdArray

Metadata

ProtocolInfo

TransportState

Uri

Actions

Channel

ChannelsMax

Id

IdArray

IdArrayChanged

Pause

Play

ProtocolInfo

Read

ReadList

SeekSecondAbsolute

SeekSecondRelative

SetChannel

SetId

Stop

TransportState

Technical Details

Radio Service Description (XML)