Run the examples

The code in the examples directory demonstrates how to create and control servers and clients for all three protocols: CSS-CII, CSS-TS and CSS-WC.

There are instructions below on how to run the examples and see them interact with each other.

See the sources here: on github

WallClockServer.py and WallClockClient.py

Get started

The WallClockServer and WallClockClient examples use the library to implement a simple server and client for the CSS-WC protocol.

First start the server, specifying the host and IP to listen on:

$ python examples/WallClockServer.py 127.0.0.1 6677

Leave it running in the background and start a client, telling it where to connect to the server:

$ python examples/WallClockClient.py 127.0.0.1 6677

Note

The wall clock protocol is connectionless (it uses UDP) This means the client will not report an error if you enter the wrong IP address or port number.

Watch the “dispersion” values which indicate how much margin for error there is in the client’s wall clock estimate. If the value is very large, this means it is not receiving responses from the server.

How they work

WallClockServer.py [source]

It works by instantiating a WallClockServer object and providing that object with a clock object to be used as the Wall Clock that is to be served.

At the command line you can override default options for the ip address and port the server binds to; the maximum frequency error it reports and whether it sends “follow-up” responses to requests.

Use the --help command line option for usage information.

WallClockClient.py [source]

It works by instantiating a WallClockClient object and plugs into that object a LowestDispersionCandidate algorithm object that adjusts a TunableClock representing the Wall Clock.

At the command line you must specify the host and port of the Wall Clock server. Default options can be overridden for the IP address and port that the client listens on.

Use the --help command line option for usage information.

CIIServer.py and CIIClient.py

Get started

The CIIServer and CIIClient examples implement the CSS-CII protocol, with the server sharing some pretend CII status information with the client.

First start the server:

$ python examples/CIIServer.py

The server listens on 127.0.0.1 on port 7681 and accepts WebSocket connections to ws://<ip>:<port>/cii.

Leave it running in the background and connect using the client and see how the CII data is pushed by the server whenever it changes:

$ python examples/CIIClient.py ws:/127.0.0.1:7681/cii

How they work

CIIServer.py [source]

It works by setting up a web server and the ws4py plug-in for cherrypy that provides WebSockets support. It then instantiates a CIIServer and mounts it into the cherrypy server at the URL resource path “/cii”.

While the server is running, it pretends to be hopping between a few different broadcast channels every 7 seconds, with a 2 second “transitioning” period on each hop.

This is an artificially simple example and does not provide values for most properties of the CII message - such as a MRS URL, or any URLs for a WC or TS endpoints.

It does not do any media presentation, but just provides a CSS-CII server with some pretend data.

This server, by default, serves on port 7681 and provides a CSS-CII service at the URL resource path /cii. It can therefore be connected to using the WebSocket URL “ws://<host>:7681/cii” e.g. “ws://127.0.0.1:7681/cii”. Command line options can be used to override these defaults and to reduce the amount of logging output.

Use the --help command line option for more detailed usage information.

CIIServer.py [source]

It works by instantiating a CIIClient and attaching handler functions to be notified of when connection and disconnection occurs and of changes to the CII information being pushed from the server.

At the command line you must specify:

  • the WebSocket URL of the CSS-CII server, in the form ws://<host>:<port>/<path>

Command line options can be used to reduce the amount of logging output.

Use the --help command line option for usage information.

TSServer.py and TSClient.py

Get started

The TServer and TSClient examples implement the CSS-TS protocol, with the server pretending to have a few different timelines for a DVB broadcast service (where the content ID is a DVB URL).

First start the server:

$ python examples/TSServer.py

The server listens on 127.0.0.1 on port 7681 and accepts WebSocket connections to ws://<ip>:<port>/ts. It also includes a wall clock server, also on 127.0.0.1 on port 6677.

Leave it running in the background and connect using the client and see how the client is able to synchronise and periodically print an estimate of the timeline position (converted to units of seconds):

$ python examples/TSClient.py ws://127.0.0.1:7681/ts udp://127.0.0.1:6677 "dvb://" "urn:dvb:css:timeline:pts" 90000

Here we have told it to request a timeline for whatever content the server thinks it is showing provided that the content ID begins with “dvb://”. Assuming that matches, then the timeline is to be a PTS timeline, which ticks at 90kHz (the standard rate of PTS in an MPEG transport stream).

How they work

TSServer.py [source]

It works by setting up a web server and the ws4py plug-in for cherrypy that provides WebSockets support. It then instantiates a TSServer and mounts it into the cherrypy server at the URL resource path “/ts”. It also includes a wall clock server.

It does not play any media, but instead serves an imaginary set of timelines.

It creates clock objects to represent timelines and the wall clock. SimpleClockTimelineSource objects are used to interface the clocks as sources of timelines to the TS server object.

It has a hardcoded DVB URL as the content ID (displayed when you start it running) and provides the following timelines:

  • “urn:dvb:css:timeline:pts” … a PTS timeline
  • “urn:dvb:css:timelime:temi:1:1” … a TEMI timeline ticking at 1kHz
  • “urn:dvb:css:timelime:temi:1:5” … a TEMI timeline ticking at 1kHz, that toggles availability every 10 seconds
  • “urn:dvb:css:timelime:temi:1:2” … the same, but it takes 10 seconds for the server to begin providing this timeline after a client first requests it
  • “urn:pydvbcss:sporadic” … a meaningless timeline whose availability toggles every 10 seconds.

The PTS and TEMI timelines both pause periodically and have their timing tweaked by a fraction of a second. The “sporadic” timeline shows how the protocol supports having timelines appear (become available) and disappear (become unavailable) while a client is connected.

By default, this server serves at 127.0.0.1 on port 7681 and provides a CSS-TS service at the URL ws://127.0.0.1:7681/ts. It also provides a wall clock server bound to 0.0.0.0 on UDP port 6677. Command line options can be used to override these defaults and to reduce the amount of logging output.

Use the --help command line option for more detailed usage information.

TSClient.py [source]

It works by implementing both a wall clock client and a CSS-TS client. A TSClientClockController object is instantiated and provided with a CorrelatedClock object to represent the synchronisation timeline. The controller adjusts the clock object to match the timeline information coming from the server.

At the command line you must specify:

  • the WebSocket URL of the CSS-TS server, in the form ws://<host>:<port>/<path>
  • a udp://<host>:<port> format URL for the Wall Clock server
  • The content ID stem and timeline selector to be used when requesting the timeline
  • The tick rate of the timeline.

Default options can be overridden for the IP address and port that the Wall Clock client binds to and to reduce the amount of logging output.

Use the --help command line option for usage information.

TVDevice.py

Get started

This is a very simple example of a server running all three protocols (CSS-WC, CSS-TS and CSS-CII). It pretends to be showing a DVB broadcast service and able to provide a PTS or TEMI timeline for it.

First start the server:

$ python examples/TVDevice.py

While we leave it running in the background, we can try to interact with it using the various example clients described above.

By default it provides a wall clock server on all interfaces on port 6677

$ python examples/WallClockClient.py 127.0.0.1 6677

… and a CSS-CII server that can be reached at ws://{{host}}:7681/cii where {{host}} is any interface, including 127.0.0.1.

$ python examples/CIIClient.py ws:/127.0.0.1:7681/cii

… and a CSS-TS server that can be reached at ws://{{host}}:7681/ts

$ python examples/TSClient.py ws://127.0.0.1:7681/ts udp://127.0.0.1:6677 "dvb://" "urn:dvb:css:timeline:temi:1:1" 1000

How it works

TVDevice.py [source]

This example works by setting up a web server and the ws4py plug-in for cherrypy that provides WebSockets support. It then instantiates a TSServer and CIIServer and mounts it into the cherrypy server. It also includes a wall clock server.

It does not play any media, but instead serves an imaginary set of timelines and pretends to be presenting a broadcast service.

It creates clock objects to represent timelines and the wall clock. SimpleClockTimelineSource objects are used to interface the clocks as sources of timelines to the TS server object.

It has a hardcoded DVB URL as the content ID (displayed when you start it running) and provides the following timelines:

  • urn:dvb:css:timeline:pts … a PTS timeline
  • urn:dvb:css:timelime:temi:1:1 … a TEMI timeline ticking at 1kHz that toggles availability every 30 seconds

The PTS and TEMI timelines both start ticking up from zero the moment the server starts.

By default, this server binds to 0.0.0.0 on port 7681 and provides a CSS-CII service at the URL ws://{host}:7681/cii and a CSS-TS service at the URL ws://{host}:7681/ts. It also provides a wall clock server bound to 0.0.0.0 on UDP port 6677.

The CII service will provide URLs for the TS and WC endpoints that match the host name on which the

Command line options can be used to override these defaults and to reduce the amount of logging output.

Use the --help command line option for more detailed usage information.