CII Message¶

class dvbcss.protocol.cii.CII(**kwargs)[source]¶

Object representing a CII message used in the CSS-CII protocol.

Initialisation takes the following parameters, all of which are optional keyword arguments that default to OMIT :

Parameters:

protocolVersion (OMIT or “1.1”) – The protocol version being used by the server. mrsUrl (OMIT or str) – The URL of an MRS server known to the server. contentId (OMIT or str) – Content identifier URI. contentIdStatus (OMIT or “partial” or “final”) – Content identifier status. presentationStatus (OMIT or list of str) – Presentation status as a list of one or more strings, e.g. [ "okay" ] wcUrl (OMIT or str) – CSS-WC server endpoint URL in the form “udp://<host>:<port>” tsUrl (OMIT or str) – CSS-TS server endpoint WebSocket URL teUrl (OMIT or str) – CSS-TE server endpoint WebSocket URL timelines (OMIT or list of TimelineOption) – List of timeline options. private (OMIT or Signalling that a property is to be omitted from a message) – Private data.

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

• protocolVersion
• mrsUrl
• contentId
• contentIdStatus
• presentationStatus
• wcUrl
• tsUrl
• teUrl
• timelines
• private

Properties are accessed as attributes of this object using the same name as their JSON property name.

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.

protocolVersion = OMIT[source]¶

(read/write OMIT or “1.1”) The protocol version being used by the server.

mrsUrl = OMIT[source]¶

(read/write OMIT or str) The URL of an MRS server known to the server

contentId = OMIT[source]¶

(read/write OMIT or str) Content identifier (URL)

contentIdStatus = OMIT[source]¶

(read/write OMIT or “partial” or “final”) Content identifier status

presentationStatus = OMIT[source]¶

(read/write OMIT or list of str) Presentation status, e.g. [ "okay" ]

wcUrl = OMIT[source]¶

(read/write OMIT or str) CSS-WC server endpoint URL in form “udp://<host>:<port>”

tsUrl = OMIT[source]¶

(read/write OMIT or str) CSS-TS server endpoint WebSocket URL

teUrl = OMIT[source]¶

(read/write OMIT or str) CSS-TE server endpoint WebSocket URL

timelines = OMIT[source]¶

(read/write OMIT or list`(:class:`TimelineOption)) Timeline options

private = OMIT[source]¶

(OMIT or list of dict ) Private data as a list of dict objects that can be converted to JSON by json.dumps(). Each dict must contain at least a key called “type” with a URI string as its value.

classmethod allProperties()[source]¶

Returns a list of all property names, whether OMITted or not

combine(diff)[source]¶

Copies this CII object, and updates that copy with any properties (that are not omitted) in the CII object supplied as the diff argument. The updated copy is then returned.

Parameters:	diff – (CII) A CII object whose properties (that are not omitted) will be used to update the copy before it is returned.

new = old.combine(diff) is equivalent to the following operations:

new = old.copy()
new.update(diff)

copy()[source]¶

Returns:	a copy of this CII object. The copy is a deep copy.

definedProperties()[source]¶

Returns a list of the names of properties whose value is not OMIT

classmethod diff(old, new)[source]¶

Parameters:	old – (CII) A CII object new – (CII) A CII object
Returns:	CII object representing changes from old to new CII objects.

If in the new CII object a property is OMITted, it property won’t appear in the returned CII object that represents the changes.

If in the old CII object a property is OMITted, but it has a non-omitted value in the new object, then it is assumed to be a change.

pack()[source]¶

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

classmethod unpack(msg)[source]¶

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

Throws ValueError:
	if not possible.

update(diff)[source]¶

Updates this CII object with the values of any properties (that are not omitted) in the CII object provided as the diff argument.

Note that this changes this object.

Parameters:	diff – (CII) A CII object whose properties (that are not omitted) will be used to update this CII object.

Timeline Option¶

class dvbcss.protocol.cii.TimelineOption(timelineSelector, unitsPerTick, unitsPerSecond, accuracy=OMIT, private=OMIT)[source]¶

Object representing a CSS-CII Timeline Option used in the “timelines” property of a CII message.

Initialisation takes the following parameters:

Parameters:

timelineSelector (str) – The timeline selector unitsPerTick (int) – Denominator of tick rate (in ticks per second) for the corresponding timeline unitsPerSecond (int) – Numerator of tick rate (in ticks per second) for the corresponding timeline accuracy (OMIT or float) – Optional indication of timeline accuracy private (OMIT or Signalling that a property is to be omitted from a message) – Optional private data.

It represents a timeline selector and the tick rate of the timeline if that selector is used to request a timeline from the CSS-TS server. It is carried in a list in the timelines property of a CII message.

The tick rate of the timeline is expressed by the unitsPerTick and unitsPerSecond values. The tick rate in ticks per second is equal to unitsPerTick / unitsPerSecond.

Accuracy and private data are optional, but the other fields are mandatory.

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

• timelineSelector
• unitsPerTick
• unitsPerSecond
• accuracy
• 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.

timelineSelector = OMIT[source]¶

(str) The timeline selector

unitsPerTick = OMIT[source]¶

(int) The units per tick of the timeline

unitsPerSecond = OMIT[source]¶

(int) The units per second of the timeline

accuracy = OMIT[source]¶

(OMIT or float) The accuracy of the timeline with respect to the content in seconds.

private = OMIT[source]¶

(OMIT or list of dict ) Private data as a list of dict objects that can be converted to JSON by json.dumps(). Each dict must contain at least a key called “type” with a URI string as its value.

classmethod decode(struct)[source]¶

Internal method used by a CII message object when unpacking to JSON format.

classmethod encode(item)[source]¶

Internal class method used by a CII message object when packing to JSON format.

pack()[source]¶

Returns:	string containing JSON presentation of this message.

classmethod unpack(msg)[source]¶

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

Throws ValueError:
	if not possible.

CIIClient¶

class dvbcss.protocol.client.cii.CIIClient(ciiUrl)[source]¶

Manages a CSS-CII protocol connection to a CSS-CII Server and notifies of changes to CII state.

Use by subclassing and overriding the following methods:

• onConnected()
• onDisconnected()
• onChange()
• individual onXXXXChange() methods named after each CII property
• onCiiReceived() (do not use, by preference)

If you do not wish to subclass, you can instead create an instance of this class and replace the methods listed above with your own functions dynamically.

The connect() and disconnect() methods connect and disconnect the connection to the server and getStatusSummary() provides a human readable summary of CII state.

This object also provides properties you can query:

• cii represents the current state of CII at the server
• latestCII is the most recently CII message received from the server
• connected indicates whether the connection is currently connect

Initialisation takes the following parameters:

Parameters:	ciiUrl – (str) The WebSocket URL of the CSS-CII Server (e.g. “ws://127.0.0.1/myservice/cii”)

connected[source]¶

True if currently connected to the server, otherwise False.

cii[source]¶

(CII) CII object representing the CII state at the server

latestCII[source]¶

(CII or None) The most recent CII message received from the server or None if nothing has yet been received.

connect()[source]¶

Start the client by trying to open the connection.

Throws ConnectionError:
	There was a problem that meant it was not possible to connect.

disconnect()[source]¶

Disconnect from the server.

onChange(changedPropertyNames)[source]¶

This method is called when a CII message is received from the server that causes one or more of the CII properties to change to a different value.

Parameters:	changedPropertyNames – A list of str names of the properties that have changed. Query the cii attribute to find out the new values.

onCiiReceived(newCii)[source]¶

This method is called when a CII message is received, but before any ‘onXXXXChange()’ handlers (if any) are called. It is called even if the message does not result in a change to CII state held locally.

By preference is recommended to use the ‘onXXXXChange()’ handlers instead since these will only be called if there is an actual change to the value of a property in CII state.

This is a stub for this method. Sub-classes should implement it.

Parameters:	cii – A CII object representing the received message.

onConnected()[source]¶

This method is called when the connection is opened.

This is a stub for this method. Sub-classes should implement it.

onContentIdChange(newValue)[source]¶

Called when the contentId property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onContentIdStatusChange(newValue)[source]¶

Called when the contentIdStatus property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onDisconnected(code, reason=None)[source]¶

This method is called when the connection is closed.

This is a stub for this method. Sub-classes should implement it.

Parameters:	code – (int) The connection closure code to be sent in the WebSocket disconnect frame reason – (str or None) The human readable reason for the closure

onMrsUrlChange(newValue)[source]¶

Called when the mrsUrl property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onPresentationStatusChange(newValue)[source]¶

Called when the presentationStatus property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onPrivateChange(newValue)[source]¶

Called when the private property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onProtocolError(msg)[source]¶

This method is called when there has been an error in the use of the CII protocol - e.g. receiving the wrong kind of message.

This is a stub for this method. Sub-classes should implement it.

Parameters:	msg – A str description of the problem.

onProtocolVersionChange(newValue)[source]¶

Called when the protocolVersion property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onTeUrlChange(newValue)[source]¶

Called when the teUrl property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onTimelinesChange(newValue)[source]¶

Called when the timelines property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onTsUrlChange(newValue)[source]¶

Called when the tsUrl property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

onWcUrlChange(newValue)[source]¶

Called when the wcUrl property of the CII message has been changed by a state update from the CII Server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	newValue – The new value for this property.

CIIClientConnection¶

class dvbcss.protocol.client.cii.CIIClientConnection(url)[source]¶

Simple object for connecting to a CSS-CII server and handling the connection.

Use by subclassing and overriding the following methods:

• onConnected()
• onDisconnected()
• onCII()
• onProtocolError()

If you do not wish to subclass, you can instead create an instance of this class and replace the methods listed above with your own functions dynamically.

Initialisation takes the following parameters:

Param:	url (str) The WebSocket URL of the CII Server to connect to. E.g. “ws://127.0.0.1/mysystem/cii”

connect()[source]¶

Open the connection.

:throws ConnectionError if there was a problem and the connection could not be opened.

connected[source]¶

True if the connection is connect, otherwise False

disconnect(code=1001, reason='')[source]¶

Close the connection.

Parameters:	code – (optional int) The connection closure code to be sent in the WebSocket disconnect frame reason – (optional str) The human readable reason for the closure

onCII(cii)[source]¶

This method is called when a CII message is received from the server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	cii – A CII object representing the received message.

onConnected()[source]¶

This method is called when the connection is opened.

This is a stub for this method. Sub-classes should implement it.

onDisconnected(code, reason=None)[source]¶

This method is called when the connection is closed.

This is a stub for this method. Sub-classes should implement it.

Parameters:	code – (int) The connection closure code to be sent in the WebSocket disconnect frame reason – (str or None) The human readable reason for the closure

onProtocolError(msg)[source]¶

This method is called when there has been an error in the use of the CII protocol - e.g. receiving the wrong kind of message.

This is a stub for this method. Sub-classes should implement it.

Parameters:	msg – A str description of the problem.

1. Imports and initialisation¶

To run a CII server, you must import both ws4py’s cherrypy server and the dvbcss.protocol.server.cii module. When the dvbcss.protocol.server.cii module is imported, it will register as a “tool” with cherrypy, so it must be imported after cherrypy is imported.

Next, subscribe the ws4py websocket plugin to cherrypy.

import cherrypy
from ws4py.server.cherrypyserver import WebSocketPlugin
from dvbcss.protocol.server.cii import CIIServer

# initialise the ws4py websocket plugin
WebSocketPlugin(cherrypy.engine).subscribe()

2. Create and mount the CII server¶

You can now create an instance of a CIIServer and mount it into the cherrypy server at a path of your choosing.

The configuration for that path must turn on the “dvb_cii” tool and pass a “handler_cls” argument whose value is the handler class that the CIIServer instance provides via the CIIServer.handler attribute.

For example, to create a CIIServer mounted at the URL path “/cii”:

# create CII Server
ciiServer = CIIServer(maxConnectionsAllowed=2)

# bind it to the URL path /cii in the cherrypy server
class Root(object):
    @cherrypy.expose
    def cii(self):
        pass

# construct the configuration for this path, providing the handler and turning on the tool hook
cfg = {"/cii": {'tools.dvb_cii.on': True,
                'tools.dvb_cii.handler_cls': ciiServer.handler
               }
      }

cherrypy.tree.mount(Root(), "/", config=cfg)    

3. Start cherrypy running¶

Start cherrypy running and our CII server will start to accept connections from clients:

# configure cherrypy to serve on port 7681
cherrypy.config.update({"server.socket_port":7681})

# activate cherrypy web server (non blocking)
cherrypy.engine.start()

The cherrypy engine runs in a background thread when the cherrypy engine is started.

4. Setting CII state and pushing it to connected clients¶

The CIIServer.cii is a CII message object representing the CII state. Your code can read and alter the attributes of this message object to update the server side state.

When a client first connects, a CII message object will automatically be sent to that client to send it the current CII state. Your code does not need to do this.

If you update the CII state then you need to ask the CII server to push a change to all connected clients. To do this call the CIIServer.updateClients() method. By default this will only push changes to CII state, and will not send a message at all if there is no change. However this behaviour can be overridden.

ciiServer.cii.contentId = "dvb://233a.1004.1080"
ciiServer.cii.contentIdStatus = "partial"
ciiServer.updateClients()

...

ciiServer.cii.contentId = "dvb://233a.1004.1080;21af~20131004T1015Z--PT01H00M"
ciiServer.cii.contentIdStatus = "final"
ciiServer.updateClients()

CIIServer - CII Server handler for cherrypy¶

class dvbcss.protocol.server.cii.CIIServer(maxConnectionsAllowed=-1, enabled=True, initialCII=CII(protocolVersion='1.1'))[source]¶

The CIIServer class implements a server for the CSS-CII protocol. It transparently manages the connection and disconnection of clients and provides an interface for simply setting the CII state and requesting that it be pushed to any connected clients.

Must be used in conjunction with a cherrypy web server:

1. Ensure the ws4py WebSocketPlugin is subscribed, to the cherrypy server. E.g.

   WebSocketPlugin(cherrypy.engine).subscribe()
   

2. Mount the instance onto a particular URL path on a cherrypy web server. Set the config properties for the URL it is to be mounted at as follows:

   { 'tools.dvb_cii.on'         : True,
     'tools.dvb_cii.handler_cls': myCiiServerInstance.handler }
   

Update the cii property with the CII state information and call the updateClients() method to propagate state changes to any connected clients.

When the server is “disabled” it will refuse attempts to connect by sending the HTTP status response 403 “Forbidden”.

When the server has reached its connection limit, it will refuse attempts to connect by sending the HTTP status response 503 “Service unavailable”.

This object provides properties:

• enabled (read/write) controls whether this server is enabled or not
• cii (read/write) the CII state that is being shared to connected clients

Initialisation takes the following parameters:

Parameters:	maxConnectionsAllowed – (int, default=-1) Maximum number of concurrent connections to be allowed, or -1 to allow as many connections as resources allow. enabled – (bool, default=True) Whether the endpoint is initially enabled (True) or disabled (False) initialCII – (dvbcss.protocol.cii.CII, default=CII(protocolVersion=”1.1”)) Initial value of CII state.

cii[source]¶

A dvbcss.protocol.cii.CII message object representing current CII state. Set the attributes of this object to update that state.

When updateClients() is called, it is this state that will be sent to connected clients.

handler[source]¶

Handler class for new connections.

When mounting the CII server with cherrypy, include in the config dict a key ‘tools.dvb_cii.handler_cls’ with this handler class as the value.

enabled[source]¶

(read/write bool) Whether this server endpoint is enabled (True) or disabled (False).

Set this property enable or disable the endpoint.

When disabled, existing connections are closed with WebSocket closure reason code 1001 and new attempts to connect will be refused with HTTP response status code 403 “Forbidden”.

getConnections()[source]¶

Returns dict:	mapping a WebSocket object to connection related data for all connections to this server. This is a snapshot of the connections at the moment the call is made. The dictionary is not updated later if new clients connect or existing ones disconnect.

onClientConnect(webSock)[source]¶

If you override this method you must call the base class implementation.

onClientDisconnect(webSock, connectionData)[source]¶

If you override this method you must call the base class implementation.

onClientMessage(webSock, message)[source]¶

If you override this method you must call the base class implementation.

updateClients(sendOnlyDiff=True, sendIfEmpty=False)[source]¶

Send update of current CII state from the CIIServer.cii object to all connected clients.

Parameters:	sendOnlyDiff – (bool, default=True) Send only the properties in the CII state that have changed since last time a message was sent. Set to False to send the entire message. sendIfEmpty – (bool, default=False) Set to True to force that a CII message be sent, even if it will be empty (e.g. no change since last time)

By default this method will only send a CII message to clients informing them of the differencesin state since last time a message was sent to them. If no properties have changed at all, then no message will be sent.

The two optional arguments allow you to change this behaviour. For example, to force the messages sent to include all properties, even if they have not changed:

myCiiServer.updateClients(sendOnlyDiff=False)

To additionally force it to send even if the CII state held at this server has no values for any of the properties:

myCiiServer.updateClients(sendOnlyDiff=False, sendIfEmpty=True)

setup-data¶

class dvbcss.protocol.ts.SetupData(contentIdStem, timelineSelector, private=OMIT)[source]¶

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[source]¶

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

timelineSelector[source]¶

(read/write str) The timeline selector

private = OMIT[source]¶

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

copy()[source]¶

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

pack()[source]¶

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

classmethod unpack(msg)[source]¶

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)[source]¶

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[source]¶

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

timelineSpeedMultiplier[source]¶

(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()[source]¶

Returns:	a deep copy of this Control Timestamp object

pack()[source]¶

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

classmethod unpack(msg)[source]¶

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))[source]¶

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[source]¶

(read/write OMIT or Timestamp) Actual presentation timestamp

earliest[source]¶

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

latest[source]¶

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

copy()[source]¶

Returns:	a deep copy of this AptEptLpt object

pack()[source]¶

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

classmethod unpack(msg)[source]¶

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)[source]¶

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[source]¶

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

wallClockTime[source]¶

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

TSClientConnection¶

class dvbcss.protocol.client.ts.TSClientConnection(url, contentIdStem, timelineSelector)[source]¶

Simple object for connecting to a CSS-TS server (an MSAS) and handling the connection.

Use by subclassing and overriding the following methods or assigning your own functions to them at runtime:

• onConnected()
• onDisconnected()
• onControlTimestamp()
• onProtocolError()

If you do not wish to subclass, you can instead create an instance of this class and replace the methods listed above with your own functions dynamically.

Use the sendTimestamp() method to send Actual, Earliest and Latest Presentation Timestamps to the server.

This class has the following properties:

• connected (read only) whether the client is connected or not

Initialisation takes the following parameters:

Parameters:	url (str) – The WebSocket URL of the TS Server to connect to. E.g. “ws://127.0.0.1/mysystem/ts” contentIdStem (str) – The stem of the content id to be included in the SetupData message that is sent as soon as the connection is opened. timelineSelector (str) – The timeline selector to be included in the SetupData message that is sent as soon as the connection is opened.

connect()[source]¶

Open the connection.

Throws ConnectionError:
	if there was a problem and the connection could not be opened.

connected[source]¶

This property is True if the connection is connect, otherwise False

disconnect(code=1001, reason='')[source]¶

Close the connection.

Parameters:	code – (optional int) The connection closure code to be sent in the WebSocket disconnect frame reason – (optional str) The human readable reason for the closure

onConnected()[source]¶

This method is called when the connection is opened and the setup-data message has been sent.

This is a stub for this method. Sub-classes should implement it.

onControlTimestamp(controlTimestamp)[source]¶

This method is called when a Control Timestamp message is received from the server.

This is a stub for this method. Sub-classes should implement it.

Parameters:	controlTimestamp – A ControlTimestamp object representing the received message.

onDisconnected()[source]¶

This method is called when the connection is closed.

This is a stub for this method. Sub-classes should implement it.

onProtocolError(msg)[source]¶

This method is called when there has been an error in the use of the TS protocol - e.g. receiving the wrong kind of message.

This is a stub for this method. Sub-classes should implement it.

Parameters:	msg – A str description of the problem.

sendTimestamp(aptEptLpt)[source]¶

Send an Actual, Earliest and Latest Presentation Timestamp message to the TS Server.

Parameters:	aptEptLpt – The AptEptLpt object representing the Actual, Earliest and Latest Presentation Timestamp to be sent.

TSClientClockController¶

class dvbcss.protocol.client.ts.TSClientClockController(tsUrl, contentIdStem, timelineSelector, timelineClock, correlationChangeThresholdSecs=0.0001, earliestClock=None, latestClock=None)[source]¶

This class manages a CSS-TS protocol connection and controls a CorrelatedClock to synchronise it to the timeline provided by the server.

Subclass and override the following methods when using this class:

• onConnected()
• onDisconnected()
• onTimingChange()
• onTimelineAvailable()
• onTimelineUnavailable()
• onProtocolError()

If you do not wish to subclass, you can instead create an instance of this class and replace the methods listed above with your own functions dynamically.

Create an instance of this class and use the connect() and disconnect() methods to start and stop its connection to the server. The contentIdStem and timelineSelector you specify are sent to the server in a SetupData message to choose the timeline to receive from the server.

While connected, while the timeline is available, the timelineClock you provided will have its correlation updated to keep it in sync with the timeline received from the server.

The speed property of the timeline clock will also be adjusted to match the timeline speed indicated by the server. For example: it will be set to zero when the timeline is paused, or 2.0 when the timeline speed is x2. The tickRate property of the clock is not changed.

Requirements for the timeline clock you provide:

• The tickRate of the timeline clock must match that of the timeline.
• Its parent must represent the wall clock
• The wall clock must have a ~dvbcss.clock.CorrelatedClock.tickRate that matches the wall clock tick rate.

The TSClientClockController has the following properties:

• connected (read only) is the client connected?
• timelineAvailable (read only) is the timeline available?
• latestCt (read only) is the most recently received ControlTimestamp message
• earliestClock (read/write) A clock object representing earliest possible presentation timing, or None
• latestClock (read/write) A clock object representing latest possible presentation timing, or None

Initialisation takes the following parameters:

Parameters:

url (str) – The WebSocket URL of the TS Server to connect to. E.g. “ws://127.0.0.1/mysystem/ts” contentIdStem (str) – The stem of the content id to be included in the SetupData message that is sent as soon as the conncetion is opened. timelineSelector (str) – The timeline selector to be included in the SetupData message that is sent as soon as the conncetion is opened. timelineClock (CorrelatedClock) – A clock object whose parent must represent the wall clock. correlationChangeThresholdSecs (float) – Minimum threshold for the change in the timeline (in units of seconds) that will result in the timeline clock being adjusted. earliestClock (CorrelatedClock or None) – An optional clock object representing the earliest possible presentation timing that this client can achieve (expressed on the same timeline) latestClock (CorrelatedClock or None) – An optional clock object representing the latest possible presentation timing that this client can achieve (expressed on the same timeline)

connected[source]¶

(bool) True if currently connected to the server, otherwise False.

latestCt[source]¶

(ControlTimestamp) A copy of the most recently received Control Timestamp.

earliestClock[source]¶

None or a CorrelatedClock correlated to the WallClock representing the earliest possible presentation timing.

latestClock[source]¶

None or a CorrelatedClock correlated to the WallClock representing the latest possible presentation timing.

connect()[source]¶

Start the client by trying to open the connection.

If the connection opens successfully, a SetupData message will be sent automatically.

Throws ConnectionError:
	if there was a problem and the connection could not be opened.

disconnect()[source]¶

Disconnect from the server.

getStatusSummary()[source]¶

Returns str:	A human readable string describing the state of the timeline and the connection.

onConnected()[source]¶

This method is called when the connection is opened and the setup-data message has been sent.

This is a stub for this method. Sub-classes should implement it.

onDisconnected()[source]¶

This method is called when the connection is closed.

This is a stub for this method. Sub-classes should implement it.

onProtocolError(msg)[source]¶

This method is called when there has been an error in the use of the CII protocol - e.g. receiving the wrong kind of message.

This is a stub for this method. Sub-classes should implement it.

Parameters:	msg – A str description of the problem.

onTimelineAvailable()[source]¶

This method is called when the server indicates that the timeline is available.

This is a stub for this method. Sub-classes should implement it.

onTimelineUnavailable()[source]¶

This method is called when the server indicates that the timeline is unavailable.

This is a stub for this method. Sub-classes should implement it.

onTimingChange(speedChanged)[source]¶

This method is called when the server indicates that the timeline timing has changed.

This means that a received Control Timestamp has changed the timing of the clock relative to the wall clock by the threshold amount or more, or that the speed of the timeline has changed. (as indicated by the timelineSpeedMultiplier property of received Control Timestamps).

This is a stub for this method. Sub-classes should implement it.

Parameters:	speedChanged – (bool) True if the speed of the timeline has changed, otherwise False.

sendAptEptLpt(includeApt=True)[source]¶

Sends an Actual, Earliest and Latest presentation timestamp to the CSS-TS server.

• The EPT is derived from the earliestClock property, if it is not None and it is a clock that is available.
• The LPT is derived from the latestClock property, if it is not None and it is a clock that is available.
• The APT is only included if the includeApt argument is True (default=True) and it is a clock that is available.

Parameters:	includeApt – (bool) Set to False if the Actual Presentation Timestamp is not to be included in the message (default=True)

timelineAvailable[source]¶

(bool) True if the most recently received Control Timestamp indicates that the timeline is available.

Changed in version 0.4: It is now recommended to not use this method. Instead, use the isAvailable() method of a clock instead.

1. Imports and initialisation¶

To run a CSS-TS server, you must import both ws4py’s cherrypy server and the dvbcss.protocol.server.ts module. When the dvbcss.protocol.server.ts module is imported, it will register as a “tool” with cherrypy, so it must be imported after cherrypy is imported.

Next, subscribe the ws4py websocket plugin to cherrypy.

import cherrypy
from ws4py.server.cherrypyserver import WebSocketPlugin
from dvbcss.protocol.server.ts import TSServer

# initialise the ws4py websocket plugin
WebSocketPlugin(cherrypy.engine).subscribe()

2. Create and mount the TS server¶

You can now create an instance of a TSServer and mount it into the cherrypy server at a path of your choosing.

The configuration for that path (see example code below) must turn on the “dvb_ts” tool and pass a “handler_cls” argument whose value is the handler class that the TS Server instance provides via the TSServer.handler attribute.

The TS Server needs, at initialisation, to be told the initial contentId that it is providing timelines for and it also needs to be provided with a clock object representing the Wall Clock (ticking at the correct rate of 1e9 ticks per second). It needs the WallClock so it can set the WallClockTime property in Control Timestamps that notify clients of a timeline being unavailable.

For example, to create a TS Server mounted at the URL path “/ts”:

# create a Wall Clock
from dvbcss.clock import SysClock, CorrelatedClock
sysClock = SysClock()
wallClock = CorrelatedClock(parentClock=sysClock, tickRate=1000000000)

# create TS Server
tsServer = TSServer(contentId="dvb://1004", wallClock=wallClock, maxConnectionsAllowed=10)

# bind it to the URL path /ts in the cherrypy server
class Root(object):
    @cherrypy.expose
    def ts(self):
        pass

# construct the configuration for this path, providing the handler and turning on the tool hook
cfg = {"/ts": {'tools.dvb_ts.on': True,
                'tools.dvb_ts.handler_cls': tsServer.handler
               }
      }

cherrypy.tree.mount(Root(), "/", config=cfg)    

3. Start cherrypy running¶

Start cherrypy running and our TS server will start to accept connections from clients:

# configure cherrypy to serve on port 7681
cherrypy.config.update({"server.socket_port":7682})

# activate cherrypy web server (non blocking)
cherrypy.engine.start()

The cherrypy engine runs in a background thread when the cherrypy engine is started. Callbacks from the TSServer happen on the ws4py websocket library’s thread(s) for handling received messages.

4. Providing timelines through the TS Server¶

To make a timeline available to clients, we create a source for that timeline. For example, a SimpleClockTimelineSource based on a clock object that corresponds to the ticking of progress on the timeline. We also decide the timeline selector that clients must use to obtain that timeline.

For example, we might create a Timeline Source to represent ticking of a PTS timeline:

from dvbcss.protocol.server.ts import SimpleClockTimelineSource
from dvbcss.clock import Correlation

ptsClock = CorrelatedClock(parentClock=wallClock, tickRate=90000)
ptsTimelineSrc = SimpleClockTimelineSource(timelineSelector="urn:dvb:css:timeline:pts", wallClock=wallClock, clock=ptsClock)

# set that ptsClock to start counting from zero starting NOW:
ptsClock.correlation = Correlation(wallClock.ticks, 0)

When we want that timeline to become available to connected clients we add it to the TS Server:

tsServer.attachTimelineSource(ptsTimelineSrc)
tsServer.updateAllClients()

When we make any change (adding or removing timlelines, or changing a timeline in any way) then we must call TSServer.updateAllClients() to ensure Control Timestamp messages are sent immediately to all connected clients to notify them of any changes.

Any new client connections or existing connections, that ask for that timeline (using the timeline selector and matching the content id) will have the timeline made available to them.

If at some point the relationship between PTS and wall clock changes, or the clock availability changes, then we must instruct the TS Server to send new Control Timestamps out if needed:

# lets reset the pts timeline position to zero again
ptsClock.correlation = Correlation(wallClock.ticks, 0)
tsServer.updateAllClients()

When we want to make the timeline unavailable, we can simply update the availability of the clock:

ptsClock.setAvailability(False)
tsServer.updateAllClients()

Or if we wish to stop more permanently, we can instead detatch the timeline source from the TS Server:

tsServer.removeTimelineSource(ptsTimelineSrc)
tsServer.updateAllClients()

If there are clients connected that have asked for that timeline, then the update call will cause Control Timestamps to be sent to them that indicate that the timeline is no longer available.

We can also change the contentId for which the timelines are being provided. If we do this, then again, it may change whether timelines are available to any currently connected clients:

5. Changing content id¶

tsServer.contentId = "http://myservice.com/new-content-id"
tsServer.updateAllClients()

Exising timeline source implementations¶

Two implementations are provided:

• SimpleTimelineSource is a timeline source where you directly specify the Control Timestamp that will be sent to clients.
• SimpleClockTimelineSource is a timeline source where Control Timestamps are generated from Clock objects representing the position of the timeline and the Wall Clock.

The CSS-TS server does not automatically push out new Control Timestamps to connected clients. It will only do so when the updateAllClients() or updateClient() methods are called. This allows you to do things like swap out and replace a timeline source object without causing spurious Control Timestamps to be sent.

Creating new Timeline Sources¶

Create new Timeline Source types by subclasing TimelineSource and, at minimum, implementing the stubs recognisesTimelineSelector() and getControlTimestamp().

For example, here is a timeline source that recognises a timeline selector “urn:pretend-timeline:N” where N is the ticks per second of the timeline. The progress of this timeline is controlled by the code outside of this object periodcally calling the setTimelinePositionNow method. It needs a clock object representing the WallClock to be passed to it. It can serve different tick rates to different clients.

from dvbcss.protocol.server.ts import TimelineSource
from dvbcss.protocol.ts import ControlTimestamp, Timestamp
from dvbcss.clock import Correlation
import re

class PretendTimelineSource(TimelineSource):
    def __init__(self, wallClock):
        super(PretendTimelineSource,self).__init__()
        self.wallClock = wallClock
        self.correlation = Correlation(0,0)
                
    def recognisesTimelineSelector(self, timelineSelector):
        return re.match("^urn:pretend-timeline:([0-9]+)$", timelineSelector)
    
    def getControlTimestamp(self, timelineSelector):
        match = re.match("^urn:pretend-timeline:([0-9]+)$", timelineSelector)
        if not match:
            raise RuntimeError("This should never happen.")
        elif self.correlation is None:
            # timeline not yet available, so return 'null' control timestamp
            return ControlTimestamp(Timestamp(None, self.wallClock.ticks), None)
        else:
            tickRate = int(match.group(1))
            contentTime = tickRate * self.correlation.childTicks
            wallClockTime = self.correlation.parentTicks
            speed = 1
            return ControlTimestamp(Timestamp(contentTime, wallClockTime), speed)

    def setTimelinePositionNow(self, timelineSecondsNow):
        self.correlation = Correlation(self.wallClock.nanos, timelineSecondsNow)

The base class also has stub methods to support notification of when a sink is attached to the timeline source and also methods to notify of when a particular timeline selector is being requested by at least one client and when it is no longer required by any clients. See the documentation for TimelineSource for more details.

TSServer¶

class dvbcss.protocol.server.ts.TSServer(contentId, wallClock, maxConnectionsAllowed=-1, enabled=True)[source]¶

Implements a server for the CSS-TS protocol that serves timelines provided by sources that are plugged into this server object.

Use by instantiating. You may subclass if you wish to optionally override the following methods:

• onClientConnect()
• onClientDisconnect()
• onClientMessage()
• onClientSetup()

When the server is “disabled” it will refuse attempts to connect by sending the HTTP status response 403 “Forbidden”.

When the server has reached its connection limit, it will refuse attempts to connect by sending the HTTP status response 503 “Service unavailable”.

This object has the following properties:

• enabled (read/write) controls whether the server is enabled
• contentId (read/write) controls the contentId that timelines are being served for
• handler (read) the class that must be passed as part of the cherrypy configuration for the URL path this server is attached to.

The contentId and enabled attributes can be changed at runtime. Whether the contentId matches that provided by a client when it initially connects is part of determining whether the timeline is available to the client.

Use attachTimelineSource() and removeTimelineSource() to add and remove sources of timelines. Adding or removing a source of a timeline will affect availablilty of a timeline to a client.

This server does not automatically send Control Timestamp messages to clients. After you make a change (e.g. to the contentId or a state change in a timeline source or attaching or removing a timeline source) then you must call updateAllClients() to cause messages to be sent.

The only exception to this is changes to the enabled state which takes effect immediately.

Initialisation takes the following parameters:

Parameters:	contentId (str) – The content-id for which timelines will be made available. wallClock (clock) – The wall clock maxConnectionsAllowed (int) – (int, default=-1) Maximum number of concurrent connections to be allowed, or -1 to allow as many connections as resources allow. enabled (bool) – Whether this server starts off enabled or disabled.

contentId[source]¶

(read/write str) The content ID for all timelines currently being served. Can be changed at runtime.

handler[source]¶

Handler class for new connections.

When mounting the CII server with cherrypy, include in the config dict a key ‘tools.dvb_cii.handler_cls’ with this handler class as the value.

attachTimelineSource(timelineSource)[source]¶

Attach (add) a source of a timeline to this CSS-TS server. This causes the timeline to become available immediately to any connected clients that might be requesting it.

This causes the addSink() method of the timeline source to be called, to notify it that this CSS-TS server is now a recipient (sink) for this timeline.

Parameters:	timelineSource – Any object implementing the methods of the TimelineSource base class

enabled[source]¶

(read/write bool) Whether this server endpoint is enabled (True) or disabled (False).

Set this property enable or disable the endpoint.

When disabled, existing connections are closed with WebSocket closure reason code 1001 and new attempts to connect will be refused with HTTP response status code 403 “Forbidden”.

getConnections()[source]¶

Returns dict:	mapping a WebSocket object to connection related data for all connections to this server. This is a snapshot of the connections at the moment the call is made. The dictionary is not updated later if new clients connect or existing ones disconnect.

getDefaultConnectionData()[source]¶

Internal method. Creates empty ‘connection data’ for the connection consisting of: a dict: { "setup":None, "prevCt":None, "aptEptLpt":None }

This reflects that no setup-data has been received yet, and no Control Timestamps have been sent, and no AptEptLpt has been received either

onClientAptEptLpt(webSock, apteptlpt)[source]¶

Called when a client has sent an updated AptEptLpt message

This is a stub for this method. Sub-classes should implement it.

Parameters:	webSock – The connection from the client. aptEptLpt – (AptEptLpt) object representing the received timestamp message.

onClientConnect(webSock)[source]¶

Called when a client establishes a connection.

If you override, make sure you call the superclass implementation of this method.

Parameters:	webSock – The connection from the client.

onClientDisconnect(webSock, connectionData)[source]¶

Called when a client disconnects.

If you override, make sure you call the superclass implementation of this method.

Parameters:	webSock – The connection from the client. connectionData – A dict containing data relating to this (now closed) connection

onClientMessage(webSock, message)[source]¶

Called when a message is received from a client.

If you override, make sure you call the superclass implementation of this method.

Parameters:	webSock – The connection from the client. msg – (Message) WebSocket message that has been received. Will be either a Text or a Binary message.

onClientSetup(webSock)[source]¶

Called when a client has connected and submitted its SetupData message to provide context for the connection.

This is a stub for this method. Sub-classes should implement it.

Parameters:	webSock – The connection from the client.

removeTimelineSource(timelineSource)[source]¶

Remove a source of a timeline from this CSS-TS server. This causes the timeline to become unavailable immediately to any connected clients that are using it.

This causes the removeSink() method of the timeline source to be called, to notify it that this CSS-TS server is no longer a customer (sink) for this timeline.

Parameters:	timelineSource – Any object implementing the methods of the TimelineSource base class

updateAllClients()[source]¶

Causes an update to be sent to all clients that need it (i.e. if the ControlTimestamp that would be sent now is different to the one most recently sent to that client)

updateClient(webSock)[source]¶

Causes an updated ControlTimestamp to be sent to the WebSocket connection specified.

The ControlTimestamp is only sent if it is different to the last time this was done for this connection.

The value of the Control Timestamp is determined by searching all attached timeline sources to find one that can supply a Control Timestamp for this connection.

TimelineSource¶

class dvbcss.protocol.server.ts.TimelineSource[source]¶

Base class for timeline sources.

Subclass and implement the stub methods to create Timeline Source:

• recognisesTimelineSelector()
• getControlTimestamp()

If your source needs to be informed of when a timeline is needed and when it becomes no longer needed (e.g. so you can allocate/deallocate resources needed to extract it) then also implement these stub methods:

• timelineSelectorNeeded()
• timelineSelectorNotNeeded()

You can also optionally override the following methods, provided your code still calls through to the base class implementations:

• attachSink() (see note)
• removeSink() (see note)

The attachSink() and removeSink() methods will be called by parties interested in the TimelineSource (such as a TSServer) when they wish to use the timeline source. The base class implementations of these methods maintain the sinks attribute as a dictionary indexed by sink.

Note: When subclassing attachSink() and removeSink() remember to call the base class implementations of these methods.

attachSink(sink)[source]¶

Called to notify this Timeline Source that there is a sink (such as a TSServer) that wishes to use this timeline source.

Parameters:	sink – The sink object (e.g. a TSServer)

A TimelineSource implementation can use knowledge of what sinks are attached in whatever way it wishes. For example: it might use this to proactively call updateAllClients() on the attached TSServer when its Timeline’s relationship to wall clock changes in some way. It is up to the individual implementation whether it chooses to do this or not.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

getControlTimestamp(timelineSelector)[source]¶

Get the Control Timestamp from this Timeline Source given the supplied timeline selector.

This method will only be called with timelineSelectors for which the recognisesTimelineSelector() method returned True.

This is a stub for this method. Sub-classes should implement it.

The return value should be a ControlTimestamp object. If the timeline is known to be unavailable, then the contentTime and speed properties of that Control Timestamp must be None.

If, however, you want the TS Server to not send any Control Timestamp to clients at all, then return None instead of a Control Timestamp object. Use this when, for example, you are still awaiting an result from code that has only just started to try to extract the timeline and doesn’t yet know if there is one available or not.

Parameters:	timelineSelector – (str) A timeline selector supplied by a CSS-TS client
Returns:	A ControlTimestamp object for this timeline source appropriate to the timeline selector, or None if the timleine is recognised no Control Timestamp should yet be provided.

recognisesTimelineSelector(timelineSelector)[source]¶

This is a stub for this method. Sub-classes should implement it.

Parameters:	timelineSelector – (str) A timeline selector supplied by a CSS-TS client
Returns:	True if this Timeline Source can provide a Control Timestamp given the specified timeline selector

removeSink(sink)[source]¶

Called to notify this Timeline Source that there is a sink that no longer wishes to use this timeline source.

Parameters:	sink – The sink object

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

timelineSelectorNeeded(timelineSelector)[source]¶

Called to notify this Timeline Source that there is a need to provide a timeline for the specified timeline selector.

Parameters:	timelineSelector – (str) A timeline selector supplied by a CSS-TS client that has not been specified by any other currently connected clients.

This is useful to, for example, initiate processes needed to extract the timeline for the specified timeline selector. You will not receive repeats of the same notification.

If the timeline is no longer needed then the timelineSelectorNotNeeded() function will be called to notify of this. After this, then you might be notified again in future if a timeline for the timeline selector becomes needed again.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

timelineSelectorNotNeeded(timelineSelector)[source]¶

Called to notify this Timeline Source that there is no longer a need to provide a timeline for the specified timeline selector.

Parameters:	timelineSelector – (str) A timeline selector that was previously needed by one or more CSS-TS client(s) but which is no longer needed by any.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

SimpleTimelineSource¶

class dvbcss.protocol.server.ts.SimpleTimelineSource(timelineSelector, controlTimestamp, *args, **kwargs)[source]¶

A simple Timeline Source implementation for a fixed timeline selector and where the Control Timestamp is specified manually.

Initialisation takes the following parameters:

Parameters:	timelineSelector – (str) The exact timeline selector that this Timeline Source will provide Control Timestamps for. controlTimestamp – (ControlTimestamp) The initial value of the Control Timestamp

attachSink(sink)[source]¶

Called to notify this Timeline Source that there is a sink (such as a TSServer) that wishes to use this timeline source.

Parameters:	sink – The sink object (e.g. a TSServer)

A TimelineSource implementation can use knowledge of what sinks are attached in whatever way it wishes. For example: it might use this to proactively call updateAllClients() on the attached TSServer when its Timeline’s relationship to wall clock changes in some way. It is up to the individual implementation whether it chooses to do this or not.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

removeSink(sink)[source]¶

Called to notify this Timeline Source that there is a sink that no longer wishes to use this timeline source.

Parameters:	sink – The sink object

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

timelineSelectorNeeded(timelineSelector)[source]¶

Called to notify this Timeline Source that there is a need to provide a timeline for the specified timeline selector.

Parameters:	timelineSelector – (str) A timeline selector supplied by a CSS-TS client that has not been specified by any other currently connected clients.

This is useful to, for example, initiate processes needed to extract the timeline for the specified timeline selector. You will not receive repeats of the same notification.

If the timeline is no longer needed then the timelineSelectorNotNeeded() function will be called to notify of this. After this, then you might be notified again in future if a timeline for the timeline selector becomes needed again.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

timelineSelectorNotNeeded(timelineSelector)[source]¶

Called to notify this Timeline Source that there is no longer a need to provide a timeline for the specified timeline selector.

Parameters:	timelineSelector – (str) A timeline selector that was previously needed by one or more CSS-TS client(s) but which is no longer needed by any.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

SimpleClockTimelineSource¶

class dvbcss.protocol.server.ts.SimpleClockTimelineSource(timelineSelector, wallClock, clock, speedSource=None, autoUpdateClients=False)[source]¶

Simple subclass of TimelineSource that is based on a clock object.

The Control Timestamp returned by the getControlTimestamp() method reflects the state of the clock.

Note that this does not result in a new Control Timestamp being pushed to clients, unless you set the auto update parameter to True when initialising this object. By default (with no auto-updating), you still have to call updateAllClients() manually yourself to cause that to happen.

Use auto-updating with caution: if you have multiple Timeline Sources driven by a common clock, then a change to that clock will cause each Timeline Source to call updateAllClients(), resulting in multiple unnecessary calls.

The tick rate is fixed to that of the supplied clock and timeline selectors are only matched as an exact match.

The speed property of the clock will be used as the timelineSpeedMultiplier value, unless a different clock is provided as the optional speedSource argument at initialisation. This is useful if the speed of the timeline is set by setting the speed property of a parent clock, and not the speed property of this clock (e.g. in situations where a single clock represents timeline progress but there are multiple clocks as children of that to represent the timeline on different scales - e.g. PTS, TEMI etc).

The availability of the clock is mapped to whether the timeline is available.

SimpleClockTimelineSource generates its correlation by observing the current tick value of the wallClock and the provided clock whenever a ControlTimestamp needs to be provided.

Initialisation takes the following parameters:

Parameters:

timelineSelector – (str) The timeline selector that this TimelineSource will provide Control Timestamps for wallClock – (ClockBase) A clock object representing the Wall Clock clock – (ClockBase) A clock object representing the flow of ticks of the timeline. speedSource – (None or ClockBase) A different clock object from which the timelineSpeedMultiplier is determined (from the clock’s speed property), or None if the clock for this is not different. autoUpdateClients – (bool) Automatically call updateAllClients() if there is a change in the clock or wallClock

notify(cause)[source]¶

Called by clocks to notify of changes (because this class binds itself to the clock object).

If auto-updating is enabled then this will result in a call to updateAllClients() on all sinks.

timelineSelectorNeeded(timelineSelector)[source]¶

Called to notify this Timeline Source that there is a need to provide a timeline for the specified timeline selector.

Parameters:	timelineSelector – (str) A timeline selector supplied by a CSS-TS client that has not been specified by any other currently connected clients.

This is useful to, for example, initiate processes needed to extract the timeline for the specified timeline selector. You will not receive repeats of the same notification.

If the timeline is no longer needed then the timelineSelectorNotNeeded() function will be called to notify of this. After this, then you might be notified again in future if a timeline for the timeline selector becomes needed again.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

timelineSelectorNotNeeded(timelineSelector)[source]¶

Called to notify this Timeline Source that there is no longer a need to provide a timeline for the specified timeline selector.

Parameters:	timelineSelector – (str) A timeline selector that was previously needed by one or more CSS-TS client(s) but which is no longer needed by any.

NOTE: If you override this in your subclass, ensure you still call this implementation in the base class.

ciMatchesStem¶

dvbcss.protocol.server.ts.ciMatchesStem(ci, stem)[source]¶

Checks if a content identifier stem matches a content identifier. A match is when the content identifier starts with the stem and is the same length as the stem, or longer.

Parameters:	ci (str or OMIT) – Content identifier stem (str) – Content identifier stem
Returns:	True if the supplied content identifier stem (stem) matches the content identifier. If the ci is OMIT then always returns False.

isControlTimestampChanged¶

dvbcss.protocol.server.ts.isControlTimestampChanged(prev, latest)[source]¶

Checks whether a new (latest) Control Timestamp is different when compared to a old (previous) Control Timestamp.

Note that this does not check equivalency (if two Control Timestamps represent the same mapping between Wall clock time and content time) but instead checks if the property values comprising the two timestamps are exact matches.

Parameters:	prev – None or a previous ControlTimestamp latest – A new ControlTimestamp
Returns:	True if the previous Control Timestamp is supplied is None, or if any of its properties differ in value to that of the latest Control Timestamp
Throws ValueError:
	The new Control Timestamp supplied is None instead of a Control Timetamp

WCMessage¶

class dvbcss.protocol.wc.WCMessage(msgtype, precision, maxFreqError, originateNanos, receiveNanos, transmitNanos, originalOriginate=None)[source]¶

Create object representing a CSS-WC wall clock request or response message.

Initialisation takes the following parameters:

Parameters:

msgtype (int) – Type of message. One of: TYPE_REQUEST, TYPE_RESPONSE, TYPE_RESPONSE_WITH_FOLLOWUP and TYPE_FOLLOWUP precision (int) – Precision (of the server’s wall clock) encoded in log base 2 seconds between -128 and +127 inclusive. maxFreqError (int) – Maximum frequency error (of the server’s wall clock) in units of 1/256ths ppm. originateNanos (int) – Originate timevalue in integer number of nanoseconds receiveNanos (int) – Receive timevalue in integer number of nanoseconds transmitNanos (int) – Transmit timevalue in integer number of nanoseconds originalOriginate (None or (int, int)) – Optional original encoding of the originate timevalue as (seconds, nanos). Overrides originateNanos if not None.

The originalOriginate parameter, if not None, overrides the originateNanos parameter.

Convert to and from a string containing the binary encoding of this message using the pack() method and unpack() class method.

msgtype[source]¶

(read/write int) Type of message. 0=request, 1=response, 2=response-with-followup, 3=followup

precision[source]¶

(read/write int) Precision encoded in log base 2 seconds between -128 and +127 inclusive. For example: -10 encodes a precision value of roughly 0.001 seconds.

maxFreqError[source]¶

(read/write int) Maximum frequency error in units of 1/256ths ppm. For example: 12800 encodes a max freq error of 50ppm.

originateNanos[source]¶

(read/write int) Originate timevalue in integer number of nanoseconds

receiveNanos[source]¶

(read/write int) Receive timevalue in integer number of nanosecond

transmitNanos[source]¶

(read/write int) Transmit timevalue in integer number of nanosecond

originalOriginate[source]¶

(read/write None or (int, int)) Optional original encoding of the originate timevalue as (seconds, nanos). Overrides originateNanos when the message is packed if the value is not None.

TYPE_FOLLOWUP = 3[source]¶

Constant: Message type 3 “follow-up response”

TYPE_REQUEST = 0[source]¶

Constant: Message type 0 “request”

TYPE_RESPONSE = 1[source]¶

Constant: Message type 1 “response with no follow-up”

TYPE_RESPONSE_WITH_FOLLOWUP = 2[source]¶

Constant: Message type 2 “response to be followed by a follow-up response”

copy()[source]¶

Duplicate this wallclock message object

classmethod encodePrecision(precisionSecs)[source]¶

Convert a precision value in seconds to the format used in these messages

getMaxFreqError()[source]¶

Get frequency error in ppm

getPrecision()[source]¶

Get precision value in fractions of a second

pack()[source]¶

Pack wall clock message into binary representation.

Returns:	String containing the wall clock message in final bitstream form.

setMaxFreqError(maxFreqErrorPpm)[source]¶

Set freq error given a freq error represented as ppm

setPrecision(precisionSecs)[source]¶

Set precision value given a precision represented as factions of a second

classmethod unpack(data)[source]¶

Class method that takes a string containing a wall clock message and unpacks it to a WCMessage object.

Parameters:	data (str) – String containing binary representation of a Wall Clock message as received from a client or server.
Returns:	WCMessage object representing the wall clock message.

Candidate¶

class dvbcss.protocol.wc.Candidate(msg, nanosRx)[source]¶

This object represents a measurement “candidate” to be fed into a Wall Clock Client’s algorithm. It is calculated from a WCMessage received as a response from a Wall Clock server.

This object requires that response comes from a Wall Clock Client that measured the parent of the clock that will be used to model the wall clock locally.

Initialisation takes the following parameters:

Parameters:	msg (WCMessage) – Response message received from server nanosRx (int) – the time, in nanoseconds, at which it was received (from the server)

Pass in a received WallClockMessage that is a response and this will represent the candidate data derived from that request-response interaction.

Populates properties of this objects with the candidate information. t1, t2, t3 and t4 represent the times of message sending and receiving as shown below:

It also calculates and provides, as properties, the round-trip time (rtt) and clock offset estimate (offset) based on this measurement.

All data is in units of nanoseconds, except for precision which is measured in seconds, and maximum frequency error which is measured in ppm.

A helper function calcCorrelationFor() makes it easy to calculate the Correlation needed to take this measurment candidate and use it to control a CorrelatedClock.

t1 = msg.originateNanos[source]¶

(read only) The time “t1” at which the request was sent in the request-response measurement (nanoseconds)

t2 = msg.receiveNanos[source]¶

(read only) The time “t2” at which the request was received in the request-response measurement (nanoseconds)

t3 = msg.transmitNanos[source]¶

(read only) The time “t3” at which the response was sent in the request-response measurement (nanoseconds)

t4 = nanosRx[source]¶

(read only) The time “t4” at which the response was received in the request-response measurement (nanoseconds)

offset = ((t3+t2)-(t4+t1))/2[source]¶

(read only) Server<->client clock offset (nanoseconds)

rtt = (t4-t1)-(t3-t2)[source]¶

(read only) Round trip time (nanoseconds)

isNanos = True[source]¶

precision = msg.getPrecision()[source]¶

(read only) The precision reported by the server in its response (units of factions of a second)

maxFreqError = msg.getMaxFreqError()[source]¶

(read only) The maximum frequency error reported by the server in its response (units of ppm)

msg = WCMessage[source]¶

(read only WCMessage) The response message from which this candidate was derived

calcCorrelationFor(clock, localMaxFreqErrorPpm=None)[source]¶

Calculates and returns the Correlation for a CorrelatedClock that is equivalent to this candidate.

The returned correlation can then be applied to the clock to model the time at the server. This includes the error bounds information needed to enable the clock to correctly calculate dispersion.

Parameters:	clock – CorrelatedClock that will model the server clock. Its parent must be the one that was measured for t1 and t4 this candidate. localMaxFreqErrorPpm – Optional. By defeault the getRootMaxFreqError() of the clock is used. Provide this value to override that.
Returns:	Correlation representing this candidate, and that can be used with the CorrelatedClock.

Note

The parameters of the correlation are calculated by this function as follows:

• parentTicks = (t1’ + t4’) / 2
• childTicks = (t2’ + t3’) / 2
• initialError = precision + ( rtt/2 + mfeC * (t4 - t1) + mfeS * (t3 - t2) ) / 10⁹
• errorGrowthRate = mfeC + mfeS

Where:

• t1, t2, t3 and t4 are in units of nanoseconds
• t1’ and t4’ are the same as t1 and t4 but converted to ticks of the parent of the specified clock
• t2’ and t3’ are the same as t2 and t3 but converted to ticks of the specified clock
• mfeC is the clock’s getRootMaxFreqError(), converted from ppm to a fraction by dividing by 10⁶
• mfeS is the max freq error reported by the server, converted from ppm to a fraction by dividing by 10⁶

New in version 0.4.

toTicks(clock)[source]¶

Returns a new Candidate object the same as this one but whose measurements have been converted to match the timescale of a clock.

Raises:	NotImplementedError – This function has been deprecated.

Warning

Deprecated since version 0.4: This function has been deprecated because of the architectural change to taking taking readings from a different clock to the one that is adjusted.

Use calcCorrelationFor() instead as this will perform the necessary conversion to clock tick rate units as well as creating the correlation needed to configure that clock.

Dispersion algorithm¶

The LowestDispersionCandidate algorithm is the recommended algorithm. It uses the candidate with the lowest dispersion.

Simple algorithm¶

The MostRecent algorithm is a simple naive algorithm that uses the most recent candidate irrespective of its quality (e.g. how long the round-trip time of the measurement was)

Writing new algorithms¶

An algorithm is an object that has the following method:

.algorithm(self)[source]¶

A python generator function that yields whenever it wants a Wall Clock protocol measurement to be taken:

candidateOrNone = yield timeoutSecs

The yield must pass a timeout in seconds. This is the maximum amount of time the Wall Clock client will wait for a response to its request before timing out.

Changed in version 0.4: The yield statement will return either None or a Candidate object representing the result of the measurement.

The algorithm can then use the Candidate object in its algorithm for estimating the wall clock (and in the case of most practical implementations: adjusting a clock object).

Here is an example of a simple naive algorithm that adjusts a CorrelatedClock object using the most recent measurement, irrespective of influencing factors such as previous measurements or network latency (round trip time). It makes requests at most once per second and has a timeout on waiting for responses of 0.5 seconds:

class NaiveAlgorithm(object):

    def __init__(self,clock):
        self.clock = clock
    
    def algorithm(self):
        while True:
            candidate=(yield 0.5)
            if candidate is not None:
                self.clock.correlation = candidate.calcCorrelationFor(self.clock)
                time.sleep(1.0)