OpenHome - New pages [en]

Av:Developer:PinInvokers

2018-08-17T16:06:11Z

Simonc: /* CalmRadio */

= Overview =

All pins have a uri associated with them which is used by the pins service to interpret one or more playable items and must be in the following form:

<tt> <mode>://<type>?<pin specific query parameters>&version<pin version> </tt>

The <tt>mode</tt> indicates which music provider will provide the playable content. Each has a number of query parameters which are outlined below. The pins service allows you to query which modes the device currently supports.

The <tt>type</tt> describes what the pin is such as an artist, album or playlist.

The current pin version is <tt>1</tt>. The version has been omitted from the examples below.

= (Linn) Kazoo Server =

{|
|-
| mode
| openhome.me
|
|-
| type
| album
| Requires response type tracks
|-
|
| artist
| Requires response type albums
|-
|
| playlist
| Requires response type tracks
|-
|
| genre
| Requires response type of either albums, playlists or tracks
|-
|
| container
| Only supported in a list pin
|-
| ''Query Parameters''
|
|
|-
| udn
| Server's Udn
|
|-
| me
| Endpoint Id
|
|-
| response
| Response type
| See above
|-
| browse
| Item id
| Performs a browse query with the given item id. Can't contain list parameter
|-
| list
| Tag id
| Performs a list query with given tag id. Can't contain a browse parameter
|}

Example Uris:
<code>
// Browse pin
openhome.me://[type]?udn=[device udn]&me=[endpoint id]&browse=[item id]&response=[response type]

// List pin
openhome.me://[type]?udn=[device udn]&me=[endpoint id]&list=[item id]&response[response type]
</code>

= Tidal =
== Tracks ==

{|
|-
| mode
| tidal
|-
| type
| track
|-
| ''Query Parameters''
|
|-
| trackId
| Tidal track id
|}

Example Uri:
<code>
tidal://track?trackId=[id]
</code>

== Other Tidal Content ==

For other Tidal content the pin will provide a link to the Tidal API resource and a hint as to what you expect that resource to return.

{|
|-
| mode
| tidal
|
|-
| type
| album
| Requires response type tracks
|-
|
| artist
| Requires response type albums
|-
|
| playlist
| Requires response type tracks
|-
|
| genre
| Requires response type of either albums, playlists or tracks
|-
|
| container
| Requires response type of either albums, playlists or tracks
|-
| ''Query Parameters''
|
|
|-
| path
| Tidal API link
| Must to be url encoded
|-
| response
| Response type
| See above
|}

Example Uri:
<code>
tidal://[type]?path=[api link]&response=[response type]
</code>

= Qobuz =
== Tracks ==

{|
|-
| mode
| qobuz
|-
| type
| track
|-
| ''Query Parameters''
|
|-
| trackId
| Qobuz track id
|}

Example Uri:
<code>
qobuz://track?trackId=[id]
</code>

== Other Qobuz Content ==

For other Qobuz content the pin will provide a link to the Qobuz API resource and a hint as to what you expect that resource to return.

{|
|-
| mode
| qobuz
|
|-
| type
| album
| Requires response type tracks
|-
|
| artist
| Requires response type albums
|-
|
| playlist
| Requires response type tracks
|-
|
| container
| Requires response type of either albums, playlists
|-
| ''Query Parameters''
|
|
|-
| path
| Qobuz API link
| Must to be url encoded
|-
| response
| Response type
| See above
|-
|}

Example Uri:
<code>
qobuz://[type]?path=[api link]&response=[response type]
</code>

= TuneIn =
== Stations ==

A TuneIn station pin should play the station from the TuneIn link specified in the pin uri.
 Note that the pin's title and artwork uri will be presented as track metadata by the [[Av:Developer:InfoService | Info]] service.

{|
|-
| mode
| tunein
|
|-
| type
| stream
|
|-
| ''Query Parameters''
|
|
|-
| path
| Radio stream link
| Must to be url encoded
|-
|}

Example Uri:
<code>
tunein://stream?path=[stream]
</code>

== Shows / Podcasts ==

A TuneIn show/podcast pin should play the most recent episode as reported by the TuneIn link specified in the pin uri.

{|
|-
| mode
| tunein
| Latest episode
|-
| mode
| tuneinlist
| All episodes
|-
| type
| podcast
|
|-
| ''Query Parameters''
|
|
|-
| path
| Show/podcast link
| Must to be url encoded
|-
|}

Example Uri:
<code>
tunein://podcast?path=[stream]
tuneinlist://podcast?path=[stream]
</code>

= Radio Preset =
Play a radio preset by index:
<code>
radio://preset?id=[index]
</code>

= iTunes Podcast =
Play either the latest episode from a podcast or load a playlist with the last N episodes
{|
|-
| mode
| itunes
| Latest episode only
|-
| mode
| ituneslist
| Load all of the episode list
|-
| type
| podcast
|
|-
| ''Query Parameters''
|
|
|-
| id
| iTunes podcast id
|
|-
|}

<code>
itunes://podcast?id=[identifier]
ituneslist://podcast?id=[identifier]
</code>

= Sources =

A source pin should switch to the source matching the system name specified in the pin uri.

{|
|-
| mode
| transport
|-
| type
| source
|-
| ''Query Parameters''
|
|-
| id
| The system name of the source
|-
| udn
| Udn of the device to which the source belongs
|-
|}

Example Uri:
<code>
transport://source?id=[system name]&udn=[device udn]
</code>

= CalmRadio =

A CalmRadio pin should play the stream specified in the pin uri
 Note that the pin's title and artwork uri will be presented as track metadata by the [[Av:Developer:InfoService | Info]] service.

{|
|-
| mode
| calmradio
|
|-
| type
| stream
|
|-
| ''Query Parameters''
|
|
|-
| path
| Radio stream link
| Must to be url encoded
|-
|}

Example Uri:
<code>
calmradio://stream?path=[stream]
</code>

= Url =
Play a hard-coded url.
 Note that the pin's title and artwork uri will be presented as track metadata by the [[Av:Developer:InfoService | Info]] service.
<code>
url://stream?path=[stream]
</code>

Av:Developer:PinsService

2018-08-17T09:10:11Z

Simonc:

= Overview =

A pin is a set of instructions to switch source or play one or more tracks on a device. Some pins will have wholly predictable results (e.g. switch to Analog2, play named playlist); others may be more dynamic (e.g. play the latest podcast from a given feed or a curated playlist of the week from a streaming service).

The Pins service provides access both device-specific and account-wide pins. Both classes of pin can be read from or invoked on a device. Device-specific pins can also be edited; account-wide pins may be editable via a device but should also have edit APIs in the service or location that provides general account support.

= Supported Content =
Reference code contains support for the following [[Av:Developer:PinInvokers | pinnable content]].

= State Variables =
== DeviceMax ==
The maximum number of device-specific pins supported

== AccountMax ==
The maximum number of account-wide pins supported

== Modes ==
JSON array of strings identifying the different styles of pins supported

== CloudConnected ==
<tt>true</tt> if a connection is available to cloud-backed master copy of account pins (i.e. when account pins are editable); <tt>false</tt> otherwise.

== IdArray ==
JSON array of identifiers (unsigned integer) for all pins.
 Device pins are listed first, followed by Account pins. i.e. array will always have <tt>DeviceMax</tt> + <tt>AccountMax</tt> entries.
 Identifiers will normally be unique; <tt>0</tt> is a special case which signifies an empty pin.

= Actions =
== GetDeviceMax ==
Read the <tt>DeviceMax</tt> property.

== GetAccountMax ==
Read the <tt>AccountMax</tt> property.

== GetModes ==
Read the <tt>Modes</tt> property.

== GetCloudConnected ==
Read the <tt>CloudConnected</tt> property.

== GetIdArray ==
Read the <tt>IdArray</tt> property.

== ReadList ==
Input: JSON integer array, specifying ids of pins to be read.
 Output: JSON array of pins
<code>
[
{
"id": {unsigned integer, unique across device & account pins},
"mode": "where track(s) will be fetched from",
"type": "instructs the device how to interpret the uri below",
"uri": "absolute uri",
"title": "Short text, may be user-visible",
"description": "Longer text, may be user-visible",
"artworkUri": "absolute uri to image",
"shuffle": {boolean}
},
{ ... }
]
</code>

== InvokeIndex ==
Invoke the pin at the specified index in <tt>IdArray</tt>. This will stop anything that is currently playing and may clear any current playlist.

== InvokeId ==
Invoke the pin with the specified id. This will stop anything that is currently playing and may clear any current playlist.

== InvokeUri ==
Invoke a pin using data (mode, type, uri, shuffle) from a control point. Should be used by any control point that wants to determine which account to read pins from. (Note however that pins which themselves require cloud support to load cannot be loaded by the device - control points would have to load them directly into a playlist instead.) This will stop anything that is currently playing and may clear any current playlist.

== SetDevice ==
Set a device pin, specifying the mode, type, uri, title, description, artworkUri and shuffle plus index into the set of device pins.
 Any pin currently assigned at the specified index will be replaced.
 Any playing content is unaffected (i.e. invoking then replacing a pin leaves the old representation of the pin playing).
index must be in the range <tt>[0..DeviceMax)</tt>.
 Some errors are notified in response to this action. Success should only be assumed when an update is evented to IdArray showing a change in id at the specified index.

== SetAccount ==
Set an account pin, specifying the mode, type, uri, title, description, artworkUri and shuffle plus index into the set of device pins.
 Any pin currently assigned at the specified index will be replaced.
 Any playing content is unaffected (i.e. invoking then replacing a pin leaves the old representation of the pin playing).
index must be in the range <tt>[0..AccountMax)</tt>.
 Requests to update an account pin are proxied to a remote server so are likely to be slower and have greater chance of failure.
 Some errors are notified in response to this action. Success should only be assumed when an update is evented to <tt>IdArray</tt> showing a change in id at <tt>DeviceMax + index</tt>.

== Clear ==
Clear any content in the pin with the specified id.
 As with Set, changes to device pins are implemented locally; changes to account pins are proxied to a remote server.
 Some errors are notified in response to this action. Success should only be assumed when an update is evented to the sequence number for the specified id.

== Swap ==
Swap contents of the 2 pins at the specified indices.
 Pins can only be swapped within either device or account lists.

= Technical Details =
<code>
Domain : av.openhome.org
Name : Pins
Version : 1
</code>

== Service Description (XML) ==
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>GetDeviceMax</name>
<argumentList>
<argument>
<name>DeviceMax</name>
<direction>out</direction>
<relatedStateVariable>DeviceMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetAccountMax</name>
<argumentList>
<argument>
<name>AccountMax</name>
<direction>out</direction>
<relatedStateVariable>AccountMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetModes</name>
<argumentList>
<argument>
<name>Modes</name>
<direction>out</direction>
<relatedStateVariable>Modes</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetIdArray</name>
<argumentList>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetCloudConnected</name>
<argumentList>
<argument>
<name>CloudConnected</name>
<direction>out</direction>
<relatedStateVariable>CloudConnected</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Ids</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>List</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>InvokeId</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>InvokeIndex</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>InvokeUri</name>
<argumentList>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Type</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetDevice</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Type</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Title</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>ArtworkUri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetAccount</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Type</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Title</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>ArtworkUri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Clear</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Swap</name>
<argumentList>
<argument>
<name>Index1</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
<argument>
<name>Index2</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>DeviceMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>AccountMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Modes</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CloudConnected</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Uint</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Bool</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

Av::OhMetadata

2017-06-23T15:39:00Z

Simonc: /* OpenHome Metadata Format */

= OpenHome Metadata Format =
OpenHome Metadata format describes metadata for an audio track as a series of key-value pairs.

The list of supported keys, their mapping into DIDL-Lite and the number of instances that may be used are listed below:
{|
! '''Key'''
! '''DIDL-Lite mapping'''
! '''Instances'''
|-
| uri
| res
| 1
|-
| id
| @id in item
| [0..1]
|-
| type
|
* track -> object.item.audioItem.musicTrack
| [0..1]
|-
| provider
| oh:provider
| [0..1]
|-
| title
| dc:title
| [0..1]
|-
| artwork
| oh:artwork
| [0..1]
|-
| artist
| upnp:artist
| [0..n]
|-
| composer
| upnp:artist @role=composer
| [0..n]
|-
| conductor
| upnp:artist @role=conductor
| [0..n]
|-
| genre
| upnp:genre
| [0..n]
|-
| albumTitle
| upnp:album
| [0..1]
|-
| albumArtwork
| upnp:albumArtURI
| [0..1]
|-
| albumArtist
| upnp:artist @role=AlbumArtist
| [0..n]
|-
| albumGenre
| upnp:genre
| [0..n]
|-
| year
| dc:date
| [0..1]
|-
| disc
| oh:originalDiscNumber
| [0..1]
|-
| discs
| oh:originalDiscCount
| [0..1]
|-
| track
| upnp:originalTrackNumber
| [0..1]
|-
| tracks
| oh:originalTrackCount
| [0..1]
|-
| channels
| res @nrAudioChannels
| [0..1]
|-
| bitDepth
| res @bitsPerSample
| [0..1]
|-
| sampleRate
| res @sampleFrequency
| [0..1]
|-
| bitRate
| res @bitrate (integer / string of digits)
| [0..1]
|-
| duration
| res @duration (seconds - string of digits, zero = live/eternal)
| [0..1]
|-
| mimeType
| res @protocolInfo
| [0..1]
|-
| work
| oh:work
| [0..1]
|-
| movement
| oh:movement
| [0..1]
|-
| show
| oh:show
| [0..1]
|-
| episode
| oh:episodeNumber
| [0..1]
|-
| episodes
| oh:episodeCount
| [0..1]
|-
| author
| dc:author
| [0..n]
|-
| narrator
| upnp:artist @role=narrator
| [0..n]
|-
| performer
| upnp:artist @role=performer
| [0..n]
|-
| publisher
| dc:publisher
| [0..1]
|-
| published
| oh:published (ISO 8601)
| [0..1]
|-
| website
| oh:website
| [0..1]
|-
| location
| oh:location (ISO 6709)
| [0..1]
|-
| details
| oh:details
| [0..1]
|-
| description
| dc:description
| [0..1]
|-
| rating
| upnp:rating
| [0..1]
|-
| extensions
| oh:extensions
| [0..1]
|}

Av:Developer:Odp

2017-06-23T14:40:01Z

Simonc: Rev protocol version (addition of device id and service domains in various messages)

= OpenHome Device Protocol =
== Overview ==
OpenHome Device Protocl (ODP) allows a control point to control and receive evented updates from an OpenHome device using a single TCP socket. This has some advantages over UPnP:
* No need to define error handling policy for cases where evented updates cannot be delivered. If the socket connection is open, it'll be possible to deliver an evented update. If the socket connection is broken, the device can automatically clean up all subscriptions from that control point.
* No need to define additional protocol to allow control points to infer removal of a device. If the socket connection is open, a control point can assume the device is available. If the socket connection is broken, the control point is immediately prompted to retry connection; if this fails, it can quickly update its state to show that the device is no longer available.
* No danger of TIME_WAIT socket errors when control points invoke very large numbers of actions and/or devices are rebooted.

== Discovery ==
Using mDNS, search for <tt>_openhome._odp</tt> to identify an ODP endpoint.

== Sample Code ==
[https://github.com/openhome/ohPipeline ohPipeline] contains [https://github.com/openhome/ohPipeline/tree/master/OpenHome/Net/Odp reference code] for control point or device stacks.

Control point authors can instantiate [https://github.com/openhome/ohPipeline/blob/master/OpenHome/Net/Odp/Tests/CpiDeviceOdp.h CpiDeviceOdp] then use standard ohNet proxy classes to access all OpenHome network services. Proxies can be generated from UPnP service XML; pre-generated versions are available in [https://github.com/openhome/ohNetGenerated ohNetGenerated].

See [https://github.com/openhome/ohPipeline/blob/master/OpenHome/Net/Odp/Tests/TestDvOdp.cpp ODP test code] for a simple example of a control point invoking actions and receiving evented updates over ODP.

Sample code for mDNS discovery of ODP devices is coming soon.

== Protocol ==
=== Framing ===
Each message, in either direction, is a JSON object followed by a newline (<tt>'\n'</tt>)

=== Announcement ===
When a client connects, a device announces its capabilities:
{
"type":"announcement",
"protocolVersion":3,
"devices": [
{
"id":"udn",
"type":"one of Ds, MediaRenderer, ZoneSetup, ZoneSource, ZoneReceiver",
"services": [
{ "domain": "abc.org", "name":"service1", "version":1 },
{ "domain": "abc.org", "name":"service2", "version":2 },
{ "domain": "xyz.com", "name":"service3", "version":1 }
]
},
{
"id": "udn",
"type":"one of Ds, MediaRenderer, ZoneSetup, ZoneSource, ZoneReceiver",
"services": [
{ "domain": "abc.org", "name":"service4", "version":1 },
{ "domain": "xyz.com", "name":"service5", "version":1 }
]
}
]
}

=== Control ===
The control point can invoke an action on a device as follows. This will block until a response is sent. Note that it is possible that the control point may receive other messages (e.g. <tt>notify</tt> - see below) before the action response.
 The name for each input argument will match the <tt>name</tt> element for that argument in the service description XML. All values are strings.
{
"type": "action",
"id": "udn",
"device": "type",
"service": { "domain": "xyz.com", "name": "service_name", "version": 1 },
"action": "action_name",
"arguments": [
{ "name": "input_arg_str", "value":"json_escaped_str" },
{ "name": "input_arg_bin", "value":"base64_encoded_str" },
{ "name": "input_arg_bool", "value":"true" },
{ "name": "input_arg_int", "value":"-1" },
{ "name": "input_arg_uint", "value":"3" }
],
"correlationId":"optional request identifier",
"userAgent":"optional client identifier"
}

Response when action invocation is successful.
 The name for each output argument will match the <tt>name</tt> element for that argument in the service description XML. All values are strings.
{
"type": "actionResponse",
"error": null,
"arguments": [
{ "name": "output_arg_str", "value":"json_escaped_str" },
{ "name": "output_arg_bin", "value":"base64_encoded_str" },
{ "name": "output_arg_bool", "value":"true" },
{ "name": "output_arg_int", "value":"-1" },
{ "name": "output_arg_uint", "value":"3" }
],
"correlationId":"echoed from request"
}

Response when action invocation fails:
{
"type": "actionResponse",
"error": { "code": 123, "description": "error msg" },
"arguments": null,
"correlationId":"echoed from request"
}

=== Eventing ===
Subscribe to a particular service. On successful completion, the device will send out unsolicited messages (with type <tt>notify</tt>) whenever one or more evented properties of a service change.
{
"type": "subscribe",
"id", "udn",
"device": "type",
"service": { "domain": "abc.org", "name": "service_name", "version": 2 },
"correlationId":"optional request identifier"
}

Response when a subscribe request succeeds. The subscription id (sid) will be included in all later evented updates for this subscription.
{
"type": "subscribeResponse",
"device": "type",
"service": { "name": "service_name", "version": 2 }
"error": null,
"correlationId":"echoed from request",
"sid": "subscription_id"
}

Response when a subscribe request fails. No later evented updates will be sent.
{
"type": "subscribeResponse",
"id", "udn",
"device": "type",
"service": { "domain": "abc.org", "name": "service_name", "version": 2 }
"error": { "code": 123, "description": "error msg" },
"correlationId":"echoed from request",
"sid": null
}

Unsubscribe (halt a particular stream of evented updates).
{
"type": "unsubscribe",
"correlationId":"optional request identifier",
"sid": "subscription_id"
}

Response when an unsubscribe completes. No evented updates for this subscription will be sent after this.
{
"type": "unsubscribeResponse",
"correlationId":"echoed from request"
}

A device will send the following whenever one or more evented properties change on a service with an active subscription.
 The name for each property will match the <tt>name</tt> element for the associated <tt>stateVariable</tt> in the service description XML. All values are strings.
{
"type": "notify",
"sid": "subscription_id",
"properties": [
{ "name": "property_str", "value":"json_escaped_str" },
{ "name": "property_bin", "value":"base64_encoded_str" },
{ "name": "property_bool", "value":"true" },
{ "name": "property_int", "value":"-1" },
{ "name": "property_uint", "value":"3" }
]
}

Av:Developer:Scd

2017-06-23T12:47:35Z

Simonc: /* Overview */

= Songcast Direct =
== Overview ==
Songcast Direct (SCD) can be used to send decoded audio from any computing device to an OpenHome device. The Sender device is responsible for decoding audio to PCM, framing this in a simple protocol and making it available via a simple TCP server. The Receiver pulls data from this server, giving the Receiver complete control of the audio clock.

A Songcast Direct sender performs a broadly similar role to a Songcast sender. Applications that perform their own decoding to PCM will find SCD is easier to integrate and offers higher audio performance:
* There is a constant TCP connection between sender and receiver, avoiding the need for application-level resend support
* It uses the clock of the receiver, allowing for higher quality playback if the sender is on a desktop computer
* It offers the receiver limited control over the stream – initially Transport (play / pause / stop) and Volume. While the primary control UI may reside on the sender device, this allows for basic integration with any Ir handset for the receiver.

== Sample Code ==
[https://github.com/openhome/ohPipeline/tree/master/OpenHome/Av/Scd ohPipeline] contains sample code.

<tt>WavSender</tt> contains an example of a trivial SCD Sender, scanning a single directory and decoding then sending any WAV files it finds. (Note that compilation of this is currently disabled. <tt>DirScanner::Run()</tt> contains code from an experimental precursor to C++17's <tt>std::filesystem::directory_iterator</tt>. Current code is compatible with VS2013; it should only require a couple of lines of change to make this compile against any more recent compiler.)

Code in the [https://github.com/openhome/ohPipeline/tree/master/OpenHome/Av/Scd Scd] and [https://github.com/openhome/ohPipeline/tree/master/OpenHome/Av/Scd/Sender Sender] directories should be usable without any change. It will be possible to write a commercial quality sender using the <tt>ScdSender</tt> library, passing audio into <tt>IScdSupply</tt> and relying on the configuration of <tt>ScdMsgFactory</tt> to determine how much audio is buffered by the Sender.

Sample code demonstrating how a Sender can control a Receiver via ODP is coming soon. For now, see [https://github.com/openhome/ohPipeline/blob/master/OpenHome/Net/Odp/Tests/TestDvOdp.cpp ODP tests] for a basic example.

== Discovery ==
=== SSDP ===
First search for <tt>av-openhome-org:service:Product:2</tt> then either
* Check <tt>Attributes</tt> on <tt>Product</tt> service for <tt>"Transport"</tt>
* Check <tt>Modes</tt> on <tt>Transport</tt> service for <tt>"scd"</tt>
or
* Check <tt>SourceXml</tt> on <tt>Product</tt> for a source with <tt>Type</tt> of <tt>"scd"</tt>

=== mDNS ===
Search for <tt>_openhome._odp</tt> service to identify ODP endpoint

== Control ==
Control of the Receiver is out of band, via the standard [[OhMediaDevelopers#Network_Services | OpenHome network APIs]]. These are available over UPnP or [[OhMediaDevelopers#ODP | ODP]] (a single connected socket).

== Protocol ==
The protocol used for communication between Sender and Receiver contains the following message types:
{|
! '''Type'''
! '''Description'''
! '''Sent by'''
|-
| Ready
| Signals availability and version support to other party
| Receiver & Sender
|-
| MetadataDidl
| Metadata relevant until the end of the next track. Will cause the receiver to reset its reported time indicator for the audio stream. Should be sent after all Audio for any preceding track. Uses DIDL-Lite.
| Sender
|-
| MetadataOh
| Metadata relevant until the end of the next track. Will cause the receiver to reset its reported time indicator for the audio stream. Should be sent after all Audio for any preceding track. Uses [[Av::OhMetadata | OpenHome Metadata format]].
| Sender
|-
| Format
| Format for the following (PCM) audio. Must be sent before any audio.
| Sender
|-
| FormatDsd
| Format for the following (DSD) audio. Must be sent before any audio.
| Sender
|-
| Audio
| Decoded audio. Can only be sent after a <tt>Format</tt> message describing its sample rate etc.
| Sender
|-
| MetatextDidl
| Metadata relevant to a portion of a track. May be sent [0..n] times during a track. Uses DIDL-Lite.
| Sender
|-
| MetatextOh
| Metadata relevant to a portion of a track. May be sent [0..n] times during a track. Uses [[Av::OhMetadata | OpenHome Metadata format]]. Note that a uri does not need to be specified.
| Sender
|-
| Halt
| Indicates that a break in audio follows. E.g. at the end of a track with no further tracks to be played, or when the Sender has paused.
| Sender
|-
| Disconnect
| Indicates that the originator of the message is closing its SCD session. No further audio will be available. The message receiver should disconnect its socket.
| Receiver & Sender
|-
| Seek
| Indicates that the Receiver wants to jump to a different point in the current track. Is only sent for tracks that the Sender has indicated support seeking.
| Receiver
|-
| Skip
| Indicates that the Receiver wants to immediately jump to the next or previous track.
| Receiver
|}

A SCD session is initiated by the Sender. It instantiates a simple TCP server then instructs the Receiver to start playing from it.

The Receiver connects to the Sender and sends a <tt>Ready</tt> message, indicating the protocol version it supports. If the Sender is compatible with this version, it responds with a <tt>Ready</tt> message stating the same version. Otherwise, the Sender sends a <tt>Ready</tt> message stating the version it supports. If the Receiver cannot support this version, it must close the connection.

After sending a <tt>Ready</tt> message, the Sender should send either <tt>Halt</tt> (if it has nothing to send yet) or one of <tt>MetadataDidl</tt> or <tt>MetadataOh</tt> plus <tt>Format</tt>. The order of <tt>Format</tt> versus <tt>Metadata*</tt> is not important.

After this, the Sender should then send <tt>Audio</tt>. Any number of <tt>Audio</tt> messages can be sent until the end of the stream is reached. <tt>Metatext</tt> messages (either <tt>Didl</tt> or <tt>Oh</tt>) may be interleaved with <tt>Audio</tt>.

A <tt>Halt</tt> message implies that a break in audio may follow. If this break is during a stream, the Sender must have applied attenuation to samples immediately before this to avoid any audio artifacts at the break in transmission. Senders which cannot do this should implement pausing of streams using the Transport.Pause control API instead.

The details of the wire protocol are shown below. Note that all multi-byte integer values are big endian.
{|
! '''Bytes'''
! '''Name'''
! '''Description'''
|-
| '''Header'''
|
| Prefixes to all messages below
|-
| 4
| Signature
| 0x73, 0x63, 0x64,0x20 ('scd ')
|-
| 1
| Type
| The type of message:
* 0 – Ready
* 1 – MetadataDidl
* 2 - MetaDataOh
* 3 – Format
* 4 – FormatDsd
* 5 – Audio
* 7 – MetatextDidl
* 8 – MetatextOh
* 9 – Halt
* 10 – Disconnect
* 11 – Seek
* 12 – Skip
|-
| 2
| Length
| Length in bytes of the whole message including this header
|-
| 4
| Reserved
| Unused, reserved for future use
|-
| '''Ready'''
|
|
|-
| 2
| Major Version
| 1
|-
| 2
| Minor Version
| 0
|-
| '''MetadataDidl'''
|
|
|-
| 2
| TrackUriLength
| Length, in bytes, of the track URI
|-
| m
| TrackUri
| The track URI, where m = TrackUriLength
|-
| 2
| MetadataLength
| Length, in bytes, of the track metadata, in DIDL-Lite format
|-
| n
| Metadata
| The track metadata, where n = MetadataLength
|-
| '''MetadataOh'''
|
|
|-
| 1
| Count
| Number of key-value pairs that follow
|-
| 1
| KeyLength
| Length, in bytes, of the key
|-
| p
| Key
| Key for the metadata element, where p = KeyLength
|-
| 2
| ValueLength
| Length, in bytes, of the value
|-
| q
| Value
| Value for the metadata element, where q = ValueLength
|-
| ...
| ...
| Repeat key-value pairs for all Count metadata elements
|-
| '''Format'''
|
|
|-
| 1
| BitDepth
| Bit depth of the following audio
|-
| 4
| SampleRate
| Sample rate of the following audio
|-
| 1
| Channels
| Number of channels of the following audio
|-
| 4
| BitRate
| Bit rate of the following audio
|-
| 8
| SampleStart
| Sample position of the first sample in the next <tt>Audio</tt> message
|-
| 8
| SamplesTotal
| Total number of samples in the following audio (requirement for this to be confirmed)
|-
| 1
| Flags
|
* Bit 0 - Seekable
* Bit 1 - Lossless
* Bit 2 - Live (content generated upstream of the Sender, e.g. internet radio)
* Bit 3 - Broadcastable (whether the Receiver is allowed to offer the following audio via any multi-room protocols
* Bits 4-7 - Reserved. Must be zero.
|-
| 1
| CodecNameLength
| Length, in bytes, of the codec name
|-
| r
| CodecName
| The codec name, where r = CodecNameLength
|-
| '''FormatDsd'''
|
|
|-
| 4
| SampleRate
| Sample rate of the following audio
|-
| 1
| Channels
| Number of channels of the following audio
|-
| 2
| SampleBlockBits
| Block size (in bits) of DSD data. 2 for stereo where left/right channels are interleaved, 16 for stereo with one byte of left subsamples followed by one byte of right subsamples, etc.
|-
| 8
| SampleStart
| Sample position of the first sample in the next <tt>Audio</tt> message
|-
| 8
| SamplesTotal
| Total number of samples in the following audio (requirement for this to be confirmed)
|-
| 1
| Flags
|
* Bit 0 - Seekable
* Bit 1-2 - Reserved. Must be zero.
* Bit 3 - Broadcastable (whether the Receiver is allowed to offer the following audio via any multi-room protocols
* Bits 4-7 - Reserved. Must be zero.
|-
| 1
| CodecNameLength
| Length, in bytes, of the codec name
|-
| r
| CodecName
| The codec name, where r = CodecNameLength
|-
| '''Audio'''
|-
| 2
| NumSamples
| The number of audio samples in this message
|-
| s
| AudioData
| Audio data. Where s = NumSamples * (BitDepth/8) * NumChannels. Multi-channel audio must supply data sample at a time, with left channel first. Audio is packed (i.e. no padding bytes rounding samples up to 32-bit boundaries) and big endian.
|-
| '''MetatextDidl'''
|
|
|-
| 2
| Metatext Length
| Length, in bytes, of the metatext, in DIDL-Lite format
|-
| n
| Metatext
| The metatext, where n = MetatextLength
|-
| '''MetatextOh'''
|
|
|-
| 1
| Count
| Number of key-value pairs that follow
|-
| 1
| KeyLength
| Length, in bytes, of the key
|-
| p
| Key
| Key for the metatext element, where p = KeyLength
|-
| 2
| ValueLength
| Length, in bytes, of the value
|-
| q
| Value
| Value for the metatext element, where q = ValueLength
|-
| ...
| ...
| Repeat key-value pairs for all Count metatext elements
|-
| '''Halt'''
|
|
|-
|
|
| No message body (only header required)
|-
| '''Disconnect'''
|
|
|-
|
|
| No message body (only header required)
|-
| '''Seek'''
|
|
|-
|
|
| To be confirmed
|-
| '''Skip'''
|
|
|-
|
|
| To be confirmed
|}

CalmRadioInternetRadio

2017-06-02T08:26:48Z

Simonc: Created page with "Calm Radio's API is private. See Calm Radio for access to it. Or speak to us for help if you think that your access to the API would benefit OpenHome. Assuming access to Calm ..."

Calm Radio's API is private. See Calm Radio for access to it. Or speak to us for help if you think that your access to the API would benefit OpenHome.

Assuming access to Calm Radio's API, the [[Av:Developer:CredentialsService | Credentials]] service can be used to retrieve the following information:

* The <tt>Ids</tt> state variable includes <tt>calmradio.com</tt> if Calm Radio is supported.
* <tt>Data</tt> from <tt>Get</tt> contains the json object returned from login (so includes both a login token and a note on membership level).
* <tt>Status</tt> from <tt>Get</tt> is blank if Username and Password are both either blank or set and valid. If <tt>Status</tt> is not blank, it contains either json returned from a Calm Radio API or an error string.
* The token returned from <tt>Login</tt> and <tt>ReLogin</tt> is a Calm Radio token. No streams can be played if this is empty.

Tracks can be added to either [[Av:Developer:PlaylistService | Playlist]] or [[Av:Developer:RadioService | Radio]] services with urls in the form <tt>calmradio://stream?[url encoded full url to calm radio stream]</tt>

Av:Developer:TransportPlayAsCommands

2017-04-24T13:38:42Z

Simonc: Add track={json}

= Transport PlayAs Options =
The [[Av:Developer:TransportService | Transport]] service’s <tt>PlayAs</tt> action takes arguments for <tt>mode</tt> (source or group of related sources) and a mode-specific <tt>command</tt>. Some standard modes and commands are listed below; other manufacturer-specific options are possible.

=== Playlist ===
The <tt>"playlist"</tt> mode supports the following commands:
* <tt>id=[track_id]</tt> - Halt playback of any current track and switch to the track with the specified id. Returns a <tt>800</tt> fault code if <tt>[track_id]</tt> is not valid.
* <tt>index=[playlist_index]</tt> - Halt playback of the current track and switch to the track with the specified index. Returns a <tt>802</tt> fault code if the index is beyond the end of the playlist.
* <tt>track={"uri":"track_uri","metadata":"didl_lite"}</tt> - load the specified track at the end of the current Playlist and play it next.

=== Radio ===
The <tt>"radio"</tt> mode supports the following command:
* <tt>id=[preset_id]</tt> – Start playing the specified preset. Returns a <tt>800</tt> fault code if <tt>[preset_id]</tt> does not match a current preset

The <tt>"Radio-Single"</tt> mode supports the following command:
* <tt>track={"uri":"track_uri","metadata":"didl_lite"}</tt> - load the specified track.

Av:Developer:TransportService

2017-04-24T13:36:36Z

Simonc: /* SeekSecondAbsolute */

= Transport Service =
== Overview ==
The Transport service provides source-independent control of play, pause, stop, skip and seek.

If a device's [[Av:Developer:ProductService | Product]] service reports an attribute <tt>"Transport"</tt>, then that device is guaranteed to bear the Transport service. If the Transport service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== Modes ===
List of available modes (JSON array of strings).

=== CanSkipNext ===
<tt>true</tt> if the <tt>SkipNext</tt> action is currently available; <tt>false</tt> otherwise.

Any mode that is sometimes capable of changing stream as a consequence of <tt>SkipNext</tt> will always report <tt>CanSkipNext</tt> as <tt>true</tt>.

=== CanSkipPrevious ===
<tt>true</tt> if the <tt>SkipPrevious</tt> action is currently available; <tt>false</tt> otherwise.

Any mode that is sometimes capable of changing stream as a consequence of <tt>SkipPrevious</tt> will always report <tt>CanSkipPrevious</tt> as <tt>true</tt>.

=== CanRepeat ===
<tt>true</tt> if the <tt>SetRepeat</tt> action is currently available; <tt>false</tt> otherwise.

=== CanShuffle ===
<tt>true</tt> if the <tt>SetShuffle</tt> action is currently available; <tt>false</tt> otherwise.

=== StreamId ===
Integer id, uniquely identifying the current stream.

=== CanSeek ===
<tt>true</tt> if the <tt>SeekSecondAbsolute</tt> and <tt>SeekSecondRelative</tt> actions are available for the current stream; <tt>false</tt> otherwise.

=== CanPause ===
<tt>true</tt> if the stream can be paused (so is not being played at a rate determined by a remote sender); <tt>false</tt> otherwise.

=== TransportState ===
One of
* <tt>Playing</tt>
* <tt>Paused</tt>
* <tt>Stopped</tt>
* <tt>Buffering</tt>
* <tt>Waiting</tt>

=== Repeat ===
<tt>true</tt> if repeat mode is currently enabled; <tt>false</tt> otherwise.

=== Shuffle ===
<tt>true</tt> if shuffle mode is currently enabled; <tt>false</tt> otherwise.

== Actions ==
=== PlayAs ===
<tt>
Arguments: (in string mode, in string command)
</tt> 
Start a new stream playing, specifying both a mode (source) to be used and a mode-specific command which describes the track to be played. Common options for [[Av:Developer:TransportPlayAsCommands | modes and commands]] are documented separately.

=== Play ===
<tt>
Arguments: None
</tt> 
Start a pending stream playing.

A stream must be ready to play. Possibly via calls to another network service.

Behaviour when a stream is already playing varies depending on the active modes (source).

=== Pause ===
<tt>
Arguments: None
</tt> 
Pause the current stream.

Returns a <tt>801</tt> fault code if the current channel does not support being paused (is being played at a rate determined by a remote sender).

=== Stop ===
<tt>
Arguments: None
</tt>
Stop the current stream.

=== Next ===
<tt>
Arguments: None
</tt> 
Move to the next stream (i.e. skip forwards). Determination of what comes next may vary between sources/modes. If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

=== Previous ===
<tt>
Arguments: None
</tt> 
Move to the previous stream (i.e. skip backwards). If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>801</tt> fault code if the current channel does not support skipping backwards.

=== SetRepeat ===
<tt>
Arguments: (in uint repeat)
</tt> 
Sets the Repeat state of the device, affecting all sources that are capable of implementing a repeat feature.

=== SetShuffle ===
<tt>
Arguments: (in uint shuffle)
</tt> 
Sets the Shuffle state of the device, affecting all sources that are capable of implementing a randomise feature.

=== SeekSecondAbsolute ===
<tt>
Arguments: (in uint streamId, in uint secondsAbsolute)
</tt> 
Seek to an absolute position in the current stream. If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>803</tt> fault code if the seek is not possible.

=== SeekSecondRelative ===
<tt>
Arguments: (in uint streamId, in int secondsRelative)
</tt> 
Seek to a position relative to what's currently playing in the current stream. If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>803</tt> fault code if the seek is not possible.

=== TransportState ===
<tt>
Arguments: (out string state)
</tt> 
Read the current value of the TransportState property.

=== Modes ===
<tt>
Arguments: (out string modes)
</tt> 
Return the value of the <tt>Modes</tt> property.

=== ModeInfo ===
<tt>
Arguments: (out string mode, out bool canSkipNext, out bool canSkipPrevious, out bool canRepeat, out bool canShuffle)
</tt> 
Reports the values of the <tt>Mode</tt>, <tt>CanSkipNext</tt>, <tt>CanSkipPrev</tt>, <tt>CanRepeat</tt> and <tt>CanShuffle</tt> properties.

=== StreamInfo ===
<tt>
Arguments: 
(out uint streamId, out bool seekable, out bool pausable)
</tt>

Reports current stream information:
* <tt>StreamId</tt>
* <tt>Seekable</tt>
* <tt>Pausable</tt>

=== StreamId ===
<tt>
Arguments: (out uint streamId)
</tt> 
Read the current value of the <tt>StreamId</tt> property.

=== Repeat ===
<tt>
Arguments: (out uint repeat)
</tt> 
Read the current value of the <tt>Repeat</tt> property.

=== Shuffle ===
<tt>
Arguments: (out uint shuffle)
</tt> 
Read the current value of the <tt>Shuffle</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Transport"
 domain: "av.openhome.org"
 version: "1"</tt>
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>PlayAs</name>
<argumentList>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
<argument>
<name>Command</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Play</name>
</action>
<action>
<name>Pause</name>
</action>
<action>
<name>Stop</name>
</action>
<action>
<name>SkipNext</name>
</action>
<action>
<name>SkipPrevious</name>
</action>
<action>
<name>SetRepeat</name>
<argumentList>
<argument>
<name>Repeat</name>
<direction>in</direction>
<relatedStateVariable>Repeat</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetShuffle</name>
<argumentList>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>Shuffle</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SeekSecondAbsolute</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>in</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
<argument>
<name>SecondAbsolute</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SeekSecondRelative</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>in</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
<argument>
<name>SecondRelative</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_int</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TransportState</name>
<argumentList>
<argument>
<name>State</name>
<direction>out</direction>
<relatedStateVariable>TransportState</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Modes</name>
<argumentList>
<argument>
<name>Modes</name>
<direction>out</direction>
<relatedStateVariable>Modes</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ModeInfo</name>
<argumentList>
<argument>
<name>CanSkipNext</name>
<direction>out</direction>
<relatedStateVariable>CanSkipNext</relatedStateVariable>
</argument>
<argument>
<name>CanSkipPrevious</name>
<direction>out</direction>
<relatedStateVariable>CanSkipPrevious</relatedStateVariable>
</argument>
<argument>
<name>CanRepeat</name>
<direction>out</direction>
<relatedStateVariable>CanRepeat</relatedStateVariable>
</argument>
<argument>
<name>CanShuffle</name>
<direction>out</direction>
<relatedStateVariable>CanShuffle</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>StreamInfo</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>out</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
<argument>
<name>CanSeek</name>
<direction>out</direction>
<relatedStateVariable>CanSeek</relatedStateVariable>
</argument>
<argument>
<name>CanPause</name>
<direction>out</direction>
<relatedStateVariable>CanPause</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>StreamId</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>out</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Repeat</name>
<argumentList>
<argument>
<name>Repeat</name>
<direction>out</direction>
<relatedStateVariable>Repeat</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Shuffle</name>
<argumentList>
<argument>
<name>Shuffle</name>
<direction>out</direction>
<relatedStateVariable>Shuffle</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Modes</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CanSkipNext</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CanSkipPrevious</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CanRepeat</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CanShuffle</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>StreamId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CanSeek</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CanPause</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TransportState</name>
<dataType>string</dataType>
<allowedValueList>
<allowedValue>Playing</allowedValue>
<allowedValue>Paused</allowedValue>
<allowedValue>Stopped</allowedValue>
<allowedValue>Buffering</allowedValue>
<allowedValue>Waiting</allowedValue>
</allowedValueList>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Repeat</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Shuffle</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_uint</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_int</name>
<dataType>i4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_string</name>
<dataType>string</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:DavaarChanges

2015-12-15T14:54:55Z

Simonc: Created page with "= Changes between Davaar and Eriskay = This page outlines the API changes between Davaar and Eriskay. == Device == New service. Control points use this service to determine wh..."

= Changes between Davaar and Eriskay =

This page outlines the API changes between Davaar and Eriskay.

== Device ==
New service.

Control points use this service to determine whether a device is using compatible software. The presence of some services below can be inferred from this service.

== Product ==
Still the entrypoint for Topology algorithm. Control points no longer need to search for this – its presence can be inferred by checking for the <tt>openhome.org.product</tt> attribute in the versions section of the [[Av:Developer:Eriskay:DeviceService | Device]] description.

The following actions / properties have changed:
* <tt>SourceXml</tt> is now <tt>SourceArray</tt> and is formatted as JSON
* Similarly, <tt>SourceXmlChangeCount</tt> is now <tt>SourceArrayChangeCount</tt>
* <tt>ProductName</tt> and <tt>ProductRoom</tt> are now simply <tt>Name</tt> and <tt>Room</tt>
* The <tt>Product</tt> action is now <tt>Names</tt>
* <tt>SetSourceIndexByName</tt> and <tt>SetSourceIndex</tt> have been replaced by <tt>SetSource</tt>
* <tt>SourceIndex</tt> has been replaced by <tt>SourceSystemName</tt>

The following actions / properties have been (re)moved:
* <tt>SourceCount</tt> and <tt>SourceIndex</tt> have been removed. Use the <tt>SetSource</tt> action and <tt>SourceSystemName</tt> property instead.
* The <tt>Source</tt> action has been removed. Use <tt>SourceArray</tt>, parsing the JSON returned, to get information about a single source.
* <tt>Standby</tt> has been removed and is now available via the [[Av:Developer:Eriskay:DeviceService | Device]] service.
* The various <tt>Manufacturer</tt> properties and <tt>Manufacturer</tt> action have been removed and are now available via the [[Av:Developer:Eriskay:DeviceService | Device]] service.
* The various <tt>Model</tt> properties and <tt>Model</tt> action have been removed and are now available via the [[Av:Developer:Eriskay:DeviceService | Device]] service.
* The <tt>ProductInfo</tt>, <tt>ProductUri</tt>, <tt>ProductImageUri</tt> properties have been removed and are no longer returned by the <tt>Product</tt> action. These can now be read via the [[Av:Developer:Eriskay:DeviceService | Device]] service.
* <tt>SetSourceIndexByName</tt> has been removed.

The following actions / properties have been added:
* <tt>Home</tt> provides an identifier for a group of rooms. Traditional control points do not need to use this.

== Info ==
Removed. Use the [[Av:Developer:Eriskay:TransportService | Transport]] service instead.

== Transport ==
New service.

Replaces Info service plus transport commands (<tt>Play</tt>, <tt>Pause</tt>, <tt>Stop</tt>, <tt>Next</tt>, <tt>Prev</tt>, <tt>SeekSecondsAbsolute</tt> and <tt>SeekSecondsRelative</tt>) from source-specific services.

== Time ==
No Changes

== Volume ==
Removed the <tt>VolumeMilliDbPerStep</tt> property. Control points which set volume as an absolute decibel level are no longer supported.

One new property – <tt>UnityGain</tt> – which reports whether the current channel is already volume controlled.

== Credentials ==
<tt>ReLogin</tt> action renamed <tt>Relogin</tt>.

Tokens and data returned for Tidal and Qobuz streaming services are now JSON arrays to allow for additional information to be communicated in future.

== Sender==
<tt>Attributes</tt> and <tt>PresentationUrl</tt> properties / getters have been removed. These can be published as attributes via the [[Av:Developer:Eriskay:DeviceService | Device]] service if required.

<tt>Metadata</tt> format has changed from DIDL-Lite to OpenHome Metadata.

Updated list of allowed values for <tt>Status</tt> property (no change in behaviour – Davaar docs were incorrect).

== Configuration ==
New service.

Developer aid that may be useful from test programs but should not be used in production code.

== Playlist ==
The following actions have been removed. Use equivalents in [[Av:Developer:Eriskay:TransportService | Transport]] service instead:
* <tt>Play</tt> / <tt>Pause</tt> / <tt>Stop</tt>
* <tt>Next</tt> / <tt>Prev</tt>
* <tt>SeekSecondsAbsolute</tt> / <tt>SeekSecondsRelative</tt>
* <tt>TransportState</tt>

<tt>Read</tt> and <tt>DeleteId</tt> have been removed. Use <tt>ReadList</tt> and <tt>DeleteList</tt> instead.

<tt>Metadata</tt> passed to <tt>Insert</tt> is expected to now be in OpenHome Metadata format. Whatever format is passed in will be returned from both <tt>Read</tt> and <tt>ReadList</tt>.

The following actions have been added:
* <tt>Move</tt>, which simplifies playlist editing
* <tt>DeleteList</tt>, which simplifies bulk deletion (e.g. an entire album).

The <tt>IdArray</tt> property now has string type and contains a JSON integer array.

The <tt>SeekId</tt> and <tt>SeekIndex</tt> actions have been removed. Equivalent functionality is available via
 <tt>Transport.PlayAs("playlist", "id=[track_id]")</tt> 
or
 <tt>Transport.PlayAs("playlist", "index=[track_index]")</tt>

The <tt>ProtocolInfo</tt> property / getter has been removed. Control points are recommended to just queue any audio content with a player. Any that still want to check audio capabilities can do so via <tt>AVTransport</tt>.

== Radio ==
The following actions have been removed. Use equivalents in [[Av:Developer:Eriskay:TransportService | Transport]] service instead:
U <tt>Play</tt> / <tt>Pause</tt> / <tt>Stop</tt>
U <tt>SeekSecondsAbsolute</tt> / <tt>SeekSecondsRelative</tt>
U <tt>TransportState</tt>

<tt>Next</tt> / <tt>Prev</tt> are now supported via the [[Av:Developer:Eriskay:TransportService | Transport]] service

<tt>Metadata</tt> (for the current track and from <tt>Read</tt> / <tt>ReadList</tt>) is now in OpenHome Metadata format

The <tt>IdArray</tt> property now has string type and contains a JSON integer array.

The <tt>SetId</tt> and <tt>SetChannel</tt> actions have been removed. Equivalent functionality is available via
 <tt>Transport.PlayAs("radio", "id=[preset_id]")</tt> 
or
 <tt>Transport.PlayAs("single", "{"url": "[track_url]", "metadata": "{track_metadata]"}")</tt>

The <tt>ProtocolInfo</tt> property / getter has been removed. Control points are recommended to just queue any audio content with a player. Any that still want to check audio capabilities can do so via <tt>AVTransport</tt>.

== Receiver ==
The <tt>TransportState</tt> property and getter have been removed. Use equivalents in [[Av:Developer:Eriskay:TransportService | Transport]] service instead.

The <tt>ProtocolInfo</tt> property / getter is now a space-separated list of protocols.

The <tt>SetSender</tt> action has been removed. Equivalent functionality is available via
 <tt>Transport.PlayAs("receiver", "{"url": "[sender_url]", "metadata": "[openhome_sender_metadata]"}")</tt>

== Exakt ==
Service has been moved to the <tt>linn.co.uk</tt> domain.

There are no guarantees about compatibility so use by third parties is not encouraged.

== NetworkMonitor ==
Service has been moved to the <tt>linn.co.uk</tt> domain.

There are no guarantees about compatibility so use by third parties is not encouraged.

== PlaylistManager ==
Service has been withdrawn.

There is no support for shared playlists in Eriskay media servers.

Equivalent functionality may be supported by a cloud service in future.

Av:Developer:Eriskay:StreamingServices

2015-12-15T14:47:25Z

Simonc: Created page with "= Streaming Services = == TIDAL == Tidal's API is private. See Tidal for access to it. Or speak to us for help if you think that your access to the API would benefit OpenHome. ..."

= Streaming Services =

== TIDAL ==
Tidal's API is private. See Tidal for access to it. Or speak to us for help if you think that your access to the API would benefit OpenHome.

Assuming access to Tidal's API, the [[Av:Developer:Eriskay:CredentialsService | Credentials]] service can be used to retrieve the following information:
* The <tt>Ids</tt> property variable includes <tt>tidalhifi.com</tt> if Tidal is supported.
* <tt>Data</tt> from <tt>Get</tt> is JSON and contains at least the following fields:
<tt>
{
"country_code": "Tidal country code",
"user_id": "Tidal user identifier"
.....
}
</tt>
* <tt>Status</tt> from <tt>Get</tt> is blank if <tt>Username</tt> and <tt>Password</tt> are both either blank or set and valid. If <tt>Status</tt> is not blank, it contains either JSON returned from a Tidal API or an error string.
* The token returned from <tt>Login</tt> and <tt>Relogin</tt> is JSON and contains at least the following fields:
<tt>
{
"session_id": "Tidal session id"
.....
}
</tt>
* Tracks can be added to the [[Av:Developer:Eriskay:PlaylistService | Playlist]] service with urls in the form
<tt>
tidal://track?version=1&trackId=[tidal_track_id]
</tt>

== Qobuz ==
Qobuz's [https://github.com/Qobuz/api-documentation developer API] is published on github.

The [[Av:Developer:Eriskay:CredentialsService | Credentials]] service can be used to retrieve the following information:

* The <tt>Ids</tt> state variable includes <tt>qobuz.com</tt> if Qobuz is supported.
* <tt>Data</tt> from <tt>Get</tt> is JSON and contains at least the following fields:
<tt>
{
"app_id": "qobuz app id"
.....
}
</tt>
* <tt>Status</tt> from <tt>Get</tt> is blank if <tt>Username</tt> and <tt>Password</tt> are both either blank or set and valid. If <tt>Status</tt> is not blank, it contains either JSON returned from a Qobuz API or an error string.
* The token returned from <tt>Login</tt> and <tt>Relogin</tt> is JSON and contains at least the <tt>user_auth_token</tt> required by some Qobuz calls.
<tt>
{
"user_auth_token": "[token from qobuz]"
.....
}
</tt>

Some Qobuz APIs require an <tt>app_secret</tt> argument. These APIs should not need to be called from control points. Qobuz's standard development agreement prohibits this being shared between device and control point.

Tracks can be added to the [[Av:Developer:Eriskay:PlaylistService | Playlist]] service with urls in the form
<tt>
qobuz://track?version=2&trackId=[qobuz_track_id]
</tt>

Av:Developer:Eriskay:TransportPlayAsCommands

2015-12-15T14:44:39Z

Simonc: Created page with "= Transport PlayAs Options = The Transport service’s <tt>PlayAs</tt> action takes arguments for <tt>mode</tt> (source or group of re..."

= Transport PlayAs Options =
The [[Av:Developer:Eriskay:TransportService | Transport]] service’s <tt>PlayAs</tt> action takes arguments for <tt>mode</tt> (source or group of related sources) and a mode-specific <tt>command</tt>. Some standard modes and commands are listed below; other manufacturer-specific options are possible.

=== Playlist ===
The <tt>"playlist"</tt> mode supports the following commands:
* <tt>id=[track_id]</tt> - Halt playback of any current track and switch to the track with the specified id. Returns a <tt>800</tt> fault code if <tt>[track_id]</tt> is not valid.
* <tt>index=[playlist_index]</tt> - Halt playback of the current track and switch to the track with the specified index. Returns a <tt>802</tt> fault code if the index is beyond the end of the playlist.

=== Radio ===
The <tt>"radio"</tt> mode supports the following command:
* <tt>id=[preset_id]</tt> – Start playing the specified preset. Returns a <tt>800</tt> fault code if <tt>[preset_id]</tt> does not match a current preset

=== Receiver ===
The <tt>"receiver"</tt> mode supports the following command:
<tt>
{
"url": "[sender_url]",
"metadata": "[openhome_sender_metadata]"
}
</tt>
and will start playing the same content as the device that either hosts the <tt>ohu</tt> or <tt>ohm</tt> sender or matches the zone in the <tt>ohz</tt> url.

=== Single ===
The <tt>"single"</tt> mode supports the following command
<tt>
{
"url": "[track_url]",
"metadata": "[openhome_metadata]"
}
</tt>
and will start playing <tt>[track_url]</tt>, reporting the specified metadata. When the track completes, it will be queued again then <tt>TransportState</tt> will change to <tt>Stopped</tt>.

=== External ===
The <tt>"external"</tt> mode supports the following command:
* <tt>[system_name]</tt> – activate the source with whose system name matches <tt>[system_name]</tt> and start playing.

=== UpnpAv ===
The <tt>"upnpav"</tt> mode supports the following command:
* <tt>[blank]</tt> – Start playing the last uri set via <tt>AVTransport.SetAVTransportUri</tt>. Activates the source but leaves transport state as <tt>STOPPED</tt> if no uri is set.

Av:Developer:Eriskay:DeviceService

2015-12-15T14:42:02Z

Simonc: Created page with "= Device Service = == Overview == The Device service serves as the starting point for retrieving information about an OpenHome device and resolving questions of compatibility bet..."

= Device Service =
== Overview ==
The Device service serves as the starting point for retrieving information about an OpenHome device and resolving questions of compatibility between that device and an OpenHome control point.

Before consuming further services, an OpenHome control point MUST engage with the Device service in order to establish whether the device is compatible with the OpenHome client software with which the control point was built.

An OpenHome control point SHOULD indicate to the user the presence of any incompatible device on the network but MUST NOT engage with the device beyond this requirement.

In this situation the device can be identified to the user using the version-independent information provided by the Device service: primarily the name and manufacturer information.

In addition to describing standard OpenHome capabilities, the Device service can be used to publish the presence of vendor-specific enhancements using the version-specific attributes property.

The Device service may also be used to publish the availability of both standard and vendor-specific web applications using the webapps property.

Further free-form vendor-specific information can be included in the JSON document using the extensions property.

The Device publishes read-only information about an OpenHome device using its Description property, which is in JSON format and has the following JSON-Schema.
<tt>
{
"title": "OpenHome Device Description",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": "string"
},
"id": {
"type": "string"
},
"manufacturer" : {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"info": {
"type": "string"
},
"url": {
"type": "string"
},
"image": {
"type": "string"
}
},
"required": ["name"]
},
"model" : {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"info": {
"type": "string"
},
"url": {
"type": "string"
},
"image": {
"type": "string"
}
},
"required": ["name"]
},
"webapps" : {
"type": "array",
"items": {
"type": "object",
"properties": {
"id" : {
"type": "string",
},
"url": {
"type": "string",
}
},
"required": ["id", "url"]
},
"minItems": 1,
"uniqueItems": true
},
"versions" : {
"type": "array",
"items": {
"type": "object",
"properties": {
"version" : {
"type": "integer",
"minimum" : 5
},
"attributes": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"required": ["version"]
},
"minItems": 1,
"uniqueItems": true
},
"extensions" : {
}
},
"required": [
"name",
"domain",
"id",
"manufacturer",
"model",
"versions"
],
"additionalProperties": false
}
</tt>

=== Examples ===
A typical device supporting Eriskay (OpenHome Version 5)
<tt>
{
"name": "Kitchen:Sneaky DS",
"domain": "linn.co.uk",
"id": "1203431",
"manufacturer" : {
"name": "Linn",
"info": "just listen"
"url": "http://www.linn.co.uk",
"image": "/images/logo.png"
},
"model" : {
"name": "Sneaky DS",
"url": "http://www.linn.co.uk//wiki/index.php/sneaky",
"image": "/images/icon.png"
},
"webapps": [
{
"id": "openhome.org.presentation",
"url": "/index.html"
},
{
"id": "openhome.org.configuration",
"url": "/Config/Layouts/Default/index.html?service=Ds"
},
{
"id": "openhome.org.control",
"url": "Control/Layouts/Default/index.html?service=Ds"
}
],
"versions": [
{
"version": 5
}
],
"extensions": {
"bsp": "magma",
"mac": "00:26:0f:21:82:e9",
"software": "4.25.1134",
"boards" : [
{
"pcb": 723,
"type": "PCAS723L2R3",
"id": "070000041bdec314",
"description": ""
}
]
}
}
</tt>

A device that supports Eriskay (OpenHome Version 5) and Fetlar (OpenHome Version 6). The device implements the Linn Exakt extension in Version 5 and 6, and the Linn Exakt v2 extension in version 6.
<tt>
{
"name": "Bedroom:Akurate DSM",
"domain": "linn.co.uk",
"id": "1286201",
"manufacturer" : {
"name": "Linn",
"url": "http://www.linn.co.uk",
"image": "/images/logo.png"
},
"model" : {
"name": "Akurate DSM",
"url": "http://www.linn.co.uk//wiki/index.php/akurate-dsm",
"image": "/images/icon.png"
},
"webapps": [
{
"id": "openhome.org.presentation",
"url": "/index.html"
},
{
"id": "openhome.org.configuration",
"url": "/Config/Layouts/Default/index.html?service=Ds"
},
{
"id": "openhome.org.control",
"url": "/Control/Layouts/Default/index.html?service=Ds"
}
],
"versions": [
{
"version": 5,
"attributes": [
"openhome.org.topology",
"linn.co.uk.exakt"
]
},
{
"version": 6,
"attributes": [
"openhome.org.topology",
"linn.co.uk.exakt",
"linn.co.uk.exakt2"
]
}
],
"extensions": {
"bsp": "magma",
"mac": "00:26:0f:21:b1:18",
"software": "4.24.1066",
"boards" : [
{
"pcb": 797,
"type": "PCAS797L1R1",
"id": "db000004d775f014",
"description": "2011 variant"
},
{
"pcb": 802,
"type": "PCAS802L3R1",
"id": "9f00000505929814",
"description": ""
},
{
"pcb": 611,
"type": "PCAS611L1R2",
"id": "45000004d7a73414",
"description": "Moving Coil"
},
{
"pcb": 799,
"type": "PCAS799L2R1",
"id": "5f000004d7757214",
"description": ""
}
]
}
}
</tt>

=== Difference Between Device Service Attributes and Product Service Attributes ===
Those attributes that are necessary for the operation of OpenHome Topology remain in the Product service. These include <tt>Info</tt>, <tt>Time</tt>, <tt>Volume</tt>, <tt>Credentials</tt>, and <tt>Sender</tt>.

The <tt>Exakt</tt> attribute is now more sensibly expressed in the Device service. And the functionality of the <tt>App:Config</tt> attribute is now delivered, not as an attribute, but using the <tt>webapps</tt> property of the Device service.

== Evented Properties ==
=== Description ===
A device description in the format outlined above.
 Does not change at run-time.

== Actions ==
=== Description ===
Read the value of the <tt>Description</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Device"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Description</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:ReceiverService

2015-12-15T13:28:49Z

Simonc: Created page with "= Receiver Service = == Overview == A Songcast receiver plays audio broadcast from a sender. The Receiver service provides the means for..."

= Receiver Service =
== Overview ==
A Songcast receiver plays audio broadcast from a [[Av:Developer:Eriskay:SenderService | sender]]. The Receiver service provides the means for controlling a Receiver source.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports a source of type <tt>Receiver</tt>, then that device is guaranteed to bear the Receiver service. If the Receiver service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== Metadata ===
The metadata of the sender to listen to. In the OpenHome Metadata format provided by the [[Av:Developer:Eriskay:SenderService | Sender]] service.

=== Uri ===
The uri of the [[Av:Developer:Eriskay:SenderService | Sender]] to listen to.

== Actions ==
== Sender ==
<tt>
Arguments: (out string uri, out string metadata)
</tt> 
Report the values of the <tt>Uri</tt> and <tt>Metadata</tt> properties.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Receiver"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="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>Sender</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>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Uri</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:RadioService

2015-12-15T13:25:01Z

Simonc: Created page with "= Radio Service = == Overview == The Radio service offers a means for controlling radio presets. If a device's Product service reports ..."

= Radio Service =
== Overview ==
The Radio service offers a means for controlling radio presets.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports a source of type <tt>"Radio"</tt>, then that device is guaranteed to also bear the Radio service. If the Radio service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== ChannelsMax ===
The maximum number of presets (and so the number of elements in <tt>IdArray</tt>). Does not vary at run-time.

=== Id ===
The id of the currently selected preset. Or <tt>0</tt> if no preset has ever been selected.

=== IdArray ===
A JSON integer array containing preset ids. Will always have <tt>ChannelsMax</tt> elements. A value of <tt>0</tt> implies that no preset is set for that slot.

=== Metadata ===
Metadata for the last preset to be selected.

=== Uri ===
Uri for the last preset to be selected.

== Actions ==
=== Channel ===
<tt>
Arguments: (out string uri, out string metadata)
</tt> 
Return the values of the <tt>Uri</tt> and <tt>Metadata</tt> properties.

=== ChannelsMax ===
<tt>
Arguments: (out uint max)
</tt> 
Return the value of the <tt>ChannelsMax</tt> property.

=== Id ===
<tt>
Arguments: (out uint id)
</tt> 
Return the value of the <tt>Id</tt> property.

=== IdArray ===
<tt>
Arguments: (out uint token, out string idArray)
</tt> 
Return the value of the <tt>IdArray</tt> property.

=== IdArrayChanged ===
<tt>
Arguments: (in uint token, out bool changed)
</tt> 
Check to see if the <tt>IdArray</tt> state variable has changed since gathering the specified <tt>IdArrayToken</tt>. This Token must have been previously collected from the <tt>IdArray</tt> action. This action is provided specifically for clients which cannot consume standard evented updates of properties.

=== Read ===
<tt>
Arguments: (in uint id, out string metadata)
</tt> 
Given a channel preset id, return its associated metadata. The metadata will be of the form
<tt>
{
"Title": "[title]"
"Origin": "[id of origin of metadata]"
"Uri": "[preset uri]"
"Artwork": "[image url]"
}
</tt>
The elements listed above are guaranteed to be present; additional elements may also be included.

=== ReadList ===
<tt>
Arguments: (in string ids, out string json)
</tt> 
Given a space separated list of channel preset ids, return their associated metadata. The metadata will be of the form
<tt>
{
"channels": [
{
"id": [preset_id_1],
"metadata": {
"Title": "[title]"
"Origin": "[id of origin of metadata]"
"Uri": "[preset uri]"
"Artwork": "[image url]"
}
},
{
"id": [preset_id_1],
"metadata": {
"Title": "[title]"
"Origin": "[id of origin of metadata]"
"Uri": "[preset uri]"
"Artwork": "[image url]"
}
},
........
]
}
</tt>

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Radio"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="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>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>Id</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Id</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>
</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>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ChannelsMax</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>
</syntaxhighlight>

Av:Developer:Eriskay:PlaylistService

2015-12-15T13:22:59Z

Simonc: Created page with "= Playlist Service = == Overview == The Playlist service provides access to a list of tracks, which can be played in sequence, starting at any point. ‘Shuffle’ and ‘Repeat..."

= Playlist Service =

== Overview ==
The Playlist service provides access to a list of tracks, which can be played in sequence, starting at any point. ‘Shuffle’ and ‘Repeat’ modes also exist, allowing track order to be randomised and playback to loop.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports a source of type <tt>"Playlist"</tt>, then that device is guaranteed to bear the Playlist service. If the Playlist service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== Repeat ===
By default a playlist plays each track in sequence then stops after playing the final track. Setting the <tt>Repeat</tt> property changes this behaviour to loop from the last track back to the first, playing it immediately.

By default, <tt>Repeat</tt> is off.

=== Shuffle ===
Tracks are played in random order if the <tt>Shuffle</tt> property is enabled. As with normal playback, each track is played once then the playlist stops. If <tt>Shuffle</tt> is enabled mid-way through a playlist, each track in the list is shuffled, including any that have just been played.

When combined with <tt>Repeat</tt>, each track is played once before any track is played for a second time.

By default, <tt>Shuffle</tt> is off.

=== Id ===
The id of the current track (the track currently playing or that would be played if the <tt>Transport.Play</tt> action was invoked while this source was active). Or <tt>0</tt> if the playlist is empty.

=== IdArray ===
A JSON integer array containing the ids of the tracks currently in the playlist.

For example, <tt>[2, 276, 19]</tt> describes a playlist containing track ids 2, 276, and 19 in that order.

Contains <tt>[0..TracksMax]</tt> elements.

=== TracksMax ===
The maximum number of tracks a playlist can contain. Set on startup and invariant thereafter.

== Actions ==
=== SetRepeat ===
<tt>
Arguments: (in bool repeat)
</tt> 
Enable or disable repeat mode.

=== Repeat ===
<tt>
Arguments: (out bool repeat)
</tt> 
Report whether repeat mode is enabled.

=== SetShuffle ===
<tt>
Arguments: (out bool shuffle)
</tt> 
Enable or disable shuffle mode.

=== Shuffle ===
<tt>
Arguments: (in bool shuffle)
</tt> 
Report whether shuffle mode is enabled.

=== Id ===
<tt>
Arguments: (out uint id)
</tt> 
Return the value of the <tt>Id</tt> state variable.

=== ReadList ===
<tt>
Arguments: (in string ids, out string json)
</tt> 
Given a space separated list of track ids, report their associated uri and metadata in the following JSON form:
<tt>
[
{
"id": integer_id,
"uri": "track_uri",
"metadata": "track_metadata"
},
{
"id": integer_id,
"uri": "track_uri",
"metadata": "track_metadata"
}
]
</tt>
Any ids not in the playlist are ignored.

=== Insert ===
<tt>
Arguments: (in uint afterId, in string uri, in string metadata, out uint newId)
</tt> 
Adds the given uri and metadata as a new track to the playlist.

Set the <tt>AfterId</tt> argument to <tt>0</tt> to insert a track at the start of the playlist.

Reports a <tt>800</tt> fault code if <tt>AfterId</tt> is not <tt>0</tt> and doesn’t appear in the playlist.
 Reports a <tt>801</tt> fault code if the playlist is full (i.e. already contains <tt>TracksMax</tt> tracks).

=== DeleteList ===
<tt>
Arguments: (int string ids)
</tt> 
Given a space separated list of track ids, remove the tracks with these ids from the playlist.

If the id to be deleted is currently playing, the next track becomes current.

Any ids not in the playlist are silently ignored.

=== DeleteAll ===
<tt>
Arguments: None
</tt> 
Delete all tracks from the playlist.

== Move ==
<tt>
Arguments: (in string ids, in uint afterId)
</tt> 
Move a space separated list of ids.

Set <tt>AfterId</tt> to <tt>0</tt> to move the tracks to the start of the playlist.

Any ids not in the playlist are silently ignored.

<tt>AfterId</tt> must not also be in the list to be moved.

=== TracksMax ===
<tt>
Arguments: (out uint max)
</tt> 
Return the value of the <tt>TracksMax</tt> property.

=== IdArray ===
<tt>
Arguments: (out uint token, out string json)
</tt> 
Return the value of the <tt>IdArray</tt> property. Supports polling implementations by returning a token which can be used with the <tt>IdArrayChanged</tt> action.

=== IdArrayChanged ===
<tt>
Arguments: (in uint token, out bool changed)
</tt> 
Check to see if <tt>IdArray</tt> has changed since gathering the specified token. This token must have been previously collected from the <tt>IdArray</tt> action.

This mechanism is provided specifically for any basic control points unable to partake in standard eventing.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Playlist"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>SetRepeat</name>
<argumentList>
<argument>
<name>Repeat</name>
<direction>in</direction>
<relatedStateVariable>Repeat</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Repeat</name>
<argumentList>
<argument>
<name>Repeat</name>
<direction>out</direction>
<relatedStateVariable>Repeat</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetShuffle</name>
<argumentList>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>Shuffle</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Shuffle</name>
<argumentList>
<argument>
<name>Shuffle</name>
<direction>out</direction>
<relatedStateVariable>Shuffle</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Id</name>
<argumentList>
<argument>
<name>Id</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>Uri</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>in</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Move</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>TracksMax</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</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>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Repeat</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Shuffle</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Uri</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:ConfigurationService

2015-12-15T13:18:03Z

Simonc: Created page with "= Configuration Service = == Overview == The Configuration service provides access to all user-configurable values on a product. It is intended as a developer aid only - configu..."

= Configuration Service =
== Overview ==
The Configuration service provides access to all user-configurable values on a product. It is intended as a developer aid only - configuration UIs should use the web app framework instead.

If a device's [[Av:Developer:Eriskay:DeviceService | Device]] service to reports the attribute <tt>openhome.org.configuration</tt> in its <tt>version</tt> section, that device is guaranteed to bear the Configuration service. If the Configuration service is available, all its properties and actions must be fully implemented.

== Actions ==
=== GetKeys ===
<tt>
Arguments: (out string keys)
</tt> 
Read a JSON list of all configuration items for the product.

=== SetValue ===
<tt>
Arguments: (in string key, in string value)
</tt> 
Update the value of a configuration item.

Returns a <tt>800</tt> fault code if the specified key does not match a configuration item.
 Returns a <tt>801</tt> fault code if the configuration item has integer type but the specified value is not a number.
 Returns a <tt>802</tt> fault code if the configuration item has integer type but the specified value is outside the permitted range.
 Returns a <tt>803</tt> fault code if the configuration item has a list of allowed values and the specified value is not in this allowed list.
 Returns a <tt>804</tt> fault code if the specified value is longer than the maximum storage available for the configuration item.

=== GetValue ===
<tt>
Arguments: (in string key, out string value)
</tt> 
Read the value of a configuration item.
 The return value is always text; the caller is responsible for converting this to an integer if necessary.

Returns a <tt>800</tt> fault code if the specified key does not match a configuration item.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Configuration"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>GetKeys</name>
<argumentList>
<argument>
<name>KeyList</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetValue</name>
<argumentList>
<argument>
<name>Key</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetValue</name>
<argumentList>
<argument>
<name>Key</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:SenderService

2015-12-15T13:15:44Z

Simonc: Created page with "= Sender Service = == Overview == The Sender service indicates the presence of a Songcast sender and provides information concerning that sender. A Songcast sender broadcasts mu..."

= Sender Service =
== Overview ==
The Sender service indicates the presence of a Songcast sender and provides information concerning that sender.

A Songcast sender broadcasts music on a network in a way that is playable by a Songcast [[Av:Developer:Eriskay:ReceiverService | receiver]].

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Sender"</tt>, then that device is guaranteed to bear the Sender service. Alternatively, Songcast senders can be discovered independently of the Product service by checking for the <tt>openhome.org.sender</tt> attribute on the [[Av:Developer:Eriskay:DeviceService | Device]] service.

If the Sender service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== Audio ===
<tt>true</tt> if audio is currently available from this Sender; <tt>false</tt> otherwise.

=== Metadata ===
Provides basic information about the sender in OpenHome Metadata format.
<tt>
{
"Title" : "[sender name]",
"Origin" : "openhome.org.sender",
"Uri" : "[ohz uri. ohu/ohm if ohz is not supported]",
"Artwork" : "[uri to icon for sender]",
"Channel" : "Songcast"
}
</tt>

=== Status ===
Reports the status of the sender:
* <tt>Enabled</tt> - sender enabled by user configuration (default)
* <tt>Disabled</tt> - sender disabled by user configuration
* <tt>Blocked</tt> - audio from another sender detected on the same channel (mis-configuration)

== Actions ==
=== Audio ===
<tt>
Arguments: (out bool audio)
</tt> 
Return the value of the <tt>Audio</tt> property.

=== Metadata ===
<tt>
Arguments: (out string metadata)
</tt> 
Return the value of the <tt>Metadata</tt> property.

=== Status ===
<tt>
Arguments: (out string status)
</tt> 
Return the value of the <tt>Status</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Sender"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="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>Audio</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Audio</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Metadata</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Status</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Status</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Audio</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Status</name>
<dataType>string</dataType>
<allowedValueList>
<allowedValue>Enabled</allowedValue>
<allowedValue>Disabled</allowedValue>
<allowedValue>Blocked</allowedValue>
</allowedValueList>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:CredentialsService

2015-12-15T13:09:24Z

Simonc: Created page with "= Credentials Service = == Overview == The Credentials service provides access to username, password and current status of all remote services that require unique logins. If a d..."

= Credentials Service =
== Overview ==
The Credentials service provides access to username, password and current status of all remote services that require unique logins.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Credentials"</tt>, then that device is guaranteed to bear the Credentials service. If the Credentials service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== Ids ===
Space separated list of identifiers for services whose credentials can be set.
 Set on startup; does not change at runtime.

=== PublicKey ===
RSA public key that must be used to encrypt any/all passwords.

When encrypting ensure PKCS1 OAEP padding is used.

May be blank on startup; will not vary once set. With the exception of the <tt>Ids</tt> state variable, the rest of the service cannot usefully be used before this is set.

=== SequenceNumber ===
Increases whenever any aspect of state for any user of credentials listed in <tt>Ids</tt> changes. The client is responsible for polling each Id they are interested in to determine what has changed.

== Actions ==
=== Set ===
<tt>
Arguments: (in string id, in string username, in string password)
</tt> 
Set the username and password for a given service. The password must be encrypted using the RSA public key in the <tt>PublicKey</tt> state variable.
 Calling this action automatically enables the service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== Clear ===
<tt>
Arguments: (in string id)
</tt> 
Remove both username and password for a given service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== SetEnabled ===
<tt>
Arguments: (in string id, in bool enabled
</tt> 
Set or clear the <tt>Enabled</tt> state of a service. Disabling a service temporarily prevents its use by a device but allows the device to retain the username/password for later use (if the service is re-enabled by calling <tt>SetEnabled()</tt> again).

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== Get ===
<tt>
Arguments: (in string id, out string username, out string encPassword, out bool enabled, out string status, out string data)
</tt> 
Retrieve username, password, status and enabled state for a service.

Username, password and enabled will only change in response to invocations of the Credentials service. The password is encrypted so is not suitable for user display. Clients can infer whether a password has been set by checking whether the value returned has non-zero length.

Status may change in response to runtime events. e.g. If an account expires, the status may change to include the error returned by the remote service provider. Status is only set for error cases - a blank status indicates that a service is functioning correctly. The exact format of status content varies between services.

Data contains any other service-specific information. The format of content varies between services.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== Login ===
<tt>
Arguments: (in string id, out string token)
</tt> 
Read a token indicating that a registered user has logged in to a remote service. This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account. The data returned may vary between credential-consuming services; the control point is responsible for knowing how to interpret it.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.
 Returns a <tt>801</tt> fault code if the login was attempted but failed.

=== Relogin ===
<tt>
Arguments: (in string id, in string currentToken, out string newToken)
</tt> 
Refresh an existing token returned from <tt>Login()</tt>. This should only be called after the remote service has indicated that the current token has expired and is no longer valid.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.
 Returns a <tt>801</tt> fault code if a new login was attempted but failed.

=== GetIds ===
<tt>
Arguments: (out string ids)
</tt> 
Read the value of the <tt>Ids</tt> property.

=== GetPublicKey ===
<tt>
Arguments: (out string key)
</tt> 
Read the value of the <tt>PublicKey</tt> property.

=== GetSequenceNumber ===
<tt>
Arguments: (out uint seq)
</tt> 
Read the value of the <tt>SequenceNumber</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Credentials"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Set</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Clear</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetEnabled</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Get</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
<argument>
<name>Status</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Data</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Login</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Relogin</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>CurrentToken</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>NewToken</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetIds</name>
<argumentList>
<argument>
<name>Ids</name>
<direction>out</direction>
<relatedStateVariable>Ids</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetPublicKey</name>
<argumentList>
<argument>
<name>PublicKey</name>
<direction>out</direction>
<relatedStateVariable>PublicKey</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetSequenceNumber</name>
<argumentList>
<argument>
<name>SequenceNumber</name>
<direction>out</direction>
<relatedStateVariable>SequenceNumber</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Ids</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PublicKey</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SequenceNumber</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Binary</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Bool</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:VolumeService

2015-12-15T13:00:03Z

Simonc: Created page with "= Volume Service = == Overview == The Volume service provides a means of controlling various settings which affect the product's volume (signal amplitude) measured at the output ..."

= Volume Service =
== Overview ==
The Volume service provides a means of controlling various settings which affect the product's volume (signal amplitude) measured at the output channels. A product may have one or more output channels. Balance or Fade settings may result in different volumes at each output. In the Mute state, all output channels are reduced to zero volume.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Volume"</tt>, then that device is guaranteed to bear the Volume service. If the Volume service is available, all its properties and actions must be fully implemented.

<tt>Volume</tt> is an adjustable setting that controls the loudness of the audio at the output channels of the product. It can be set to an absolute value or incremented/decremented in single steps of integrator-defined size. The maximum <tt>Volume</tt> setting is defined by the current value of <tt>VolumeLimit</tt>. The minimum Volume setting is always zero.

<tt>Balance</tt> is an adjustable setting that specifies the bias in volume between left and right output channels. A setting of zero results in neutral balance (i.e. no bias applied) between left and right output channels. Negative values amplify left and attenuate right output channels. Conversely, positive values attenuate left and amplify right output channels. Increasing absolute values result in progressively larger amplification/attenuation being applied to output channels in this asymmetric manner. At or near the maximum settings, the attenuated channels may ended up being effectively reduced to volume zero.

<tt>Fade</tt> is an adjustable setting that specifies the bias in volume between the front and rear output channels.

== Evented Properties ==
=== Volume ===
The current user volume setting, i.e. an integer value in the range <tt>[0..VolumeLimit]</tt>.

=== Mute ===
A boolean setting indicating whether all output channels are currently forced to zero volume.

Note that (un)muting a product has no effect on its <tt>TransportState</tt> or it's ability to send audio to other rooms.

=== VolumeLimit ===
User-imposed (soft) maximum volume setting. Must be in the range <tt>[0..VolumeMax]</tt>; other values will be ignored.

=== VolumeMax ===
System-imposed (hard) maximum volume setting. Must be exactly divisible by <tt>VolumeSteps</tt>.

=== VolumeUnity ===
System-specific volume setting that results in the input signal amplitude equalling the output signal amplitude (0dB gain), i.e. an integer in the range <tt>[0..VolumeMax]</tt>.

Values in the range <tt>[0..VolumeUnity)</tt> will be attenuated. Values in the range <tt>(VolumeUnity..VolumeLimit]</tt> will be amplified.

=== VolumeSteps ===
System-specific number of user-visible volume steps that would increase the volume from zero to <tt>VolumeMax</tt>.

=== UnityGain ===
<tt>true</tt> if the active source as reported by the ["ProductServiceEriskay" Product] service is already volume controlled; <tt>false</tt> otherwise.

Changes to <tt>Volume</tt> will be accepted while <tt>UnityGain</tt> is enabled but will have no immediate effect.

=== Balance ===
Current setting of bias between left and right output channels, i.e. an integer value in the range <tt>[-BalanceMax..+BalanceMax]</tt>.

Negative values amplify left and attenuate right output channels. Conversely, positive values attenuate left and amplify right output channels.

A value of zero specifies no bias.

=== BalanceMax ===
System-specific balance value for maximum bias between left and right channels.

=== Fade ===
Current setting of bias between front and back output channels, i.e. an integer value in the range <tt>[-FadeMax..+FadeMax]</tt>.

A value of zero specifies no bias.

=== FadeMax ===
System-specific fade value for maximum bias between front and rear between channels.

== Actions ==
=== Characteristics ===
<tt>
Arguments: (out uint volMax, out uint volUnity, out uint volSteps, out uint balanceMax, out uint fadeMax)
</tt> 
Return the values of the system-specified properties which do not change at run-time - <tt>VolumeMax</tt>, <tt>VolumeUnity</tt>, <tt>VolumeSteps</tt>, <tt>BalanceMax</tt> and <tt>FadeMax</tt>.

=== Volume ===
<tt>
Arguments: (out uint volume)
</tt> 
Return the current value of the <tt>Volume</tt> property.

=== SetVolume ===
<tt>
Arguments: (in uint volume)
</tt> 
Set the <tt>Volume</tt> property to an absolute value.

Any attempt to set a value above the <tt>VolumeLimit</tt> must reset <tt>Volume</tt> to <tt>VolumeLimit</tt>.

=== VolumeInc ===
<tt>
Arguments: None
</tt> 
Increase <tt>Volume</tt> by <tt>VolumeMax / VolumeSteps</tt>.

=== Volume Dec ===
<tt>
Arguments: None
</tt> 
Decrease <tt>Volume</tt> by <tt>VolumeMax / VolumeSteps</tt>.

=== VolumeLimit ===
<tt>
Arguments: (out uint limit)
</tt> 
Return the value of the <tt>VolumeLimit</tt> property.

=== UnityGain ===
<tt>
Arguments: (out uint unityGain)
</tt> 
Return the value of the <tt>UnityGain</tt> property.

=== Balance ===
<tt>
Arguments: (out int balance)
</tt> 
Return the value of the <tt>Balance</tt> property.

=== SetBalance ===
<tt>
Arguments: (in int balance)
</tt> 
Set the <tt>Balance</tt> property to an absolute value.

=== BalanceInc===
<tt>
Arguments: None
</tt> 
Increase <tt>Balance</tt> by <tt>1</tt>.

=== BalanceDec ===
<tt>
Arguments: None
</tt> 
Decrease <tt>Balance</tt> by <tt>1</tt>.

=== Fade ===
<tt>
Arguments: (out int fade)
</tt> 
Return the value of the <tt>Fade</tt> property.

=== SetFade ===
<tt>
Arguments: (in int fade)
</tt> 
Set the <tt>Fade</tt> property to an absolute value.

=== FadeInc ===
<tt>
Arguments: None
</tt> 
Increase <tt>Fade</tt> by <tt>1</tt>.

=== FadeDec ===
<tt>
Arguments: None
</tt> 
Decrease <tt>Fade</tt> by <tt>1</tt>.

=== Mute ===
<tt>
Arguments: (out bool mute)
</tt> 
Return the value of the <tt>Mute</tt> property.

=== SetMute(in bool mute) ===
<tt>
Arguments: (in bool mute)
</tt> 
Set the <tt>Mute</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Volume"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Characteristics</name>
<argumentList>
<argument>
<name>VolumeMax</name>
<direction>out</direction>
<relatedStateVariable>VolumeMax</relatedStateVariable>
</argument>
<argument>
<name>VolumeUnity</name>
<direction>out</direction>
<relatedStateVariable>VolumeUnity</relatedStateVariable>
</argument>
<argument>
<name>VolumeSteps</name>
<direction>out</direction>
<relatedStateVariable>VolumeSteps</relatedStateVariable>
</argument>
<argument>
<name>BalanceMax</name>
<direction>out</direction>
<relatedStateVariable>BalanceMax</relatedStateVariable>
</argument>
<argument>
<name>FadeMax</name>
<direction>out</direction>
<relatedStateVariable>FadeMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetVolume</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Volume</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>VolumeInc</name>
</action>
<action>
<name>VolumeDec</name>
</action>
<action>
<name>Volume</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Volume</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetBalance</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Balance</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>BalanceInc</name>
</action>
<action>
<name>BalanceDec</name>
</action>
<action>
<name>Balance</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Balance</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetFade</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Fade</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>FadeInc</name>
</action>
<action>
<name>FadeDec</name>
</action>
<action>
<name>Fade</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Fade</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetMute</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Mute</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Mute</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Mute</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>VolumeLimit</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>VolumeLimit</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>UnityGain</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>UnityGain</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Volume</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Mute</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Balance</name>
<dataType>i4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Fade</name>
<dataType>i4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeLimit</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeUnity</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeSteps</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>UnityGain</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>BalanceMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>FadeMax</name>
<dataType>ui4</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:TimeService

2015-12-15T12:15:50Z

Simonc: Created page with "= Time Service = == Overview == The Time service reports the duration of the currently playing track and the number of seconds played so far. It also maintains a count of the to..."

= Time Service =
== Overview ==
The Time service reports the duration of the currently playing track and the number of seconds played so far. It also maintains a count of the total number of tracks played.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Time"</tt>, then that device is guaranteed to bear the Time service.

This service is intentionally separated from the [[Av:Developer:Eriskay:TransportService | Transport]] service. When a track is being played, <tt>Time</tt> delivers an event every second, which can overwhelm some primitive control points. Keeping <tt>Time</tt> separate from the ["TransportServiceEriskay" Transport] service allows control points to decide whether to subscribe to it independently.

== Evented Properties ==
=== Track Count ===
The number of tracks that have been played, including any currently playing one.

<tt>TrackCount</tt> corresponds with the <tt>TrackCount</tt> property reported by the ["TransportServiceEriskay" Transport] service, but bears no relation to a track or preset <tt>Id</tt> properties reported from the ["PlaylistServiceEriskay" Playlist] or ["RadioServiceEriskay" Radio] services.

=== Duration ===
The total length of the current track in seconds. Zero for live streams.

=== Seconds ===
The total length of time in seconds for which the current track has been playing.

== Actions ==
=== Time ===
Return the values of the <tt>TrackCount</tt>, <tt>Duration</tt> and <tt>Seconds</tt> properties.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Time"
 domain: "openhome.org.eriskay"
 version: "1"</tt>
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Time</name>
<argumentList>
<argument>
<name>TrackCount</name>
<direction>out</direction>
<relatedStateVariable>TrackCount</relatedStateVariable>
</argument>
<argument>
<name>Duration</name>
<direction>out</direction>
<relatedStateVariable>Duration</relatedStateVariable>
</argument>
<argument>
<name>Seconds</name>
<direction>out</direction>
<relatedStateVariable>Seconds</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>TrackCount</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Duration</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Seconds</name>
<dataType>ui4</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:ProductService

2015-12-15T12:10:15Z

Simonc: /* UPnP Service Description */

= Product Service =

== Overview ==
The Product service contains a summary of a single product’s capabilities. After using the [[Av:Developer:Eriskay:DeviceService | Device]] service to confirm both compatibility and the presence of the <tt>openhome.org.product</tt> attribute, control points should begin their interaction with an OpenHome device by using the Product service. Presence of various other services can be inferred from the sources and attributes this reports.

If the Product service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== SourceArray ===
Returns a summary of all sources as a JSON array:
<tt>
[
{
"name": "user name for source"
"type": "type of source"
"visible": "Boolean. Whether control points should display source"
"systemName": "default name for source"
}
]
</tt>
Source <tt>type</tt> may have any implementation-defined value. The following values have a commonly understood meaning:

* <tt>Playlist</tt> - the <tt>openhome.org.eriskay:Playlist:1</tt> service must be available
* <tt>Radio</tt> - the <tt>openhome.org.eriskay:Radio:1</tt> service must be available
* <tt>Receiver</tt> - the <tt>openhome.org.eriskay:Receiver:1</tt> service must be available
* <tt>UpnpAv</tt> - the <tt>upnp.org:MediaRenderer:1</tt> device must be available
* <tt>Single</tt> - software source that plays a single track
* <tt>NetAux</tt> - Specifies 3rd party, non OpenHome controllable, network protocols such as AirPlay
* <tt>Analog</tt> - Specifies an analog external input
* <tt>Digital</tt> - Specifies a digital external input
* <tt>Hdmi</tt> - Specifies a HDMI external input

Other implementation-defined values are possible. Control points that have not been developed to support them should treat such sources as comparable to external inputs.

Each <tt>systemName</tt> is guaranteed to be unique within the array.

=== SourceSystemName ===
The <tt>systemName</tt> of the currently active source.

=== Attributes ===
Space delimited set of values. Each value guarantees the availability of a service or resource, saving a control point from searching for each of these in turn. Supported values for attributes include

* <tt>Transport</tt> – the <tt>openhome.org.eriskay:Transport:1</tt> service must be available
* <tt>Time</tt> – the <tt>openhome.org.eriskay:Time:1</tt> service must be available
* <tt>Volume</tt> – the <tt>openhome.org.eriskay:Volume:1</tt> service must be available
* <tt>Sender</tt> - the <tt>openhome.org.eriskay:Sender:1</tt> service must be available
* <tt>Credentials</tt> - the <tt>openhome.org.eriskay:Credentials:1</tt> service must be available

=== Name ===
User-visible product name. By default this is set to the model name as reported by the Device service.
Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>.

=== Room ===
The name of the room where the Product is located. <tt>Room</tt> is used to group the Product with other related Products in the same physical room (e.g. a source with a pre-amp). Products which are physically linked must always share the same <tt>Room</tt> name.

=== Home ===
User-visible name for a home (a collection of rooms). Reserved for future use.

== Actions ==
=== SourceArray ===
<tt>
Arguments: (out string array)
</tt> 
Return the value of the <tt>SourceArray</tt> property.

=== SourceArrayChangeCount ===
<tt>
Arguments: (out uint count)
</tt> 
Query how often the <tt>SourceArray</tt> property has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, <tt>SourceArray</tt> has been updated so should be queried again.

=== SourceSystemName ===
<tt>
Arguments: (out string systemName)
</tt> 
Return the value of the <tt>SourceSystemName</tt> property.

=== SetSource ===
<tt>
Arguments: (in string systemName)
</tt> 
Set the currently active source to the one with the specified system name.

=== Attributes ===
<tt>
Arguments: (out string attributes)
</tt> 
Return the value of the <tt>Attributes</tt> property.

=== Names ===
<tt>
Arguments: (out string room, out string name, out string home)
</tt> 
Return the values of the <tt>Room</tt>, <tt>Name</tt> and <tt>Home</tt> properties.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Product"
 domain: "openhome.org.eriskay"
 version: "1"</tt>
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Names</name>
<argumentList>
<argument>
<name>Room</name>
<direction>out</direction>
<relatedStateVariable>Room</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Home</name>
<direction>out</direction>
<relatedStateVariable>Home</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SourceArray</name>
<argumentList>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>SourceArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetSource</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>SourceSystemName</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Attributes</name>
<argumentList>
<argument>
<name>Attributes</name>
<direction>out</direction>
<relatedStateVariable>Attributes</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SourceSystemName</name>
<argumentList>
<argument>
<name>SourceSystemName</name>
<direction>out</direction>
<relatedStateVariable>Attributes</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SourceArrayChangeCount</name>
<argumentList>
<argument>
<name>Count</name>
<direction>out</direction>
<relatedStateVariable>SourceArrayChangeCount</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Room</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Home</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SourceSystemName</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SourceArray</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Attributes</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>SourceArrayChangeCount</name>
<dataType>ui4</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:TransportService

2015-12-14T18:05:32Z

Simonc: /* UPnP Service Description */

= Transport Service =
== Overview ==
The Transport service provides both source-independent control of play, pause, stop, skip and seek and information concerning the currently playing media.

Summary information is provided in a number of levels, each of which have a URI and metadata in OpenHome Metadata format. E.g. A (notional) internet radio service that broadcast information about the currently playing track may have a level describing the radio station then another level describing the track. Control points with limited screen estate may choose to display the most derived level(s) of metadata that are available.

In addition to a hierarchy of metadata, detailed information such as bit-rate, sample-rate, bit-depth is available describing what is currently playing.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Transport"</tt>, then that device is guaranteed to bear the Transport service. If the Transport service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== Modes ===
Space separated list of available modes.

=== LevelCount ===
The number of levels of information (uri / metadata) provided by this device. Does not vary at run-time.

=== Mode ===
The currently active mode

=== SequenceNumbers ===
A space-separated list of integers that change when their associated uri and/or metadata are updated. A value of <tt>0</tt> implies that both the associated uri and metadata are empty.

=== StreamCount ===
Changes when each new stream is played.

Indicates a change in one or more stream encoding parameters (<tt>Duration</tt>, <tt>Seekable</tt>, <tt>Pausable</tt>, <tt>BitRate</tt>, <tt>BitDepth</tt>, <tt>SampleRate</tt>, <tt>Lossless</tt>, <tt>CodecName</tt>).

A value of <tt>0</tt> can be assumed to imply empty/<tt>0</tt>/<tt>false</tt> values for all stream-specific data.

=== MetatextCount ===
Changes whenever metatext changes.

=== NextAvailable ===
<tt>true</tt> if the <tt>Next</tt> (skip forwards) action is currently available; <tt>false</tt> otherwise.

This will only change when <tt>Mode</tt> changes. A mode that is sometimes capable of changing stream as a consequence of <tt>Next</tt> will always report <tt>NextAvailable</tt> as <tt>true</tt>.

=== PrevAvailable ===
<tt>true</tt> if the <tt>Prev</tt> (skip backwards) action is currently available; <tt>false</tt> otherwise.

This will only change when <tt>Mode</tt> changes. A mode that is sometimes capable of changing stream as a consequence of <tt>Prev</tt> will always report <tt>PrevAvailable</tt> as <tt>true</tt>.

=== StreamId ===
Integer id, uniquely identifying the current stream.

=== Duration ===
The length of the currently playing stream in seconds.

=== Seekable ===
<tt>true</tt> if the <tt>SeekSecondsAbsolute</tt> and <tt>SeekSecondsRelative</tt> actions are available for the current stream; <tt>false</tt> otherwise.

=== Pausable ===
<tt>true</tt> if the stream can be paused (so is not being played at a rate determined by a remote sender); <tt>false</tt> otherwise.

=== BitRate ===
Dataflow rate in bits per second of the currently playing stream in its encoded representation.

=== BitDepth ===
Sample (data) resolution in bits per channel sample of the currently playing stream.

=== SampleRate ===
Time resolution of samples per second in kHz of the currently playing stream.

=== Lossless ===
Indication of whether the currently playing stream can be decoded (decompressed) to a bit-accurate representation of the original audio data (lossless) or merely to a good approximation (lossy encoding).

=== CodecName ===
Shorthand name for the audio encoding and container format used to represent the currently playing stream (e.g. AAC).

=== Metatext ===
Additional textual information (if any) associated with the currently playing stream.

=== TransportState ===
One of
* <tt>Playing</tt>
* <tt>Paused</tt>
* <tt>Stopped</tt>
* <tt>Buffering</tt>
* <tt>Waiting</tt>

== Actions ==
=== PlayAs ===
<tt>
Arguments: (in string mode, in string command)
</tt> 
Start a new stream playing, specifying both a mode (source) to be used and a mode-specific command which describes the track to be played. Common options for [[Av:Developer:Eriskay:TransportPlayAsCommands | modes and commands]] are documented separately.

=== Play ===
<tt>
Arguments: None
</tt> 
Start a pending stream playing.

A stream must be ready to play. Possibly via calls to another network service.

Behaviour when a stream is already playing varies depending on the active modes (source).

=== Pause ===
<tt>
Arguments: None
</tt> 
Pause the current stream.

Returns a <tt>801</tt> fault code if the current channel does not support being paused (is being played at a rate determined by a remote sender).

=== Stop ===
<tt>
Arguments: None
</tt>
Stop the current stream.

=== Next ===
<tt>
Arguments: (in uint streamId)
</tt> 
Move to the next stream (i.e. skip forwards). Determination of what comes next may vary between sources/modes. If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>801</tt> fault code if the current channel does not support skipping forwards.

=== Prev ===
<tt>
Arguments: (in uint streamId)
</tt> 
Move to the previous stream (i.e. skip backwards). If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>801</tt> fault code if the current channel does not support skipping backwards.

=== SeekSecondsAbsolute ===
<tt>
Arguments: (in uint streamId, in uint secondsAbsolute)
</tt> 
Seek to an absolute position in the current stream. If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>801</tt> fault code if the current stream does not support seek.
[[br]]Returns a <tt>803</tt> fault code if the seek position is beyond the end of the stream.

=== SeekSecondsRelative ===
<tt>
Arguments: (in uint streamId, in int secondsRelative)
</tt> 
Seek to a position relative to what's currently playing in the current stream. If <tt>TransportState</tt> is <tt>Stopped</tt> or <tt>Paused</tt>, try to start playing.

Returns a <tt>801</tt> fault code if the current stream does not support seek.
[[br]]Returns a <tt>803</tt> fault code if the seek position is beyond the end of the stream.

=== TransportState ===
<tt>
Arguments: (out string state)
</tt> 
Read the current value of the TransportState property.

=== Modes ===
<tt>
Arguments: (out string modes)
</tt> 
Return the value of the <tt>Modes</tt> property.

=== Counters ===
<tt>
Arguments: (out string seq, out uint stream, out uint metatext)
</tt> 
Read the values of the sequence numbers associated with each level of information plus the counters for current stream details.

=== ModeInfo ===
<tt>
Arguments: (out string mode, out bool nextAvailable, out bool prevAvailable)
</tt> 
Reports the values of the <tt>Mode</tt>, <tt>NextAvailable</tt> and <tt>PrevAvailable</tt> properties.

=== LevelInfo ===
<tt>
Arguments: (in uint index, out string uri, out string metadata)
</tt> 
Reports uri & metadata for the specified level (a zero-based index into the <tt>SequenceNumbers</tt> array).

=== StreamInfo ===
<tt>
Arguments: 
(out uint streamId, out string uri, out bool seekable, out bool pausable,
out uint durationSecs, out uint bitRate, out uint bitDepth, out uint SampleRate,
out bool lossless, out string codec)
</tt>

Reports current stream information:
* <tt>StreamId</tt>
* <tt>Uri</tt>
* <tt>Seekable</tt>
* <tt>Pausable</tt>
* <tt>Duration</tt>
* <tt>BitRate</tt>
* <tt>BitDepth</tt>
* <tt>SampleRate</tt>
* <tt>Lossless</tt>
* <tt>CodecName</tt>

=== StreamId ===
<tt>
Arguments: (out uint streamId)
</tt> 
Read the current value of the <tt>StreamId</tt> property.

=== Metatext ===
<tt>
Arguments: (out string text)
</tt> 
Read the current value of the <tt>Metatext</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Transport"
 domain: "openhome.org.eriskay"
 version: "1"</tt>
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>

<actionList>
<action>
<name>PlayAs</name>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
<argument>
<name>Command</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
</action>
<action>
<name>Play</name>
</action>
<action>
<name>Pause</name>
</action>
<action>
<name>Stop</name>
</action>
<action>
<name>Next</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>in</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Prev</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>in</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SeekSecondsAbsolute</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>in</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
<argument>
<name>SecondsAbsolute</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SeekSecondsRelative</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>in</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
<argument>
<name>SecondsRelative</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_int</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TransportState</name>
<argumentList>
<argument>
<name>State</name>
<direction>out</direction>
<relatedStateVariable>TransportState</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Modes</name>
<argumentList>
<argument>
<name>Modes</name>
<direction>out</direction>
<relatedStateVariable>Modes</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Counters</name>
<argumentList>
<argument>
<name>SequenceNumbers</name>
<direction>out</direction>
<relatedStateVariable>SequenceNumbers</relatedStateVariable>
</argument>
<argument>
<name>StreamCount</name>
<direction>out</direction>
<relatedStateVariable>StreamCount</relatedStateVariable>
</argument>
<argument>
<name>MetatextCount</name>
<direction>out</direction>
<relatedStateVariable>MetatextCount</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>LevelInfo</name>
<argumentList>
<argument>
<name>Index</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_uint</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ModeInfo</name>
<argumentList>
<argument>
<name>Mode</name>
<direction>out</direction>
<relatedStateVariable>Mode</relatedStateVariable>
</argument>
<argument>
<name>NextAvailable</name>
<direction>out</direction>
<relatedStateVariable>NextAvailable</relatedStateVariable>
</argument>
<argument>
<name>PrevAvailable</name>
<direction>out</direction>
<relatedStateVariable>PrevAvailable</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>StreamInfo</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>out</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
</argument>
<argument>
<name>Seekable</name>
<direction>out</direction>
<relatedStateVariable>Seekable</relatedStateVariable>
</argument>
<argument>
<name>Pausable</name>
<direction>out</direction>
<relatedStateVariable>Pausable</relatedStateVariable>
</argument>
<argument>
<name>Duration</name>
<direction>out</direction>
<relatedStateVariable>Duration</relatedStateVariable>
</argument>
<argument>
<name>BitRate</name>
<direction>out</direction>
<relatedStateVariable>BitRate</relatedStateVariable>
</argument>
<argument>
<name>BitDepth</name>
<direction>out</direction>
<relatedStateVariable>BitDepth</relatedStateVariable>
</argument>
<argument>
<name>SampleRate</name>
<direction>out</direction>
<relatedStateVariable>SampleRate</relatedStateVariable>
</argument>
<argument>
<name>Lossless</name>
<direction>out</direction>
<relatedStateVariable>Lossless</relatedStateVariable>
</argument>
<argument>
<name>CodecName</name>
<direction>out</direction>
<relatedStateVariable>CodecName</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>StreamId</name>
<argumentList>
<argument>
<name>StreamId</name>
<direction>out</direction>
<relatedStateVariable>StreamId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Metatext</name>
<argumentList>
<argument>
<name>Metatext</name>
<direction>out</direction>
<relatedStateVariable>Metatext</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Modes</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>LevelCount</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Mode</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SequenceNumbers</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>StreamCount</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>MetatextCount</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>NextAvailable</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PrevAvailable</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>StreamId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Duration</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Seekable</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Pausable</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>BitRate</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>BitDepth</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SampleRate</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Lossless</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CodecName</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Metatext</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TransportState</name>
<dataType>string</dataType>
<allowedValueList>
<allowedValue>Playing</allowedValue>
<allowedValue>Paused</allowedValue>
<allowedValue>Stopped</allowedValue>
<allowedValue>Buffering</allowedValue>
<allowedValue>Waiting</allowedValue>
</allowedValueList>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_uint</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_int</name>
<dataType>i4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_string</name>
<dataType>string</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:EriskayServices

2015-12-14T17:36:01Z

Simonc: /* Other APIs */

= Eriskay =
This page describes APIs for Eriskay, the second major release of OpenHome network services.

There are a number of [[Av:Developer:Eriskay:DavaarChanges | changes]] from Davaar.

== Services ==
Links to documentation for individual services is below.

The Device service is in the <tt>openhome.org</tt> domain; all other services are in the <tt>openhome.org.eriskay</tt> domain. Provision of the device service is mandatory; all other services are optional. All properties and actions in all services are mandatory; a device that implements a service must fully implement all of its properties and actions.
* [[Av:Developer:Eriskay:DeviceService | Device]]
* [[Av:Developer:Eriskay:TransportService | Transport]]
* [[Av:Developer:Eriskay:ProductService | Product]]
* [[Av:Developer:Eriskay:TimeService | Time]]
* [[Av:Developer:Eriskay:VolumeService | Volume]]
* [[Av:Developer:Eriskay:CredentialsService | Credentials]]
* [[Av:Developer:Eriskay:SenderService | Sender]]
* [[Av:Developer:Eriskay:ConfigurationService | Configuration]]
* [[Av:Developer:Eriskay:PlaylistService | Playlist]]
* [[Av:Developer:Eriskay:RadioService | Radio]]
* [[Av:Developer:Eriskay:ReceiverService | Receiver]]

== Other APIs ==
* [[Av:Developer:Eriskay:TransportPlayAsCommands | PlayAs]] options in [[Av:Developer:Eriskay:TransportService | Transport]] service
* [[Av:Developer:Eriskay:StreamingServices | Streaming Services]]

QobuzStreamingService

2015-03-02T17:16:38Z

Simonc:

Qobuz's [https://github.com/Qobuz/api-documentation developer API] is published on github.

The [[Av:Developer:CredentialsService | Credentials]] service can be used to retrieve the following information:

* The <tt>Ids</tt> state variable includes <tt>qobuz.com</tt> if Qobuz is supported.
* <tt>Data</tt> from <tt>Get</tt> contains the <tt>app_id</tt> used by many Qobuz API calls.
* <tt>Status</tt> from <tt>Get</tt> is blank if Username and Password are both either blank or set and valid. If <tt>Status</tt> is not blank, it contains either json returned from a Qobuz API or an error string.
* The token returned from <tt>Login</tt> and <tt>ReLogin</tt> is a Qobuz <tt>user_auth_token</tt>.

Some Qobuz APIs require an <tt>app_secret</tt> argument. These APIs should not need to be called from control points.

Tracks can be added to the [[Av:Developer:PlaylistService | Playlist]] service with urls in the form <tt>qobuz://track?version=2&trackId=[insert_qobuz_track_id]</tt>

Av:Developer:ohTopologyDescription

2015-02-13T16:51:14Z

Eamonnb: /* Source Naming */

=ohTopology=

== Overview ==
ohTopology is a software stack which provides a means of controlling devices, on a local network, via their UPnP service actions. Devices are grouped based on their Room names and presented as a tree structure based on their interconnectivity. It consists of a number of distinct layers. Each layer focuses on exposing specific properties and actions that are intended to be utilised by the layers above. Clients of ohTopology need only interface directly with the highest layer of the stack to gain access to the properties and actions exposed by the lower layers.

==Watchable System==
===Overview===
Actions exposed by a layer can be called directly, but property values can only be monitored through a callback notification system (observer pattern). Properties are exposed as "watchable" values that may be monitored by "watcher" clients. When a (watchable) property changes, all of its watchers are automatically notified of the change and the property's new value. Watchers can be added and removed at any time. The IWatchable interface is used to expose single value properties and the IWatchableUnordered and IWatchableOrdered interfaces are used for multivalue property lists. Property client objects must conform to the appropriate Iwatchable/IWatchableUnordered/IWatchableOrdered interface for the property that they wish to observe.

===Watchable Thread ===
Although ohTopology is designed to run on multithreaded platforms, actions are executed in a single thread through the use of a thread scheduler class, WatchableThread. Enforcing single threaded execution removes the burden of having to manage thread safety, simplifies debugging and reduces the risk of deadlock. The WatchableThread class provides three methods; Execute, Schedule and Assert.

===Schedule Method===
Schedule provides a mechanism for '''asynchronous callback'''. The specified callback is placed in a queue (FIFO) to be run on the watchable thread, in turn, at some point in the future. Schedule takes a functor, for the callback method, and a generic void* argument to be passed to the callback.

===Execute Method===
Execute provides a mechanism for '''synchronous callback'''. If called from the watchable thread it executes the callback immediately. Otherwise it schedules the callback, for execution on the watchable thread. In either case, it blocks until the callback has completed. Execute takes a functor for the callback method and a generic void* argument to be passed to the callback.

===Assert Method===
Assert provides a way of checking if the current thread is the watchable thread.

==Injector==

==Network==

==Topology1==

===Overview===
Topology1 collects a list of '''Product Service''' devices from Network and exposes a collection of '''Products'''.

===Topology1===
Topology1 watches a (Product Service) device list from '''Network''' and creates a corresponding list of '''ProxyProduct''' objects that is updated whenever the device list changes. The '''Products''' method exposes the '''ProxyProduct''' list as an IWatchableUnordered.

==Topology2 ==
===Overview===
Topology2 collects the list of '''Products''' from '''Topology1''' and exposes a collection of '''Groups'''. Each '''Group''' exposes a '''Sources''' collection and pertinent properties and actions of the '''Product Service'''. Each '''Source''' exposes the standard set of Source properties.

===Topology2===
Topology2 watches '''Topology1::Products''' and creates a corresponding list of '''Topology2Group''' objects that is updated whenever '''Topology1::Products''' changes. The '''Groups''' method exposes the '''Topology2Group''' list as an IWatchableUnordered.

===Topology2Source===
Topology2Source exposes the three standard source properties: '''Name''', '''Visible''' and '''Type'''. The '''Index''' method exposes the source's position in the source list of '''Topology2Group'''.

===Topology2Group===
Topology2Group watches the '''SourceXml''' property of its underlying '''ProxyProduct''' object. Source information retrieved from '''SourceXml''' is used to to create and update a list of '''Topology2Source''' objects. The '''Sources''' method exposes the '''Topology2Source''' list as an IWatchableUnordered.

==Topology3 ==
===Overview===
Topology3 collects the list of '''Groups''' from '''Topology2''' and exposes a collection of '''Groups'''. Each '''Group''' exposes a '''Sources''' collection, pertinent actions and properties of the '''Product Service''', and a '''Sender''' property.

===Topology3===
Topology3 watches '''Topology2::Groups''' to create and maintain a corresponding list of '''Topology3Group''' objects. A dedicated '''SenderWatcher''' is created for each '''Topology3Group''' that has a Sender attribute, to monitor the '''Metadata''' property of its '''Sender Service''' . A dedicated '''ReceiverWatcher''' is created for each '''Topology3Group''' to monitor both the '''Metadata''' and '''TransportState''' properties of its '''Receiver Service'''.

Topology3 marries receivers and senders by matching their '''Uri''' properties, reassigning the '''Sender''' property of each '''Topology3Group''' when changes are reported by the watchers. The '''Groups''' method exposes the '''Topology3Group''' list as an IWatchableUnordered.

===Topology3Group ===
Topology3Group exposes all of the properties and actions of its underlying '''Topology2Group''' plus a '''Sender''' property. The Sender property holds a reference to a '''Sender''' object that reflects the Songcast sender device that the group's receiver source is listening to. The '''SenderEmpty''' object is used when no sender is selected or the selected sender is inactive.

===ReceiverWatcher===
ReceiverWatcher watches the '''Sources''' property of Topology3Group to find a source of type '''Receiver''' as an indicator of the existence of a '''Receiver service'''. If it exists, the '''Receiver service''' is subscribed to and its '''TransportState''' and '''Metadata''' properties are watched. When either of these two properties change Topology3 is notified via its '''ReceiverChanged''' method.

===SenderWatcher===
SenderWatcher subscribes to it's group's '''Sender service''' to watch its '''Metadata''' property. When this property changes Topology3 is notified via its '''SenderChanged''' method.

==Topology4 ==
===Overview===
Topology4 collects the list of '''Groups''' from '''Topology3''' and exposes a new collection of '''Rooms'''. Each '''Room''' in the new collection exposes a collection of '''Groups''' with matching '''RoomName''' properties.

===Topology4===

Topology4 watches '''Topology3::Groups''' and creates a '''Topology4Room''' list that is updated whenever there is a change to the '''RoomName''' property of any '''Topology3Group'''. A dedicated '''Topology4GroupWatcher''' is created for each '''Topology3Group''' to watch its '''RoomName''' property. The Rooms method exposes the '''Topology4Room''' list as an IWatchableUnordered.

===Topology4Room ===
Topology4Room maintains a collection of '''Topology4Group''' objects with matching '''RoomName''' properties. The collection contains at least one group. Groups are added and removed by the Topology4 class. The '''Name''' method exposes the '''Name''' property which reflects the common '''RoomName''' value shared by all groups in the collection. The '''SetStandby''' method sets the standby state of all groups. The '''Groups''' method exposes the collection of groups as an IWatchableUnordered.

===Topology4GroupWatcher ===
Topology4GroupWatcher watches the '''RoomName''' property of a single '''Topology3Group''' and updates '''Topology4''', removing the group from one room and adding it to another, whenever its '''RoomName''' property changes.

==Topology5 ==
===Overview===
Topology5 collects the list of '''Rooms''' from '''Topology4''' and organises the products ('''Groups''') in each room, evaluating their interrelationship as a family tree of connected '''parents''' and '''children'''. It exposes a list of '''Rooms''', with each '''Room''' exposing a list of parent products ('''Roots''') and a list of sources.

====Roots====
Products in a room can be daisychained by connecting the outputs of one product to the inputs of another, creating a tree of devices. In such a setup, the '''Root''' (parent) of the tree (the product at the end of the chain) is the output for all the products in the room. Typically there should only be one '''Root''' in each room, whose outputs are connected to the speakers. A '''Root''' is thus defined as a product whose outputs are '''not''' connected to the inputs of any other product.

====Source Naming====
It is not possible for a product to detect if other products are connected to its inputs. Topology, therefore, can only imply this through source naming configured by the user, as follows. If a '''source name''' on a product "ProductA" matches the '''device name''' of another product "ProductB", in the same room, it implies that the outputs of ProductB are connected to the inputs of that source on ProductA. In the family tree of products in a room, ProductA is the '''parent''' of ProductB and ProductB is a '''child''' of ProductA.

===Topology5===
Topology5 watches '''Topology4::Rooms''' to create and maintain a corresponding collection of '''Topology5Room''' objects. The '''Rooms''' method exposes the collection of rooms as an IWatchableUnordered.

===Topology5Room ===
Topology5Room maintains a Topology3Group list of by watching the Groups list of its underlying Topology4Room. A dedicated Topology5GroupWatcher is created for each group to watch its '''Name''' and '''Sources''' properties. Since all groups in the room may not share the same standby state, an additional "'''mixed'''" state is introduced to create a '''tristate Standby''' property. The '''Topology3Group''' list is used to maintain a corresponding '''Topology5Group''' list which is then filtered to obtain a '''Roots''' list. A super list of sources (Topology5Source) is then created by gathering all the sources of each Root replacing each source with its child group's sources where appropriate. The '''Roots''' method exposes the Roots list as an IWatchableUnordered. The '''Sources''' method exposes the Roots list as an IWatchableUnordered. The '''Standby''' method exposes the standby state of the room. The '''SetStandby''' method sets the standby state of all groups in the room. The '''Name''' method exposes the common room name shared by all groups in the room.

===Topology5Group ===
Topology5Group keeps track of it's '''parent''' and '''children''' groups, its currently active source, a list of its currently visible sources (expanded to include the sources of any child groups), a list of groups (from my group upwards) with the Volume service, a list of all child groups that have the Sender service.

===Topology5GroupWatcher ===
Monitors the '''Name''' and '''Sources''' properties of a specific '''Topology3Group''', updating '''Topology5Room''' whenever a change occurs.

===Topology5Source ===
Topology5Source provides a number of methods that expose the standard source parameters, flags to the presence of the Info and Time services, the source's parent group, the group's device and a list of parent groups with the Volume service. Also provided is a method to reset the list of volume service groups, a method select the source and a factory method, '''CreatePreset''', that returns a '''MediaPresetExternal''' object.

===MediaPresetExternal===
MediaPresetExternal is an object that provides access to a single '''Topology5Source''' object via the standard '''IMediaPreset''' interface. It monitors the transport state of the Source by watching the '''Source''' property of the its parent '''Topology5Group'''. The state is exposed via the three IWatchable properties '''Playing''', '''Buffering''' and '''Selected'''. The '''Play''' method selects the source in its parent group.

==Services==
===Overview===

===Service===
===ServicePlaylist===
===ServiceRadio===
===ServiceSender===
===ServiceReceiver===
===ServiceVolume===
===ServiceInfo===
===ServiceProduct===

TidalStreamingService

2014-12-08T18:30:24Z

Simonc:

Tidal's API is private. See Tidal for access to it. Or speak to us for help if you think that your access to the API would benefit OpenHome.

Assuming access to Tidal's API, the [[Av:Developer:CredentialsService | Credentials]] service can be used to retrieve the following information:

* The <tt>Ids</tt> state variable includes <tt>tidalhifi.com</tt> if Tidal is supported.
* <tt>Data</tt> from <tt>Get</tt> contains the country code used for many Tidal API calls.
* <tt>Status</tt> from <tt>Get</tt> is blank if Username and Password are both either blank or set and valid. If <tt>Status</tt> is not blank, it contains either json returned from a Tidal API or an error string.
* The token returned from <tt>Login</tt> and <tt>ReLogin</tt> is a Tidal session id.

Tracks can be added to the [[Av:Developer:PlaylistService | Playlist]] service with urls in the form <tt>tidal://track?version=1&trackId=[insert_tidal_track_id]</tt>

Av:Developer:CredentialsService

2014-11-11T13:43:01Z

Davidd: /* ReLogin */

= Overview =

The Credentials provides access to username, password and current status of all remote services that require unique logins.
 If a device's [[Developer:ProductService|Product]] service reports an attribute 'Credentials', then that device is guaranteed to bear the Credentials service.

= State Variables =
== Ids ==
Space separated list of identifiers for services whose credentials can be set.
 Set on startup; does not change at runtime.

== PublicKey ==
RSA public key that must be used to encrypt any/all passwords.
 When encrypting ensure PKCS1 OAEP padding is used.
 May be blank on startup; will not vary once set. With the exception of the <tt>Ids</tt> state variable, the rest of the service cannot usefully be used before this is set.

== SequenceNumber ==
Increases whenever any aspect of state for any user of credentials listed in <tt>Ids</tt> changes. The client is responsible for polling each Id they are interested in to determine what has changed.

= Actions =
== Set ==
Set the username and password for a given service. The password must be encrypted using the RSA public key in the <tt>PublicKey</tt> state variable.
 Calling this action automatically enables the service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Clear ==
Remove both username and password for a given service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== SetEnabled ==
Set or clear the enabled state of a service. Disabling a service temporarily prevents its use by a device but allows the device to retain the username/password for later use (if the service is re-enabled by calling <tt>SetEnabled()</tt> again).
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Get ==
Retrieve username, password, status and enabled state for a service.
 Username, password and enabled will only change in response to invocations of the Credentials service. The password is encrypted so is not suitable for user display. Clients can infer whether a password has been set by checking whether the value returned has non-zero length.
 Status may change in response to runtime events. e.g. If an account expires, the status may change to include the error returned by the remote service provider. Status is only set for error cases - a blank status indicates that a service is functioning correctly. The exact format of status content varies between services.
 Data contains any other service-specific information. The format of content varies between services.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Login ==
Read a token indicating that a registered user has logged in to a remote service. This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account. The data returned may vary between credential-consuming services; the control point is responsible for knowing how to interpret it.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
 Returns a 801 fault code if the login was attempted but failed.

== ReLogin ==
Refresh an existing token returned from <tt>Login()</tt>. This should only be called after the remote service has indicated that the current token has expired and is no longer valid.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
 Returns a 801 fault code if a new login was attempted but failed.

== GetIds ==
Read the value of the <tt>Ids</tt> state variable.

== GetPublicKey ==
Read the value of the <tt>PublicKey</tt> state variable.

== GetSequenceNumber ==
Read the value of the <tt>SequenceNumber</tt> state variable.

= Technical Details =
<code>
Domain : av.openhome.org
Name : Credentials
Version : 1
</code>

== Service Description (XML) ==
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Set</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Clear</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetEnabled</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Get</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
<argument>
<name>Status</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Data</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Login</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReLogin</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>CurrentToken</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>NewToken</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetIds</name>
<argumentList>
<argument>
<name>Ids</name>
<direction>out</direction>
<relatedStateVariable>Ids</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetPublicKey</name>
<argumentList>
<argument>
<name>PublicKey</name>
<direction>out</direction>
<relatedStateVariable>PublicKey</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetSequenceNumber</name>
<argumentList>
<argument>
<name>SequenceNumber</name>
<direction>out</direction>
<relatedStateVariable>SequenceNumber</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Ids</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PublicKey</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SequenceNumber</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Binary</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Bool</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

Developer:IdArray

2014-03-27T09:52:44Z

Simonc:

An <tt>IdArray</tt> is an array of 32 bit, big endian unsigned integers. Each Id typically represents a track. An empty <tt>IdArray</tt> indicates an rray with no elements i.e. no tracks are available.

For example the <tt>IdArray</tt> of:
<syntaxhighlight lang="cpp">
0x00 0x00 0x00 0x02 0x00 0x00 0x01 0x14 0x00 0x00 0x00 0x13
</syntaxhighlight>

contains 3 ids with the values of 2, 276, and 19 in that order.

Av:Developer:IdArray

2013-08-01T14:28:33Z

Simonc: Created page with "= IdArray = Various services require the ability to return a collection of track identifiers. This is achieved using an IdArray. An IdArray represents an array of big endian 32..."

= IdArray =
Various services require the ability to return a collection of track identifiers. This is achieved using an IdArray.

An IdArray represents an array of big endian 32-bit unsigned integers. For example,
<pre>0x00 0x00 0x00 0x02 0x00 0x00 0x01 0x03 0x00 0x00 0x00 0x13</pre>
represents 3 tracks with the id's 2, 259, and 19 in that order.

Since UPnP has no native collection types, an IdArray has binary type in UPnP services.

OhMediaPlayer

2013-07-12T08:47:43Z

Simonc: /* Source Code */

= ohMediaPlayer =
ohMediaPlayer is a portable software version of the ohMedia and UPnP:AV network services. It is written in C++ and can be deployed to any desktop or mobile platform and many embedded platforms.
Its headline features include
* Support for all popular digital formats
** …including FLAC, MP3, ALAC, WAV, AAC, Vorbis, WMA
** …for both 44.1kHz and 48kHz family sample rates
** …supported sample rates from 7.35kHz to 192kHz
** …at 8/16/24 bit depths
** …in 1-8 channels
* Playlist source. Store a playlist of hundreds or even thousands of tracks on device, playing these without requiring further interaction from a control point.
* Songcast.
** Sender. Share your audio stream with an unlimited number of other players
** Receiver. Listen to the same audio stream as another device, in exact synchronisation with that device and all other receivers.
** Supports all audio resolutions, up to and including 24-bit / 192kHz
** "Clock pulling" architecture guarantees that playback starts then remains synchronised between all devices
* Radio. Supports internet radio stations, podcasts and listen again. Includes integration to the popular TuneIn service, allowing users to setup personalised presets from a list of all worldwide internet stations.
* UPnP:AV. Presents the standard UPnP Media Renderer network services for use with basic control points.
* Playback of popular analogue and digital inputs - HDMI, SPDIF, TOS, Analogue, etc.
* Airplay. Receive an audio stream via Apple’s Airplay protocol.

= Architecture Overview =
[[File:MediaPlayer-Integrators.png]]

= System Requirements =
RAM: 16MB standard; 4MB possible

ROM: 8MB standard; 2.5MB possible (if Radio and Airplay sources are omitted)

= Integration =
The integrator supplies a small number of components
* Driver. This pulls decoded audio samples from ohMediaPlayer’s audio pipeline and is responsible for feeding them into the host’s audio hardware at the appropriate rate.
* Mutes. Optionally mute audio hardware around changes in audio sample rate or bit depth.
* OS compatibility layer. Threading and socket abstractions. Many standard platforms are available with ohNet, including
** Linux (x86, x64, ARM)
** Windows (x86, x64)
** Mac (x86, x64)
** Embedded (using [http://www.freertos.org/ FreeRTOS] and [http://lwip.wikia.com/wiki/LwIP_Wiki lwIP]). Big and little endian ports exist.
* R/W Store. At a minimum, this can simply provide a set of string literals that are determined at design time. If runtime user configuration is supported, this should also provide a means to persist and restore (string) key / (binary) value pairs.
* Application. This can be pretty short - <100 lines of code - to cover
** Initialise the UPnP stack
** Create a UPnP device, adding manufacturer-specific attributes to it
** Create MediaPlayer object
** Add desired plug-ins to MediaPlayer object
*** Sources
*** Codecs
*** Protocols
*** Content Processors
*** (Note that a future release may reduce this to selection of sources, with each source enabling appropriate codecs, protocols, etc. automatically.)
** Create Driver, R/W Store
** Enable UPnP device
No further code is required. ohMediaPlayer is controlled via [[OhMediaDevelopers#Network_Services | network APIs]] which will be automatically advertised on the network, ready to be used by any number of controllers in parallel.

= Configuration =
APIs are provided for design-time configuration
* Which audio ‘sources’ to include
* Which audio formats to support
* Sizes of various thread and memory pools
Additional software can be provided for run-time configuration, including
* Product name
* Username for externally provided radio presets
* Source naming + visibility to control app
* Delays to apply to different sources (e.g. for lip-sync)
This additional software includes
* On-device UPnP service
* On-device web UI to access these configuration values
* Desktop/mobile app to detect media players and display their configuration page.

= Software Updates =
Deployments to open systems are assumed to use the host’s existing support for application deployment and update.
A highly robust, well proved firmware update mechanism is available for embedded products. This includes
* Additional UPnP services to support reprogramming
* Desktop reprogramming utility
* Optionally, a desktop app which includes the reprogramming utility plus a user interface onto other device configuration options
This functionality is supplied separately from ohMediaPlayer and requires an additional 500KB ROM.

= Source Code =
ohMediaPlayer is provided in binary form (static library + header files) by default. Contact us if you want to discuss a license to access the full source code.
 Note that we use a small number of externally sourced, commercially licensed audio codecs. We could only share the source for these if you negotiate access to them directly with the copyright holders.

OhMediaDevelopers

2013-07-12T08:37:50Z

Simonc: Add Pins

= Network Services =
ohMedia defines the following network services:
* [[Av:Developer:ProductService | Product]]. The core of a renderer and the only mandatory service. The state of this service allows control points to infer which other services are present on a device. In more complex installations it allows devices to mapped into a multi-room hi-fi system
* [[Av:Developer:PlaylistService | Playlist]]. An ordered list of tracks to be played.
* [[Av:Developer:RadioService | Radio]]. Browse and select from a list of favourite internet radio, podcast and listen again presets.
* [[Av:Developer:InfoService | Info]]. Report information about currently playing track.
* [[Av:Developer:TimeService | Time]]. Report information about progress through a track.
* [[Av:Developer:VolumeService | Volume]]. Control volume on a renderer or a connected pre-amp.
* [[Av:Developer:TransportService | Transport]]. Source-independent transport controls.
* [[Av:Developer:SenderService | Sender]]. Indicate presence and state of a Songcast sender.
* [[Av:Developer:ReceiverService | Receiver]]. Control a Songcast receiver.
* [[Av:Developer:CredentialsService | Credentials]]. Securely manage login details for external services supported by a device.
* [[Av:Developer:PinsService | Pins]]. Quick access to smart presets, supporting dynamic content.
* NetworkMonitor. Measures network performance.
* [[Av:Developer:PlaylistManagerService | PlaylistManager]]. Included in media servers. Allows playlists to be shared between renderers and saved for future reuse.

The [[Av:Developer:EriskayServices | Eriskay]] family of services will later replace these. Feedback on Eriskay is welcomed.

= UPnP =
All ohMedia products publish and/or consume network services using UPnP. This is enabled by [[OhNet | ohNet]] - a cross-platform UPnP stack suitable for use in control points and devices. ohNet is open source, liberally licensed and intended for use in external products.

= ODP =
[[Av:Developer:Odp | OpenHome Device Protocol]] (ODP) allows control of and evented updates from a device via a single socket. [https://github.com/openhome/ohPipeline ohPipeline] contains [https://github.com/openhome/ohPipeline/tree/master/OpenHome/Net/Odp reference code] for control point or device stacks.

All services that are available using over UPnP are also available using ODP. The same auto-generated 'proxies' allow control point authors to invoke an action as a single function call and register callbacks to be informed of evented updates.

= Songcast =
The Songcast brand encompasses a range of products and protocols.

== Desktop senders ==
Virtual audio drivers that send all audio from a Windows or Mac device to a songcast receiver. [https://www.linn.co.uk/software#songcast Linn] provide a full implementation of these. The bulk of the code required is also available in the [https://github.com/openhome/ohSongcast ohSongcast] repo.

== Multi-room ==
The Songcast protocol enables synchronised playing of audio from an unbounded number of ohMedia renderers.

The [https://github.com/openhome/ohSongcast ohSongcast] repo provides a cross-platform C++ library offering much of the code needed to write a stand-alone songcast sender. The [https://github.com/openhome/ohPipeline ohPipeline] repo contains a reference sender and receiver fully integrated to the OpenHome reference audio pipeline.

The Songcast protocols are also documented:
* [[Av:Developer:Songcast:Ohm | OHM/OHU protocol specification]]
* [[Av:Developer:Songcast:Ohz | OHZ protocol specification]]

== Direct ==
A specialised protocol, offering simpler integration and potentially higher audio quality, used when there is a single receiver and the sender has control over the rate of streaming (this often means that the sender is responsible for audio decode).

More information, including protocol spec and sample code is available [[Av:Developer:Scd | here]].

= Topology =
ohMedia models a home as a number of hi-fi systems, which are located in rooms.

A hi-fi system is modelled as a hierarchical tree of products, where a product is defined as a single physical box that is located in a room, has a unique name within the room, has at least one output and any number of inputs.

A product is modelled through the [[Av:Developer:ProductService | Product]] service specification.

When a control point wants to construct a model of a user's home they use the Topology algorithm:
* discover all the products in the home that have a Product service
* group the discovered products based on the room they are in
* create a hierarchical tree structure by matching source names to product names *
* discover source functionality based on source type
* discover additional functionality based on product attributes
Example implementations of the Topology algorithm are available in C# and C++ from the [https://github.com/openhome/ohTopology ohTopology] github repo.

A more detailed description of the ohTopology software can be found [[Av:Developer:ohTopologyDescription | here]].

= Streaming Services =
Both Linn's DS and [[OhMediaPlayer | ohMediaPlayer]] include reference implementations for the following streaming services:
* [[TidalStreamingService | Tidal]]
* [[QobuzStreamingService | Qobuz]]
* [[CalmRadioInternetRadio | Calm Radio]]