From OpenHome
(FormatDsd) |
(→Overview) |
||
| Line 6: | Line 6: | ||
* There is a constant TCP connection between sender and receiver, avoiding the need for application-level resend support | * There is a constant TCP connection between sender and receiver, avoiding the need for application-level resend support | ||
* It uses the clock of the receiver, allowing for higher quality playback if the sender is on a desktop computer | * It uses the clock of the receiver, allowing for higher quality playback if the sender is on a desktop computer | ||
| - | * It offers the receiver limited control over the stream – initially | + | * It offers the receiver limited control over the stream – initially Transport (play / pause / stop) and Volume. While the primary control UI may reside on the sender device, this allows for basic integration with any Ir handset for the receiver. |
== Sample Code == | == Sample Code == | ||
Latest revision as of 10:08, 13 December 2019
Contents |
Songcast Direct
Overview
Songcast Direct (SCD) can be used to send decoded audio from any computing device to an OpenHome device. The Sender device is responsible for decoding audio to PCM, framing this in a simple protocol and making it available via a simple TCP server. The Receiver pulls data from this server, giving the Receiver complete control of the audio clock.
A Songcast Direct sender performs a broadly similar role to a Songcast sender. Applications that perform their own decoding to PCM will find SCD is easier to integrate and offers higher audio performance:
- There is a constant TCP connection between sender and receiver, avoiding the need for application-level resend support
- It uses the clock of the receiver, allowing for higher quality playback if the sender is on a desktop computer
- It offers the receiver limited control over the stream – initially Transport (play / pause / stop) and Volume. While the primary control UI may reside on the sender device, this allows for basic integration with any Ir handset for the receiver.
Sample Code
ohPipeline contains sample code.
WavSender contains an example of a trivial SCD Sender, scanning a single directory and decoding then sending any WAV files it finds. (Note that compilation of this is currently disabled. DirScanner::Run() contains code from an experimental precursor to C++17's std::filesystem::directory_iterator. Current code is compatible with VS2013; it should only require a couple of lines of change to make this compile against any more recent compiler.)
Code in the Scd and Sender directories should be usable without any change. It will be possible to write a commercial quality sender using the ScdSender library, passing audio into IScdSupply and relying on the configuration of ScdMsgFactory to determine how much audio is buffered by the Sender.
Sample code demonstrating how a Sender can control a Receiver via ODP is coming soon. For now, see ODP tests for a basic example.
Discovery
SSDP
First search for av-openhome-org:service:Product:2 then either
- Check Attributes on Product service for "Transport"
- Check Modes on Transport service for "scd"
or
- Check SourceXml on Product for a source with Type of "scd"
mDNS
Search for _openhome._odp service to identify ODP endpoint
Control
Control of the Receiver is out of band, via the standard OpenHome network APIs. These are available over UPnP or ODP (a single connected socket).
Protocol
The protocol used for communication between Sender and Receiver contains the following message types:
| Type | Description | Sent by |
|---|---|---|
| Ready | Signals availability and version support to other party | Receiver & Sender |
| MetadataDidl | Metadata relevant until the end of the next track. Will cause the receiver to reset its reported time indicator for the audio stream. Should be sent after all Audio for any preceding track. Uses DIDL-Lite. | Sender |
| MetadataOh | Metadata relevant until the end of the next track. Will cause the receiver to reset its reported time indicator for the audio stream. Should be sent after all Audio for any preceding track. Uses OpenHome Metadata format. | Sender |
| Format | Format for the following (PCM) audio. Must be sent before any audio. | Sender |
| FormatDsd | Format for the following (DSD) audio. Must be sent before any audio. | Sender |
| Audio | Decoded audio. Can only be sent after a Format message describing its sample rate etc. | Sender |
| MetatextDidl | Metadata relevant to a portion of a track. May be sent [0..n] times during a track. Uses DIDL-Lite. | Sender |
| MetatextOh | Metadata relevant to a portion of a track. May be sent [0..n] times during a track. Uses OpenHome Metadata format. Note that a uri does not need to be specified. | Sender |
| Halt | Indicates that a break in audio follows. E.g. at the end of a track with no further tracks to be played, or when the Sender has paused. | Sender |
| Disconnect | Indicates that the originator of the message is closing its SCD session. No further audio will be available. The message receiver should disconnect its socket. | Receiver & Sender |
| Seek | Indicates that the Receiver wants to jump to a different point in the current track. Is only sent for tracks that the Sender has indicated support seeking. | Receiver |
| Skip | Indicates that the Receiver wants to immediately jump to the next or previous track. | Receiver |
A SCD session is initiated by the Sender. It instantiates a simple TCP server then instructs the Receiver to start playing from it.
The Receiver connects to the Sender and sends a Ready message, indicating the protocol version it supports. If the Sender is compatible with this version, it responds with a Ready message stating the same version. Otherwise, the Sender sends a Ready message stating the version it supports. If the Receiver cannot support this version, it must close the connection.
After sending a Ready message, the Sender should send either Halt (if it has nothing to send yet) or one of MetadataDidl or MetadataOh plus Format. The order of Format versus Metadata* is not important.
After this, the Sender should then send Audio. Any number of Audio messages can be sent until the end of the stream is reached. Metatext messages (either Didl or Oh) may be interleaved with Audio.
A Halt message implies that a break in audio may follow. If this break is during a stream, the Sender must have applied attenuation to samples immediately before this to avoid any audio artifacts at the break in transmission. Senders which cannot do this should implement pausing of streams using the Transport.Pause control API instead.
The details of the wire protocol are shown below. Note that all multi-byte integer values are big endian.
| Bytes | Name | Description |
|---|---|---|
| Header | Prefixes to all messages below | |
| 4 | Signature | 0x73, 0x63, 0x64,0x20 ('scd ') |
| 1 | Type | The type of message:
|
| 2 | Length | Length in bytes of the whole message including this header |
| 4 | Reserved | Unused, reserved for future use |
| Ready | ||
| 2 | Major Version | 1 |
| 2 | Minor Version | 0 |
| MetadataDidl | ||
| 2 | TrackUriLength | Length, in bytes, of the track URI |
| m | TrackUri | The track URI, where m = TrackUriLength |
| 2 | MetadataLength | Length, in bytes, of the track metadata, in DIDL-Lite format |
| n | Metadata | The track metadata, where n = MetadataLength |
| MetadataOh | ||
| 1 | Count | Number of key-value pairs that follow |
| 1 | KeyLength | Length, in bytes, of the key |
| p | Key | Key for the metadata element, where p = KeyLength |
| 2 | ValueLength | Length, in bytes, of the value |
| q | Value | Value for the metadata element, where q = ValueLength |
| ... | ... | Repeat key-value pairs for all Count metadata elements |
| Format | ||
| 1 | BitDepth | Bit depth of the following audio |
| 4 | SampleRate | Sample rate of the following audio |
| 1 | Channels | Number of channels of the following audio |
| 4 | BitRate | Bit rate of the following audio |
| 8 | SampleStart | Sample position of the first sample in the next Audio message |
| 8 | SamplesTotal | Total number of samples in the following audio (requirement for this to be confirmed) |
| 1 | Flags |
|
| 1 | CodecNameLength | Length, in bytes, of the codec name |
| r | CodecName | The codec name, where r = CodecNameLength |
| FormatDsd | ||
| 4 | SampleRate | Sample rate of the following audio |
| 1 | Channels | Number of channels of the following audio |
| 2 | SampleBlockBits | Block size (in bits) of DSD data. 2 for stereo where left/right channels are interleaved, 16 for stereo with one byte of left subsamples followed by one byte of right subsamples, etc. |
| 8 | SampleStart | Sample position of the first sample in the next Audio message |
| 8 | SamplesTotal | Total number of samples in the following audio (requirement for this to be confirmed) |
| 1 | Flags |
|
| 1 | CodecNameLength | Length, in bytes, of the codec name |
| r | CodecName | The codec name, where r = CodecNameLength |
| Audio | ||
| 2 | NumSamples | The number of audio samples in this message |
| s | AudioData | Audio data. Where s = NumSamples * (BitDepth/8) * NumChannels. Multi-channel audio must supply data sample at a time, with left channel first. Audio is packed (i.e. no padding bytes rounding samples up to 32-bit boundaries) and big endian. |
| MetatextDidl | ||
| 2 | Metatext Length | Length, in bytes, of the metatext, in DIDL-Lite format |
| n | Metatext | The metatext, where n = MetatextLength |
| MetatextOh | ||
| 1 | Count | Number of key-value pairs that follow |
| 1 | KeyLength | Length, in bytes, of the key |
| p | Key | Key for the metatext element, where p = KeyLength |
| 2 | ValueLength | Length, in bytes, of the value |
| q | Value | Value for the metatext element, where q = ValueLength |
| ... | ... | Repeat key-value pairs for all Count metatext elements |
| Halt | ||
| No message body (only header required) | ||
| Disconnect | ||
| No message body (only header required) | ||
| Seek | ||
| To be confirmed | ||
| Skip | ||
| To be confirmed |