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.