Repository files navigation

• 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 theprotocols defined in the DVB CSS specification (published asETSI 103-286 part 2)and are used for the "inter-device synchronisation" feature inHbbTV 2.These protocols enable synchronisation of media presentation between a TVand Companion devices (mobiles, tablets, etc).

This library includes simple to use high level abstractions that wrap up theserver or client behaviour for each protocol as well as low level code forpacking and unpacking messages sent across the protocols. There are alsoobjects 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 buildingprototypes and testing tools that implement TV (server) or Companion(client) behaviour. It is not considered production ready or suitable forintegration into consumer products.

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

The DVB CSS specification was formerly published asDVB Bluebook A167-2. This is deprecated in favour of theETSI spec.

pydvbcss requiresws4py foruse in clients and servers, and alsocherrypyfor server implementations. The steps below describe how to install these.

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

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.

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

• See the pydvbcss PyPI package page.

If you ONLY want the library (not thecode examples and tools ) andif you don't require the very latest bugfixes, then you can install a recentrelease package from the Python Package Index (PyPI) usingpip:

$ pip install pydvbcss

Or if upgrading from a previous version:

$ pip install --upgrade pydvbcss

You can usepip search pydvbcss to verify which version is installed.

See note in the next section aboutCherryPy andws4py dependencies.

Themaster branch is the lateststate of the code, including any recent bugfixes. It is mostly stable butmight have occasional small API changes.Release snapshots are also availablebut won't contain the very latest bugfixes or new features.Both of these options include the full code, includingexamples.

First you need to install dependencies...

We recommend usingpip to installdependencies from the Python Package IndexPyPI:

$ pip install -r requirements.txt

NOTE: There have been recent incompatibilities between certain versions ofcherrypy,ws4py andcheroot. Therefore,requirements.txt requires specific(older) versions of these pacakges. You are welcome to try newer versions installingthem manually. See#15 for backgrounddetails.

Then take (or update) your clone of the repositorymaster branch, ordownload and unzip a snapshot release and run thesetup.py script toinstall:

$ 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 notrunning any CPU intensive tasks at the time.

There is a set of example and tools demonstrating simple servers and clients for theprotocols included with the library. See thequick start guidein 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 IDand timeline(s) that a companion application expects.

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

Suppose the TV is serving the CII protocol at the URLws://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 beingws://192.168.0.57:7681/ts and the wall clock protocol as being at192.168.0.57 port6677...

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

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

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

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

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

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

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

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

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

$ pip install sphinx$ pip install sphinx_rtd_theme

Thedocs directory contains the configuration and main documentationsources that descibe the structure. Most of the actual words are in theinline 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

Discuss and ask questions on thepydvbcss google group.

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

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

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