Handling the broadcast a/v object

Before you read

Introduction

This example will build up on our Hello world example and will demonstrate interaction with broadcast video and audio using the video/broadcast object. The following figure shows the states that a video/broadcast object may be in. Dashed lines indicate automatic transitions between states. The video/broadcast object will be in the unrealized state when it is instantiated.

Applications can use the playState property of the video/broadcast object to read its current state. Possible playState values are:

Example application

The example application will:

• Initialize the video/broadcast object so it displays the current channel in „windowed“ (not full screen) mode in bottom right part of the screen;
• Attach an event listener to video/broadcast object which will display current state of the object (playState variable)
• Show info on current channel being displayed on terminal
• Show info on channels available on terminal

Observe the application scene post startup (FireHbbTV emulator):

Full source code is available here: https://github.com/HbbTV-Association/Tutorials/tree/main/broadcast-object

The code consists of:

• broadcast-object.html HTML document holding the application scene
• broadcast-object.css CSS document holding the application scene styling
• broadcast-object.js JavaScript file holding the application logic

broadcast-object.html

We start with:

as is required by chapter A.2.6.2 MIME type and DOCTYPE of the ETSI TS 102 796 V1.1.1 standard.

In head section we load our CSS and JS:

In body tag we set our onload function:

And we follow with our embedded objects:

The  application/oipfApplicationManager embedded object is used within our application logic to acquire the Application object, as set by standard and explained in Hello world example. The video/broadcast is our broadcast a/v object that we will use to control the display of broadcast video.

We follow with our application scene, contained in safe area as recommended by the standard:

The scene contains three status fields:

• Initialization status (shows status of initialization)
• video/broadcast object playState (updated by PlayStateChange event handler)
• Current channel info (shows info on channel currently displayed within video/broadcast object)

which are followed by a list of channels available to the terminal (which is acquired using functions / properties available with the video/broadcast object).

broadcast-object.css

Document defines style for body:

Style for the embedded objects:

The video/broadcast object is positioned to the lower-right part of the screen, at coordinates 890, 530 with set width to 250px and height to 140px. When setting width & height please observe limitations set by ETSI TS 102 796 V1.1.1 standard, Table 14: Minimum terminal capabilities. Z index is set to make sure that the video/broadcast is on top OSD graphics. The HbbTV graphics planes model is described in the chapter 10.1.1 Logical plane model of the standard.

Style for safe area:

Then we finish by setting style for status fields and channel list:

broadcast-object.js

Application logic is implemented in broadcast-object.js:

We define a broadcastObject which shall be used  for all things regarding broadcast video and audio and the initialization function. The initialization function retrieves the video/broadcast object using DOM and adds the PlayStateChange event listener. Then it calls bindToCurrentChannel() as defined by the state machine described in the beginning of this article followed by a call to setFullScreen(false) function which should put the broadcast a/v in “windowed” mode.  The video/broadcast object method void setFullScreen( Boolean fullscreen ) sets the rendering of the video content to full-screen (fullscreen = true) or windowed (fullscreen = false) mode. If a change in mode is indicated, it results in a change of the value of the video/broadcast object property fullScreen. Changing the mode does not affect the z-index of the object.

Finally, the initialization function obtains the currentChannel property and stores it to broadcastObject.currentLiveChannel.

After the initialization function other utility functions are defined:

The getChannelList() function retrieves the channelList property which contains a list of channels available to the terminal. The getChannelInfo(ch) function returns a text representation of a Channel object containing channel name and identifiers for that particular broadcast service within the broadcast network where it’s carried. Finally, the playStateChangeEventHandler() function implements the event listener for the PlayStateChange event.

The remainder of our code is the app entry function start(). It starts with Application object acquisition:

Once the Application object is acquired we initialize our broadcastObject and display corresponding initialization status and current channel information:

Then we retrieve and display the list of available channels:

We finish with the remainder of our app entry function: