= 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

{|
|-
| 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
|
|-
| type
| podcast
|
|-
| ''Query Parameters''
|
|
|-
| path
| Show/podcast link
| Must to be url encoded
|-
|}

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

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

= iTunes Podcast =
<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

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

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

Av:Developer:PinInvokers

2018-08-20T17:03:37Z

2017-06-23T14:51:31Z

Simonc: /* Protocol */

= 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":1,
"devices": [
{
"id":"udn",
"type":"one of Ds / MediaRenderer / Preamp",
"services": [
{ "name":"service1", "version":1 },
{ "name":"service2", "version":2 },
{ "name":"service3", "version":1 }
]
},
{
"id": "udn",
"type":"one of Ds / MediaRenderer / Preamp",
"services": [
{ "name":"service4", "version":1 },
{ "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",
"device": "type",
"service": { "name": "service_name", "version": 1 },
"action": "action_name",
"arguments": {
"input_arg_str":"json_escaped_str",
"input_arg_bin":"base64_encoded_str",
"input_arg_bool":"true",
"input_arg_int":"-1",
"input_arg_uint":"3"
},
"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": {
"output_arg_str":"json_escaped_str",
"output_arg_bin":"base64_encoded_str",
"output_arg_bool":"true",
"output_arg_int":"-1",
"output_arg_uint":"3"
}
}

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

=== 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",
"device": "type",
"service": { "name": "service_name", "version": 2 }
}

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,
"sid": "subscription_id"
}

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

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

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

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": {
"property_str":"json_escaped_str",
"property_bin":"base64_encoded_str",
"property_bool":"true",
"property_int":"-1",
"property_uint":"3"
}
}

Av:Developer:Odp

Simonc: Created page with "= 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 ..."

OhMediaDevelopers

2017-06-23T11:37:19Z

Simonc: /* Direct */

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

= 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 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]]