====== General information ======

The DTVKit HBBTV module is composed of the static library libhbbtv.a and the plug-in libnpapihbbtvplugin.so and is based on the HbbTV standard, version 1.2.1.


===== libhbbtv.a =====

This library contains the implementation of the HbbTV standard and interfaces directly with the different parts of the system via various API, defined in the corresponding header files:
  * hbbtv.h: Contains functions to control the HBBTV module from the application, to initialise it, terminate it, set the debug level, notify events and so on. These functions are implemented by libhbbtv.a.
  * hbbtv_js.h: Contains functions used by the plug-in to implement the Javascript extensions needed by HbbTV applications. These functions are implemented by libhbbtv.a.
  * hbbtv_sif_browser.h: Contains functions that the HBBTV module uses to control the browser, to set the URL, pass the remote control keys, etc. These functions must be implemented outside the HBBTV module. As long as these functions are implemented correctly, the HBBTV module can interface to any browser supporting the NPAPI interface.
  * hbbtv_sif_conf.h: Contains functions that the HBBTV module uses to retrieve information from the system, such as preferred languages, network status, etc. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, the majority of such functions are implemented under externals/HBBTV, with the exception of HBBTV_GetPrefUiLang which is specific to the user interface.
  * hbbtv_sif_debug.h: Contains the definition of the function that the HBBTV module uses to output debug messages when compiled in debug mode. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.
  * hbbtv_sif_decoding.h: Contains the definition of the functions that the HBBTV module uses to control the live audio, video and subtitles presentation. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.
  * hbbtv_sif_mediaplayer.h: Contains the definition of the functions that the HBBTV module uses to control the presentation of media content streamed over the internet. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.
  * hbbtv_sif_os.h: Contains the definition of functions implementing operating system functionality such as memory allocation, semaphores, queues, etc... These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.
  * hbbtv_sif_pvr.h: Contains the definition of functions that the HBBTV module needs to implement PVR functionalities. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.
  * hbbtv_sif_service.h: Contains the definition of functions that the HBBTV module calls to retrieve information about live services, such as service details, service list and events. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.
  * hbbtv_sif_tuner.h: Contains the definition of functions used by the HBBTV module to control the tuner. These functions must be implemented outside the HBBTV module. If DTVKit DVBcore is used, they functions are implemented under externals/HBBTV.


===== Plugin =====

The plug-in implements the extension to the standard Javascript objects needed by the HbbTV applications using the NPAPI interface.
  * browser_app.h: The plug-in uses the functions defined in this header file to request that all the graphics in the specified area are removed to make a video visible. This is used to simulate the right z-order for video objects.
====== API Documentation ======

The online API for the latest version of HBBTV can be found [[http://www.dtvkit.org/wiki/HbbTV_1_0_api/|here]]
====== Building ======

To build the HBBTV module it is first necessary to configure the environment, an example configuration script is provided (example_setenv.sh). Please ensure the correct value for the environment variables is exported, some of them might not be needed. Please read the comments in the example script for more information.
Once the environment has been set up, compile by doing


//make//


in the root folder of the HBBTV module, this will compile both libhbbtv.a and the plugin. For the browser to be able to load the plug-in you will need to copy it in the proper location, which is browser specific. If you correctly set-up DTVKIT_HBBTV_PLUGIN_INSTALL_FOLDER, doing


//make install-plugin//


will copy the folder to the specified location.












====== Testing ======

===== Introduction =====

HBBTV in DTVKit is tested by substituting the normal [[application|DTVKit application]] with a specialised test application. The specialised test application: (1) isolates HBBTV from [[DVBCore]] by implementing its own, light DVB functionality, and (2) incorporates simulation functionality to facilitate the recording and playback of tests.

<code>cd app/test/HBBTV
source setenv.sh
make</code>

See 'app/example_setenv.sh' for an example build environment.

===== Record Tests =====

<code>./hbbtvtestsimulator -m record -t testdirectory</code>

When the test application is started with the record mode option, user actions are recorded in the test directory.

==== User Actions for Playback Validation ====

  * A region in the window can be: (1) selected by clicking two points, and (2) captured by pressing F11. In playback mode, it is checked that the same region matches what was captured in record mode.

  * The audio and video status can be captured by pressing F10. In playback mode, it is checked that the audio and video status matches what was captured in record mode.

===== Playback Tests =====

<code>./hbbtvtestsimualtor -m playback -t testdirectory -r resultfile.tap</code>

When the test application is started with the playback mode option, user actions which were recorded in the test directory are played back. If any playback validation check fails, a fail is recorded in the result file, otherwise a pass is recorded; result files conform to the [[http://testanything.org/|Test Anything Protocol (TAP)]] format.

===== Pre-recorded Tests =====
The 'mit-experts-testsuite' directory contains a number of tests (recordings), each of these tests automate the execution of a test in the MIT-xperts HbbTV-Testsuite. The MIT-xperts HbbTV-Testsuite is available from https://github.com/mitxp/HbbTV-Testsuite/wiki.

==== Portability ====

For the upcoming release of version 1.1, the tests were recorded on a system with Qt 4.8.1 and the Liberation font collection installed. A different system configuration could affect the application’s visual output, so could cause some or all of the pre-recorded tests to fail.