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
| Name | Value | Use |
| ID_TVA_CRID | 0 | Used in the programmeIDType property to indicate that the programme is identified by its TV-Anytime CRID (Content Reference Identifier). |
| ID_DVB_EVENT | 1 | Used 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_CRID | 2 | Used 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. |
| 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:
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:
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, | ||
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. |