Skip to main content

pydvbcss is a library implementing DVB "CSS" protocols for Companion Screen Synchronisation.

Project description

Python DVB Companion Screen Synchronisation protocol library
============================================================

|Build status| |Docs Status (stable)| |Docs Status (latest)| |Latest
PyPI package|

- **`How to install <#install-the-code>`__**
- **`Read the documentation <#read-the-documentation>`__**
- **`Run the examples <#run-the-examples>`__**

**pydvbcss** is a set of Python 2.7 libraries that implement some of the
protocols defined in the DVB CSS specification (published as `ETSI
103-286 part
2 <http://www.etsi.org/standards-search?search=103+286&page=1&title=1&keywords=1&ed=1&sortby=1>`__).
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 <https://www.dvb.org/search/results/keywords/A167>`__. This is
deprecated in favour of the `ETSI
spec <http://www.etsi.org/standards-search?search=103+286&page=1&title=1&keywords=1&ed=1&sortby=1>`__.

Getting started
---------------

**pydvbcss** requires
`ws4py <https://ws4py.readthedocs.io/en/latest/>`__ for use in clients
and servers, and also `cherrypy <http://www.cherrypy.org>`__ 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 Status (stable)| `Docs for 0.4.1
release <http://pydvbcss.readthedocs.io/en/0.4.1/?badge=0.4.1>`__

- |Docs Status (latest)| `Docs for latest commits to master
release <http://pydvbcss.readthedocs.io/en/latest/?badge=latest>`__

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)*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you ONLY want the library (not the `code examples <#run-examples>`__
) 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 <https://pip.pypa.io/en/latest/installing.html>`__:

::

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

- |Latest PyPI package| `See the pydvbcss PyPI package
page <https://pypi.python.org/pypi/pydvbcss>`__.

From Github or a release tarball *(library and examples)*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The `master branch <https://github.com/BBC/pydvbcss/tree/master>`__ is
the latest state of the code, including any recent bugfixes. It is
mostly stable but might have occasional small API changes. `Release
snapshots <https://github.com/BBC/pydvbcss/releases>`__ are also
available but won't contain the very latest bugfixes or new features.
Both of these options include the full code, including
`examples <#run-examples>`__.

First you need to install dependencies...

We recommend using
`pip <https://pip.pypa.io/en/latest/installing.html>`__ to install
dependencies from the Python Package Index
`PyPI <https://pypi.python.org/pypi>`__:

::

$ pip install 'cherrypy<9.0.0'
$ pip install 'ws4py<=0.3.5'

**NOTE: There is a temporary incompatibility between cherrypy, ws4py and
pydvbcss. Until this is resolved, you should install a *pre 9.0.0
version of cherrypy* and *version 0.3.5 of ws4py*. Details of the issue
are `available here <https://github.com/bbc/pydvbcss/issues/13>`__**

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.

Run the examples
~~~~~~~~~~~~~~~~

There is a set of examples demonstrating simple servers and clients for
the protocols included with the library. See the `quick start
guide <https://BBC.github.io/pydvbcss/docs/latest/examples.html>`__ in
the documentation to see how to run them.

They demonstrate simple clients and servers. As appropriate, they
pretend that there is content playing and that it has a progressing
timeline. These examples serve to demonstrate how to use the library.
They are not intended as finished and useful tools.

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 <http://www.sphinx-doc.org>`__ documentation build system.

Building the documentation requires
`sphinx <http://www.sphinx-doc.org>`__ 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 <https://groups.google.com/forum/#!forum/pydvbcss>`__.

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 <CONTRIBUTING.md>`__ for details.

.. |Build status| image:: https://travis-ci.org/bbc/pydvbcss.svg?branch=0.4.1
:target: https://travis-ci.org/bbc/pydvbcss
.. |Docs Status (stable)| image:: https://readthedocs.org/projects/pydvbcss/badge/?version=stable
:target: http://pydvbcss.readthedocs.io/en/stable/?badge=stable
.. |Docs Status (latest)| image:: https://readthedocs.org/projects/pydvbcss/badge/?version=latest
:target: http://pydvbcss.readthedocs.io/en/latest/?badge=latest
.. |Latest PyPI package| image:: https://img.shields.io/pypi/v/pydvbcss.svg
:target: https://pypi.python.org/pypi/pydvbcss
.. |Docs Status (stable)| image:: https://readthedocs.org/projects/pydvbcss/badge/?version=0.4.1
:target: http://pydvbcss.readthedocs.io/en/0.4.1/?badge=0.4.1

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydvbcss-0.4.1.tar.gz (88.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page