Extensions to video/broadcast for recording and time-shift

Support in HbbTV

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

OIPF DAE[1], section 7.13.2, shall be replaced by the text in clauses A.2.4.7 and A.2.4.8.

Terminals that support PVR shall support all of clauses A.2.4.7 and A.2.4.8.

Terminals that support time-shift of broadcast video shall support the following events and properties even if they do not support the full PVR

option:

– onRecordingEvent

– recordingState

– playPosition

– onPlayPositionChanged

– playSpeed

– onPlaySpeedChanged

– onPlaySpeedsArrayChanged

– playbackOffset

– maxOffset

– timeShiftMode

– currentTimeShiftMode

Comment

Broadcast-related

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

NameValueUse
POSITION_START0Indicates a playback position relative to the start of the buffered content.
POSITION_CURRENT1Indicates a playback position relative to the current playback position.
POSITION_END2Indicates 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:

ValueDescription
0Timeshift is turned off.
1Timeshift 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:

ValueDescription
0Timeshift is turned off.
1Timeshift 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()
DescriptionPause playback of the broadcast. This is equivalent to setSpeed(0).
Boolean resume()
DescriptionResumes playback of the time-shifted broadcast. This is equivalent to setSpeed(1).
Boolean setSpeed( Number speed )
DescriptionSets 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.

ArgumentsspeedThe 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 )
DescriptionSets 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.

ArgumentsoffsetThe 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.
referenceThe reference point from which the offset shall be measured. The reference point can be either POSITION_CURRENT, POSITION_START, or POSITION_END.
Boolean stopTimeshift()
DescriptionStops 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 eventCorresponding DOM 2 eventDOM 2 Event properties
onRecordingEventRecordingEventBubbles: No

Cancelable: No

Context Info: state, error, recordingId

onPlaySpeedChangedPlaySpeedChangedBubbles: No

Cancelable: No

Context Info: speed

onPlayPositionChangedPlayPositionChangedBubbles: No

Cancelable: No

Context Info: position

onPlaySpeedsArrayChangedPlaySpeedsArrayChangedBubbles: 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

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 recording of the current broadcast.

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:

ValueDescription
0Unrealized: user/application has not requested timeshift or recordNow functionality for the channel shown. No timeshift or recording resources are claimed in this state.
1Value not used
2Value not used
3Acquiring recording resources (for example, space on the media storage device).
4Recording has started.
5Value not used
6Recording 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:

ValueDescription
0Unrealized: user/application has not requested timeshift or recordNow functionality for the channel shown. No timeshift or recording resources are claimed in this state.
1Value not used
2Value not used
3Acquiring recording resources (for example, space on the media storage device).
4Recording has started.
5Value not used
6Recording 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:

ValueDescription
0The recording sub-system is unable to record due to resource limitations.
1There is insufficient storage space available. (Some of the recording may be available).
2Value not used
3Recording not allowed due to DRM restrictions.
4Recording 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 )
DescriptionStarts 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.

ArgumentsdurationThe 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()
DescriptionStops the current recording started by recordNow().

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

Note that this functionality is subject to the security model as specified in section 10.1.

This functionality is subject to the state transitions represented in the following state diagram:

Figure 15: PVR States for recordNow and timeshifting 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 OITF 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.

Constants

NameValueUse
POSITION_START0Indicates a playback position relative to the start of the buffered content.
POSITION_CURRENT1Indicates a playback position relative to the current playback position.
POSITION_END2Indicates a playback position relative to the end of the buffered content.

Properties

function onPlaySpeedChanged( Number speed )
The function that is called when the playback speed of a channel changes. 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. If the playback reaches the beginning of the time-shift buffer at rewind playback speed, then the play state is changed to 2 (‘paused’) and a PlaySpeedChanged event with a speed of 0 is generated. If the playback reaches the end of the time-shift buffer at fast-forward playback speed, then the play speed is set to 1.0 and a PlaySpeedChanged event is generated.
function onPlayPositionChanged( Integer position )
The function that is called when change occurs in the play position of a channel due to the use of trick play functions. 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. If the value of the currentTimeShiftMode property is 1, this is measured in milliseconds from the start of the timeshift buffer. If the value of the currentTimeShiftMode property is 2, this is measured in milliseconds from the start of the media item. If the play position cannot be determined, this argument takes the value undefined.
readonly Integer playbackOffset
Returns the playback position, specified as the positive offset of the live broadcast in seconds, in the currently rendered (timeshifted) broadcast. When the currentTimeShiftMode property has the value 1, 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 (timeshifted) broadcast. If the maximum offset is unknown, the value of this property SHALL be undefined. When the currentTimeShiftMode property has the value 1, the value of this property is undefined.

readonly Integer recordingState

Returns the state of the OITF’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

Recording has been newly scheduled.

2

Recording is about to start. The receiver may be monitoring EPG data in order to ensure that the programme scheduled to be recorded has not been moved, or to support “accurate recording” functionality as defined in section 11 of TS 102 323 [TS 102 323], where slight changes in the start time of the recording do not result in the start of the recording being missed. No recording resources have yet been acquired, although the OITF may have tuned to the channel which is to be recorded.

3

Acquiring recording resources (incl. media connection).

4

Recording has started.

5

Recording has been updated.

6

Recording has successfully completed.

10

Acquiring timeshift resources (incl. media connection).

11

Timeshift mode has started.

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

Recording has been newly scheduled.

2

Recording is about to start . The receiver may be monitoring EPG data in order to ensure that the programme scheduled to be recorded has not been moved, or to support “accurate recording” functionality as defined in section 11 of TS 102 323 [TS 102 323], where slight changes in the start time of the recording do not result in the start of the recording being missed. No recording resources have yet been acquired, although the OITF may have tuned to the channel which is to be recorded.

3

Acquiring recording resources (incl. media connection).

4

Recording has started.

5

Recording has been updated.

6

Recording has successfully completed.

10

Acquiring timeshift resources (incl. media connection).

11

Timeshift mode has started.

· 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

Tuner conflict (e.g. due to conflicting scheduled recording).

3

Recording not allowed due to DRM restrictions.

4

Recording has stopped before completion due to unknown (probably hardware) failure.

10

Timeshift not possible due to resource limitations.

11

Timeshift not allowed due to DRM restrictions.

12

Timeshift ended due to unknown 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.

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. If the value of the currentTimeShiftMode property is 2, the current playback position of the media, measured in milliseconds from the start of the media item.
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 A/V content can be played (as a time-shifted broadcast in the video/broadcast object), or undefined if the supported playback speeds are not known or the video/broadcast object is not in timeshift mode. If the video/broadcast object is in timeshift mode, the playSpeeds array SHALL always include at least values 1.0 and 0.0.
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”.

2

Timeshift shall use “network resources”.

3

Timeshift shall first use “local resource” when available and fallback to “network resources”.

If property is not set the default value of the property is according to preferredTimeShiftMode in section 7.3.2.1.

readonly Integer currentTimeShiftMode

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

Value

Description

0

No timeshift.

1

Timeshift using “local resource”.

2

Timeshift using “network resources”.

Methods

String recordNow( Integer duration )

Description

Starts recording the broadcast currently rendered in the video/broadcast object. If the OITF 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 OITF 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 OITF provides recording management functionality through the APIs defined in section 7.10.4, this SHALL be the value of the id property of the associated Recording object defined in section 7.10.5.

The OITF 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 OITF 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().

Boolean pause()

Description

Pause playback of the broadcast.

The action taken depends on the value of the timeShiftMode property.

If the value of the timeShiftMode property is 0, if trick play is not supported for the channel currently being rendered, or if the current time shift mode is not supported for the type of channel being presented (e.g. attempting to use network resource to time shift a DVB or analogue channel) this method shall return false.

If the timeshift mode is set to 1 or 3 (local resources) and if recording has not yet been started, this method will start recording the broadcast that is currently being rendered live (i.e., not time-shifted) in the video/broadcast object. If the OITF has buffered the ‘live’ broadcasted content, the recording starts with the content that is currently being rendering in the video/broadcast object. If the recording started successfully, the rendering of the broadcasted content is paused, i.e. a still-image video frame is shown.

If the timeshift mode is set to 2 (network resources) then the OITF shall follow the procedures defined in section 8.2.6.4 and returns true. Since this operation is asynchronous when the procedure are executed successful the rendering of the broadcasted content is paused, i.e. a still-image video frame is shown, and PlaySpeedChanged event is generated.

If the specified timeshift mode is not supported, this method shall return false. Otherwise, this method shall return true. Acquiring the necessary resources to enable the specified timeshift mode may be an asynchronous operation; applications may receive updates of this process by registering a listener for RecordingEvents as defined in section 7.13.2.4.

If trick play is not supported for the channel currently being rendered, this method shall return false, otherwise true is returned.

This operation may be asynchronous, and presentation of the video may not pause until after this method returns. For this reason, a PlaySpeedChanged event will 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.

Boolean resume()

Description

Resumes playback of the time-shifted broadcast channel that is currently being rendered in the video/broadcast object at the speed specified by setSpeed(). If the desired speed was not set via setSpeed(), playback is resumed at normal speed (i.e. speed 1.0). If the video/broadcast object is currently not rendering a time-shifted channel, the OITF shall ignore the request to start playback and shall return false. If playback cannot be resumed the OITF shall also return false, otherwise true is returned.

This operation may be asynchronous, and presentation of the video may not resume until after this method returns. For this reason, a PlaySpeedChanged event will 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.

The action taken depends on the value of the timeShiftMode property.

If the value of the timeShiftMode property is 1 or 3 (local resources) then the OITF shall resume playback of the broadcast channel as specified above and return true.

If the value of the timeShiftMode property is 2 (network resources) then the OITF shall follow the procedures defined in section 8.2.6.4 and return true. Since this operation is asynchronous when the procedure is successfully executed a PlaySpeedChanged event is generated with current speed.

After initial operation of resume() several events may affect the operation.

If during fast forward the end of stream is reached the playback SHALL resume at normal speed and a PlaySpeedChanged event is generated. If the end of stream is reached due to end of content the playback will automatically be paused and a PlaySpeedChanged event is 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 will automatically be paused (i.e. the play speed will be changed to 0) and a PlaySpeedChanged event is generated.

If for any of these events timeShiftMode is set to 3 and local resources are not available anymore then network sources SHALL be used according to the procedures defined in section 8.2.6.4. The OITF SHALL perform a smooth transition of the stream between local and network resources.

Boolean setSpeed( Number speed )

Description

Sets the playback speed of the time-shifted broadcast to the value speed, without changing the paused/resumed state of the time-shifted broadcast.

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

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. Applications are not required to pause playback of the broadcast or take any other action before calling setSpeed().

If the video/broadcast object is currently not rendering a time-shifted channel, the OITF shall ignore the request to change the playback speed and shall return false, otherwise true is returned.

This operation may be asynchronous, and presentation of the video may not be affected until after this method returns. For this reason, a PlaySpeedChanged event will 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.

The action taken depends on the value of the timeShiftMode property.

If the value of the timeShiftMode property is 1 or 3 (local resources) then the setSpeed() method sets the playback speed of the time-shifted broadcast to the value speed.

If the timeShiftMode is set to 2 (network resources) the OITF shall follow the procedures defined in section 8.2.6.4 and return true. Since this operation is asynchronous when the procedure is successfully executed PlaySpeedChanged event is generated with the new speed.

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

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

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

If for any of these events if timeShiftMode is set to 3 and local resources are not available anymore then network sources SHALL be used according to the procedures defined in section 8.2.6.4. The OITF SHALL perform a smooth transition of the stream between local and network resources.

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. If the time-shifted broadcast cannot be played at the desired speed, the playback speed will be set to the best approximation.

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 section 7.13.2.1. Returns true if the playback position is a valid position to seek to, false otherwise. If the video/broadcast object is currently not rendering a time-shifted channel or if the position falls outside the time-shift buffer, the OITF 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 will 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.

The action taken depends on the value of the timeShiftMode property.

If the timeShiftMode is set to 1 (local resources) the seek() method sets the playback position of the time-shifted broadcast that is being rendered in the video/broadcast object as defined above. Playback of live content is resumed if the new position equals the end of the time-shift buffer.

If the timeShiftMode is set to 2 (network resources) the OITF shall follow the procedures defined in section 8.2.6.4 and return true. Since this operation is asynchronous when the procedure is successfully executed PlayPositionChanged event is generated with the new position.

Note that if timeShiftMode is set to 3 then local resources are used over network resources.

After initial operation of seek() several events may affect the operation.

If during fastforward the end of stream is reached the playback SHALL resume at normal speed and a PlaySpeedChanged event is generated. If the end of stream is reached due to end of content the playback will automatically be paused and a PlaySpeedChanged event is generated. Any resources used for time-shifting SHALL NOT be discarded.

If for any of these events if timeShiftMode is set to 3 and local resources are not available anymore then network sources SHALL be used according to the procedures defined in section 8.2.6.4. The OITF SHALL perform a smooth transition of the stream between local and network resources.

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 a 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 time-shifted mode of the broadcast channel in the video/broadcast object and, if applicable, plays the current broadcast from the live point and stops time-shifting the broadcast. The OITF SHALL release all resources that were used to support time-shifted rendering of the broadcast.

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

In addition to these methods, the OITF SHALL support an additional optional attribute “offSet” on the setChannel(Channel channel, Boolean trickplay, String contentAccessDescriptorURL) method of the video/broadcast object as defined in section 7.13.1.3, if the OITF has indicated support for scheduled content over IP by defining one or more ID_IPTV_* values as part of the transport attribute of the <video_broadcast> element in the capability description.

void setChannel( Channel channel, Boolean trickplay,
String contentAccessDescriptorURL, Integer offset )

Description

Requests the OITF to switch a (logical or physical) tuner to the specified channel and render the received broadcast content in the area of the browser allocated for the video/broadcast object, as specified by the setChannel(Channel channel, Boolean trickPlay, String contentAccessDescriptorURL) method in section 7.13.1.3.

The additional offSet attribute optionally specifies the desired offset with respect to the live broadcast in number of seconds from which the OITF SHOULD start playback immediately after the channel switch (whereby offSet is given as a positive value for seeking to a time in the past). If an OITF cannot start playback from the desired position, as indicated by the specified offSet (e.g. because the OITF did not, or could not, record the specified channel prior to the call to setChannel), if the specified offSet is ‘0’, or if the offSet is not specified, the OITF SHALL start playback from the live position after the specified channel switch.

Arguments

channel

As defined for method setChannel()in section 7.13.1.3.

trickplay

Optional flag as defined for method setChannel()in section 7.13.1.3.

contentAccessDescriptorURL

Optional attribute as defined for method setChannel()in section 7.13.1.3.

offset

The optional offset attribute MAY be used to specify the desired offset with respect to the live broadcast in number of seconds from which the OITF SHOULD start playback immediately after the channel switch (whereby offset is given as a negative value for seeking to a time in the past).

Events

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

Intrinsic eventCorresponding DOM eventDOM Event properties
onRecordingEventRecordingEventBubbles: No Cancellable: No Context Info: state, error, recordingId
onPlaySpeedChangedPlaySpeedChangedBubbles: No Cancellable: No Context Info: speed
onPlayPositionChangedPlayPositionChangedBubbles: No Cancellable: No Context Info: position
onPlaySpeedsArrayChangedPlaySpeedsArrayChangedBubbles: No Cancellable: No Context Info: None

Note: the 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.