The Programme class

Support in HbbTV

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

The following properties are required:

– name

– programmeID

– programmeIDType

– description

– longDescription

– startTime

– duration

– channelID

– parentalRatings

All other properties and methods are not included.

The constants defined in clause 7.16.2.1 shall be supported however support for CRIDs is outside the scope of the present document.

Application developers need to be aware of clause A.2.29.1 concerning security.

Metadata extensions to Programme (7.16.2.3) are not implemented.

Recording extensions to Programme mandatory if PVR feature enabled.

Comment

Broadcast-related

A.2.29.1 Risk of tampering with data returned by APIs

Application developers should be aware that some APIs return data that may not be authenticated. In some circumstances an attacker may be able to modify the broadcast signalling from which this data is derived. This particularly applies to the properties and methods of the Channel and Programme classes:

  • Applications should be written to be tolerant of values which are outside the expected range without hanging up, locking up or crashing.
  • Applications should treat the values returned by name, Programme.name, Programme.description and Programme.longDescription with caution as an attacker may modify the broadcast signalling to include HTML or JavaScript as well as values that are outside the expected set. Applications shall not use the data returned by these properties in a way that would result in them being executed by the browser.
  • Applications should treat data returned by the getSIDescriptors method with caution. Applications shall not use this data in a way that would result in that such data being executed by the browser. Applications should be written to be tolerant of values which are outside the expected range without hanging up, locking up or crashing.

The Programme class represents an entry in a programme schedule.

Note: as described in the record( Programme programme ) method of the application/oipfRecordingScheduler object, only the programmeID property of the programme object is used to determine the programme or series that will be recorded. The other properties are solely used for annotation of the (scheduled) recording with programme metadata. The use of these metadata properties is optional. If such programme metadata is provided, it is retained in the ScheduledRecording object that is returned if the recording of the programme was scheduled successfully.

Constants

NameValueUse
ID_TVA_CRID0Used in the programmeIDType property to indicate that the programme is identified by its TV-Anytime CRID (Content Reference Identifier).
ID_DVB_EVENT1Used in the programmeIDType property to indicate that the programme is identified by a DVB URL referencing a DVB-SI event as enabled by section 4.1.3 of [OIPF_META2]. OPTIONAL.
ID_TVA_GROUP_CRID2Used in the programmeIDType property to indicate that the Programme object represents a group of programmes identified by a TV-Anytime group CRID.

Properties

String name
The short name of the programme, e.g. ‘Star Trek: DS9’.
String longName
The long name of the programme, e.g. ‘Star Trek: Deep Space Nine’. If the long name is not available, this property will be undefined.
String description
The description of the programme, e.g. an episode synopsis. If no description is available, this property will be undefined.
String longDescription
The long description of the programme. If no description is available, this property will be undefined.
Integer startTime
The start time of the programme, measured in seconds since midnight (GMT) on 1/1/1970.
Integer duration
The duration of the programme (in seconds).
String channelID
The identifier of the channel from which the broadcasted content is to be recorded. Specifies either a ccid or ipBroadcastID (as defined by the Channel object in section 7.13.11)
Integer episode
The episode number for the programme if it is part of a series. This property is undefined when the programme is not part of a series or the information is not available.
Integer totalEpisodes
If the programme is part of a series, the total number of episodes in the series. This property is undefined when the programme is not part of a series or the information is not available.
readonly Boolean is3D
Flag indicating whether the programme has 3D video.
String programmeID
The unique identifier of the programme or series, e.g., a TV-Anytime CRID (Content Reference Identifier).
Integer programmeIDType
The type of identification used to reference the programme, as indicated by one of the ID_* constants defined above.
readonly String IMI
The TV-Anytime Instance Metadata ID for this programme.
readonly ParentalRatingCollection parentalRatings
A collection of parental rating values for the programme for zero or more parental rating schemes supported by the OITF. For instances of the Programme class created by the createProgramme() method defined in section 7.10.1.1, the initial value of this property (upon creation of the Programme object) is an instance of the ParentalRatingCollection object (as defined in section 7.9.5) with length 0. Parental rating values can be added to this empty readonly parental rating collection by using the addParentalRating() method of the ParentalRatingCollection object. The ParentalRatingCollection is defined in section 7.9.5. The related ParentalRating and ParentalRatingScheme objects are defined in section 7.9.4 and 7.9.2 respectively. For instances of the Programme class returned through the metadata APIs defined in section 7.12 or through the programmes property of the video/broadcast object defined in section 7.13.3, the initial value of this property SHALL include the parental rating value(s) carried in the metadata or DVB-SI entry describing the programme, if this information is included. Note that if the service provider specifies a certain parental rating (e.g. PG-13) through this property and the actual parental rating extracted from the stream says that the content is rated PG-16, then the conflict resolution is implementation dependent.
readonly StringCollection groupCRIDs
The group CRIDs associated with this programme.

Metadata extensions to Programme

The OITF SHALL extend the Programme class defined in section 7.16.2 with the properties and methods described below.

This subsection SHALL apply for OITFs that have indicated <clientMetadata> with value “true” and a “type” attribute with values “bcg”, “eit-pf” or “dvb-si” as defined in section 9.3.7 in their capability profile.

Properties
readonly Channel channel
Reference to the broadcast channel where the programme is available. The value of this field is derived from the serviceIDref attribute of the Schedule element that refers to this programme.

readonly Boolean blocked

Flag indicating whether the programme is blocked due to parental control settings or conditional access restrictions.

The blocked and locked properties work together to provide a tri-state flag describing the status of a programme. This can best be described by the following table:

Description

blocked

locked

No parental control applies.

false

false

Item is above the parental rating threshold (or manually blocked); no PIN has been entered to view it and so the item cannot currently be viewed.

true

true

Item is above the parental rating threshold (or manually blocked); the PIN has been entered and so the item can be viewed.

true

false

Invalid combination – OITFs SHALL NOT support this combination

false

true

Integer showType

Flag indicating the type of show (live, first run, rerun, etc,).

The value of this property is determined by the child elements of the programme’s BroadcastEvent or ScheduleEvent element from the Program Location Table. Values are determined as follows:

Value

Description

1

The programme is live; indicated by the presence of a Live element with a value attribute set to true.

2

The programme is a first-run show; indicated by the presence of a FirstShowing element with a value attribute set to true.

3

The programme is a rerun; indicated by the presence of a Repeat element with a value attribute set to true.

If none of the above conditions are met, the default value of this field SHALL be 2.

Boolean subtitles
Flag indicating whether subtitles or closed-caption information is available. This flag SHALL be true if one or more BCG CaptionLanguage elements are present in this programme’s description, false otherwise.
Boolean isHD
Flag indicating whether the programme has high-definition video. This flag SHALL be true if a VerticalSize element is present in the programme’s description and has a value greater than 576, false otherwise.

Integer audioType

Bitfield indicating the type of audio that is available for the programme.

The value of this field is determined by the NumOfChannels elements in a programme’s A/V attributes. Values are determined as follows:

Value

Description

1

A mono audio stream is available (at least one AvAttributes.AudioAttributes element is present which has a child NumOfChannels element whose value is 1).

2

A stereo audio stream is available (at least one AvAttributes.AudioAttributes element is present which has a child NumOfChannels element whose value is 2).

4

A multi-channel audio stream is available (at least one AvAttributes.AudioAttributes element is present which has a child NumOfChannels element whose value is greater than 2).

For programmes with multiple audio streams, these values may be ORed together.

Boolean isMultilingual
Flag indicating whether more than one audio language is available for the programme. This flag SHALL be true if more than one BCG Language element is present in the programme’s description, false otherwise.
StringCollection genre
A collection of genres that describe this programme. The value of this field is the concatenation of the values of any Name elements that are children of Genre elements in the programme’s description.
readonly Boolean hasRecording
Flag indicating whether the Programme has a recording associated with it (either scheduled, in progress, or completed).
StringCollection audioLanguages
Supported audio languages, indicated by their ISO.639-2 language codes as defined in [ISO 639-2].
StringCollection subtitleLanguages
Supported subtitle languages, indicated by their ISO.639-2 language codes as defined in [ISO 639-2].
readonly Boolean locked
Flag indicating whether the current state of the parental control system prevents the programme from being viewed (e.g. a correct parental control PIN has not been entered to allow the programme to be viewed).
Methods

String getField( String fieldId )

Description

Get the value of the field referred to by fieldId that is contained in the metadata for this programme. If the field does not exist, this method SHALL return undefined.

Arguments

fieldId

The name of the field whose value SHALL be retrieved.

DVB-SI extensions to Programme

The following method SHALL be added to the Programme object, if the OITF has indicated support for accessing DVB-SI information, by giving the value “true” to element <clientMetadata> and the value “dvb-si” or “eit‑pf” to the “type” attribute of that element as defined in section 9.3.7 in their capability profile.

StringCollection getSIDescriptors( Integer descriptorTag,
Integer descriptorTagExtension, Integer privateDataSpecifier )

Description

Get the contents of the descriptor specified by descriptorTag from the DVB SI EIT programme’s descriptor loop. If more than one descriptor with the specified tag is available for the given programme, the contents of all matching descriptors SHALL be returned in the order the descriptors are found in the stream.

The descriptor content bytes SHALL be encoded in a string whose characters shall be restricted to the ISO Latin-1 character set. Each character in the string represents a byte of a DVB-SI descriptor, such that a byte at position “i” in the descriptor is equal the Latin-1 character code of the character at position “i” in the string.

Described in the syntax of JavaScript: let desc[ ] be the byte array of a descriptor, in which desc[0] is the descriptor_tag, then, the returned string (retval in the example below) is its equivalent string, if :

desc.length==retval.length and

for each integer i : 0<=i<desc.length holds

desc[i] == retval.charCodeAt(i).

If the descriptor specified by descriptorTag and (optionally) descriptorTagExtension and privateDataSpecifier does not exist, or if the metadata for this programme was retrieved from a source other than DVB-SI, this method SHALL return null.

If metadata for this programme has not yet been retrieved, this method SHALL return undefined. If the OITF supports the application/oipfSearchManager object as defined in section 7.12.1, the OITF SHALL notify applications of the availability of additional metadata via MetadataSearch events targeted at the application/oipfSearchManager object used to retrieve the programme metadata.

Arguments

descriptorTag

The descriptor tag as specified by [EN 300 468].

descriptorTagExtension

An optional argument giving the descriptor tag extension as specified by [EN 300 468]. This argument is mandatory when descriptorTag is 0x7f and ignored in all other cases.

privateDataSpecifier

An optional argument giving the private_data_specifier as specified by [EN 300 468]. If this argument is present, only descriptors related to the identified specifier will be returned.

Recording extensions to Programme

The OITF SHALL support the following extensions to the Programme class.

Clients supporting the recording management APIs defined in this section SHALL indicate this by adding the attribute “manageRecordings” to the <recording> element with a value unequal to ‘none’ in the client capability description as defined in section 9.3.3.

The functionality as described in this section is subject to the security model of section 10.

readonly ScheduledRecording recording
If available, this property represents the recording associated with this programme (either scheduled, in-progress or completed). Has value undefined if this programme has no scheduled recording associated with it.