A practical guide on handling the broadcast a/v object

Before you read this post

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

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.