From OpenHome

(Difference between revisions)
Jump to: navigation, search
(→Introduction)
 
(14 intermediate revisions not shown)
Line 32: Line 32:
! Description
! Description
|- align="left" style="color:#ffffff; background-color:#008833;"
|- align="left" style="color:#ffffff; background-color:#008833;"
-
! colspan="3" | Header
+
| Header
 +
|
 +
|
|-
|-
| 4
| 4
Line 64: Line 66:
| 2
| 2
| Length
| Length
-
| The length in bytes of the whole message including this header
+
| The length in bytes of the whole message including this header [8..5000]
-
|-
+
|- align="left" style="color:#ffffff; background-color:#008833;"
 +
| Zone Query
|
|
-
| Minimum
 
-
| 8
 
-
|-
 
|
|
-
| Maximum
 
-
| 5000
 
-
|- align="left" style="color:#ffffff; background-color:#008833;"
 
-
! colspan="3" | Audio
 
-
|-
 
-
| 1
 
-
| AudioHeaderLength
 
-
| 50
 
-
|-
 
-
| 1
 
-
| Flags
 
-
| Bit 0 - halt
 
-
|-
 
-
|
 
-
|
 
-
| Bit 1 - lossless
 
-
|-
 
-
|
 
-
|
 
-
| Bit 2 - timestamped
 
-
|-
 
-
|
 
-
|
 
-
| Bit 3 - 0
 
-
|-
 
-
|
 
-
|
 
-
| Bit 4 - 0
 
-
|-
 
-
|
 
-
|
 
-
| Bit 5 - 0
 
-
|-
 
-
|
 
-
|
 
-
| Bit 6 - 0
 
-
|-
 
-
|
 
-
|
 
-
| Bit 7 - 0
 
-
|-
 
-
| 2
 
-
| SampleCount
 
-
| The number of samples in this frame
 
|-
|-
| 4
| 4
-
| Frame
+
| QueryZoneLength
-
| The frame number
+
| The length in bytes of the zone
-
|-
+
-
| 4
+
-
| NetworkTimestamp
+
-
| The time when the previous frame was sent over the network (if the timestamped flag is on)
+
-
|-
+
-
| 4
+
-
| MediaLatency
+
-
| The length in milliseconds of the audio buffer
+
-
|-
+
-
| 4
+
-
| MediaTimestamp
+
-
| The time when this frame was placed into the audio buffer {if the timestamp flag is on)
+
-
|-
+
-
| 8
+
-
| StartSample
+
-
| The sample number within the current track of the first sample in this frame
+
-
|-
+
-
| 8
+
-
| TotalSamples
+
-
| The total number of samples in the current track
+
-
|-
+
-
| 4
+
-
| SampleRate
+
-
| The sample rate in samples per second
+
-
|-
+
-
| 4
+
-
| BitRate
+
-
| The bit rate in bits per second
+
-
|-
+
-
| 2
+
-
| VolumeOffset
+
-
| The volume offset in signed binary milli-dB (+/- 32dB)
+
-
|-
+
-
| 1
+
-
| BItDepth
+
-
| The bit depth (8, 16, or 24)
+
-
|-
+
-
| 1
+
-
| Channels
+
-
| The number of interleaved audio channels
+
-
|-
+
-
| 1
+
-
| AudioReserved
+
-
| 0
+
-
|-
+
-
| 1
+
-
| CodecNameLength
+
-
| The number of bytes in the name of the codec
+
-
|-
+
-
| m
+
-
| CodecName
+
-
| The codec name (in UTF-8), where m = CodecNameLength
+
|-
|-
| n
| n
-
| Pcm
+
| QueryZone
-
| Pcm samples, where n = Channels * BitDepth * SampleCount / 8
+
| The queried Zone Id, where n = QueryZoneLength
|- align="left" style="color:#ffffff; background-color:#008833;"
|- align="left" style="color:#ffffff; background-color:#008833;"
-
! colspan="3" | Track
+
| Zone Uri
-
|-
+
|
-
| 4
+
|
-
| TrackSequence
+
-
| Sequence number for this track.
+
|-
|-
| 4
| 4
-
| TrackUriLength
+
| ZoneLength
-
| The length in bytes of the track uri
+
| The length in bytes of the Zone Id
|-
|-
| 4
| 4
-
| TrackMetadataLength
+
| UriLength
-
| The length in bytes of the track metadata
+
| The length in bytes of the URI
|-
|-
| p
| p
-
| TrackUri
+
| Zone
-
| The track uri, where p = TrackUriLength
+
| The Zone Id, where p = ZoneLength
|-
|-
| q
| q
-
| TrackMetadata
+
| Uri
-
| The track metadata in DIDL-Lite format, where q = TrackMetadataLength
+
| The URI, where q = UriLength
|- align="left" style="color:#ffffff; background-color:#008833;"
|- align="left" style="color:#ffffff; background-color:#008833;"
-
! colspan="3" | Metatext
+
| Preset Query
 +
|
 +
|
|-
|-
| 4
| 4
-
| MetatextSequence
+
| QueryPreset
-
| Sequence number for this metatext.
+
| The queried preset number
 +
|- align="left" style="color:#ffffff; background-color:#008833;"
 +
| Preset Info
 +
|
 +
|
|-
|-
| 4
| 4
-
| MetatextLength
+
| Preset
-
| The length in bytes of the metatext
+
| The preset number
-
|-
+
-
| r
+
-
| Metatext
+
-
| The metatext in DIDL-Lite format, where r = MetatextLength
+
-
|- align="left" style="color:#ffffff; background-color:#008833;"
+
-
! colspan="3" | Slave
+
|-
|-
| 4
| 4
-
| SlaveCount
+
| MetadataLength
-
| The number of slaves
+
| The length in bytes of the metadata
|-
|-
-
| s
+
| r
-
| SlaveList
+
| Metadata
-
| The list of slave endpoints, where s = 6 * SlaveCount
+
| The metadata in DIDL-Lite format, where r = MetadataLength
|}
|}
 +
 +
== Zone Handling ==
 +
 +
Each participating Sender must have a unique Zone Id. This Id is often derived from the Sender's MAC address, but any other network-unique Id is acceptable.
 +
 +
The OHZ URI for a Sender is: <tt>ohz://239.255.255.250:51972/ZoneId</tt>
 +
 +
=== From The Receiver's Perspective ===
 +
 +
In order to listen to <tt>ohz://239.255.255.250:51972/ZoneId</tt>, a Receiver should send a Zone Query message to the Multicast endpoint <tt>239.255.255.250:51972</tt> and listen for an equivalent Zone Uri message.
 +
 +
If no Zone Uri message is received within 100mS, then the process should be repeated.
 +
 +
Once a matching Zone Uri message has been received, the contained OHM or OHU URI is used to establish an audio connection to the Sender.
 +
 +
The OHZ handler should continue listening for Zone Uri messages that match the Zone Id. If a different URI is published by the Sender, then audio playback should be terminated and a new audio connection established  using the new OHM or OHU URI.
 +
 +
=== From The Sender's Perspective ===
 +
 +
A Sender should listen on the Multicast endpoint <tt>239.255.255.250:51972</tt> for Zone Query messages that match its Zone Id, and should respond with a single Zone Uri message.
 +
 +
Whenever the Sender's OHM or OHU URI changes, it should send 3 consecutive Zone Uri messages with the new URI.
 +
 +
== Presets ==
 +
 +
A Sender can optionally participate in the OHZ Preset system. This allows for a Sender to be configured with a network-unique preset number that can be used by a primitive control points, such as an IR handset.
 +
 +
To participate in this system, a Sender must listen for Preset Query messages and send Preset Info messages accordingly.
 +
 +
The metadata for the Preset Info message is the same DIDL-Lite metadata that is published using the [[Av:Developer:SenderService|Sender service]].

Latest revision as of 12:25, 6 November 2013

Contents

Songcast OHZ Protocol Specification (Version 1.0)

Introduction

OHZ, together with OHM and OHU, form the Songcast family of OpenHome protocols for transporting audio around a home network.

OHZ provides the ability for a uniquely identified Songcast Sender to redirect its Receivers to different OHM or OHU URIs.

How does a Songcast Sender use OHZ?

In order to use OHZ, a Songcast Sender must:

  • Publish an OHZ URI instead of an OHM or OHU URI
  • Broadcast the OHM or OHU URI associated with this OHZ URI whenever it is requested by a Receiver (solicited broadcast)
  • Broadcast the OHM or OHU URI associated with this OHZ URI whenever it changes (unsolicited broadcast)

Why would a Songcast Sender use OHZ?

There are two known reasons for the use of OHZ.

  • To allow devices that are both Senders and Receivers to manage complicated patterns of one-to-many communication, such as a Receiver listening to a Sender that is itself listening to another Sender. In this instance, the intermediate Sender can redirect its Receivers to the root Sender rather than rebroadcast Audio messages, which would accumulate network delays.
  • In order to allow a Receiver to continue listening to a Sender even though the configuration of the Sender has changed from Unicast to Multicast, or vice versa. Or when the Multicast channel is changed while the Sender is in Multicast mode.

Message Format

The OHZ protocol has the following message format.


Bytes Name Description
Header
4 Signature 0x6f, 0x68, 0x7a, 0x20 ('ohz ')
1 Version 1
1 Type The type of message
0 - Zone Query
1 - Zone Uri
2 - Preset Query
3 - Preset Info
2 Length The length in bytes of the whole message including this header [8..5000]
Zone Query
4 QueryZoneLength The length in bytes of the zone
n QueryZone The queried Zone Id, where n = QueryZoneLength
Zone Uri
4 ZoneLength The length in bytes of the Zone Id
4 UriLength The length in bytes of the URI
p Zone The Zone Id, where p = ZoneLength
q Uri The URI, where q = UriLength
Preset Query
4 QueryPreset The queried preset number
Preset Info
4 Preset The preset number
4 MetadataLength The length in bytes of the metadata
r Metadata The metadata in DIDL-Lite format, where r = MetadataLength

Zone Handling

Each participating Sender must have a unique Zone Id. This Id is often derived from the Sender's MAC address, but any other network-unique Id is acceptable.

The OHZ URI for a Sender is: ohz://239.255.255.250:51972/ZoneId

From The Receiver's Perspective

In order to listen to ohz://239.255.255.250:51972/ZoneId, a Receiver should send a Zone Query message to the Multicast endpoint 239.255.255.250:51972 and listen for an equivalent Zone Uri message.

If no Zone Uri message is received within 100mS, then the process should be repeated.

Once a matching Zone Uri message has been received, the contained OHM or OHU URI is used to establish an audio connection to the Sender.

The OHZ handler should continue listening for Zone Uri messages that match the Zone Id. If a different URI is published by the Sender, then audio playback should be terminated and a new audio connection established using the new OHM or OHU URI.

From The Sender's Perspective

A Sender should listen on the Multicast endpoint 239.255.255.250:51972 for Zone Query messages that match its Zone Id, and should respond with a single Zone Uri message.

Whenever the Sender's OHM or OHU URI changes, it should send 3 consecutive Zone Uri messages with the new URI.

Presets

A Sender can optionally participate in the OHZ Preset system. This allows for a Sender to be configured with a network-unique preset number that can be used by a primitive control points, such as an IR handset.

To participate in this system, a Sender must listen for Preset Query messages and send Preset Info messages accordingly.

The metadata for the Preset Info message is the same DIDL-Lite metadata that is published using the Sender service.

Retrieved from "http://wiki.openhome.org/wiki/Av:Developer:Songcast:Ohz"