bbc / pydvbcss

Python library that implements DVB protocols for companion synchronisation

Python DVB Companion Screen Synchronisation protocol library and tools

• How to install
• Read the documentation
• Run the examples

pydvbcss is a set of Python 2.7 libraries and command-line tools that implement some of the protocols defined in the DVB CSS specification (published as ETSI 103-286 part 2) and are used for the "inter-device synchronisation" feature in HbbTV 2. These protocols enable synchronisation of media presentation between a TV and Companion devices (mobiles, tablets, etc).

This library includes simple to use high level abstractions that wrap up the server or client behaviour for each protocol as well as low level code for packing and unpacking messages sent across the protocols. There are also objects that work with the rest of the library to represent clocks and timelines.

This code is intended as an informal reference and is suitable for building prototypes and testing tools that implement TV (server) or Companion (client) behaviour. It is not considered production ready or suitable for integration into consumer products.

The code does not implement media playback functionality and this is not a planned feature.

The DVB CSS specification was formerly published as DVB Bluebook A167-2. This is deprecated in favour of the ETSI spec.

Getting started

pydvbcss requires ws4py for use in clients and servers, and also cherrypy for server implementations. The steps below describe how to install these.

pydvbcss has been developed on Mac OS X 10.10 but has also been used successfully on Microsoft Windows 7 and Ubuntu 14.04.

Read the Documentation

The docs for the library can be read online on readthedocs.org:

• Docs for current stable release

• Docs for latest commits to master release

Links are also available from those pages through to documentation for earlier releases.

Install the code ...

On Mac OS X and Linux you may need to run one or more of the commands as root.

Using PyPi (core library only, no examples or tools)

• See the pydvbcss PyPI package page.

If you ONLY want the library (not the code examples and tools ) and if you don't require the very latest bugfixes, then you can install a recent release package from the Python Package Index (PyPI) using pip:

$ pip install pydvbcss

Or if upgrading from a previous version:

$ pip install --upgrade pydvbcss

You can use pip search pydvbcss to verify which version is installed.

See note in the next section about CherryPy and ws4py dependencies.

From Github or a release tarball (includes examples and tools)

The master branch is the latest state of the code, including any recent bugfixes. It is mostly stable but might have occasional small API changes. Release snapshots are also available but won't contain the very latest bugfixes or new features. Both of these options include the full code, including examples.

First you need to install dependencies...

We recommend using pip to install dependencies from the Python Package Index PyPI:

$ pip install -r requirements.txt

NOTE: There have been recent incompatibilities between certain versions of cherrypy, ws4py and cheroot. Therefore, requirements.txt requires specific (older) versions of these pacakges. You are welcome to try newer versions installing them manually. See #15 for background details.

Then take (or update) your clone of the repository master branch, or download and unzip a snapshot release and run the setup.py script to install:

$ python setup.py install

This will install all module packages under 'dvbcss'.

There is a limited test suite (it only tests certain classes at the moment). Run it via setup.py:

$ python setup.py test

This checks some timing sensitive implementation issues, so ensure you are not running any CPU intensive tasks at the time.

Running the examples and tools

There is a set of example and tools demonstrating simple servers and clients for the protocols included with the library. See the quick start guide in the documentation to see how to run them.

The clients are useful tools to test a TV implementation is outputting the correect data.

The servers can be modified to simulate a TV that is playing content with an ID and timeline(s) that a companion application expects.

Example: checking protocols implemented by a TV

Start the content playing on the TV and ensure it is serving the protocols (for HbbTV 2 TVs this requires an HbbTV application to enable inter-device synchronisation).

Suppose the TV is serving the CII protocol at the URL ws://192.168.0.57:7681/cii...

To check the CII protocol:

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

Suppose that the messages returned report the URL of the TS protocol endpoint as being ws://192.168.0.57:7681/ts and the wall clock protocol as being at 192.168.0.57 port 6677...

To check the TV's Wall Clock protocol:`

$ python examples/WallClockClient.py 192.168.0.57 6677

To check the TV reporting a PTS timeline (uses both Wall Clock and TS protocols):

$ python examples/TSClient.py ws://192.168.0.57:7681/ts \
    udp://192.168.0.57:6677 \
    "" \
    "urn:dvb:css:timeline:pts" \
    9000

Super-quick introduction to the protocols

DVB has defined 3 protocols for communicating between a companion and TV in order to create synchronised second screen / dual screen / companion experiences (choose whatever term you prefer!) that are implemented here:

• CSS-CII - A WebSockets+JSON protocol that conveys state from the TV, such as the ID of the content being shown at the time. It also carries the URLs to connect to the other two protocols.

• CSS-WC - A simple UDP protocol (like NTP but simplified) that establishes a common shared clock (a "wall clock") between the TV and companion, compensating for network delays.

• CSS-TS - Another WebSockets+JSON protocol that communicates timestamps from TV to Companion that describe the current timeline position.

The TV implements servers for all 3 protocols. The Companion implements clients.

There are other protocols defined in the specification (CSS-TE and CSS-MRS) that are not currently implemented by this library.

Building the documentation for yourself

You can also build the documentation yourself. It is written using the sphinx documentation build system.

Building the documentation requires sphinx and the sphinx "read the docs" theme. The easiest way is using PyPI:

$ pip install sphinx
$ pip install sphinx_rtd_theme

The docs directory contains the configuration and main documentation sources that descibe the structure. Most of the actual words are in the inline docstrings in the source code. These structural pages pull these in.

To build docs in HTML format, either:

$ python setup.py build_sphinx

or:

$ cd docs
$ make html

Contact and discuss

Discuss and ask questions on the pydvbcss google group.

The original author is Matt Hammond 'at' bbc.co.uk

Licence

All code and documentation is licensed under the Apache License v2.0.

Contributing

If you would like to contribute to this project, see CONTRIBUTING for details.

pydvbcss's Issues

ImportError: No module named wsgiserver2

Attempting to run 'examples/WallClockServer.py' fails with this error:
ImportError: No module named wsgiserver2

Travis-ci for OSX not yet working

travis-ci/travis-ci#4729
travis-ci/travis-ci#2312

travis-ci build fails because solution to #15 surfaces problem in pip dependency resolver

travis-ci build is failing because pip is unable to install correct dependencies for cherrypy==11.0.0 and cheroot==5.9.1 because only later versions of cherrypy explicitly spec the version for a common sub-dependency six.

This has arisen because the temporary fix for #15 results in this particular combination of package versions. Once #15 is resolved upstream, this problem will hopefully go away.

Enable CII server to match wcUrl, tsUrl, teUrl with interface client connects on

At the moment the tsUrl, wcUrl and teUrl reported by a CII Server are set by the application using pydvbcss and they are the same for all clients that connect.

However, if the CII Server is bound to 0.0.0.0 then clients could connect via multiple different interfaces, each with different IP addresses. For example, a client connecting to local loopback (eg. 127.0.0.1) vs a client connecting via the LAN (e.g. 192.168.1.26). To work, each ought to receive a value for wcUrl and tsUrl where the hostname/IP address matches the one they used when they connected.

Add an ability for CIIServer to transparently rewrite the wcUrl and tsUrl on a per client connection basis to match the IP address of the local interface on which the client connected.

This should be an optional extension. Existing behaviour should be preserved to maintain backward compatibility.

Not yet python 3 compatible

thread safety issues

cherrypy+ws4py create a thread per WebSocket connection when running a WebSocket server. This gives rise to thread safety issues in classes such as TSServer where lists of connections are altered whilst they are being iterated over.

Fortunately it occurs relatively rarely. But is still a good idea to fix.

wc dispersion calc

Hello Matt Hammond,
I am testing your dvbcss project. I have some problems. In code as followed,the currentDispersion will be always bigger than candidateDispersion, because currentDispersion uses time_now() to calc. Is it right? Thank you!

currentDispersion = self.getCurrentDispersion()

        if candidate is not None:
            cn=candidate['nanos']
            ct=candidate['ticks']
            candidateDispersion=self.dispCalc.calc(cn)

            if currentDispersion >= candidateDispersion:
                self.bestCandidate = candidate
                update=True
                self.clock.adjustTicks(ct.offset)
                if cumulativeOffset is None:
                    cumulativeOffset=0
                else:
                    cumulativeOffset+=ct.offset

                # notify of the change
                growthRate = self.dispCalc.getGrowthRate(cn)
                self.onClockAdjusted(self.clock.ticks, ct.offset, currentDispersion, candidateDispersion, growthRate)

            else:
                pass

pydvbcss 0.5.1 pypi package missing `requirements.txt`

requirements.txt appears to be missing from pydvbcss 0.5.1 package on pypi (tarball)

$ sudo pip install pydvbcss
Collecting pydvbcss
  Downloading pydvbcss-0.5.1.tar.gz (90kB)
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-build-GmSygW/pydvbcss/setup.py", line 68, in <module>
        install_requires = filter(len, [req.strip() for req in open("requirements.txt","r").read().splitlines()]),
    IOError: [Errno 2] No such file or directory: 'requirements.txt'

Broken when using cherrypy>=11.1.0

CII or TS servers are currently broken when using cherrypy>=11.1.0

This appears to be an upstream problem. See Lawouach/WebSocket-for-Python#235

does this support none integer framerates

24000/1001 fps 23.98 23.976 etc
30000/1001 fps 29.97 etc

Python setup.py run and test doesnt work(Python 3.7)

Python setup.py run and test doesnt work , whenever i try to run it gives me that i need to be a superuser of this repo, and whenever i run other commands to check the examples i get a lot of errors and the code doesn't work, it might be because i am a beginner in this field but would love some help❤️