From OpenHome

(Difference between revisions)
Jump to: navigation, search
Simonc (Talk | contribs)
(Created page with "= Transport Service = == Overview == The Transport service provides both source-independent control of play, pause, stop, skip and seek and information concerning the currently p...")
Newer edit →

Revision as of 18:05, 14 December 2015

Contents

Transport Service

Overview

The Transport service provides both source-independent control of play, pause, stop, skip and seek and information concerning the currently playing media.

Summary information is provided in a number of levels, each of which have a URI and metadata in OpenHome Metadata format. E.g. A (notional) internet radio service that broadcast information about the currently playing track may have a level describing the radio station then another level describing the track. Control points with limited screen estate may choose to display the most derived level(s) of metadata that are available.

In addition to a hierarchy of metadata, detailed information such as bit-rate, sample-rate, bit-depth is available describing what is currently playing.

If a device's Product service reports an attribute "Transport", then that device is guaranteed to bear the Transport service. If the Transport service is available, all its properties and actions must be fully implemented.

Evented Properties

Modes

Space separated list of available modes.

LevelCount

The number of levels of information (uri / metadata) provided by this device. Does not vary at run-time.

Mode

The currently active mode

SequenceNumbers

A space-separated list of integers that change when their associated uri and/or metadata are updated. A value of 0 implies that both the associated uri and metadata are empty.

StreamCount

Changes when each new stream is played.

Indicates a change in one or more stream encoding parameters (Duration, Seekable, Pausable, BitRate, BitDepth, SampleRate, Lossless, CodecName).

A value of 0 can be assumed to imply empty/0/false values for all stream-specific data.

MetatextCount

Changes whenever metatext changes.

NextAvailable

true if the Next (skip forwards) action is currently available; false otherwise.

This will only change when Mode changes. A mode that is sometimes capable of changing stream as a consequence of Next will always report NextAvailable as true.

PrevAvailable

true if the Prev (skip backwards) action is currently available; false otherwise.

This will only change when Mode changes. A mode that is sometimes capable of changing stream as a consequence of Prev will always report PrevAvailable as true.

StreamId

Integer id, uniquely identifying the current stream.

Duration

The length of the currently playing stream in seconds.

Seekable

true if the SeekSecondsAbsolute and SeekSecondsRelative actions are available for the current stream; false otherwise.

Pausable

true if the stream can be paused (so is not being played at a rate determined by a remote sender); false otherwise.

BitRate

Dataflow rate in bits per second of the currently playing stream in its encoded representation.

BitDepth

Sample (data) resolution in bits per channel sample of the currently playing stream.

SampleRate

Time resolution of samples per second in kHz of the currently playing stream.

Lossless

Indication of whether the currently playing stream can be decoded (decompressed) to a bit-accurate representation of the original audio data (lossless) or merely to a good approximation (lossy encoding).

CodecName

Shorthand name for the audio encoding and container format used to represent the currently playing stream (e.g. AAC).

Metatext

Additional textual information (if any) associated with the currently playing stream.

TransportState

One of

  • Playing
  • Paused
  • Stopped
  • Buffering
  • Waiting

Actions

PlayAs

Arguments: (in string mode, in string command)
Start a new stream playing, specifying both a mode (source) to be used and a mode-specific command which describes the track to be played. Common options for modes and commands are documented separately.

Play

Arguments: None
Start a pending stream playing.

A stream must be ready to play. Possibly via calls to another network service.

Behaviour when a stream is already playing varies depending on the active modes (source).

Pause

Arguments: None
Pause the current stream.

Returns a 801 fault code if the current channel does not support being paused (is being played at a rate determined by a remote sender).

Stop

Arguments: None Stop the current stream.

Next

Arguments: (in uint streamId)
Move to the next stream (i.e. skip forwards). Determination of what comes next may vary between sources/modes. If TransportState is Stopped or Paused, try to start playing.

Returns a 801 fault code if the current channel does not support skipping forwards.

Prev

Arguments: (in uint streamId)
Move to the previous stream (i.e. skip backwards). If TransportState is Stopped or Paused, try to start playing.

Returns a 801 fault code if the current channel does not support skipping backwards.

SeekSecondsAbsolute

Arguments: (in uint streamId, in uint secondsAbsolute)
Seek to an absolute position in the current stream. If TransportState is Stopped or Paused, try to start playing.

Returns a 801 fault code if the current stream does not support seek. brReturns a 803 fault code if the seek position is beyond the end of the stream.

SeekSecondsRelative

Arguments: (in uint streamId, in int secondsRelative)
Seek to a position relative to what's currently playing in the current stream. If TransportState is Stopped or Paused, try to start playing.

Returns a 801 fault code if the current stream does not support seek. brReturns a 803 fault code if the seek position is beyond the end of the stream.

TransportState

Arguments: (out string state)
Read the current value of the TransportState property.

Modes

Arguments: (out string modes)
Return the value of the Modes property.

Counters

Arguments: (out string seq, out uint stream, out uint metatext)
Read the values of the sequence numbers associated with each level of information plus the counters for current stream details.

ModeInfo

Arguments: (out string mode, out bool nextAvailable, out bool prevAvailable)
Reports the values of the Mode, NextAvailable and PrevAvailable properties.

LevelInfo

Arguments: (in uint index, out string uri, out string metadata)
Reports uri & metadata for the specified level (a zero-based index into the SequenceNumbers array).

StreamInfo

Arguments:
(out uint streamId, out string uri, out bool seekable, out bool pausable, out uint durationSecs, out uint bitRate, out uint bitDepth, out uint SampleRate, out bool lossless, out string codec)

Reports current stream information:

  • StreamId
  • Uri
  • Seekable
  • Pausable
  • Duration
  • BitRate
  • BitDepth
  • SampleRate
  • Lossless
  • CodecName

StreamId

Arguments: (out uint streamId)
Read the current value of the StreamId property.

Metatext

Arguments: (out string text)
Read the current value of the Metatext property.

UPnP Service Description

For devices supporting the UPnP protocol, the service description is

name: "Transport" brdomain: "openhome.org.eriskay" brversion: "1" 

<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
  <specVersion>
    <major>1</major>
    <minor>0</minor>
  </specVersion>
 
  <actionList>
    <action>
      <name>PlayAs</name>
      <argument>
        <name>Mode</name>
        <direction>in</direction>
        <relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
      </argument>
      <argument>
        <name>Command</name>
        <direction>in</direction>
        <relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
      </argument>
    </action>
    <action>
      <name>Play</name>
    </action>
    <action>
      <name>Pause</name>
    </action>
    <action>
      <name>Stop</name>
    </action>
    <action>
      <name>Next</name>
      <argumentList>
        <argument>
          <name>StreamId</name>
          <direction>in</direction>
          <relatedStateVariable>StreamId</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Prev</name>
      <argumentList>
        <argument>
          <name>StreamId</name>
          <direction>in</direction>
          <relatedStateVariable>StreamId</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>SeekSecondsAbsolute</name>
      <argumentList>
        <argument>
          <name>StreamId</name>
          <direction>in</direction>
          <relatedStateVariable>StreamId</relatedStateVariable>
        </argument>
        <argument>
          <name>SecondsAbsolute</name>
          <direction>in</direction>
          <relatedStateVariable>A_ARG_TYPE_uint</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>SeekSecondsRelative</name>
      <argumentList>
        <argument>
          <name>StreamId</name>
          <direction>in</direction>
          <relatedStateVariable>StreamId</relatedStateVariable>
        </argument>
        <argument>
          <name>SecondsRelative</name>
          <direction>in</direction>
          <relatedStateVariable>A_ARG_TYPE_int</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>TransportState</name>
      <argumentList>
        <argument>
          <name>State</name>
          <direction>out</direction>
          <relatedStateVariable>TransportState</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Modes</name>
      <argumentList>
        <argument>
          <name>Modes</name>
          <direction>out</direction>
          <relatedStateVariable>Modes</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Counters</name>
      <argumentList>
        <argument>
          <name>SequenceNumbers</name>
          <direction>out</direction>
          <relatedStateVariable>SequenceNumbers</relatedStateVariable>
        </argument>
        <argument>
          <name>StreamCount</name>
          <direction>out</direction>
          <relatedStateVariable>StreamCount</relatedStateVariable>
        </argument>
        <argument>
          <name>MetatextCount</name>
          <direction>out</direction>
          <relatedStateVariable>MetatextCount</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>LevelInfo</name>
      <argumentList>
        <argument>
          <name>Index</name>
          <direction>out</direction>
          <relatedStateVariable>A_ARG_TYPE_uint</relatedStateVariable>
        </argument>
        <argument>
          <name>Uri</name>
          <direction>out</direction>
          <relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
        </argument>
        <argument>
          <name>Metadata</name>
          <direction>out</direction>
          <relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>ModeInfo</name>
      <argumentList>
        <argument>
          <name>Mode</name>
          <direction>out</direction>
          <relatedStateVariable>Mode</relatedStateVariable>
        </argument>
        <argument>
          <name>NextAvailable</name>
          <direction>out</direction>
          <relatedStateVariable>NextAvailable</relatedStateVariable>
        </argument>
        <argument>
          <name>PrevAvailable</name>
          <direction>out</direction>
          <relatedStateVariable>PrevAvailable</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>StreamInfo</name>
      <argumentList>
        <argument>
          <name>StreamId</name>
          <direction>out</direction>
          <relatedStateVariable>StreamId</relatedStateVariable>
        </argument>
        <argument>
          <name>Uri</name>
          <direction>out</direction>
          <relatedStateVariable>A_ARG_TYPE_string</relatedStateVariable>
        </argument>
        <argument>
          <name>Seekable</name>
          <direction>out</direction>
          <relatedStateVariable>Seekable</relatedStateVariable>
        </argument>
        <argument>
          <name>Pausable</name>
          <direction>out</direction>
          <relatedStateVariable>Pausable</relatedStateVariable>
        </argument>
        <argument>
          <name>Duration</name>
          <direction>out</direction>
          <relatedStateVariable>Duration</relatedStateVariable>
        </argument>
        <argument>
          <name>BitRate</name>
          <direction>out</direction>
          <relatedStateVariable>BitRate</relatedStateVariable>
        </argument>
        <argument>
          <name>BitDepth</name>
          <direction>out</direction>
          <relatedStateVariable>BitDepth</relatedStateVariable>
        </argument>
        <argument>
          <name>SampleRate</name>
          <direction>out</direction>
          <relatedStateVariable>SampleRate</relatedStateVariable>
        </argument>
        <argument>
          <name>Lossless</name>
          <direction>out</direction>
          <relatedStateVariable>Lossless</relatedStateVariable>
        </argument>
        <argument>
          <name>CodecName</name>
          <direction>out</direction>
          <relatedStateVariable>CodecName</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>StreamId</name>
      <argumentList>
        <argument>
          <name>StreamId</name>
          <direction>out</direction>
          <relatedStateVariable>StreamId</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Metatext</name>
      <argumentList>
        <argument>
          <name>Metatext</name>
          <direction>out</direction>
          <relatedStateVariable>Metatext</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
  </actionList>
 
  <serviceStateTable>
    <stateVariable sendEvents="yes">
      <name>Modes</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>LevelCount</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Mode</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>SequenceNumbers</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>StreamCount</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>MetatextCount</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>NextAvailable</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>PrevAvailable</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>StreamId</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Duration</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Seekable</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Pausable</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>BitRate</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>BitDepth</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>SampleRate</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Lossless</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>CodecName</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Metatext</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>TransportState</name>
      <dataType>string</dataType>
      <allowedValueList>
        <allowedValue>Playing</allowedValue>
        <allowedValue>Paused</allowedValue>
        <allowedValue>Stopped</allowedValue>
        <allowedValue>Buffering</allowedValue>
        <allowedValue>Waiting</allowedValue>
      </allowedValueList>
    </stateVariable>
    <stateVariable sendEvents="no">
      <name>A_ARG_TYPE_uint</name>
      <dataType>ui4</dataType>
    </stateVariable>
    <stateVariable sendEvents="no">
      <name>A_ARG_TYPE_int</name>
      <dataType>i4</dataType>
    </stateVariable>
    <stateVariable sendEvents="no">
      <name>A_ARG_TYPE_string</name>
      <dataType>string</dataType>
    </stateVariable>
  </serviceStateTable>
</scpd>
Retrieved from "http://wiki.openhome.org/wiki/Av:Developer:Eriskay:TransportService"