CSS-TS Clients

Module: dvbcss.protocol.client.ts

There are two classes provided for implementing CSS-TS clients:

• TSClientClockController wraps a TSClientConnection and provides a higher level interface that provides information about timeline availability and drives a clock object to match the timeline.
• TSClientConnection implements the core functionality of connecting to a CSS-TS server and providing methods and callbacks to manage the connection and send and receive timestamp messages.

An example client is provided in this package that uses the TSClientClockController class.

Using TSClientClockController

This class provides a high level interface that drives a CorrelatedClock object to match the timeline provided by a CSS-TS server. Subclass to get notifications of connection, disconnection and timing changes or changes in timeline availability.

Create it, passing the URL of the server to connect to, and a connect and disconnect() to connect and disconnect from the server.

The clock you provide must be a CorrelatedClock object and the parent clock of that clock must represent the wall clock. The tick rate of this clock must match that of the timeline and the tick rate of the wall clock must be 1 tick per nanosecond (1e9 ticks per second). This should therefore be used in conjunction with a WallClockClient to ensure the wall clock is meaningfully synchronised to the same server.

The TSClientClockController object maintains the connection and automatically adjusts the correlation of the clock to synchronise it, using the information in the Control Timestamps received from the server. It adjusts the speed() to match speed changes of the timeline. It also sets the availability of the clock to reflect the availability of the timeline.

You can set a minimum threshold for how much the timing must change before the the timeline clock will be adjusted.

You can also provide separate clock objects to represent the earliest and latest presentation timings that your application can achieve (and that you wish to convey to the server). These must also be CorrelatedClock objects. Use the TSClientClockController.sendAptEptLpt() method to cause that information to be sent to the server.

A simple example:

from dvbcss.protocol.client.ts import TSClientClockController
from dvbcss.clock import CorrelatedClock, SysClock

sysClock = SysClock()
wallClock = CorrelatedClock(parent=sysClock, tickRate=1000000000)  # 1 nanosecond per tick
timelineClock = CorrelatedClock(parent=wallClock, tickRate=90000)  # will represent PTS

# NOTE: need a Wall Clock Client too (not shown in this example)
#       to ensure wallClock is synchronised 

class MyTSClient(TSClientClockController):
    
    def onConnected(self):
        print "Conected!"
    
    def onDisconnected(self):
        print "Disconnected :-("
    
    def onTimelineAvailable(self):
        print "Timeline is available!"
        
    def onTimelineUnavailable(self):
        print "Timeline is not available :-("

    def onTimingChange(self, speedHasChanged):
        print "Timing of clock has been adjusted."
        if speedHasChanged:
            print "The speed of the clock has altered."
            
# make connection. Want PTS timeline for any DVB service.
client = MyTSClient("ws://192.168.1.1:7682/ts",
                    "dvb://",
                    "urn:dvb:css:timeline:pts",
                    timelineClock)
client.connect()

for i in range(0,60):
    time.sleep(1)
    print "Timeline available?", timelineClock.isAvailable()
    if timelineClock.isAvailable():
        print "Timeline currently at tick value = ", timelineClock.ticks
        print "         ... and moving at speed = ", timelineClock.speed
    
client.disconnect()

The client runs in a separate thread managed by the websocket client library, so the onXXX methods are called while the main thread sleeps.

Using TSClientConnection

This class provides the lowest level interface to a CSS-TS server. It only implements the parsing of incoming Control Timestamp messages and sending of outgoing Actual, Earliest and Latest Presentation Timestamp messages. It does not try to understand the meaning of the messages sent or received.

You can use the class either by subclassing and overriding the various stub methods or by creating an instance and replacing the stub methods with your own function handlers dynamically.

Pass the WebSocket URL of the CSS-TS server during initialisation then call the connect() and disconnect() methods to connect and disconnect from the server. The onXXX() methods are called when connection or disconnection takes place, if there is a protocol error (e.g. a message was received that could not be parsed as Control Timestamp) or a new Control Timestamp is received.

A simple example:

from dvbcss.protocol.client.ts import TSClientConnection
from dvbcss.protocol.ts import AptEptLpt
from dvbcss.protocol import OMIT

class MyClientConnection(TSClientConnection):
    def onConnected(self):
        print "Connected!"
        e = Timestamp(0, float("-inf"))
        l = Timestamp(0, float("+inf"))
        aptEptLpt = AptEptLpt(earliest=e, latest=l, actual=OMIT)
        client.sendTimestamp(aptEptLpt)
        
    def onDisconnected(self, code, reason):
        print "Disconnected :-("
        
    def onControlTimestamp(self, ct):
        print "Received a ControlTimestamp: "+str(ct)

# make connection. Want PTS timeline for any DVB service.
client = MyTSClientConnection("ws://127.0.0.1/ts", "dvb://", "urn:dvb:css:timeline:pts")
client.connect()

time.sleep(60)      # run only for 60 seconds then disconnect

client.disconnect()

Classes

TSClientConnection

class dvbcss.protocol.client.ts.TSClientConnection(url, contentIdStem, timelineSelector)

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()

Open the connection.

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

connected

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

disconnect(code=1001, reason='')

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()

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)

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()

This method is called when the connection is closed.

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

onProtocolError(msg)

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)

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)

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

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

latestCt

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

earliestClock

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

latestClock

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

connect()

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()

Disconnect from the server.

getStatusSummary()

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

onConnected()

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()

This method is called when the connection is closed.

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

onProtocolError(msg)

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()

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()

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)

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)

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

(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.