Package: pydvbcss
`How to install <#install-the-code>`__`Read the documentation <#read-the-documentation>`__`Run the examples <#run-the-examples>`__pydvbcssis a set of Python 2.7 libraries and command-line tools
that implement some of the protocols defined in the DVB CSS
specification (published asETSI 103-286 part
2)
and are used for the “inter-device synchronisation” feature in`HbbTV
2 <http://hbbtv.org/resource-library/>`__. 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 asDVB Bluebook
A167-2. This is
deprecated in favour of theETSI
spec.Getting startedpydvbcssrequiresws4pyfor use in clients
and servers, and alsocherrypyfor server
implementations. The steps below describe how to install these.pydvbcsshas been developed on Mac OS X 10.10 but has also been used
successfully on Microsoft Windows 7 and Ubuntu 14.04.Read the DocumentationThe docs for the library can be read online on readthedocs.org:Docs for 0.5.2
releaseDocs for latest commits to master
releaseLinks 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 thecode 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) usingpip:$ pip install pydvbcssOr if upgrading from a previous version:$ pip install --upgrade pydvbcssYou can usepip search pydvbcssto 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)Themaster branchis
the latest state of the code, including any recent bugfixes. It is
mostly stable but might have occasional small API changes.Release
snapshotsare also
available but 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 usingpipto install
dependencies from the Python Package IndexPyPI:$ 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 <https://github.com/bbc/pydvbcss/issues/15>`__
for background details.*Then take (or update) your clone of the repositorymasterbranch, or
download and unzip a snapshot release and run thesetup.pyscript to
install:$ python setup.py installThis 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 testThis checks some timing sensitive implementation issues, so ensure you
are not running any CPU intensive tasks at the time.Running the examples and toolsThere is a set of example and tools demonstrating simple servers and
clients for the protocols 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 ID and timeline(s) that a companion application expects.Example: checking protocols implemented by a TVStart 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 URLws://192.168.0.57:7681/cii…To check the CII protocol:$ python examples/CIIClient.py ws://192.168.0.57:7681/ciiSuppose that the messages returned report the URL of the TS protocol
endpoint as beingws://192.168.0.57:7681/tsand the wall clock
protocol as being at192.168.0.57port6677…To check the TV’s Wall Clock protocol:`$ python examples/WallClockClient.py 192.168.0.57 6677To 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" \
    9000Super-quick introduction to the protocolsDVB 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 yourselfYou can also build the documentation yourself. It is written using thesphinxdocumentation build system.Building the documentation requiressphinxand the sphinx “read the docs”
theme. The easiest way is using PyPI:$ pip install sphinx
$ pip install sphinx_rtd_themeThedocsdirectory 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_sphinxor:$ cd docs
$ make htmlContact and discussDiscuss and ask questions on thepydvbcss google
group.The original author is Matt Hammond ‘at’ bbc.co.ukLicenceAll code and documentation is licensed under the Apache License v2.0.ContributingIf you would like to contribute to this project, seeCONTRIBUTINGfor details.