From OpenHome

(Difference between revisions)
Jump to: navigation, search
(→Why would Songcast Sender use OHZ?)
 
(20 intermediate revisions not shown)
Line 5: Line 5:
OHZ, together with [[Av:Developer:Songcast:Ohm|OHM and OHU]], form the Songcast family of OpenHome protocols for transporting audio around a home network.
OHZ, together with [[Av:Developer:Songcast:Ohm|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.
+
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? ===
=== How does a Songcast Sender use OHZ? ===
Line 11: Line 11:
In order to use OHZ, a Songcast Sender must:
In order to use OHZ, a Songcast Sender must:
-
* Publish an OHZ Uri instead of an OHM or OHU Uri
+
* 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 is requested by a Receiver (solicited broadcast)
-
* Broadcast the OHM or OHU Uri associated with this OHZ Uri whenever it changes (unsolicited broadcast)
+
* Broadcast the OHM or OHU URI associated with this OHZ URI whenever it changes (unsolicited broadcast)
=== Why would a Songcast Sender use OHZ? ===
=== Why would a Songcast Sender use OHZ? ===
Line 21: Line 21:
* 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.
* 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 Receivers 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.
+
* 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 ==
== Message Format ==
-
The OHM and OHU protocols share the same message format.
+
The OHZ protocol has the following message format.
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
| Signature
| Signature
-
| 0x6f, 0x68, 0x6d, 0x20 ('ohm ')
+
| 0x6f, 0x68, 0x7a, 0x20 ('ohz ')
|-
|-
| 1
| 1
Line 48: Line 50:
|
|
|  
|  
-
| 0 - Join
+
| 0 - Zone Query
|-
|-
|
|
|
|
-
| 1 - Listen
+
| 1 - Zone Uri
|-
|-
|
|
|
|
-
| 2 - Leave
+
| 2 - Preset Query
|-
|-
|
|
|
|
-
| 3 - Audio (details below)
+
| 3 - Preset Info
-
|-
+
-
|
+
-
|
+
-
| 4 - Track  (details below)
+
-
|-
+
-
|
+
-
|
+
-
| 5 - Metatext  (details below)
+
-
|-
+
-
|
+
-
|
+
-
| 6 - Slave  (details below)
+
|-
|-
| 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
 
-
| 16392
 
-
|- 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
| 4
-
| TrackSequence
+
| ZoneLength
-
| Sequence number for this track.
+
| The length in bytes of the Zone Id
|-
|-
| 4
| 4
-
| TrackUriLength
+
| UriLength
-
| The length in bytes of the track uri
+
| The length in bytes of the URI
-
|-
+
-
| 4
+
-
| TrackMetadataLength
+
-
| The length in bytes of the track metadata
+
|-
|-
| 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
|}
|}
-
=== Control Messages ===
+
== Zone Handling ==
-
The Join and Listen messages are used for OHM control. The Join, Listen, Leave, and Slave messages are used for OHU control.
+
-
 
+
-
=== Audio Messages ===
+
-
Audio is transmitted as a timely and continuous stream of Audio messages.
+
-
 
+
-
It is typical to send Audio messages every 5ms - 10ms with the length of each message dependent on the format of the audio being played.
+
-
 
+
-
It is also typical at a track boundary to send a shorter Audio message so that a single Audio message does not span two tracks.
+
-
 
+
-
If no audio material is to be played because, for instance, the user has told the sender to pause playback, then the sender should not send silence. Rather, the sender should adorn the last Audio message with the 'halt' flag to indicate that this continuous stream of audio has completed and that the next continuous stream of audio will start at an arbitrary time in the future.
+
-
 
+
-
Note that AudioCodecName should represent the codec that was used to decode the PCM payload. If no appropriate codec name is available then AudioCodecName should be set to "PCM".
+
-
 
+
-
=== Timestamps ===
+
-
Accurate timestamps allow appropriately equipped Songcast Receivers to achieve close audio synchronisation. But timestamps should only be used when high accuracy is achievable. Timestamps are made according to an audio MCLK that is 256 * 44K1, or 256 * 48K.
+
-
 
+
-
=== Track Messages ===
+
-
Track messages are transmitted to provide Songcast Receivers with in-band information concerning the currently playing track. They should be sent shortly after a Receiver sends a Join message, and whenever the track changes. The incrementing sequence number can be used by Receivers to distinguish between the Track messages sent at the start of a new track and those sent when a new Receiver joins.
+
-
 
+
-
=== Metatext Messages ===
+
-
Metatext messages are used to convey dynamic textual information concerning the currently playing audio material. This is typically information broadcast by internet radio stations. The incrementing sequence number can be used by Receivers to distinguish between the Metatext messages sent when this dynamic information changes and those sent when a new Receiver joins.
+
-
 
+
-
=== Slave Messages ===
+
-
OHU uses Slave messages to deliver one-to-many communication using unicast UDP. The message contains a list of endpoints arranged as 6-byte ordered pairs of ip-address and port.
+
-
 
+
-
== Multicast ==
+
-
 
+
-
=== OHM Sender Channel ===
+
-
OHM is used to stream audio from a single sender to multiple receivers using multicast UDP.
+
-
 
+
-
Each OHM Sender within a single multicast networking domain has a unique 16 bit OHM Channel, which must be configurable by the user to avoid conflicts. And each OHM Channel has an equivalent URI as follows:
+
-
 
+
-
{| border="1" cellpadding="5" style="background-color:#ffffcc;"
+
-
! colspan="2" | Multicast Sender Channel
+
-
|- align="left" style="color:#ffffff; background-color:#008833;"
+
-
| Channel
+
-
| Uri
+
-
|-
+
-
| 0
+
-
| ohm://239.253.0.0:51972
+
-
|-
+
-
| 1
+
-
| ohm://239.253.0.1:51972
+
-
|-
+
-
| 2
+
-
| ohm://239.253.0.2:51972
+
-
|-
+
-
| 3
+
-
| ohm://239.253.0.3:51972
+
-
|-
+
-
|| ...
+
-
|| ...
+
-
|-
+
-
| 65535
+
-
| ohm://239.253.255.255:51972
+
-
|}
+
-
 
+
-
An OHM Sender usually publishes its URI using the OpenHome Sender service over UPnP. However, it is also possible for an OHM Sender to publish its URI by some other mechanism.
+
-
 
+
-
An OHM Receiver engages with an OHM Sender by exchanging messages with the multicast endpoint indicated by the OHM Sender's URI.
+
-
 
+
-
=== OHM Control ===
+
-
 
+
-
In general a Receiver is required to send a Join message to the Sender when it starts listening and a Listen message every second or so after that. However, when using multicast udp it is not necessary for a Receiver to send a Listen message if it has detected that some other Receiver has already sent one. This is because the only purpose of the Listen message is to ensure that the Sender continues sending Audio messages, and any Listen message from any Receiver will serve this purpose.
+
-
 
+
-
So, the OHM Sender and OHM Receivers implement the following state machines to reduce unnecessary multicast network traffic.
+
-
 
+
-
[[File:Songcast Sender Multicast State Transition Diagram.png]]
+
-
 
+
-
'''MULTICAST SENDER STATE TRANSITION DIAGRAM'''
+
-
 
+
-
[[File:Songcast Receiver Multicast State Transition Diagram.png]]
+
-
 
+
-
'''MULTICAST RECEIVER STATE TRANSITION DIAGRAM'''
+
-
 
+
-
 
+
-
Using this scheme one Receiver tends to become the Primary Receiver, which sends Listen messages to keep the Sender producing audio messages. If the Primary Receiver ever stops listening then one of the remaining Secondary Receivers is automatically promoted to the role of Primary Receiver.
+
-
 
+
-
The OHM Sender stops producing Audio messages T seconds after the last Receiver has stopped sending Listen messages. Ts and Tp are arranged so that for a Sender to erroneously stop producing Audio messages in the presence of active Receivers it would have to miss 4 consecutive Listen messages.
+
-
 
+
-
The Sender Blocked states should only occur in a misconfigured system with more than one Sender on the same channel.
+
-
 
+
-
== Unicast ==
+
-
 
+
-
=== OHU Basics ===
+
-
The OHU protocol is arranged so that the OHU Sender need send audio to only one OHU Receiver. This is to reduce the processing overhead on those OHU Senders that have constrained processing resources.
+
-
 
+
-
If the OHU Sender is using this feature of the OHU protocol then it nominates one of its OHU Receivers to be the Primary OHU Receiver and sends it a Slave message, which contains a list of Slave OHU Receiver endpoints. The Primary OHU Receiver must forward any subsequent Audio, Track, or Metatext messages to this list.
+
-
 
+
-
As OHU Receivers come and go, the OHU Sender is responsible for nominating its OHU Primary Receiver and updating the list of OHU Slave Receivers appropriately.
+
-
 
+
-
If an OHU Sender has the processing power necessary to send to multiple OHU Receivers it may ignore the Slave feature or may adopt a hybrid approach, which would multiply the maximum number of OHU Receivers that that OHU Sender could support.
+
-
 
+
-
=== OHU Sender Uri ===
+
-
An OHU Sender URI, such as ohu://192.168.1.23:51973, represents an ip endpoint.
+
-
 
+
-
An OHU Sender usually publishes its URI using the OpenHome Sender service over UPnP. However, it is also possible for an OHU Sender to publish its URI by some other mechanism.
+
-
 
+
-
An OHU Receiver engages with an OHU Sender by exchanging udp messages with the unicast endpoint indicated by the OHU Sender's URI.
+
-
 
+
-
=== OHU Control ===
+
-
As well as the Join and Listen messages, OHU also uses the Leave message. This gives the OHU Sender instantaneous information concerning its OHU Listeners and enables it to quickly reorganise its OHU Primary Receiver and OHU Slave Receivers in a way that ensures uninterrupted audio.
+
-
 
+
-
The periodic Listen message from all receivers is still present as a fallback mechanism for detecting OHU Receivers that become disconnected in a way that prevents them from successfully informing the OHU Sender with a Leave message.
+
-
 
+
-
The Unicast Sender is difficult to express in a traditional State Transition Diagram. But the following description should serve as a reasonable specification.
+
-
 
+
-
* When a Join message is received
+
-
** If this is the first Receiver, set the Primary Receiver and move to the Alive state
+
-
** If this is not the first Receiver, add to the Slave Receiver list and send a Slave message with this updated list to the Primary Receiver
+
-
** In all cases send a Track and Metatext message to the Primary Receiver
+
-
* When a Listen message is received
+
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.
-
** Identify the sending Primary or Slave Receiver and refresh their Alive timer
+
-
** Check for expired Alive timers and modify the Primary or Slave list accordingly, possibly sending a Slave message with this updated list to the Primary Receiver
+
-
* When a Leave message is received
+
The OHZ URI for a Sender is: <tt>ohz://239.255.255.250:51972/ZoneId</tt>
-
** Identify the sending Primary or Slave Receiver modify the Primary or Slave list accordingly, possibly sending a Slave message with this updated list to the Primary Receiver
+
-
* If no more Receivers are listening, return the Waiting state
+
=== From The Receiver's Perspective ===
-
* In the Alive state send all necessary  Audio, Track, and Metatext messages to the Primary Receiver
+
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.
-
A Unicast Receiver implements the following state machine. It contains a mechanism for synchronizing the sending of a Leave message with the reception of an Audio message. This mechanism is designed to give the OHU Sender as much time as possible to reorganise its Slaves.
+
If no Zone Uri message is received within 100mS, then the process should be repeated.
-
[[File:Songcast Receiver Unicast State Transition Diagram.png]]
+
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.
-
'''UNICAST RECEIVER STATE TRANSITION DIAGRAM'''
+
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.
-
== UPnP Services ==
+
=== From The Sender's Perspective ===
-
The usual way of publishing a Songcast Sender Uri is through the Metadata state variable in the [[Av:Developer:SenderService|Sender service]]. This should cause a Songcast Sender to be listed by those Control Points compliant with the OpenHome AV standard.
+
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.
-
A Songcast Receiver should publish itself using the [[Av:Developer:ReceiverService|Receiver service]] in conjunction with the [[Av:Developer:ReceiverService|Product service]]
+
Whenever the Sender's OHM or OHU URI changes, it should send 3 consecutive Zone Uri messages with the new URI.
-
== Source Code ==
+
== Presets ==
-
A reference implementation of a Songcast Sender and Songcast Receiver will shortly be published, together with a complete open source UPnP stack.
+
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.
-
== Glossary ==
+
To participate in this system, a Sender must listen for Preset Query messages and send Preset Info messages accordingly.
-
* Binary milli-dB  - 1/1024 dB
+
The metadata for the Preset Info message is the same DIDL-Lite metadata that is published using the [[Av:Developer:SenderService|Sender service]].
-
* Endpoint  - an ip-address and port combination that specifies a particular application running on a networked machine.
+
-
* Multicast - one-to-many ip-based networking using a specially reserved set of addresses
+
-
* Unicast - basic point-to-point ip-based networking
+

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"