Blog

A practical guide on handling the broadcast a/v object

Before you read this post

IMPORTANT: It is highly recommended that prior to reading this post one consults the following tutorial

General behaviour of the broadcast a/v object

HbbTV terminals support the video/broadcast embedded object. The MIME type of this object is “video/broadcast”. The behaviour and possible states of the video/broadcast object is described in the following tutorial.

When no video/broadcast object is instantiated within the HbbTV application, or when all video/broadcast objects are in the unrealized state, broadcast video presentation is under the control of the terminal (and not the application). When video is under the control of the terminal:

  • Any broadcast video being presented gets displayed in the logical video plane.
  • The complete logical video plane is filled.
  • The terminal itself may scale and/or position video, for example to remove black bars.

When a video/broadcast object is in any state other than the unrealized state, broadcast video presentation is under the control of the application. When video is under the control of the application:

  • When the video/broadcast object is not in “full-screen mode”, any broadcast video being presented gets scaled and positioned to fit the video/broadcast object.
  • When the video/broadcast object is in “full-screen mode”, presented video gets scaled to fill the logical video plane. The terminal itself may further scale and/or position video, for example to remove black bars.
  • Depending on the Z index of the video/broadcast object with respect to other HTML elements (regardless of whether the object is in “fullscreen mode” or not), presented video may fully or partially obscure other HTML elements with a lower Z index, and may in turn be fully or partially obscured by HTML elements with a higher Z index. As a result of this, video may appear to be presented in a plane other than the logical video plane.

If the release() method is called on a video/broadcast object, or if the object is garbage collected, the control of broadcast video presentation is returned to the terminal and video gets re-scaled and re-positioned (if necessary).

Code snippets for common actions

Before doing any actual HbbTV application development, it is highly recommended to consult the related API documentation

Object declaration and instantiation:

It is important to note that the instantiation of the video/broadcast object does not cause tuner resources to be claimed. These resources are only claimed following a call to the setChannel(), bindToCurrentChannel(), nextChannel() or prevChannel() methods on a video/broadcast object:

If the applications wants to return the control of broadcast video to the terminal and release the resources, it should call the release() method:

If the application wants to stop presenting the broadcast video (but maintain control over the playback of broadcast video and tuner resources), it should call the stop() method:

A call to stop() method shall cause a transition of the video/broadcast object to the stopped state. Please note that calling this method from the unrealized state shall have no effect.
State of the video/broadcast object can be programmatically tracked using the event listener listening to PlayStateChange events:

Full code example

A fully working example can be found on the HbbTV Association’s GitHub repo: https://github.com/HbbTV-Association/Tutorials/tree/main/broadcast-object 

The example demonstrates the interaction of a HbbTV application with broadcast video and audio using the video/broadcast object and showcases how to get channel information from the terminal using the API

March 11, 2024

2024 HbbTV Plugfest and Testing Event in London

This year’s first International Plugfest and HbbTV Testing Event, co-organised by the HbbTV Association, Digital TV Group (DTG) and Deutsche TV-Plattform (DTVP), took place

  READ MORE

January 24, 2024

DTG & DTVP International Plugfest 2024

The Digital TV Group (DTG) and Deutsche TV-Plattform (DTVP) are delighted to announce their joint International Plugfest 2024 in cooperation with the HbbTV Association. This week-long

  READ MORE

December 21, 2023

Save the date: HbbTV Plugfests and Testing Events 2024

The HbbTV Association wishes to announce the following calendar for HbbTV Interoperability Plugfests and Testing Events planned in 2024, so that interested parties can

  READ MORE