From OpenHome
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, 0x6d, 0x20 ('ohm ') |
| 1 | Version | 1 |
| 1 | Type | The type of message |
| 0 - Join | ||
| 1 - Listen | ||
| 2 - Leave | ||
| 3 - Audio (details below) | ||
| 4 - Track (details below) | ||
| 5 - Metatext (details below) | ||
| 6 - Slave (details below) | ||
| 2 | Length | The length in bytes of the whole message including this header |
| Minimum | 8 | |
| Maximum | 16392 | |
| 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 | Frame | The frame number |
| 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 | Pcm | Pcm samples, where n = Channels * BitDepth * SampleCount / 8 |
| Track | ||
| 4 | TrackSequence | Sequence number for this track. |
| 4 | TrackUriLength | The length in bytes of the track uri |
| 4 | TrackMetadataLength | The length in bytes of the track metadata |
| p | TrackUri | The track uri, where p = TrackUriLength |
| q | TrackMetadata | The track metadata in DIDL-Lite format, where q = TrackMetadataLength |
| Metatext | ||
| 4 | MetatextSequence | Sequence number for this metatext. |
| 4 | MetatextLength | The length in bytes of the metatext |
| r | Metatext | The metatext in DIDL-Lite format, where r = MetatextLength |
| Slave | ||
| 4 | SlaveCount | The number of slaves |
| s | SlaveList | The list of slave endpoints, where s = 6 * SlaveCount |