{"id":18376842,"url":"https://github.com/bbc/dvbcss-synctiming","last_synced_at":"2025-04-06T20:31:40.970Z","repository":{"id":27769160,"uuid":"31257551","full_name":"bbc/dvbcss-synctiming","owner":"bbc","description":"Measuring synchronisation timing accuracy for DVB Compainion Screen Synchronisation TVs and Companions","archived":false,"fork":false,"pushed_at":"2017-05-19T08:33:44.000Z","size":1264,"stargazers_count":21,"open_issues_count":3,"forks_count":6,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-18T21:50:40.365Z","etag":null,"topics":["calibration","companion-screen","dvb-css","dvb-protocols","dvbcss","hbbtv2","measurement","media-synchronisation","rd-project","rd-section-bcs","rd-stability-green","synchronisation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"dalavanmanphonsy/InlineHistory","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-02-24T11:42:58.000Z","updated_at":"2025-02-21T06:33:12.000Z","dependencies_parsed_at":"2022-09-03T04:41:24.297Z","dependency_job_id":null,"html_url":"https://github.com/bbc/dvbcss-synctiming","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fdvbcss-synctiming","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fdvbcss-synctiming/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fdvbcss-synctiming/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fdvbcss-synctiming/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/dvbcss-synctiming/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247547588,"owners_count":20956579,"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":["calibration","companion-screen","dvb-css","dvb-protocols","dvbcss","hbbtv2","measurement","media-synchronisation","rd-project","rd-section-bcs","rd-stability-green","synchronisation"],"created_at":"2024-11-06T00:25:03.280Z","updated_at":"2025-04-06T20:31:40.268Z","avatar_url":"https://github.com/bbc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DVB companion synchronisation timing accuracy measurement\n\n**The code and hardware designs in this project form a system for measuring\nhow accurate synchronisation is for a device that implements the [DVB CSS\nSpecification](https://www.dvb.org/search/results/keywords/A167). This\nspecification defines protocols that enable synchronisation of media\npresentation between a TV and Companion devices (mobiles, tablets, etc).**\n\n* **[Overview](#overview)**\n* **[Getting Started](#getting-started)**\n* **[How does it work?](#how-does-the-measurement-system-work)**\n\nThis system can measure with approximately millisecond accuracy for\nCompanion Screen Applications (CSAs) and TV Devices.\n\n*Update: Measurement of TV Devices has been added!*\n\n*Very shortly we will be adding an example showing how to use the same\nmeasurement back-end code to measure relative synchronisation between\naudio and video. The explanations here cover all these situations.*\n\n## Overview\n\nThe measurement system consists of:\n\n* Python code running on a PC or laptop that emulates the role of either the\n  TV Device or the CSA. \n\n* A microcontroller for measuring the timing of light and sound output from\n  the device being measured.\n\n* A test video sequence that the TV or CSA plays.\n\n  ![Diagram showing the overall architecture](docs/architecture-overview.png \"System architecture\")\n\nThe PC code talks using the DVB protocols. If it is a TV Device being\nmeasured, then it listens to the timings reported by the TV (the TV's claim\nas to what presentation timing it is using). If it is a CSA being tested then\nit instructs the CSA of what timings it should use.\n\nAn external microcontroller (an [Arduino\nDue](http://arduino.cc/en/Main/arduinoBoardDue) ) samples the light and sound\nfrom the device being tested and notes the precise timing of those samples.\n\nThe TV or Companion Screen Application must present a specific video test\nsequence containing flashes and beeps at defined times. The flashes are\ndetected by a light sensor affixed to the display over the area of the image\nthat flashes. The audio output (or a microphone) feeds a line-level audio\ninput.\n\nThe microcontroller is told which light sensor and/or audio inputs should be\nread during data capture. Once the microcontroller has collected samples over\na period of time, these are sent to the PC via a USB connection. Code on the\nPC detects the flashes and beeps from the sample data and translates the\ntimings of the samples to that of the timeline used in the DVB\nsynchronisation protocols.\n\nThe PC can therefore match up the observed timings of flashes and beeps to\nthose that it expected for the video clip and determine how much they\ndiffered from what was conveyed via the DVB protocols.\n\nMore information [on how the measurement system works.](docs/README.md) is in\nthe [README](docs/README.md) in the [docs](docs) folder.\n\n\n## Getting started\n\nThe PC code is written primarily in Python 2.7 and will run under Windows,\nLinux or Mac OS X. It requires [pydvbcss](https://github.com/BBC/pydvbcss),\n[pyserial](http://pyserial.sourceforge.net/) and [pillow (a fork of\nPIL)](https://pillow.readthedocs.org/) libraries.\n\nThe Arduino microcontroller code is written using Arduino's free IDE. This\nIDE has built in support for uploading the code to the Arduino. The IDE also\nruns on Windows, Mac and Linux.\n\n\n### 1. Download this clode plus dependencies\n\n**Clone the master branch of this code:**\n\n    $ git clone https://github.com/bbc/dvbcss-synctiming.git\n\nThe [master branch](https://github.com/BBC/dvbcss-synctiming/tree/master) is the\nlatest state of the code, including any recent bug fixes and new features. It\nwill be kept stable (working). Alternatively you can download a [release\nsnapshot](https://github.com/BBC/dvbcss-synctiming/releases).\n\n**Now lets also get the dependencies...**\n\nOn Mac OS X and Linux you may need to run one or more of the following\ncommands as root.\n\n1. We recommend using [pip](https://pip.pypa.io/en/latest/installing.html) to\n   install pyserial and PIL (aka \"pillow\") from the Python Package Index\n   [PyPI](https://pypi.python.org/pypi):\n      \n        $ pip install pyserial \n        $ pip install pillow\n\n2. Download and install pydvbcss library. It can now also be installed using PIP:\n      \n        $ pip install pydvbcss  \n\n   Alternatively, you can download the (pydvbcss sources](https://github.com/BBC/pydvbcss)\n   and install manually by following the instructions in pydvbcss's README.\n\n3. Install the *Arduino SDK* to get the USB drivers for communicating with\n   the Arduino (even if you have already programmed the device (see below).\n   You need to [download version 1.6 or later](https://www.arduino.cc/en/Main/Software).\n\n### 2. Create a video test sequence\n\nDo this using the [video test sequence\ngenerator](test_sequence_gen/README.md) that is included in this project.\n\nThe device being tested (TV Device or CSA) must play a video clip containing\nsuitable beeps and flashes at defined times. The measurement system needs\nmetadata (that is also created by the test sequence generator) so that it\nknows what times the beeps and flashes occur at in the sequence.\n\n\n### 3. Get an Arduino Due and assemble the sensor hardware\n\nThis project includes details of how to create the necessary\n[sensor input hardware](hardware/README.md) for the Arduino microcontroller\nand [install the arduino code](hardware/README.md)\n\nWhen you are ready to make a measurement, connect it all up:\n\n1. Affix the light sensor to the region of the display where the flashing\nrectangular box from the test video sequence appears. Connect the light\nsensor to light sensor input 0 of the Arduino circuit.\n\n2. Connect the audio output of the TV/CSA to audio input 0 of the Arduino\ncircuit. You can also use a microphone (with line-level output) but this is\nnot recommended.\n\n3. Make sure the screen brightness is reasonable and audio output is un-muted\nand at a reasonable volume.\n\n4. Connect the Arduino's \"native\" USB port to a USB port on the PC.\n\n\n\n### 4. Decide what the TV or CSA is going to do\n\nPrior making a measurement, the measurement system, and the system being\nmeasured (the TV Device or CSA) must both agree on what timeline will be used\nvia the DVB CSS protocols (including agreeing its tick rate) and how it will\nrelate to the playing of the test video sequence.\n\n**When measuring a TV Device** the measurement system will need to be told:\n* what timeline it must request from the TV (timelineSelector value);\n* the tick rate of that timeline;\n* and what value of the timeline corresponds to the start of the video.\n\n**When measuring a CSA** the measurement system and CSA will need to know:\n* what timelineSelector is to be used;\n* the tick rate of that timeline;\n* and what value of the timeline should correspond to the start of the video.\n\nIn both cases, the measurement system also needs the metadata for the video\ntest sequence that tells it the timing of the flashes and beeps within the\nsequence. This metadata is created automatically by the\n[video test sequence generator](test_sequence_gen/README.md).\n\nFinally, if a CSA is being measured, then the **CSA must report the\ngreatest Wall Clock dispersion during the measurement period** so this can be\ntaken into account by the measurement system.\n \n*How to calculate dispersion is explained in Annex C.8 of the\n[DVB CSS specification](https://www.dvb.org/search/results/only/standards/page/1/items/12/keywords/A167-2)*\n\n(When the measurement system is measuring a TV Device, it is acting in the role\nof the CSA and so will be able to observe its dispersion for Wall Clock\nsynchronisation itself)\n\n\n### 5. Take a measurement\n\n#### Taking a measurement a Companion Screen Application\n\n*For this scenario, the measurement system will pretend to be the TV. The\nCompanion Screen Application will connect to the measurement system using the\nDVB CSS protocols. The measurement system will pretend to have a timeline, and\nwill compare the timing information it sent to the CSA to the light and sound\nthat the CSA emits.*\n\n1. Press the \"RESET\" button on the Arduino.\n\n2. Start the measurement software by running\n   [src/exampleCsaTester.py](src/exampleCsaTester.py) and configuring it using\n   command line parameters. For example (split over multiple lines for ease of\n   reading):\n\n        $ python src/exampleCsaTester.py urn:dvbcss-synctiming:testvideo  \\\n                                   urn:dvb:css:timeline:pts 1 90000       \\\n                                   12345678                               \\\n                                   --addr 192.168.1.5                     \\\n                                   --light0 metadata.json                 \\\n                                   --audio0 metadata.json                 \\\n                                   --toleranceTest 8.0                    \\\n                                   --measureSecs 15\n   \n    This instructs the measurement system to:\n\n     * Pretend to be a TV with content id of \"urn:dvbcss-synctiming:testvideo\"\n\n     * ... and to provide a PTS timeline:\n       * denoted by timeline selector value of \"urn:dvb:css:timeline:pts\"\n       * with a tick rate of 1 unit per tick and 90000 units per second\n         (meaning 90000/1 ticks per second)\n\n     * ... emulating the role of the TV at 192.168.1.5, using defaults for port\n       numbers:\n       * CSS-CII: ws://192.168.1.5:7681/cii\n       * CSS-TS: ws://192.168.1.5:7681/ts\n       * CSS-WC: udp://192.168.1.5:6677\n\n     * Assume the CSA will play the test sequence video such that the first\n       frame of that video will be showing when the timeline position is\n       12345678.\n\n     * Measure the first light sensor (light sensor 0) and first audio input\n       (audio input 0), and to compare both to the expected times of beeps\n       and flashes in `metadata.json` (this file was created by the \n       [test video sequence generator](test_sequence_gen/README.md))\n       \n     * Report on whether the timing was accurate enough to be within a\n       tolerance of +/- 8 milliseconds (after error bounds of measurement are\n       taken into account)\n   \n     * Measure for only 15 seconds. If this option is omitted, the arduino\n       measures until its memory buffer is full. See\n       [this table](#measurement-period-duration). This number must be an\n       integer number of seconds.\n   \n    (For more information on the command line arguments, use the `--help`\n    option) \n\n3. Start the CSA and get it to synchronise with the measurement system.\n\n    * The CSA needs to connect to the CSS-CII server being provided by\n      the measurement system at the URL determined by the command line\n      options, and then also use the CSS-TS and CSS-WC protocols.\n\n4. Follow the instructions (displayed by the measurement system) to start\n   taking the measurement.\n\nOnce measurement is complete, the program will ask for the \ngreatest Wall Clock dispersion of CSA during the measurement period. The CSA\nmust output this information somehow.\n\nThe system will then display the results and exit. This includes details of\nhow good a match it found between the pattern of flashes and beeps it\nexpected and those that it observed. It also reports how far ahead or behind\nthe CSA appeared to be.\n\n#### Taking a measurement of a TV Device\n\n*For this scenario, the measurement system will pretend to be the Companion\nScreen Application. It will connect to the TV using the DVB CSS protocols and\ncompare the timing information reported by the TV to the light and sound it\nsees coming from the TV.*\n\n1. Press the \"RESET\" button on the Arduino.\n\n2. Start the TV Device playing the test video sequence.\n\n3. Start the measurement software by running\n   [src/exampleTVTester.py](src/exampleTVTester.py) and configuring it using\n   command line parameters. For example (split over multiple lines for ease of\n   reading):\n\n        $ python src/exampleTVTester.py \"\"                                 \\\n                                        \"urn:dvb:css:timeline:pts\" 1 90000 \\\n                                        12345678                           \\\n                                        ws://192.168.1.23:7681/ts          \\\n                                        udp://192.168.1.23:6677            \\\n                                        --light0 metadata.json             \\\n                                        --audio0 metadata.json             \\\n                                        --toleranceTest 23.0\t\t   \\\n                                        --measureSecs 15\n   \n    This instructs the measurement system to:\n\n     * Pretend to be a CSA, connecting to:\n       * a CSS-TS service at: ws://192.168.1.23:7681/ts\n       * a CSS-WC service at 192.168.1.23 on port 6677\n      \n     * ... and to request (via CSS-TS) to synchronise to a PTS timeline:\n       * denoted by timeline selector value of \"urn:dvb:css:timeline:pts\"\n        * with a tick rate of 1 unit per tick and 90000 units per second\n         (meaning 90000/1 ticks per second)\n       * asking that the timeline be available from the TV irrespective\n         of what content is showing\n         (a contentIdStem of the empty string \"\" will match any content ID)\n\n     * Assume the TV will play the test sequence video such that the first\n       frame of that video will be showing when the timeline position is\n       12345678.\n\n     * Measure the first light sensor (light sensor 0) and first audio input\n       (audio input 0), and to compare both to the expected times of beeps\n       and flashes in `metadata.json` (this file was created by the \n       [test video sequence generator](test_sequence_gen/README.md))\n       \n     * Report on whether the timing was accurate enough to be within a\n       tolerance of +/- 23 milliseconds (after error bounds of measurement\n       are taken into account)\n\n     * Measure for only 15 seconds. If this option is omitted, the arduino\n       measures until its memory buffer is full. See\n       [this table](#measurement-period-duration). This number must be an\n       integer number of seconds.\n   \n    (For more information on the command line arguments, use the `--help`\n    option) \n\nThe measurement system will start, connect to the TV and immediately\nbegin measuring.\n\nThe system will then display the results and exit. This includes details of\nhow good a match it found between the pattern of flashes and beeps it\nexpected and those that it observed. It also reports how far ahead or behind\nthe CSA appeared to be.\n\n\n## Measurement period duration\n\nThe system can measure until the 90 KByte buffer on the arduino is full.\nFor each input pin being measured, 2000 bytes of data are used every second.\nThe table below shows the maximum measurement periods allowed:\n\nNumber of light or sound input pins being measured | Maximum measurement duration possible\n-------------------------------------------------- | -------------------------------------\n1 | 45 seconds\n2 | 22 seconds\n3 | 15 seconds\n4 | 11 seconds\n\n**Remember** that length of the measurement period in seconds must be equal\nto or greater than the sequence bit-length of the test video sequence.\nFor example: a measurement period of at least 7 seconds must be used for\na 7 bit sequence.\n\nIf the measurement period is too short then the system will sometimes fail\nto correctly determine the synchronisation accuracy and will produce spurious\nerroneous results.\n\n## Assumptions\n\nThis measurement system makes various assumptions that must be taken into\nconsideration when making a measurement:\n\n### Playback must be constant during measurement\n\nDuring the period of measurement, the media playback should proceed at a\nconstant speed without pausing, or skipping forwards or backwards.\n\n### The TV/CSA does not skip more than one or two frames when keeping in sync\n\nThe \"flashes\" and \"beeps\" detected by the measurement system are 3 frames in\nduration. If the TV or CSA playing the test video sequence skips more than 1\nor 2 consecutive frames then the \"flashes\" or \"beeps\" will not be detected.\n\n### The display's light output does not toggle on/off repeatedly during a frame\n### ...or has off-periods significantly shorter than 4 ms\n\nSome display technologies modulate their light output (e.g. modulating the\nbacklight of an LCD panel). The algorithm that detects flashes will ignore\nbrief off periods during a flash of up to 4 sample periods (4 milliseconds).\n\nIf, during a frame containing a flash, the light output is modulated off for\n4 milliseconds or longer then the algorithm will mistake this for the end of\nthe flash and the start of a new one.\n\n### The light sensor does not pick up significant stray light\n### The audio signal is free from background noise\n\nThe light sensor should be fixed as closely as possible to the display and,\nideally, enclosed to avoid too much stray light.\n\nSimilarly, the audio should be relatively free from interference. A direct\nconnection from an audio output is ideal. However, if a microphone is used,\nthen care is needed to ensure there is silence while measurements are being\ntaken. Note that the audio inputs are line-level, and so an un-powered\nmic's output signal is unlikely to work unless it is amplified.\n\n\n## How does the measurement system work?\n\nThere is an [explanation of how the measurement system works.](docs/README.md)\nare in the [docs](docs) folder.\n\n\n\n## Contact and discuss\n\nPlease get in touch with the authors to discuss or ask questions.\n\nThe original authors are:\n* Jerry 'dot' Kramskoy 'at' bbc.co.uk\n* Matt 'dot' Hammond 'at' bbc.co.uk\n\nBecause this code uses the [pydvbcss\nlibrary](https://github.com/BBC/pydvbcss), you can also discuss it at the\n[pydvbcss google group](\u003chttps://groups.google.com/forum/#!forum/pydvbcss\u003e).\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fdvbcss-synctiming","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Fdvbcss-synctiming","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fdvbcss-synctiming/lists"}