From OpenHome

(Difference between revisions)

Revision as of 11:05, 12 June 2013

Architectural 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.

Actions

Channel

Retrieve the values of the Uri and Metadata state variables.

ChannelsMax

Retrieve 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.

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

Retrieve the value of the ProtocolInfo state variable.

Read

Given a channel preset Id, retrieve 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.

ReadList

Given a space separated list of channel preset Ids, retrieve 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>

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 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.

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.

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


   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 =
-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.
-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 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.
 = Actions =
-==Channel==
+== Channel ==
-Report the Uri and Metadata of the current Channel.
+Retrieve the values of the Uri and Metadata state variables.
+== ChannelsMax ==
-==SetChannel==
+Retrieve the value of the ChannelsMax state variable.
-Set the Uri and Metadata of the current Channel.
+== Id ==
+Report the value of the Id state variable.
-==IdArray==
+== IdArray ==
-Report the current id array. The id array contains 100 presets, but this may change (see ChannelsMax).
+Retrieve the value of the IdArray state variable.
+== IdArrayChanged ==
-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.
+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 ==
-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).
+Pause any currently playing radio stream.  Should only be called when the Radio source is currently selected.
+== Play ==
-==IdArrayChanged==
+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.
-Check to see if the id array has changed since gathering the specified IdArrayToken.
+== ProtocolInfo ==
-This Token must have been previously collected from the IdArray action.
+Retrieve the value of the ProtocolInfo state variable.
+== Read ==
-This mechanism is provided specifically for clients unable to partake in UPnP eventing.
+Given a channel preset Id, retrieve its associated metadata.  The metadata will be of the form
+    <DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/"
-==ChannelsMax==
+               xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
-Report the maximum number of entries in the channel preset id array.
+               xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
+        <item id="" parentID="" restricted="True">
-==SetId==
+            <dc:title>[title]</dc:title>
-The the current Channel using the channel preset represented by the given Id, and using the provided Uri.
+            <res protocolInfo="*:*:*:*" bitrate="6000">[track url]</res>
+            <upnp:albumArtURI>[image url]</upnp:albumArtURI>
-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.
+            <upnp:class>object.item.audioItem</upnp:class>
+        </item>
-==Id==
+    </DIDL-Lite>
-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.
+Note that additional elements may be present.  The elements listed above are guaranteed to be present.
+== ReadList ==
-==ProtocolInfo==
+Given a space separated list of channel preset Ids, retrieve their associated metadata.  The metadata will be of the form
-Report the Radio Source protocol info.
+    <ChannelList>
+        <Entry>
-==Read==
+            <Id>[preset Id]</Id>
-Given a channel preset Id, report its associated Metadata.
+            <Metadata>[as for Read]</Metadata>
+        </Entry>
-==ReadList==
+        <Entry>
-Given a space separated list of channel preset Ids, report their associated Metadata.
+            ....
+        </Entry>
-==TransportState==
+    </ChannelList>
+== SeekSecondAbsolute ==
-Report the current transport state, which can be: 'Playing', 'Paused', 'Stopped', or 'Buffering'.
+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 ==
-==Play==
+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
-Play the current channel
+== 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.
-==Pause==
+== SetId ==
-Pause the current channel. This will be converted to Stop if the channel cannot be paused e.g. internet radio.
+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.
+== Stop ==
-==Stop==
+Stop any currently playing radio stream.  Should only be called when the Radio source is currently selected
-Stop the current Channel
+== TransportState ==
+Retrieve the value of the TransportState state variable.
-==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.
+= 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

Revision as of 11:05, 12 June 2013

Contents

Architectural Overview

Actions

Channel

ChannelsMax

Id

IdArray

IdArrayChanged

Pause

Play

ProtocolInfo

Read

ReadList

SeekSecondAbsolute

SeekSecondRelative

SetChannel

SetId

Stop

TransportState

State Variables

ChannelsMax

Id

IdArray

Metadata

ProtocolInfo

TransportState

Uri

Technical Details

Radio Service Description (XML)