From OpenHome
Contents |
Songcast OHM/OHU Protocol Specification (Version 1.0)
Introduction
OHM and OHU, together with OHZ, form the Songcast family of OpenHome protocols for transporting audio around a home network.
- OHM provides large scale one to many communication using multicast UDP.
- OHU provides small scale one to many communication using unicast UDP.
OHU can be used to deliver Songcast functionality to networks that do not control multicast UDP to the level required by OHM.
Message Format
The OHM and OHU protocols share the same 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 | 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 | 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 |
Control Messages
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 where high accuracy is achievable. Timestamps should use 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.
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.
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.
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:
| Multicast Sender Channel | |
|---|---|
| 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
The OHM Sender and OHM Receivers implement the following state machines to reduce unnecessary multicast network traffic.
SONGCAST SENDER MULTICAST STATE TRANSITION DIAGRAM
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 listening. 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.
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 became disconnected in a way that prevented them from successfully informing the OHU Sender.
There are a number of ways in which an OHU Sender can be implemented, but an OHU Receiver is expected to operate the following state machine.
The state machine contains a mechanism for attempting to synchronise 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.