{"id":14483229,"url":"https://github.com/bbc/pydvbcss","last_synced_at":"2025-06-12T18:32:32.121Z","repository":{"id":26615362,"uuid":"30070655","full_name":"bbc/pydvbcss","owner":"bbc","description":"Python library that implements DVB protocols for companion synchronisation","archived":false,"fork":false,"pushed_at":"2018-07-16T09:32:52.000Z","size":2114,"stargazers_count":30,"open_issues_count":3,"forks_count":8,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-15T01:44:25.594Z","etag":null,"topics":["companion","dvb","dvb-css","dvb-protocols","hbbtv2","media-synchronisation","python","python2","rd-project","rd-section-bcs","rd-stability-green","synchronisation","wall-clock"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-30T12:18:30.000Z","updated_at":"2025-04-27T20:48:12.000Z","dependencies_parsed_at":"2022-08-17T17:31:37.865Z","dependency_job_id":null,"html_url":"https://github.com/bbc/pydvbcss","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/bbc/pydvbcss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fpydvbcss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fpydvbcss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fpydvbcss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fpydvbcss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/pydvbcss/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fpydvbcss/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259519177,"owners_count":22870324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["companion","dvb","dvb-css","dvb-protocols","hbbtv2","media-synchronisation","python","python2","rd-project","rd-section-bcs","rd-stability-green","synchronisation","wall-clock"],"created_at":"2024-09-03T00:01:37.494Z","updated_at":"2025-06-12T18:32:32.087Z","avatar_url":"https://github.com/bbc.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Python DVB Companion Screen Synchronisation protocol library and tools\n\n[![Build status](https://travis-ci.org/bbc/pydvbcss.svg?branch=master)](https://travis-ci.org/bbc/pydvbcss)\n[![Docs Status (stable)](https://readthedocs.org/projects/pydvbcss/badge/?version=stable)](http://pydvbcss.readthedocs.io/en/stable/?badge=stable)\n[![Docs Status (latest)](https://readthedocs.org/projects/pydvbcss/badge/?version=latest)](http://pydvbcss.readthedocs.io/en/latest/?badge=latest)\n[![Latest PyPI package](https://img.shields.io/pypi/v/pydvbcss.svg)](https://pypi.python.org/pypi/pydvbcss)\n\n* **[How to install](#install-the-code)**\n* **[Read the documentation](#read-the-documentation)**\n* **[Run the examples](#run-the-examples)**\n\n**pydvbcss** is a set of Python 2.7 libraries and command-line tools that implement some of the\nprotocols defined in the DVB CSS specification (published as [ETSI 103-286 part 2](http://www.etsi.org/standards-search?search=103+286\u0026page=1\u0026title=1\u0026keywords=1\u0026ed=1\u0026sortby=1))\nand are used for the \"inter-device synchronisation\" feature in **[HbbTV 2](http://hbbtv.org/resource-library/)**.\nThese protocols enable synchronisation of media presentation between a TV\nand Companion devices (mobiles, tablets, etc).\n\nThis library includes simple to use high level abstractions that wrap up the\nserver or client behaviour for each protocol as well as low level code for\npacking and unpacking messages sent across the protocols. There are also\nobjects that work with the rest of the library to represent clocks and timelines.\n\nThis code is intended as an informal reference and is suitable for building\nprototypes and testing tools that implement TV (server) or Companion\n(client) behaviour. It is not considered production ready or suitable for\nintegration into consumer products.\n\nThe code does not implement media playback functionality and this is not a planned\nfeature.\n\nThe 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\u0026page=1\u0026title=1\u0026keywords=1\u0026ed=1\u0026sortby=1).\n\n## Getting started\n\n**pydvbcss** requires [ws4py](https://ws4py.readthedocs.io/en/latest/) for\nuse in clients and servers, and also [cherrypy](http://www.cherrypy.org)\nfor server implementations.  The steps below describe how to install these.\n\n**pydvbcss** has been developed on Mac OS X 10.10 but has also been used\nsuccessfully on Microsoft Windows 7 and Ubuntu 14.04.\n\n\n\n### Read the Documentation\n\nThe docs for the library can be read online on readthedocs.org:\n\n   * [![Docs Status (stable)](https://readthedocs.org/projects/pydvbcss/badge/?version=stable)](http://pydvbcss.readthedocs.io/en/stable/?badge=stable) [Docs for current stable release](http://pydvbcss.readthedocs.io/en/stable/?badge=stable)\n   \n   * [![Docs Status (latest)](https://readthedocs.org/projects/pydvbcss/badge/?version=latest)](http://pydvbcss.readthedocs.io/en/latest/?badge=latest) [Docs for latest commits to master release](http://pydvbcss.readthedocs.io/en/latest/?badge=latest)\n\nLinks are also available from those pages through to documentation for earlier releases.\n\n\n\n### Install the code ...\n\n*On Mac OS X and Linux you may need to run one or more of the commands as root.*\n\n#### Using PyPi _(core library only, no examples or tools)_\n\n   * [![Latest PyPI package](https://img.shields.io/pypi/v/pydvbcss.svg)](https://pypi.python.org/pypi/pydvbcss) [See the pydvbcss PyPI package page](https://pypi.python.org/pypi/pydvbcss). \n\nIf you ONLY want the library (not the [code examples and tools](#run-examples) ) and\nif you don't require the very latest bugfixes, then you can install a recent\nrelease package from the Python Package Index (PyPI) using\n[pip](https://pip.pypa.io/en/latest/installing.html):\n\n    $ pip install pydvbcss\n\nOr if upgrading from a previous version:\n\n    $ pip install --upgrade pydvbcss\n\nYou can use `pip search pydvbcss` to verify which version is installed.\n\n\u003e *See note in the next section about `CherryPy` and `ws4py` dependencies.*\n\n\n#### From Github or a release tarball _(includes examples and tools)_\n\nThe [master branch](https://github.com/BBC/pydvbcss/tree/master) is the latest\nstate of the code, including any recent bugfixes. It is mostly stable but\nmight have occasional small API changes.\n[Release snapshots](https://github.com/BBC/pydvbcss/releases) are also available\nbut won't contain the very latest bugfixes or new features.\nBoth of these options include the full code, including [examples](#run-examples).\n\nFirst you need to install dependencies...\n\nWe recommend using [pip](https://pip.pypa.io/en/latest/installing.html) to install\ndependencies from the Python Package Index [PyPI](https://pypi.python.org/pypi):\n\n    $ pip install -r requirements.txt\n\n\u003e *NOTE: There have been recent incompatibilities between certain versions of\n\u003e `cherrypy`, `ws4py` and `cheroot`. Therefore, `requirements.txt` requires specific\n\u003e (older) versions of these pacakges. You are welcome to try newer versions installing\n\u003e them manually. See [#15](https://github.com/bbc/pydvbcss/issues/15) for background\n\u003e details.*\n\nThen take (or update) your clone of the repository *master* branch, or\ndownload and unzip a snapshot release and run the `setup.py` script to\ninstall:\n\n    $ python setup.py install\n    \nThis will install all module packages under 'dvbcss'.\n\nThere is a limited test suite (it only tests certain classes at the moment).\nRun it via setup.py:\n\n    $ python setup.py test\n\nThis checks some timing sensitive implementation issues, so ensure you are not\nrunning any CPU intensive tasks at the time.\n\n\n\n## Running the examples and tools\n\nThere is a set of example and tools demonstrating simple servers and clients for the\nprotocols included with the library. See the \n[quick start guide](https://BBC.github.io/pydvbcss/docs/latest/examples.html) \nin the documentation to see how to run them.\n\nThe clients are useful tools to test a TV implementation is outputting the correect data.\n\nThe servers can be modified to simulate a TV that is playing content with an ID\nand timeline(s) that a companion application expects.\n\n### Example: checking protocols implemented by a TV\n\nStart the content playing on the TV and ensure it is serving the protocols (for HbbTV 2\nTVs this requires an HbbTV application to enable inter-device synchronisation).\n\nSuppose the TV is serving the CII protocol at the URL `ws://192.168.0.57:7681/cii`...\n\nTo check the CII protocol:\n\n    $ python examples/CIIClient.py ws://192.168.0.57:7681/cii\n\nSuppose 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`...\n\nTo check the TV's Wall Clock protocol:`\n\n    $ python examples/WallClockClient.py 192.168.0.57 6677\n\nTo check the TV reporting a PTS timeline (uses both Wall Clock and TS protocols):\n\n    $ python examples/TSClient.py ws://192.168.0.57:7681/ts \\\n        udp://192.168.0.57:6677 \\\n        \"\" \\\n        \"urn:dvb:css:timeline:pts\" \\\n        9000\n\n\n## Super-quick introduction to the protocols\n\nDVB has defined 3 protocols for communicating between a companion and TV in\norder to create synchronised second screen / dual screen / companion\nexperiences (choose whatever term you prefer!) that are implemented here:\n\n* CSS-CII - A WebSockets+JSON protocol that conveys state from the TV, such\n  as the ID of the content being shown at the time. It also carries the URLs\n  to connect to the other two protocols.\n\n* CSS-WC - A simple UDP protocol (like NTP but simplified) that establishes\n  a common shared clock (a \"wall clock\") between the TV and companion,\n  compensating for network delays.\n\n* CSS-TS - Another WebSockets+JSON protocol that communicates timestamps\n  from TV to Companion that describe the current timeline position.\n\nThe TV implements servers for all 3 protocols. The Companion implements\nclients.\n\nThere are other protocols defined in the specification (CSS-TE and CSS-MRS) that\nare not currently implemented by this library.\n\n\n## Building the documentation for yourself\n\nYou can also build the documentation yourself. It is written using the\n[sphinx](http://www.sphinx-doc.org) documentation build system.\n\nBuilding the documentation requires [sphinx](http://www.sphinx-doc.org) and\nthe sphinx \"read the docs\" theme. The easiest way is using PyPI:\n\n    $ pip install sphinx\n    $ pip install sphinx_rtd_theme\n\nThe `docs` directory contains the configuration and main documentation\nsources that descibe the structure. Most of the actual words are in the\ninline docstrings in the source code. These structural pages pull these in.\n\nTo build docs in HTML format, either:\n\n    $ python setup.py build_sphinx\n\nor:\n\n    $ cd docs\n    $ make html\n    \n\n\n## Contact and discuss\n\nDiscuss and ask questions on the [pydvbcss google group](\u003chttps://groups.google.com/forum/#!forum/pydvbcss\u003e).\n\nThe original author is Matt Hammond 'at' bbc.co.uk\n\n\n\n## Licence\n\nAll code and documentation is licensed under the Apache License v2.0.\n\n\n\n## Contributing\n\nIf you would like to contribute to this project, see\n[CONTRIBUTING](CONTRIBUTING.md) for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fpydvbcss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Fpydvbcss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fpydvbcss/lists"}