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 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 ==
-Retrieve the values of the Uri and Metadata state variables.
+Return the values of the Uri and Metadata state variables.
 == ChannelsMax ==
-Retrieve the value of the ChannelsMax state variable.
+Return  the value of the ChannelsMax state variable.
 == Id ==
 Report the value of the Id state variable.
 == IdArray ==
-Retrieve the value of the IdArray state variable.
+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.
@@ Line 19: / Line 36: @@
 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 ==
-Retrieve the value of the ProtocolInfo state variable.
+Return the value of the ProtocolInfo state variable.
 == Read ==
-Given a channel preset Id, retrieve its associated metadata.  The metadata will be of the form
+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/"
+<syntaxhighlight lang="xml">
-               xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
+<DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/"
-               xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
+           xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
-        <item id="" parentID="" restricted="True">
+           xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
-            <dc:title>[title]</dc:title>
+    <item id="" parentID="" restricted="True">
-            <res protocolInfo="*:*:*:*" bitrate="6000">[track url]</res>
+        <dc:title>[title]</dc:title>
-            <upnp:albumArtURI>[image url]</upnp:albumArtURI>
+        <res protocolInfo="*:*:*:*" bitrate="6000">[track url]</res>
-            <upnp:class>object.item.audioItem</upnp:class>
+        <upnp:albumArtURI>[image url]</upnp:albumArtURI>
-        </item>
+        <upnp:class>object.item.audioItem</upnp:class>
-    </DIDL-Lite>
+    </item>
-Note that additional elements may be present.  The elements listed above are guaranteed to be present.
+</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.
 == ReadList ==
-Given a space separated list of channel preset Ids, retrieve their associated metadata.  The metadata will be of the form
+Given a space separated list of channel preset Ids, return their associated metadata.  The metadata will be of the form
-    <ChannelList>
+<syntaxhighlight lang="xml">
-        <Entry>
+<ChannelList>
-            <Id>[preset Id]</Id>
+    <Entry>
-            <Metadata>[as for Read]</Metadata>
+        <Id>[preset Id]</Id>
-        </Entry>
+        <Metadata>[as for Read]</Metadata>
-        <Entry>
+    </Entry>
-            ....
+    <Entry>
-        </Entry>
+        ....
-    </ChannelList>
+    </Entry>
+</ChannelList>
+</syntaxhighlight>
+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.
@@ Line 51: / Line 76: @@
 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 buy 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.
+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 ==
-Retrieve the value of the TransportState state variable.
+Return the value of the TransportState state variable.
-= 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).
 = Technical Details =
 <code>

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)