From OpenHome

(Difference between revisions)
Jump to: navigation, search
(Message Format)
(Message Format)
Line 14: Line 14:
-
{| border="1" cellpadding="3"
+
{| border="1" cellpadding="3" style="background-color:#ffffcc;"  
! Bytes
! Bytes
! Name
! Name
Line 174: Line 174:
| Pcm
| Pcm
| Pcm samples, where n = AudioChannels * AudioBitDepth * AudioSampleCount / 8
| Pcm samples, where n = AudioChannels * AudioBitDepth * AudioSampleCount / 8
-
|- align="left" style="background-color:#00ff22;"
+
|- align="left" style="color:#ffffff; background-color:#00aa33;"
! colspan="3" | Track
! colspan="3" | Track
|-
|-
Line 192: Line 192:
| TrackMetadata
| TrackMetadata
| The track metadata in DIDL-Lite format, where q = TrackMetadataLength
| The track metadata in DIDL-Lite format, where q = TrackMetadataLength
-
|- align="left" style="background-color:#00ff22;"
+
|- align="left" style="color:#ffffff; background-color:#00aa33;"
! colspan="3" | Metatext
! colspan="3" | Metatext
|-
|-
Line 202: Line 202:
| Metatext
| Metatext
| The metatext in DIDL-Lite format, where r = MetatextLength
| The metatext in DIDL-Lite format, where r = MetatextLength
-
|- align="left" style="background-color:#00ff22;"
+
|- align="left" style="color:#ffffff; background-color:#00aa33;"
! colspan="3" | Slave
! colspan="3" | Slave
|-
|-

Revision as of 10:41, 6 May 2011

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
General
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 the 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 = AudioCodecLength
n Pcm Pcm samples, where n = AudioChannels * AudioBitDepth * AudioSampleCount / 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 AudioCodecName should be set to “PCM”.

Timestamps

Accurate timestamps provide appropriately equipped Songcast Receivers with the ability to achieve high quality 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

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:


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.

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

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.