The video/broadcast embedded object

Support in HbbTV

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

In the setChannel() method, the optional contentAccessDescriptorURL parameter may be ignored.

The setVolume() and getVolume() methods and the playerCapabilities and allocationMethod properties are not included.

The modifications in clause A.2.4 shall be supported.

Comment

A.2.4 Extensions to the video/broadcast object

A.2.4.1 State machine and related changes

This clause describes a set of changes to the state machine and related text for the video/broadcast object defined in clause 7.13.1.1 of the OIPF DAE specification [1]:

Calling the setChannel() method from any state of the video/broadcast object with a null argument shall cause the application to transition to a broadcast-independent application (as described in clause 6.2.2.6). This is in addition to what is required by OIPF – e.g. causing the video/broadcast object to transition to the unrealized state and releasing any resources used for decoding video and/or audio. Hence the setChannel(null) and release() methods do not have the same behaviour in the present document.
A video/broadcast object with a CSS rule of display:none shall not be loaded and hence shall not be decoding audio or video.
Setting CSS display:none on a video/broadcast object should be equivalent to calling the release method or the setChannel method with a parameter of null. Applications should not depend on the state of the video/broadcast object if the application sets CSS display:none. Setting CSS visibility to hidden does not cause a state change.
In Table 8, “State transitions for the video/broadcast embedded object”, the following rows are modified as shown underlined.

Old State	Trigger	New State	State Transition Events	Description
Stopped	bindToCurrentChannel()	Connecting	PlayStateChange	Video and audio presentation is enabled The terminal starts to present the current channel.
Stopped	bindToCurrentChannel when suitable video and audio decoders are not available	Stopped	PlayStateChange
Connecting	The terminal successfully connected to the broadcast or IP multicast stream but presentation of content is blocked, e.g. by a parental rating mechanism or, content protection mechanism or resources cannot be claimed that are currently in use for presenting broadband content	Connecting	ChannelChange SucceededPlayStateChange	This is conceptually equivalent to a successful channel change where a transient error immediately pre-empts media presentation without the video/broadcast object entering the presenting state.

In clause 7.13.1.3 of the OIPF DAE specification [1], the definition of the bindToCurrentChannel() method is modified as shown:
If the video/broadcast object is in the unrealized state and video from exactly one channel is currently being presented by the OITF then this binds the video/broadcast object to that videochannel (even if the current channel does not contain video and/or audio). If more than one channel is currently being presented by the OITF then this binds the video/broadcast object to the channel whose audio is being presented. A successful call shall result in control of the resources used to present the channel (tuner, video decoder if the channel includes video and audio decoder if the channel includes audio) being seamlessly transferred to the calling HbbTV® This is intentionally the opposite of the “first-come, first-served” policy used between a video/broadcast object and other video/broadcast or A/V control objects.
If the video/broadcast object is in the stopped state then this restarts presentation of video and audio from the current channel under the control of the video/broadcast object. If video from more than one channel is currently being presented by the OITF then this binds the video/broadcast object to the channel whose audio is being presented.
When bindToCurrentChannel is called on a video/broadcast object in the stopped state and no suitable media decoders are available then the method call shall fail. For example when the media decoders are used by an A/V control object or by an HTML5 video element that is playing. A playStateChange event shall be generated with error ’11’- “insufficient resources are available to present the given channel (e.g. a lack of available codec resources)”. The video/broadcast object shall stay in the stopped state. The current channel of the video/broadcast object, the current channel of the terminal and the current channel of the application shall all remain unchanged (see OIPF [2], clause H.4). If the media decoders would become available and bindToCurrentChannel is called again then the video/broadcast object shall behave as specified.
If the video/broadcast object is in the unrealized state and there is no channel currently being presented, or binding to the necessary resources to play the channel (suitable tuner, suitable video decoder if the channel includes video and suitable audio decoder if the channel includes audio) through the video/broadcast object fails for whichever reason, the OITF shall dispatch an event to the onPlayStateChange listener(s) whereby the state parameter is given value 0 (“unrealized”) and the error parameter is given the appropriate error code.
The following paragraph is amended as shown using underline/strike-through markup:
If the current channel currently being presented is requested to be changed due to an action outside the application (for example, the user pressing the CH+ key on the remote) then any video/broadcast object presenting bound to that channel (i.e. in the connecting, presenting or stopped states as the result of a call to bindToCurrentChannel()) SHALL perform the same state transitions and dispatch the same events as if the channel change operation was initiated by the application using the setChannel() method.
In clause 7.3.1.2 of the OIPF DAE specification [1], the definition of the onPlayStateChange property is modified as shown using underline/strike-through markup:
The function that is called when the play state of the video/broadcast object changes as defined in Table 8, including changes from a state back to the same state. This function may be called either in response to an action initiated by the application, an action initiated by the OITF or an error (see section 7.13.1.1). In some cases, Table 8 defines that ChannelChangeError will be called instead of this function.

A.2.4.2 Access to the video/broadcast object

The following rules and clarifications shall apply to the video/broadcast object.

Broadcast-related applications shall have full access to the video/broadcast object. If a new broadcast service is selected then this may result in the broadcast-related application being killed as defined in clause 6.2.2.2. As defined in clause 6.2.2.2, selecting MPEG programs which are not broadcast services and which do not contain an AIT will not cause the running broadcast-related application to be killed.

Broadcast-independent applications shall be able to use the video/broadcast object as follows:

The following properties and methods shall have no restrictions: createChannelObject(), onChannelChangeSucceeded, onChannelChangeError, onPlayStateChange, addEventListener(), removeEventListener(), width and height.
The setChannel() method shall trigger the behaviours defined in clause 2. If the method is used to select a broadcast service then this may result in the application becoming a broadcast-related application. If the setChannel() method is used to access an MPEG program which is not a broadcast service and which does not contain an AIT, then there are no restrictions and no consequences for the application lifecycle.
The following methods shall always throw a “Security Error” (as defined in clause 10.1.1 of the OIPF DAE specification [1]): getChannelConfig(), bindToCurrentChannel(), prevChannel() and nextChannel().
The following methods shall have no effect: setFullScreen(), release(), and stop().
The object shall always be in the unrealized or connecting states unless connected to an MPEG program which is not a broadcast service and which does not contain an AIT.

Terminals shall only support one active instance of a video/broadcast object at any time. “Active” means here that the video/broadcast object is either in the connecting or the presenting state. Trying to activate an instance of a video/broadcast object (through a call to bindToCurrentChannel() or a setChannel() call) while another instance is already active shall fail and result in an error returned to the application through a ChannelChangeError event.

A.2.4.3 Support for quiet service selection

A.2.4.3.1 Quiet service selection

The following changes shall apply to the video/broadcast object to support “quiet” service selection.

void setChannel( Channel channel, Boolean trickplay, String contentAccessDescriptorURL, Number quiet )
Description	Requests the OITF to switch a (logical or physical) tuner to the channel specified by channel and render the received broadcast content in the area of the browser allocated for the video/broadcast object. If the channel specifies an idType attribute value which is not supported by the OITF or a combination of properties that does not identify a valid channel, the request to switch channel SHALL fail and the OITF SHALL trigger the function specified by the onChannelChangeError property, specifying the value 0 (“Channel not supported by tuner”) for the errorState, and dispatch the corresponding DOM event (see below). If the channel specifies an idType attribute value supported by the OITF, and the combination of properties defines a valid channel, the OITF SHALL relay the channel switch request to a local physical tuner that is currently not in use by another video/broadcast object and that can tune to the specified channel. If no tuner satisfying these requirements is available (i.e. all physical tuners that could receive the specified channel are in use), the request SHALL fail and OITF SHALL trigger the function specified by the onChannelChangeError property, specifying the value ‘2’ (“tuner locked by other object”) for the errorState and dispatch the corresponding DOM event (see below). If multiple tuners satisfying these requirements are available, the OITF selects one. If the channel specifies an IP broadcast channel, and the OITF supports idType ID_IPTV_SDS or ID_IPTV_URI, the OITF SHALL relay the channel switch request to a logical ‘tuner’ that can resolve the URI of the referenced IP broadcast channel. If no logical tuner can resolve the URI of the referenced IP broadcast channel, the request SHALL fail and the OITF SHOULD trigger the function specified by the onChannelChangeError property, specifying the value 8 (“cannot resolve URI of referenced IP channel”) for the errorState, and dispatch the corresponding DOM event. The optional attribute contentAccessDescriptorURL allows for the inclusion of a Content Access Streaming Descriptor (the format of which is defined in clause E.2 of the OIPF DAE specification [1]) to provide additional information for dealing with IPTV broadcasts that are (partially) DRM-protected. The descriptor may for example include Marlin action tokens or a previewLicense. The attribute SHALL be undefined or null if it is not applicable. If the attribute contentAccessDescriptorURL is present, the trickplay attribute shall take a value of either true or false. If the Transport Stream cannot be found, either via the DSD or the (ONID, TSID) pair, then a call to onChannelChangeError with errorstate=5 (“unknown channel”) SHALL be triggered, and the corresponding DOM event dispatched. If the OITF succeeds in tuning to a valid transport stream but this transport stream does not contain the requested service in the PAT, the OITF SHALL remain tuned to that location and SHALL trigger a call to onChannelChangeError with errorstate=12 (“specified channel not found in transport stream”), and dispatch the corresponding DOM event. If, following this procedure, the OITF selects a tuner that was not already being used to display video inside the video/broadcast object, the OITF SHALL claim the selected tuner and the associated resources (e.g. decoding and rendering resources) on behalf of the video/broadcast object. If all of the following are true: · the video/broadcast object is successfully switched to the new channel · the channel is a locally defined channel (created using the createChannelObject method) · the new channel has the same tuning parameters as a channel already in the channel list in the OITF · the idType is a value other than ID_IPTV_URI then the result of this operation SHALL be the same as calling setChannel with the channel argument being the corresponding channel object in the channel list, such that: · the values of the properties of the video/broadcast object currentChannel SHALL be the same as those of the channel in the channel list · any subsequent call to nextChannel or prevChannel SHALL switch the tuner to the next or previous channel in the favourite list or channel list as appropriate, as described in the definitions of these methods Otherwise, if any of the above conditions is not true, then: · the values of the properties of the video/broadcast object currentChannel SHALL be the same as those provided in the channel argument to this method, updated as defined in section 8.4.3 of the OIPF DAE specification [1] · the channel is not considered to be part of the channel list The resulting current channel after any subsequent call to nextChannel() or prevChannel() is implementation dependent, however all appropriate functions SHALL be called and DOM events dispatched. The OITF SHALL visualize the video content received over the tuner in the area of the browser allocated for the video/broadcast object. If the OITF cannot visualize the video content following a successful tuner switch (e.g. because the channel is under parental lock), the OITF SHALL trigger the function specified by the onChannelChangeError property with the appropriate channel and errorState value, and dispatch a corresponding DOM event (see below). If successful, the OITF SHALL trigger the function specified by the onChannelChangeSucceeded property with the given channel value, and also dispatch a corresponding DOM event.
Arguments	channel	The channel to which a switched is requested. If the channel object specifies a ccid, the ccid identifies the channel to be set. If the channel does not specify a ccid, the idType determines which properties of the channel are used to define the channel to be set, for example, if the channel is of type ID_IPTV_SDS or ID_IPTV_URI, the ipBroadcastID identifies the channel to be set. If null, the video/broadcast object SHALL transition to the unrealized state and release any resources used for decoding video and/or audio. A ChannelChangeSucceeded event SHALL be generated when the operation has completed.
	trickplay	Optional flag indicating whether resources SHOULD be allocated to support trick play. This argument provides a hint to the receiver in order that it may allocate appropriate resources. Failure to allocate appropriate resources, due to a resource conflict, a lack of trickplay support, or due to the OITF ignoring this hint, SHALL have no effect on the success or failure of this method. If trickplay is not supported, this SHALL be indicated through the failure of later calls to methods invoking trickplay functionality. The timeShiftMode property defined in section 7.13.2.2 of the OIPF DAE specification [1] shall provide information as to type of trickplay resources that should be allocated. If argument contentAccessDescriptorURL is included then the trickplay argument SHALL be included.
	contentAccessDescriptorURL	Optional argument containing a Content Access Streaming descriptor (the format of which is defined in clause E.2 of the OIPF DAE specification [1]) that can be included to provide additional information for dealing with IPTV broadcasts that are (partially) DRM-protected. The argument SHALL be undefined or null if it is not applicable.
	quiet	Optional flag indicating whether the channel change operation shall be carried out quietly, as described in clause A.2.4.3.2 below. Valid values are: · 0: Normal channel change · 1: Normal channel change with no UI displayed · 2: Quiet channel change All other values shall cause a normal channel change to occur.

A.2.4.3.2 Changes to the video/broadcast object

For the setChannel()method, if the quiet argument is set to 0 or is omitted then the terminal shall execute the channel change operation normally. Typically, this means that the viewer experience is exactly as if they had initiated a standard channel change operation using any of the terminal’s inherent channel navigation mechanisms, e.g. using the Ch+ or Ch- keys or numeric entry. This may be reflected in (but not restricted to):

Presentation of any channel information on the terminal’s front panel.
Presentation of any now/next information or channel banner.
The channel relative to which any navigation, such as Ch+/- or calls to prevChannel() or nextChannel(), is performed.

If the quiet argument is set to 1 then the terminal shall execute the channel change operation but shall not present any channel banner that is usually displayed by the terminal.

If the quiet argument is set to 2 then the terminal shall execute the channel change operation quietly. This means that the terminal shall suppress the presentation of all information usually presented during a channel change operation. In addition, the channel selected by the last normal channel change operation shall be used for all relevant interaction with the terminal by the viewer, which may include (but is not restricted to):

Presentation of any channel information on the terminal’s front panel.
Presentation of any now/next information or channel banner.
The channel relative to which any navigation, such as Ch+/- or calls to prevChannel() or nextChannel(), is performed.

The channel which is reported to HbbTV® applications as the current channel shall be the actual channel currently selected, regardless of the type of channel change by which it was selected.

After a channel change where the quiet argument is set to a value of 1 or 2, the application lifecycle shall be identical to a normal channel change, i.e. one where the quiet argument is set to the value 0 or omitted. The lifecycle of the application shall follow the rules defined in clauses 6.2.2.2 and 6.2.2.3 of the present document. The AIT of the new channel shall be obeyed following the channel change operation.

A.2.4.4 Definition of “delivery system descriptor”

The definitions of the createChannelObject(Integer idType, String dsd, Integer sid) method on the video/broadcast object, and the dsd attribute on the returned Channel object, both refer to the “delivery system descriptor”. This “delivery system descriptor” shall be as follows:

For a DVB-T channel, the “delivery system descriptor” shall be a terrestrial_delivery_system_descriptor.

For a DVB-T2 channel, the “delivery system descriptor” shall be a T2_delivery_system_descriptor which shall include at least one centre_frequency field.

For a DVB-S channel, the “delivery system descriptor” shall be a satellite_delivery_system_descriptor.

For a DVB-S2 channel the “delivery system descriptor” shall be either a satellite_delivery_system_descriptor, or the concatenation of an S2_satellite_delivery_system_descriptor and a satellite_delivery_system_descriptor, in that order.

For a DVB-S2X channel, the “delivery system descriptor” shall be an S2X_satellite_delivery_system_descriptor.

For a DVB-C channel, the “delivery system descriptor” shall be a cable_delivery_system_descriptor.

For a DVB-C2 channel that does not use channel bundling, the “delivery system descriptor” shall be a C2_delivery_system_descriptor.

For a DVB-C2 channel that uses channel bundling, the “delivery system descriptor” shall be the concatenation of one or more C2_bundle_delivery_system_descriptor.

The descriptors referred to above are all defined in clause 6.2.13 and clause 6.4.5 of ETSI EN 300 468 [16].

A.2.4.5 Other modifications to the video/broadcast object

In clause 7.13.2.2 of the OIPF DAE specification [1] the definition of the property onPlayPositionChanged( Integer position ) is changed as shown:

The function that is called when change occurs in the play position of a channel due to the use of trick play functions random access functions.

In clause 7.13.3 of the OIPF DAE specification [1], the definition of the property onProgrammesChanged is modified with the addition of the text shown underlined:

The function that is called for a video/broadcast object in the presenting or stopped states when the programmes property has been updated with new programme information, e.g. when the current broadcast programme is finished and a new one has started. The specified function is called with no arguments.

In clause 7.13.7.1 of the OIPF DAE specification [1], the definition of the property currentChannel is changed as shown:

The channel currently being presented bybound to this embedded object (i.e. the object is in the connecting, presenting or stopped states as the result of a call to bindToCurrentChannel()) if the user has given permission to share this information, possibly through a mechanism outside the scope of this specification. If no channel is being presented bound to this embedded object, or if this information is not visible to the caller, the value of this property shall be null.

Terminals shall not show any UI (e.g. an indication of video or audio properties or attributes such as “16:9”) when a video broadcast object successfully changes either from the Stopped state to the Connecting state or from the Connecting state to the Presenting state when the previous state change was from Stopped to Connecting.

In clause 7.16.5.1.3 of the OIPF DAE specification [1], if either signature of the selectComponent method is called when the set of components are not known (where “known” has the meaning defined for getComponent and getActiveComponents) then the method call shall fail with an InvalidStateError DOMException.

A.2.4.6 Support for creating audio and video components

The following changes shall apply to the video/broadcast object to support creating AVAudioComponent and AVVideoComponent objects.

NOTE: Delivering A/V streams signalled as private data and referencing them via these methods is intended to be used for cases when those A/V streams are only appropriate for presentation under the control of an HbbTV® application.

AVAudioComponent createAVAudioComponent( Integer componentTag, String language, Boolean audioDescription, Integer audioChannels, String encoding)
Description	The method creates an AVAudioComponent object for an elementary stream in the currently selected broadcast service that is not recognizable from the signalling as being an AVVideoComponent, an AVAudioComponent or an AVSubtitleComponent. (See clause 8.4.2 of the OIPF DAE specification [1] for more information). Successfully created objects shall be usable identically to AVAudioComponent objects returned when the getComponents() method is called with the argument COMPONENT_TYPE_AUDIO. Null shall be returned if either no component with the specified value of componentTag is present in the currently selected broadcast service or if the value of componentTag specifies a component that already has an AVVideoComponent, an AVAudioComponent or an AVSubtitleComponent. The scope of successfully created objects shall be limited to the application that created them. When that application exits, they shall cease to exist and shall no longer be presented. This may result in no audio being presented.
Arguments	componentTag	A component tag identifying the elementary stream for which the AVAudioComponent object is to be created. This shall be matched against a component tag in a stream identifier descriptor in the ES loop of a stream in the PMT.
	language	The value to be returned from the language property of the object that is created. This should be an ISO 639‑2 [61] language code.
	audioDescription	The value to be returned from the audioDescription property of the object that is created.
	audioChannels	The value to be returned from the audioChannels property of the object that is created. The value indicates the number of main channels present in the stream (e.g. 5 for 5.1) excluding any potential low frequency effects channels.
	encoding	The value to be returned from the encoding property of the object that is created.

AVVideoComponent createAVVideoComponent( Integer componentTag, Number aspectratio, String encoding)
Description	The method creates an AVVideoComponent object for an elementary stream in the currently selected broadcast service that is not recognizable from the signalling as being an AVVideoComponent, an AVAudioComponent or an AVSubtitleComponent. (See clause 8.4.2 of the OIPF DAE specification [1] for more information).Successfully created objects shall be usable identically to AVVideoComponent objects returned when the getComponents() method is called with the argument COMPONENT_TYPE_VIDEO. Null shall be returned if either no component with the specified value of componentTag is present in the currently selected broadcast service or if the value of componentTag specifies a component that already has an AVVideoComponent, an AVAudioComponent or an AVSubtitleComponent.The scope of successfully created objects shall be limited to the application that created them. When that application exits, they shall cease to exist and shall no longer be presented. This may result in no video being presented.
Arguments	componentTag	A component tag identifying the elementary stream for which the AVVideoComponent object is to be created. This shall be matched against a component tag in a stream identifier descriptor in the ES loop of a stream in the PMT.
	aspectratio	The value to be returned from the aspectratio property of the object that is created.
	encoding	The value to be returned from the encoding property of the object that is created.

A.2.4.7 Extensions to video/broadcast for time-shift

A.2.4.7.1 General

If a terminal has indicated support in its capability description for recording functionality (i.e. by giving value true to the <recording> element as specified in OIPF DAE [1], section 9.3.3), the terminal shall support the following additional constants, properties and methods on the video/broadcast object, in order to start a time-shift of the current broadcast.

Note that this functionality is subject to the security model as specified in OIPF DAE [1], section 10.1.

Terminals may restrict access to the time-shift methods to those applications that are signalled as safe to run when time-shifting, i.e. those signalled in the AIT with an application_recording_descriptor and both the trick_mode_aware_flag and the time_shift_flag set to ‘1’ as described in clause 7.2.3.1.

The properties and methods defined in this clause are used when the content presented in the video/broadcast object is being time-shifted.

A.2.4.7.2 Constants

Name	Value	Use
POSITION_START	0	Indicates a playback position relative to the start of the buffered content.
POSITION_CURRENT	1	Indicates a playback position relative to the current playback position.
POSITION_END	2	Indicates a playback position relative to the end of the buffered content (co-incident with the live playback position).

A.2.4.7.3 Properties

function onPlaySpeedChanged( Number speed )

The function that is called when the playback speed of a channel changes during timeshift.

The specified function is called with one argument, speed, which is defined as follows:

· Number speed – the playback speed of the media at the time the event was dispatched.

function onPlayPositionChanged( Integer position )

The function that is called when a change occurs in the play position of a channel due to the use of trick play functions during timeshift.

The specified function is called with one argument, position, which is defined as follows:

· Integer position – the playback position of the media at the time the event was dispatched, measured from the start of the timeshift buffer in milliseconds. If the play position cannot be determined, this argument takes the value undefined.

readonly Integer playbackOffset

Returns the playback position during timeshift, specified as the number of seconds between the live broadcast and the currently rendered position in the timeshift buffer, where a value of zero means that the broadcast is not being timeshifted or is playing from the live point in a timeshift buffer.

When the currentTimeShiftMode property has the value 0, the value of this property is undefined.

readonly Integer maxOffset

Returns the maximum playback offset, in seconds of the live broadcast, which is supported for the currently rendered broadcast. If the maximum offset is unknown, the value of this property shall be undefined.

NOTE: This value gives the size of the timeshift buffer.

When the currentTimeShiftMode property has the value 0, the value of this property is undefined.

readonly Integer playPosition

If the value of the currentTimeShiftMode property is 1, the current playback position of the media, measured in milliseconds from the start of the timeshift buffer.

readonly Number playSpeed

The current play speed of the media.

readonly Number playSpeeds[]

Returns the ordered list of playback speeds, expressed as values relative to the normal playback speed (1.0), at which the currently specified content can be played (as a time-shifted broadcast in the video/broadcast object), or undefined if the supported playback speeds are not known.

If timeshift is supported by the terminal, the playSpeeds array shall always include at least the values 1.0 and 0.0.

This property may include the playback speeds that this broadcast content could be played back after being recorded, but only if they also apply to playback of the content when timeshifted.

function onPlaySpeedsArrayChanged()

The function that is called when the playSpeeds array values have changed. An application that makes use of the playSpeeds array needs to read the values of the playSpeeds property again.

Integer timeShiftMode

The time shift mode indicates the mode of operation for support of timeshift playback in the video/broadcast object. Valid values are:

Value	Description
0	Timeshift is turned off.
1	Timeshift shall use “local resource”.

If the property is not set, the default value of the property is 1.

readonly Integer currentTimeShiftMode

When timeshift is in operation the property indicates which resources are currently being used. Valid values are:

Value	Description
0	Timeshift is turned off.
1	Timeshift shall use “local resource”.

In addition, the properties recordingState and onRecordingEvent defined in clause A.2.4.8.2 shall be supported.

A.2.4.7.4 Methods

Boolean pause()
Description	Pause playback of the broadcast. This is equivalent to setSpeed(0).

Boolean resume()
Description	Resumes playback of the time-shifted broadcast. This is equivalent to setSpeed(1).

Boolean setSpeed( Number speed )

Description

Sets the playback speed of the time-shifted broadcast to the value speed.

If the value of the timeShiftMode property is 0 or if trick play is not supported for the channel currently being rendered, this method shall return false and have no effect.

If speed is a value less than 1.0 and the broadcast was not previously being time-shifted, this method shall start recording the broadcast that is currently being rendered live (i.e. not time-shifted) in the video/broadcast object. If the terminal has buffered the ‘live’ broadcasted content, the recording starts with the content that is currently being rendering in the video/broadcast object. Acquiring the necessary resources to start recording the broadcast may be an asynchronous operation, and presentation of the broadcast may not be affected until after this method returns; applications may receive updates by registering a listener for PlaySpeedChanged events as defined in clause A.2.4.7.5.

If speed is a value greater than 1.0 and the broadcast was not previously being time-shifted, this method shall have no effect and shall return false.

When playback is paused (i.e. by setting the play speed to 0), the last decoded video frame shall be shown.

If the time-shifted broadcast cannot be played at the desired speed, specified as a value relative to the normal playback speed, the playback speed will be set to the best approximation of speed.

If there is no change to the play speed as a result of the method call, it shall return false.

Unless specified otherwise above, this method shall return true.

After initial operation of setSpeed() several events may affect the content playback.

If during fast forward the end of stream is reached the playback shall resume at normal speed and a PlaySpeedChanged event generated. If the end of the timeshift buffer is reached due to end of content the playback shall automatically be paused and a PlaySpeedChanged event generated. Any resources used for time-shifting shall not be discarded.

If during rewinding the playback reaches the point that it cannot be rewound further, playback shall resume at normal speed and a PlaySpeedChanged event generated.

A PlaySpeedChanged event shall be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play speed.

Arguments

speed

The desired relative playback speed, specified as a float value relative to the normal playback speed of 1.0. A negative value indicates reverse playback.

Boolean seek( Integer offset, Integer reference )
Description	Sets the playback position of the time-shifted broadcast that is being rendered in the video/broadcast object to the position specified by the offset and the reference point as specified by one of the constants defined in clause A.2.4.7.2. Playback of live content is resumed if the new position equals the end of the time-shift buffer. Returns true if the playback position is a valid position to seek to, false otherwise. If time-shift is not supported for the current channel (e.g. due to restrictions imposed by a conditional access or DRM system) or the broadcast is not currently being time-shifted or if the position falls outside the time-shift buffer, the terminal shall ignore the request to seek and shall return the value false. Applications are not required to pause playback of the broadcast or take any other action before calling seek(). This operation may be asynchronous, and presentation of the video may not be affected until after this method returns. For this reason, a PlayPositionChanged event shall be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play position. After initial operation of seek() several events may affect the content playback. If during this operation the live playback position is reached the playback shall resume at normal speed and a PlaySpeedChanged event generated. If the timeshift buffer cannot be rewound any further, the playback shall automatically be paused and a PlaySpeedChanged event generated. Any resources used for time-shifting shall not be discarded.
Arguments	offset	The offset from the reference position, in seconds. This can be either a positive value to indicate a time later than the reference position or a negative value to indicate time earlier than the reference position.
	reference	The reference point from which the offset shall be measured. The reference point can be either POSITION_CURRENT, POSITION_START, or POSITION_END.

Boolean stopTimeshift()

Description

Stops rendering in timeshifted mode the broadcast channel in the video/broadcast object and, if applicable, plays the current broadcast from the live point and stops timeshifting the broadcast. The terminal may release all resources that were used to support timeshifted rendering of the broadcast.

Returns true if the time-shifted broadcast was successfully stopped and false otherwise. If the video/broadcast object is currently not rendering a timeshifted channel, the terminal shall ignore the request to stop the timeshift and shall return the value false.

A.2.4.7.5 Events

For the intrinsic events “onRecordingEvent”, “onPlaySpeedChanged” and “onPlayPositionChanged”, corresponding DOM level 2 events shall be generated, in the following manner:

Intrinsic event	Corresponding DOM 2 event	DOM 2 Event properties
onRecordingEvent	RecordingEvent	Bubbles: No Cancelable: No Context Info: state, error, recordingId
onPlaySpeedChanged	PlaySpeedChanged	Bubbles: No Cancelable: No Context Info: speed
onPlayPositionChanged	PlayPositionChanged	Bubbles: No Cancelable: No Context Info: position
onPlaySpeedsArrayChanged	PlaySpeedsArrayChanged	Bubbles: No Cancelable: No Context Info: None

NOTE: The DOM 2 events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM 2 event handlers have to call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

A.2.4.8 Extensions to video/broadcast for recording

A.2.4.8.1 General

Note that this functionality is subject to the security model as specified in OIPF DAE [1], section 10.1.

The recording functionality is subject to the state transitions represented in the state diagram in Figure A.1. The timeshift functionality is not represented explicitly in these state diagrams but is defined in the following clauses.

Figure A.1: PVR States for recordNow using video/broadcast (normative)

Note that when the user switches to another channel whilst the current channel is being recorded using recordNow() or the video/broadcast object gets destroyed, the conflict resolution and the release of resources is implementation dependent. The terminal may report a recording error using a RecordingEvent with value 0 (“Unrealized”) for argument state and with value 2 (“Tuner conflict”) for argument error in that case.

A.2.4.8.2 Properties

readonly Integer recordingState

Returns the state of the terminal’s timeshift and recordNow functionality for the channel shown in the video/broadcast object. One of:

Value	Description
0	Unrealized: user/application has not requested timeshift or recordNow functionality for the channel shown. No timeshift or recording resources are claimed in this state.
1	Value not used
2	Value not used
3	Acquiring recording resources (for example, space on the media storage device).
4	Recording has started.
5	Value not used
6	Recording has successfully completed.

function onRecordingEvent( Integer state, Integer error, String recordingId )

This function is the DOM 0 event handler for notification of state changes of the recording functionality. The specified function is called with the following arguments:

· Integer state – The current state of the recording. One of:

Value	Description
0	Unrealized: user/application has not requested timeshift or recordNow functionality for the channel shown. No timeshift or recording resources are claimed in this state.
1	Value not used
2	Value not used
3	Acquiring recording resources (for example, space on the media storage device).
4	Recording has started.
5	Value not used
6	Recording has successfully completed.

· Integer error – If the state of the recording has changed due to an error, this field contains an error code detailing the type of error. One of:

Value	Description
0	The recording sub-system is unable to record due to resource limitations.
1	There is insufficient storage space available. (Some of the recording may be available).
2	Value not used
3	Recording not allowed due to DRM restrictions.
4	Recording has stopped before completion due to unknown (probably hardware) failure.

If no error has occurred, this argument shall take the value undefined.

· String recordingId – The identifier of the recording to which this event refers, This shall be equal to the value of the id property for the affected recording, if the event is associated with a specific recording. This shall be undefined when the value of state is 0.

A.2.4.8.3 Methods

String recordNow( Integer duration )

Description

Starts recording the broadcast currently rendered in the video/broadcast object. If the terminal has buffered the broadcasted content, the recording starts from the current playback position in the buffer, otherwise start recording the broadcast stream as soon as possible after the recording resources have been acquired. The specified duration is used by the terminal to determine the minimum duration of the recording in seconds from the current starting point.

Calling recordNow() while the broadcast that is currently rendered in the video/broadcast object is already being recorded, shall have no effect on the recording and shall return the value null.

In other cases, this method returns a String value representing a unique identifier to identify the recording. If the terminal provides recording management functionality through the APIs defined in OIPF DAE [1], section 7.10.4, this shall be the value of the id property of the associated Recording object defined in OIPF DAE [1], section 7.10.5.

The terminal shall guarantee that recording identifiers are unique in relation to download identifiers and CODAsset identifiers.

The method returns undefined if the given argument is not accepted to trigger a recording.

If the terminal supports metadata processing in the terminal, the fields of the resulting Recording object may be populated using metadata retrieved by the terminal. Otherwise, the values of these fields shall be implementation-dependent.

Arguments

duration

The minimum duration of the recording in seconds. A value of -1 indicates that the recording should continue until stopRecording() is called, storage space is exhausted, or an error occurs. In this case it is essential that stopRecording() is called later.

void stopRecording()
Description	Stops the current recording started by recordNow().

The OITF SHALL support the video/broadcast embedded object with the following properties and methods, which SHALL adhere to the tuner related security requirements in section 10.1.3.1. The MIME type of this object SHALL be “video/broadcast”.

State diagram for video/broadcast objects

The state diagram below shows the states that a video/broadcast object may be in. Dashed lines indicate automatic transitions between states. The video/broadcast object SHALL be in the unrealized state when it is instantiated.

Figure 14: State diagram for embedded video/broadcast objects (informative).

Transient errors are defined as ones that that the OITF will automatically recover from without intervention by an application. Transient errors persist until either the condition which caused them is corrected or it is determined that it cannot be connected and the error becomes permanent. Permanent errors are defined as ones that the OITF will not automatically attempt to recover from.

Terminals SHALL perform the state changes in Table 8 under the conditions described and generate the listed event(s). Terminals SHALL not change state in circumstances other than defined in this section.

Table 8: State transitions for the video/broadcast embedded object

Old State	Trigger	New State	State Transition Events	Description
All states	setChannel( channel) where channel != null and the channel type is supported and the combination of channel properties is valid and a suitable tuner is available	Connecting	PlayStateChange	The terminal attempts to connect to the requested channel. The currentChannel object reflects the channel being changed to.
All states	setChannel( channel) where channel != null but either the channel type is not supported or the combination of channel properties is invalid or a suitable tuner is not available	No change	ChannelChangeError	The terminal remains in the same state.
Connecting or Presenting or Stopped	nextChannel(), prevChannel() where the video/broadcast object currentChannel is in the channel list and a suitable tuner is available	Connecting	PlayStateChange	The terminal attempts to connect to the requested channel. The currentChannel object reflects the channel being changed to.
Connecting	nextChannel(), prevChannel() where the video/broadcast object currentChannel is not in the channel list	Unrealized	ChannelChangeError PlayStateChange
Presenting or Stopped	nextChannel(), prevChannel() where the video/broadcast object currentChannel is not in the channel list	No change	ChannelChangeError	The terminal remains in the same state.
Connecting or Presenting or Stopped	nextChannel(), prevChannel() where the video/broadcast object currentChannel is in the channel list but no suitable tuner is available	No change	ChannelChangeError	The terminal remains in the same state.
Unrealized	bindToCurrentChannel() when at least one channel is currently being presented by the OITF and binding to the necessary resources does not fail	Presenting	PlayStateChange	The terminal binds the video/broadcast object to the current channel being natively presented. The currentChannel object reflects the channel being presented.
Unrealized	bindToCurrentChannel() when there is no channel currently being presented or binding to the necessary resources to play the channel through the video/broadcast object fails	Unrealized	PlayStateChange	The terminal continues to present the current channel, if any.
Connecting	The terminal successfully connected to the broadcast or IP multicast stream and presented its contents.	Presenting	ChannelChangeSucceeded PlayStateChange	This transition occurs automatically when media presentation starts.
Connecting	The terminal successfully connected to the broadcast or IP multicast stream but presentation of content is blocked, e.g. by a parental rating mechanism or content protection mechanism	Connecting	ChannelChangeSucceeded PlayStateChange	This is conceptually equivalent to a successful channel change where a transient error immediately pre-empts media presentation without the video/broadcast object entering the presenting state.
Connecting	Recovery from a transient error, including – presentation of content no longer being blocked by a content protection mechanism (e.g. the start of a free preview period or a channel that changes from being encrypted to being in the clear during the day) – the end-user entering a PIN code or other equivalent authorization to enable access to content protected by parental access control – resumption of delivery of media data	Presenting	PlayStateChange	If a video/broadcast object was forced from the presenting state to the connecting state due to a transient error and that error condition clears while the video/broadcast object remains in the connecting state then the video/broadcast object SHALL automatically transition back to the presenting state.
Connecting or Presenting or Stopped	release() or setChannel(null)	Unrealized	PlayStateChange	The control is returned to the terminal. The currentChannel object is set to null. If an application has modified the set of components being presented (e.g. changing the audio or subtitle stream being presented) then the same set of components will continue to be presented.
Connecting	Permanent error including – failure to change to a new channel (e.g. the channel cannot be found or none of the media components can be decoded or insufficient resources are available to present the channel) – exhaustion of all possibilities for an end-user to authorize access to content protected by a parental access control mechanism (e.g. timeout on a PIN entry dialogue) – delivery of media data was interrupted and has not resumed after an implementation-dependent timeout	Unrealized	ChannelChangeError PlayStateChange	The terminal encountered a permanent error
Connecting or Presenting	stop()	Stopped	PlayStateChange
Presenting	Transient error including – presentation of content being blocked by a content protection mechanism, – presentation of content being blocked by a parental rating mechanism, – interruption of delivery of media data (either via IP or hybrid) if either; a) the media data is delivered over a connection and the connection remains intact or b) the media data is delivered via a connectionless mechanism	Connecting	PlayStateChange	The terminal encountered a transient error. During media presentation, transient errors (e.g. transient errors in the bitstream, temporary loss of signal or temporary halting of media decoding due to parental control issues) MAY cause the object to transition from the presenting state to the connecting state. Temporary loss of resources due to presentation being interrupted by playback of audio from memory MAY cause the object to transition from the presenting state to the connecting state.
Presenting or Stopped	Permanent error including; – interruption of delivery of media data where the media data is delivered over a connection and the connection terminates	Unrealized	PlayStateChange	The terminal encountered a permanent error.
Stopped	bindToCurrentChannel()	Connecting	PlayStateChange	Video and audio presentation is enabled.
All states	Destroy video/broadcast	N/A		When a video/broadcast object is destroyed (e.g. by the video/broadcast object being garbage collected) control of broadcast video SHALL be returned to the terminal. If an application has modified the set of components being presented (e.g. changing the audio or subtitle stream being presented) then the same set of components will continue to be presented. When a video/broadcast object is destroyed due to a page transition within an application, terminals MAY delay this operation until the new page is fully loaded in order to avoid display glitches if a video/broadcast object is also present in the new page. Presentation of broadcast video or audio SHALL not be interrupted in either case.

If the channel currently being presented is requested to be changed due to an action outside the application (for example, the user pressing the CH+ key on the remote) then any video/broadcast object presenting that channel (e.g. as the result of a call to bindToCurrentChannel()) SHALL perform the same state transitions and dispatch the same events as if the channel change operation was initiated by the application using the setChannel() method.

If the value of the allocationMethod property is DYNAMIC_ALLOCATION, the following apply:

Scarce resources such as media decoders SHALL be claimed while in the connecting
Resources SHALL be released when the video/broadcast object transitions to the unrealized
Video and audio decoding resources SHALL be released when the video/broadcast object transitions to the stopped state.
Transitioning from the presenting to the connecting state SHOULD not cause scarce resources to be released.

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

When a video/broadcast object stops being rendered as defined in section 10.1 of the HTML5 specification as referenced by [OIPF_DAE2_WEB] an OITF MAY release scarce resources allocated for that object. Vice versa, a video/broadcast object which is not visible but it’s still being rendered SHALL still be decoding video if it is in the presenting state and any audio associated with the currently presented channel will still be audible. State transitions caused by calls to methods on the video/broadcast object, or due to permanent or transient errors, will occur as shown above regardless of the visibility of the object

NOTE: as implied by the text above, rendering state and visibility are not equivalent. This implies, just to give two examples, that display:none will affect the object state while visibility:hidden will not.

Properties

Integer width

The width of the area used for rendering the video object. This property is only writable if property fullScreen has value false. Changing the width property corresponds to changing the width property through the HTMLObjectElement interface, and must have the same effect as changing the width through the DOM Level 2 Style interfaces (i.e. CSS2Properties interface style.width), at least for values specified in pixels.

Integer height

The height of the area used for rendering the video object. This property is only writable if property fullScreen has value false. Changing the height property corresponds to changing the height property through the HTMLObjectElement interface, and must have the same effect as changing the height through the DOM Level 2 Style interfaces (i.e. CSS2Properties interface style.height), at least for values specified in pixels.

readonly Boolean fullScreen

Returns true if this video object is in full-screen mode, false otherwise. The default value is false.

String data

Setting the value of the data property SHALL have no effect on the video/broadcast object. If this property is read, the value returned SHALL always be the empty string.

function onChannelChangeError( Channel channel, Number errorState )

The function that is called when a request to switch a tuner to another channel resulted in an error preventing the broadcasted content from being rendered. The specified function is called with the arguments channel and errorState. This function may be called either in response to a channel change initiated by the application, or a channel change initiated by the OITF (see section 7.13.1.1). These arguments are defined as follows:

· Channel channel – the Channel object to which a channel switch was requested, but for which the error occurred. This object SHALL have the same properties as the channel that was requested, except that for channels of type ID_DVB_* the values for the onid and tsid properties SHALL be extracted from the transport stream when one was found (e.g. when errorState is 12).

· Number errorState – error code detailing the type of error:

Value	Description
0	channel not supported by tuner.
1	cannot tune to given transport stream (e.g. no signal)
2	tuner locked by other object.
3	parental lock on channel.
4	encrypted channel, key/module missing.
5	unknown channel (e.g. can’t resolve DVB or ISDB triplet).
6	channel switch interrupted (e.g. because another channel switch was activated before the previous one completed).
7	channel cannot be changed, because it is currently being recorded.
8	cannot resolve URI of referenced IP channel.
9	insufficient bandwidth.
10	channel cannot be changed by nextChannel()/prevChannel() methods either because the OITF does not maintain a favourites or channel list or because the video/broadcast object is in the Unrealized state.
11	insufficient resources are available to present the given channel (e.g. a lack of available codec resources).
12	specified channel not found in transport stream.
100	unidentified error.

readonly Integer playState

The current play state of the video/broadcast object. Valid values are:

Value	Description
0	unrealized; the application has not made a request to start presenting a channel or has stopped presenting a channel and released any resources. The content of the video/broadcast object should be transparent but if not shall be an opaque black rectangle. Control of media presentation is under the control of the OITF, as defined in section H.2.
1	connecting; the terminal is connecting to the media source in order to begin playback. Objects in this state may be buffering data in order to start playback. Control of media presentation is under the control of the application, as defined in section H.2. The content of the video/broadcast object is implementation dependent.
2	presenting; the media is currently being presented to the user. The object is in this state regardless of whether the media is playing at normal speed, paused, or playing in a trick mode (e.g. at a speed other than normal speed). Control of media presentation is under the control of the application, as defined in section H.2. The video/broadcast object contains the video being presented.
3	stopped; the terminal is not presenting media, either inside the video/broadcast object or in the logical video plane. The logical video plane is disabled. The content of the video/broadcast object SHALL be an opaque black rectangle. Control of media presentation is under the control of the application, as defined in section H.2

See section 7.13.1.1 for a description of the state model for a video/broadcast object.

NOTE: Implementations where the content of the video/broadcast object is transparent in the unrealized state will give a better user experience than ones where it is black. This happens for an application with video in the background between when it includes a video/broadcast object in the page and when a call to bindToCurrentChannel() completes. Applications which do not need to call bindToCurrentChannel() should not do so. The current channel can be obtained from the currentChannel property on the ApplicationPrivateData object which is the same as that on the video/broadcast object under most normal conditions.

function onPlayStateChange( Number state, Number error )

The function that is called when the play state of the video/broadcast object changes. This function may be called either in response to an action initiated by the application, an action initiated by the OITF or an error (see section 7.13.1.1). The specified function is called with the arguments state and error. These arguments are defined as follows: · Number state – the new state of the video/broadcast object. Valid values are given in the definition of the playState property above. · Number error – if the state has changed due to an error, this field contains an error code detailing the type of error. See the definition of onChannelChangeError above for valid values. If no error has occurred, this argument SHALL take the value undefined.

function onChannelChangeSucceeded( Channel channel )

The function that is called when a request to switch a tuner to another channel has successfully completed. This function may be called either in response to a channel change initiated by the application, or a channel change initiated by the OITF (see section 7.13.1.1). The specified function is called with argument channel, which is defined as follows: · Channel channel – the channel to which the tuner switched. This object SHALL have the same properties with the same values as the currentChannel object (see section 7.13.7).

function onFullScreenChange()

The function that is called when the value of fullScreen changes.

function onfocus()

The function that is called when the video object gains focus.

function onblur()

The function that is called when the video object loses focus.

readonly StringCollection playerCapabilities

The list of media formats that are supported by the object. Each item SHALL contain a format label according to [OIPF_MEDIA2]. If scarce resources are not claimed by the object, the value of this property SHALL be null.

readonly Integer allocationMethod

Returns the resource allocation method currently in use by the object. Valid values as defined in section 7.14.13.1 are: · STATIC_ALLOCATION · DYNAMIC_ALLOCATION

Methods

ChannelConfig getChannelConfig()
Description	Returns the channel line-up of the tuner in the form of a ChannelConfig object as defined in section 7.13.9. The method SHALL return the value null if the channel list is not (partially) managed by the OITF (i.e., if the channel list information is managed entirely in the network).

Channel bindToCurrentChannel()

Description

If the video/broadcast object is in the unrealized state and video from exactly one channel is currently being presented by the OITF then this binds the video/broadcast object to that video.

If the video/broadcast object is in the stopped state then this restarts presentation of video and audio from the current channel under the control of the video/broadcast object. If video from more than one channel is currently being presented by the OITF then this binds the video/broadcast object to the channel whose audio is being presented.

If there is no channel currently being presented, or binding to the necessary resources to play the channel through the video/broadcast object fails for whichever reason, the OITF SHALL dispatch an event to the onPlayStateChange listener(s) whereby the state parameter is given value 0 (“unrealized”) and the error parameter is given the appropriate error code.

Calling this method from any other states than the unrealized or stopped states SHALL have no effect.

See section 7.13.1.1 for more information of its usage.

NOTE: Returning a Channel object from this method does not guarantee that video or audio from that channel is being presented. Applications should listen for the video/broadcast object entering state 2 (“presenting”) in order to determine when audio or video is being presented.

Channel createChannelObject( Integer idType, String dsd, Integer sid )
Description	Creates a Channel object of the specified idType. This method is typically used to create a Channel object of type ID_DVB_SI_DIRECT. The Channel object can subsequently be used by the setChannel() method to switch a tuner to this channel, which may or may not be part of the channel list in the OITF. The resulting Channel object represents a locally defined channel which, if not already present there, does not get added to the channel list accessed through the ChannelConfig class (see section 7.13.9). Valid value for idType include: ID_DVB_SI_DIRECT. For other values this behaviour is not specified. If the channel of the given type cannot be created or the delivery system descriptor is not valid, the method SHALL return null. If the channel of the given type can be created and the delivery system descriptor is valid, the method SHALL return a Channel object whereby at a minimum the properties with the same names (i.e. idType, dsd and sid) are given the same value as argument idType, dsd and sid of the createChannelObject method.
Arguments	idType	The type of channel, as indicated by one of the ID_* constants defined in section 7.13.11.1. Valid values for idType include: ID_DVB_SI_DIRECT. For other values this behaviour is not specified.
	dsd	The delivery system descriptor (tuning parameters) represented as a string whose characters shall be restricted to the ISO Latin-1 character set. Each character in the dsd represents a byte of a delivery system descriptor as defined by DVB-SI [EN 300 468] section 6.2.13, such that a byte at position “i” in the delivery system descriptor is equal the Latin-1 character code of the character at position “i” in the dsd.
	sid	The service ID, which must be within the range of 1 to 65535.

Channel createChannelObject( Integer idType, Integer onid, Integer tsid, Integer sid, Integer sourceID, String ipBroadcastID )
Description	Creates a Channel object of the specified idType. The Channel object can subsequently be used by the setChannel() method to switch a tuner to this channel, which may or may not be part of the channel list in the OITF. The resulting Channel object represents a locally defined channel which, if not already present there, does not get added to the channel list accessed through the ChannelConfig class (see section 7.13.9). If the channel of the given idType cannot be created or the given (combination of) arguments are not considered valid or complete, the method SHALL return null. If the channel of the given type can be created and arguments are considered valid and complete, then either: 1. If the channel is in the channel list then a new object of the same type and with properties with the same values SHALL be returned as would be returned by calling getChannelWithTriplet() with the same parameters as this method. 2. Otherwise, the method SHALL return a Channel object whereby at a minimum the properties with the same names are given the same value as the given arguments of the createChannelObject() method. The values specified for the remaining properties of the Channel object are set to undefined.
Arguments	idType	The type of channel, as indicated by one of the ID_* constants defined in section 7.13.11.1.
	onid	The original network ID. Optional argument that SHALL be specified when the idType specifies a channel of type ID_DVB_, ID_IPTV_URI, or ID_ISDB_ and SHALL otherwise be ignored by the OITF.
	tsid	The transport stream ID. Optional argument that MAY be specified when the idType specifies a channel of type ID_DVB_, ID_IPTV_URI, or ID_ISDB_ and SHALL otherwise be ignored by the OITF.
	sid	The service ID. Optional argument that SHALL be specified when the idType specifies a channel of type ID_DVB_, ID_IPTV_URI, or ID_ISDB_ and SHALL otherwise be ignored by the OITF.
	sourceID	The source_ID. Optional argument that SHALL be specified when the idType specifies a channel of type ID_ATSC_T and SHALL otherwise be ignored by the OITF.
	ipBroadcastID	The DVB textual service identifier of the IP broadcast service, specified in the format “ServiceName.DomainName” when idType specifies a channel of type ID_IPTV_SDS, or the URI of the IP broadcast service when idType specifies a channel of type ID_IPTV_URI. Optional argument that SHALL be specified when the idType specifies a channel of type ID_IPTV_SDS or ID_IPTV_URI and SHALL otherwise be ignored by the OITF.

void setChannel( Channel channel, Boolean trickplay, String contentAccessDescriptorURL )
Description	Requests the OITF to switch a (logical or physical) tuner to the channel specified by channel and render the received broadcast content in the area of the browser allocated for the video/broadcast object. If the channel specifies an idType attribute value which is not supported by the OITF or a combination of properties that does not identify a valid channel, the request to switch channel SHALL fail and the OITF SHALL trigger the function specified by the onChannelChangeError property, specifying the value 0 (“Channel not supported by tuner”) for the errorState, and dispatch the corresponding DOM event (see below). If the channel specifies an idType attribute value supported by the OITF, and the combination of properties defines a valid channel, the OITF SHALL relay the channel switch request to a local physical tuner that is currently not in use by another video/broadcast object and that can tune to the specified channel. If no tuner satisfying these requirements is available (i.e. all physical tuners that could receive the specified channel are in use), the request SHALL fail and OITF SHALL trigger the function specified by the onChannelChangeError property, specifying the value ‘2’ (“tuner locked by other object”) for the errorState and dispatch the corresponding DOM event (see below). If multiple tuners satisfying these requirements are available, the OITF selects one. If the channel specifies an IP broadcast channel, and the OITF supports idType ID_IPTV_SDS or ID_IPTV_URI, the OITF SHALL relay the channel switch request to a logical ‘tuner’ that can resolve the URI of the referenced IP broadcast channel. If no logical tuner can resolve the URI of the referenced IP broadcast channel, the request SHALL fail and the OITF SHOULD trigger the function specified by the onChannelChangeError property, specifying the value 8 (“cannot resolve URI of referenced IP channel”) for the errorState, and dispatch the corresponding DOM event. The optional attribute contentAccessDescriptorURL allows for the inclusion of a Content Access Streaming Descriptor (the format of which is defined in Annex E.2) to provide additional information for dealing with IPTV broadcasts that are (partially) DRM-protected. The descriptor may for example include Marlin action tokens or a previewLicense. The attribute SHALL be undefined or null if it is not applicable. If the attribute contentAccessDescriptorURL is present, the trickplay attribute shall take a value of either true or false. If the Transport Stream cannot be found, either via the DSD or the (ONID,TSID) pair, then a call to onChannelChangeError with errorstate=5 (“unknown channel”) SHALL be triggered, and the corresponding DOM event dispatched. If the OITF succeeds in tuning to a valid transport stream but this transport stream does not contain the requested service in the PAT, the OITF SHALL remain tuned to that location and SHALL trigger a call to onChannelChangeError with errorstate=12 (“specified channel not found in transport stream”), and dispatch the corresponding DOM event. If, following this procedure, the OITF selects a tuner that was not already being used to display video inside the video/broadcast object, the OITF SHALL claim the selected tuner and the associated resources (e.g., decoding and rendering resources) on behalf of the video/broadcast object. If all of the following are true: · the video/broadcast object is successfully switched to the new channel · the channel is a locally defined channel (created using the createChannelObject method) · the new channel has the same tuning parameters as a channel already in the channel list in the OITF · the idType is a value other than ID_IPTV_URI then the result of this operation SHALL be the same as calling setChannel with the channel argument being the corresponding channel object in the channel list, such that: · the values of the properties of the video/broadcast object currentChannel SHALL be the same as those of the channel in the channel list · any subsequent call to nextChannel or prevChannel SHALL switch the tuner to the next or previous channel in the favourite list or channel list as appropriate, as described in the definitions of these methods Otherwise, if any of the above conditions is not true, then: · the values of the properties of the video/broadcast object currentChannel SHALL be the same as those provided in the channel argument to this method, updated as defined in section 8.4.3 · the channel is not considered to be part of the channel list the resulting current channel after any subsequent call to nextChannel() or prevChannel() is implementation dependent, however all appropriate functions SHALL be called and DOM events dispatched. The OITF SHALL visualize the video content received over the tuner in the area of the browser allocated for the video/broadcast object. If the OITF cannot visualize the video content following a successful tuner switch (e.g., because the channel is under parental lock), the OITF SHALL trigger the function specified by the onChannelChangeError property with the appropriate channel and errorState value, and dispatch a corresponding DOM event (see below). If successful, the OITF SHALL trigger the function specified by the onChannelChangeSucceeded property with the given channel value, and also dispatch a corresponding DOM event.
Arguments	channel	The channel to which a switched is requested. If the channel object specifies a ccid, the ccid identifies the channel to be set. If the channel does not specify a ccid, the idType determines which properties of the channel are used to define the channel to be set, for example, if the channel is of type ID_IPTV_SDS or ID_IPTV_URI, the ipBroadcastID identifies the channel to be set. If null, the video/broadcast object SHALL transition to the unrealized state and release any resources used for decoding video and/or audio. A ChannelChangeSucceeded event SHALL be generated when the operation has completed.
	trickplay	Optional flag indicating whether resources SHOULD be allocated to support trick play. This argument provides a hint to the receiver in order that it may allocate appropriate resources. Failure to allocate appropriate resources, due to a resource conflict, a lack of trickplay support, or due to the OITF ignoring this hint, SHALL have no effect on the success or failure of this method. If trickplay is not supported, this SHALL be indicated through the failure of later calls to methods invoking trickplay functionality. The timeShiftMode property defined in section 7.13.2.2 shall provide information as to type of trickplay resources that should be allocated. If argument contentAccessDescriptorURL is included then the trickplay argument SHALL be included.
	contentAccessDescriptorURL	Optional argument containing a Content Access Streaming descriptor (the format of which is defined in Annex E.2) that can be included to provide additional information for dealing with IPTV broadcasts that are (partially) DRM-protected. The argument SHALL be undefined or null if it is not applicable.

void prevChannel()

Description

Requests the OITF to switch the tuner that is currently in use by the video/broadcast object to the channel that precedes the current channel in the active favourite list, or, if no favourite list is currently selected, to the previous channel in the channel list. If it has reached the start of the favourite/channel list, it SHALL cycle to the last channel in the list.

If the previous channel is a channel that cannot be received over the tuner currently used by the video/broadcast object, the OITF SHALL relay the channel switch request to a local physical or logical tuner that is not in use and that can tune to the specified channel. The behaviour is defined in more detail in the description of the setChannel method.

If an error occurs during switching to the previous channel, the OITF SHALL trigger the function specified by the onChannelChangeError property with the appropriate channel and errorState value, and dispatch the corresponding DOM event (see below).

If the OITF does not maintain the channel list and favourite list by itself, the request SHALL fail and the OITF SHALL trigger the onChannelChangeError function with the channel property having the value null, and errorState=10 (“channel cannot be changed by nextChannel()/prevChannel() methods”).

If successful, the OITF SHALL trigger the function specified by the onChannelChangeSucceeded property with the appropriate channel value, and also dispatch the corresponding DOM event.

Calls to this method are valid in the Connecting, Presenting and Stopped states. They are not valid in the Unrealized state and SHALL fail.

void nextChannel()

Description

Requests the OITF to switch the tuner that is currently in use by the video/broadcast object to the channel that succeeds the current channel in the active favourites list, or, if no favourite list is currently selected, to the next channel in the channel list. If it has reached the end of the favourite/channel list, it SHALL cycle to the first channel in the list.

If the current channel is not part of the channel list, it is implementation dependent whether the method call succeeds or fails and, if it succeeds, which channel is selected. In both cases, all appropriate functions SHALL be called and DOM events dispatched. If the next channel is channel that cannot be received over the tuner currently used by the video/broadcast object, the OITF SHALL relay the channel switch request to a local physical or logical tuner that is not in use and that can tune to the specified channel. The behaviour is defined in more detail in the description of the setChannel method.

If an error occurs during switching to the next channel, the OITF SHALL trigger the function specified by the onChannelChangeError property with the appropriate channel and errorState value, and dispatch the corresponding DOM event (see below).

If successful, the OITF SHALL trigger the function specified by the onChannelChangeSucceeded property with the appropriate channel value, and also dispatch the corresponding DOM event.

Calls to this method are valid in the Connecting, Presenting and Stopped states. They are not valid in the Unrealized state and SHALL fail.

void setFullScreen( Boolean fullscreen )
Description	Sets the rendering of the video content to full-screen (fullscreen = true) or windowed (fullscreen = false) mode (as per [Req. 5.7.1.c] of [CEA-2014-A]). If this indicates a change in mode, this SHALL result in a change of the value of property fullScreen. Changing the mode SHALL NOT affect the z-index of the video object.
Arguments	fullScreen	Boolean to indicate whether video content should be rendered full-screen or not.

Boolean setVolume( Integer volume )

Description

Adjusts the volume of the currently playing media to the volume as indicated by volume. Allowed values for the volume argument are all the integer values starting with 0 up to and including 100. A value of 0 means the sound will be muted. A value of 100 means that the volume will become equal to current “master” volume of the device, whereby the “master” volume of the device is the volume currently set for the main audio output mixer of the device. All values between 0 and 100 define a linear increase of the volume as a percentage of the current master volume, whereby the OITF SHALL map it to the closest volume level supported by the platform.

The method returns true if the volume has changed. Returns false if the volume has not changed. Applications MAY use the getVolume() method to retrieve the actual volume set.

Arguments

volume

Integer value between 0 up to and including 100 to indicate volume level.

Integer getVolume()
Description	Returns the actual volume level set; for systems that do not support individual volume control of players, this method will have no effect and will always return 100.

void release()

Description

Releases the decoder/tuner used for displaying the video broadcast inside the video/broadcast object, stopping any form of visualization of the video inside the video/broadcast object and releasing any other associated resources.

If the object was created with an allocationMethod of STATIC_ALLOCATION, the releasing of resources shall change this to DYNAMIC_ALLOCATION.

void stop()

Description

Stop presenting broadcast video. If the video/broadcast object is in any state other than the unrealized state, it SHALL transition to the stopped state and stop video and audio presentation. This SHALL have no effect on access to non-media broadcast resources such as EIT information.

Calling this method from the unrealized state SHALL have no effect.

See section 7.13.1.1 for more information of its usage.

Events

For the intrinsic events listed in the table below, a corresponding DOM event SHALL be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onfocus	focus (as defined in section 5.2.1.2 of the DOM Level 3 Events specification as referenced in [OIPF_DAE2_WEB])	Bubbles: No Cancellable: No Context Info: None
onblur	blur (as defined in section 5.2.1.2 of the DOM Level 3 Events specification as referenced in [OIPF_DAE2_WEB])	Bubbles: No Cancellable: No Context Info: None
onFullScreenChange	FullScreenChange	Bubbles: No Cancellable: No Context Info: None
onChannelChangeError	ChannelChangeError	Bubbles: No Cancellable: No Context Info: channel, errorState
onChannelChangeSucceeded	ChannelChangeSucceeded	Bubbles: No Cancellable: No Context Info: channel
onPlayStateChange	PlayStateChange	Bubbles: No Cancellable: No Context Info: state, error

Note: these DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications SHOULD NOT rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers SHALL call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

Styling

video/broadcast objects SHALL support CSS-property z-index, in both full-screen and windowed mode.

Cookie	Duration	Description
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.

Application Management APIs