CSS-TS Message objects

Module: dvbcss.protocol.ts

A SetupData object represents a setup-data message sent by a client to a server immediately after opening a CSS-TS protocol connection.

A ControlTimestamp object represents a Control Timestamp message sent by the server to the client.

A AptEptLpt object represents an Actual, Earliest and Latest Presentation Timestamp message that may be sent by a client to the server.

The Timestamp objects are used in the above message objects to represent the relationship between wall clock time and content (timeline) time.

Examples

SetupData examples:

>>> from dvbcss.protocol.ts import SetupData
>>> from dvbcss.protocol import OMIT

>>> s = SetupData(timelineSelector="urn:dvb:css:timeline:pts", ciStem="dvb://1004")
>>> s.pack()
'{"timelineSelector": "urn:dvb:css:timeline:pts", "contentIdStem": "dvb://1004"}'

>>> jsonMessage = \"""\
... { "timelineSelector":"urn:dvb:css:timeline:temi:1:1",
...   "contentIdStem":""
... }
... \"""
>>> SetupData.unpack(jsonMessage)
SetupData(ciStem="", timelineSelector="urn:dvb:css:timeline:temi:1:1", private=OMIT)

ControlTimestamp examples:

>>> from dvbcss.protocol.ts import ControlTimestamp, Timestamp

>>> t = Timestamp(contentTime=12345, wallClockTime=900028432)
>>> ct = ControlTimestamp(timestamp=t, timelineSpeedMultiplier=1)
>>> ct.pack()
'{"timelineSpeedMultiplier": 1.0, "wallClockTime": "900028432", "contentTime": "12345"}'

>>> jsonMessage = \"""\
... { "contentTime" : "1003847",
...   "wallClockTime" : "348957623498576",
...   "timelineSpeedMultiplier" : 2.0
... }
... \"""
>>> c = ControlTimestamp.unpack(jsonMessage)
>>> c.timestamp.contentTime
1003847
>>> c.timestamp.wallClockTime
348957623498576
>>> c.timelineSpeedMultiplier
2.0

Actual, Earliest and Latest Presentation Timestamp examples:

>>> from dvbcss.protocol.ts import AptEptLpt, Timestamp

>>> te = Timestamp(contentTime=123465, wallClockTime=float("-inf"))
>>> tl = Timestamp(contentTime=123465, wallClockTime=float("+inf"))
>>> ael = AptEptLpt(earliest=te, latest=tl)
>>> ael.pack()
'{"earliest": {"wallClockTime": "minusinfinity", "contentTime": "123465"}, "latest": {"wallClockTime": "plusinfinity", "contentTime": "123465"}}'

>>> jsonMessage = \"""\
... { "earliest" : { "contentTime" : "1000", "wallClockTime": "10059237" },
...   "latest"   : { "contentTime" : "1000", "wallClockTime": "19284782" },
...   "actual"   : { "contentTime" : "1005", "wallClockTime": "10947820" }
... }
... \"""
>>> ael=AptEptLpt.unpack(jsonMessage)
>>> ael.actual.contentTime
1005
>>> ael.actual.wallClockTime
10947820

+/- infinity

For certain timestamp messages it is permissible to convey a time value that is either plus or minus infinity. Use the python float to express these values as follows:

>>> float("+inf")
inf

>>> float("-inf")
-inf

Classes

setup-data

class dvbcss.protocol.ts.SetupData(contentIdStem, timelineSelector, private=OMIT)

Object representing a CSS-TS Setup-Data message.

This carries a content identifier stem and a timeline selector string, and is used, in effect, to request the timeline to be synchronised to via the CSS-TS protocol.

Initialisation takes the following parameters:

Parameters:

• contentIdStem (str) – The content identifier stem.
• timelineSelector (str) – The timeline selector
• private (OMIT or Signalling that a property is to be omitted from a message) – Optional private data.

The attributes of the object have the same name as the SetupData message properties:

• contentIdStem
• timelineSelector
• private

Converting to and from JSON representation is performed using the pack() method and unpack() class method. Properties set to equal OMIT will be omitted when the message is packed to a JSON representation.

contentIdStem

(read/write str) The stem (subset starting from the LHS) of a content identifier

timelineSelector

(read/write str) The timeline selector

private = OMIT

(read/write OMIT or Signalling that a property is to be omitted from a message) Optional private data.

copy()

Returns:a copy of this SetupData object. Note that this does NOT deep copy any private data.

pack()

Returns:string containing JSON representation of this message. Throws ValueError:  if there are values for properties that are not permitted.

classmethod unpack(msg)

Convert JSON string representation of this message encoded as a SetupData object.

Throws ValueError:  if not possible.

Control Timestamp

class dvbcss.protocol.ts.ControlTimestamp(timestamp, timelineSpeedMultiplier)

Object representing a CSS-TS Control Timestamp message.

Initialisation takes the following parameters:

Parameters:

• timestamp (Timestamp) – carries the contentTime and wallClockTime properties of the Control Timestamp
• timelineSpeedMultiplier (float or None) – the timeline speed multiplier

The attributes of the object have the following relationship to the message properties:

• timestamp
• timelineSpeedMultiplier

Converting to and from JSON representation is performed using the pack() method and unpack() class method.

timestamp

(read/write Timestamp) Timestamp object representing the contentTime and wallClockTime parts of the timestamp)

timelineSpeedMultiplier

(read/write float or None) Timeline speed. For example: 1 = normal, 0 = pause, -0.5 = half speed reverse. Use None only when the Control Timestamp is supposed to indicate that the timeline is unavailable.

copy()

Returns:a deep copy of this Control Timestamp object

pack()

Returns:string containing JSON representation of this message. Throws ValueError:  if there are values for properties that are not permitted.

classmethod unpack(msg)

Convert JSON string representation of this message encoded as a ControlTimestamp object.

Throws ValueError:  if not possible.

AptEptLpt (Actual, Earliest and Latest Presentation Timestamp)

class dvbcss.protocol.ts.AptEptLpt(actual=OMIT, earliest=Timestamp(contentTime=0, wallClockTime=-inf), latest=Timestamp(contentTime=0, wallClockTime=inf))

Object representing a CSS-TS Actual, Earliest and Latest Presentation Timestamp message.

Initialisation takes the following parameters:

Parameters:

• actual (OMIT or Timestamp) – Optional timestamp representing the actual presentation timing
• earliest (OMIT or Timestamp) – Timestamp representing the earliest possible presentation timing
• latest (OMIT or Timestamp) – Timestamp representing the latest possible presentation timing

For the actual presentation timestamp, the contentTime and wallClockTime must both be non-null integer values.

For the earliest presentation timestamp, the contentTime must be a non-null integer. wallClockTime can be a non-null integer or plus infinity

For the latest presentation timestamp, the contentTime must be a non-null integer. wallClockTime can be a non-null integer or minus infinity

The attributes of the object have the same names as the Actual, Earliest and Latest presentation timestamp message properties:

• actual
• earliest
• latest

Converting to and from JSON representation is performed using the pack() method and unpack() class method. If values of properties do not meet the requirements described above, then pack() will raise ValueError exceptions.

actual

(read/write OMIT or Timestamp) Actual presentation timestamp

earliest

(read/write Timestamp) Earliest presentation timestamp. The wallClockTime property must be an int or float("+inf"). It must not be float("-inf").

latest

(read/write Timestamp) Latest presentation timestamp. The wallClockTime property must be an int or float("-inf"). It must not be float("+inf").

copy()

Returns:a deep copy of this AptEptLpt object

pack()

Returns:string containing JSON representation of this message. Throws ValueError:  if there are values for properties that are not permitted.

classmethod unpack(msg)

Convert JSON string representation of this message encoded as a AptEptLpt object.

Throws ValueError:  if not possible.

Timestamp

This object does not directly represent a message, but is instead used by ControlTimestamp and AptEptLpt as a representation of a correlation between a content time and a wall clock time.

class dvbcss.protocol.ts.Timestamp(contentTime, wallClockTime)

Object representing a Timestamp part(s) of a ControlTimestamp or AptEptLpt object.

Initialisation takes the following parameters:

Parameters:

• contentTime (None or int) – The content time (time on timeline) part of a timestamp
• wallClockTime (int or +/- infinity float (“+inf”) or float (“-inf”)) – The wall clock time part of a timestamp

The values for contentTime and wallClockTime are allowed to be arbitrarily large precision integers because they are carried as a string in the JSON representation.

The attributes of the object have the same name as the corresponding message properties:

• contentTime
• wallClockTime

Converting to and from JSON representation is performed using the pack() method and unpack() class method.

contentTime

(read/write None or large int) The content time part of a timestamp

wallClockTime

(read/write large int or float("+inf") or float("-inf") ) The wall clock time part of a timestamp