The application/oipfCapabilities embedded object

Support in HbbTV

Available since: HbbTV 1.0 (ETSI TS 102 796 V1.1.1, OIPF DAE V1.1)

The hasCapability() method shall be supported with the profile names being the HbbTV® option strings as defined in clause 10.2.4.8.

See clauses A.2.1 and A.2.30 for clarification of the behaviour of the extraSDVideoDecodes and extraHDVideoDecodes properties and for the definition of the extraUHDVideoDecodes property.

Comment

10.2.4.8 Option strings

The strings defined in table 13 shall be used to indicate which options are supported by a terminal. They shall be used:

  • In the HTTP User-Agent header for applications data retrieval through HTTP.
  • In the ui_profile element’s name property of the xmlCapabilities property of the application/oipfCapabilities embedded object.
  • As parameters of the hasCapability() method of the application/oipfCapabilities embedded object to dynamically query the options supported by the terminal.

NOTE: Some of the strings defined in the clause intentionally match with the “UI Profile Name Fragment” strings defined in the OIPF DAE specification [1].

Table 13: HbbTV® Option Strings

Option stringMeaning
“+DL”Support for file download feature.
“+PVR”Support for PVR feature.
“+DRM”Support for the DRM feature – specifically that the XML capabilities include a <drm> element as defined below (see note).
“+IPC”Support for the “IP delivery CICAM player mode” as defined in the DVB Extensions to CI Plus ETSI TS 103 205 [37].
“+AFS”Support for the CICAM Auxiliary File System as defined in the DVB Extensions to CI Plus ETSI TS 103 205 [37].
NOTE: “+DRM” has a specific meaning in OIPF which it does not have in the present document.

A.2.1 Resource management

In clause 4.4.5 of the OIPF DAE specification [1], the STATIC_ALLOCATION model is not included in the present document. All resource allocation is under the DYNAMIC_ALLOCATION model.

Resource allocation between any number of A/V control objects and/or video/broadcast objects shall be based on a “first-come, first-served” policy. Resources shall not be taken away from one object of either of these types in order to meet a request on a second object of either of these types:

  • If the resources needed for the request on the second object (suitable video decoder, suitable audio decoder and, if the second object is a video/broadcast object, suitable tuner) are not available then the request on the second object shall fail as defined by the API for the type of object concerned.
  • If the resources needed for the request on the second object are available (e.g. the terminal has multiple audio and video decoders available to the HbbTV®implementation) then the resources shall be allocated to the second object and the request shall not fail due to lack of resources (although it may fail for an another unrelated reason).
  • If the request on the second object succeeds then the terminal shall present both objects at the same time without synchronization. If applications wish to have multiple objects present media with synchronization then the objects need to be added to a MediaSynchroniser object.

NOTE 1:  Broadcast-related applications that wish to use a video/broadcast object and also wish to use broadband-delivered content need to put the video/broadcast object into the stopped state to release the media decoders. Calling the unselectComponent method on a video/broadcast object does not release the media decoder for that component type. Changing a video/broadcast object from presenting a TV service to presenting a radio service should not release the video decoder. Changing a video/broadcast object from presenting a TV or radio service to presenting a data service (see clause 7.2.6 of the present document) should not release the video or audio decoder.

NOTE 2:  The policy for managing hardware resources defined here that applies to the A/V Control object and video/broadcast objects (first-come, first-served) is intentionally the exact opposite of the policy defined for the HTML 5 media element in clause 9.6.2 of the present document.

If a broadcast-related application that either:

  • does not include a video/broadcast object at all; or
  • includes a video/broadcast object that is in the unrealized state;

attempts to start playing broadband-delivered video/audio then the presentation of the broadcast channel shall be suspended and allocation of the required media resources by the A/V control object shall succeed. After the A/V control object release the allocated resources, e.g. by stopping the media, presentation of the broadcast service shall resume.

NOTE 3:  In spite of the above requirement, applications wishing to present only broadband-delivered video/audio should explicitly stop broadcast video/audio presentation in order to avoid implementation-dependent behaviour during the transition.

NOTE 4:  The above requirement is unrelated to availability of video and audio decoder resources. Hence such applications will give the same user experience on terminals supporting multiple video and audio decoders as they do on terminals supporting only one decoder of each type. Applications wishing to simultaneously present broadcast-delivered video/audio and broadband-delivered video/audio need to create both a video/broadcast object and an A/V control object or HTML5 media element.

When an HTML5 media element is unable to obtain the resources it needs to present media, then the request to present media through the media element shall fail with a MediaError with code MEDIA_ERR_DECODE.

An HTML5 media element shall not be able to obtain resources that are already in use either by an A/V control object or to present broadcast video (either by the HbbTV® application through a video/broadcast object, or by the terminal when it is presenting broadcast content not under the control of a video/broadcast object). An exception to the previous requirement is when the HTML5 media element and the resources that are in use are under the control of a single MediaSynchroniser object.

Resources are under the control of a single MediaSynchroniser object if there are media objects using those resources (video/broadcast object, A/V control object or HTML5 media element) and they are all currently added to the same MediaSynchroniser object (by means of the initMediaSynchroniser()and addMediaObject() methods).If the resources that would be needed by an A/V Control object or a video/broadcast object are allocated to an HTML5 media element (see clause 9.6.2), and the media element requiring the resource and the current media element owning the resource have not been added to the same media synchronizer object, then the request to present media through the object shall fail. For an A/V control object, the object shall go to playState 6 with the error property being 3, “insufficient resources”. For a video/broadcast object, this shall be reported by an onChannelChangeError with errorState 11, “insufficient resources are available to present the given channel (e.g. a lack of available codec resources)”.

NOTE 5:  Component selection and resource management behaviour is different after a media element has been added to a MediaSynchroniser object. This behaviour ensures that only one audio or video component is decoded simultaneously and the terminal allocates resources across the media objects to achieve this. See clauses 10.2.7.3, 10.2.7.4 and 10.2.7.5 for more details.

The properties extraSDVideoDecodes and extraHDVideoDecodes shall return the number of additional A/V decoders available at the time the application reads the properties and that can be used with either the A/V Control object or HTML5 media elements to render additional broadband streams.

A.2.30 Extensions and clarifications to the application/oipfCapabilities embedded object

The properties extraSDVideoDecodes, extraHDVideoDecodes shall be modified as follows:

  • The values returned shall reflect the number of additional streams containing video accompanied by audio that are possible to decode and present. If decoding a video stream is possible but not accompanied by an audio stream then the decoding of that video stream shall not be included in the value returned. Video streams that can be decoded but not presented shall not be included in the value returned.
  • If the value returned is non zero then a call to play an A/V Control object or video/broadcast object or an HTML5 video element shall not fail due to lack of availability of media decoding resources if the call is made in that same spin of the event loop and if the video to be played is SD (for extraSDVideoDecodes) or HD (for extraHDVideoDecodes).

The application/oipfCapabilities embedded object shall be extended as follows.

readonly Number extraUHDVideoDecodes
This property holds the number of additional streams containing UHD video accompanied by audio that are possible to decode. Depending on the current usage of system resources this value may vary. The value of this property is likely to change if an SD or HD video is started. If decoding a video stream is possible but not accompanied by decoding an audio stream then the decoding of that video stream shall not be included in the value returned. Video streams that can be decoded but not presented shall not be included in the value returned.

If the value returned is non zero then a call to play an A/V Control object or video/broadcast object or an HTML5 video element shall not fail due to lack of availability of media decoding resources if the call is made in that same spin of the event loop. Otherwise playing an A/V Control object or video/broadcast object or an HTML5 video element may still fail, even if extraUHDVideoDecodes was larger than 0 when last read. For A/V Control objects, in case of failure the play state for the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 3 (‘insufficient resources’). For video/broadcast objects, in case of failure the play state of the video/broadcast object shall be set to 0 (‘unrealized’) with a detailed error code of 11 (‘insufficient resources’). For an HTML5 video element, the request to present media through the media element shall have the error attribute set to a MediaError with code MEDIA_ERR_DECODE.

The OITF SHALL support following non-visual embedded object with the mime type “application/oipfCapabilities”.

Properties

readonly Document xmlCapabilities
Returns the OITF’s capability description as an XML Document object using the syntax as defined in Annex F without using any namespace definitions.
readonly Number extraSDVideoDecodes
This property holds the number of possible additional decodes for SD video. Depending on the current usage of system resources this value may vary. The value of this property is likely to change if an HD video is started. Adding an A/V Control object or video/broadcast object may still fail, even if extraSDVideoDecodes is larger than 0. For A/V Control objects, in case of failure the play state for the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 3 (‘insufficient resources’). For video/broadcast objects, in case of failure the play state of the video/broadcast object shall be set to 0 (‘unrealized’) with a detailed error code of 11 (‘insufficient resources’).
readonly Number extraHDVideoDecodes
This property holds the number of possible additional decodes for HD video. Depending on the current usage of system resources this value may vary. The value of this property is likely to change if an SD video is started. Adding an A/V Control object or video/broadcast object may still fail, even if extraHDVideoDecodes is larger than 0. For A/V Control objects, in case of failure the play state for the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 3 (‘insufficient resources’). For video/broadcast objects, in case of failure the play state of the video/broadcast object shall be set to 0 (‘unrealized’) with a detailed error code of 11 (‘insufficient resources’).

Methods

Boolean hasCapability( String profileName )

Description

Check if the OITF supports the passed capability.

Returns true if the OITF supports the passed capability, false otherwise.

Arguments

profileName

An OIPF base UI profile string or a UI Profile name fragment string as defined in section 9.2.

Examples of valid profileName: “OITF_HD_UIPROF” or “+PVR”.