Attributes

tv of type TVControl, readonly

MUST return the object that exposes the interface to the TV control service.

Methods

getTVManager

This method makes a request to retrieve a manager for TV services. It returns a new TVManager that can be used for interacting with TV services available through the device. Note that these services may include radio services delivered via a digital TV system.

No parameters.

Return type: Promise<TVManager>

getRadioManager

This method makes a request to retrieve a manager for radio services. It returns a new TVManager that can be used for interacting with radio services (e.g. delivered via AM, FM or DAB) available through the device.

No parameters.

Return type: Promise<TVManager>

Attributes

totalRecordingSize of type unsigned long long, readonly

MUST return the total recording size of the TV device in bytes.

availableRecordingSize of type unsigned long long, readonly

MUST return the current available recording size of the TV device in bytes.

isParentalControlled of type boolean, readonly

MUST return the current state of the TV parental control, which is applied system-wide to the TV device. Once the parental control is unset, all the locked TV channels/programs will become accessible.

ontunerchange of type EventHandler

Handles the tunerchange event of type TVTunerChangeEvent, fired when the TV/Radio device detects a tuner is added/removed.

onrecordingchange of type EventHandler

Handles the recordingchange event of type TVRecordingChangeEvent, fired when the recording time frame or the state of the TV/Radio recording has been changed.

onparentalcontrolchange of type EventHandler

Handles the parentalcontrolchange event, fired when the parental control status is changed.

oncicardchange of type EventHandler

Handles the cicardchange event, fired when the CI (Common Interface) card status is changed.

Methods

getCapabilities

This method makes a request to retrieve the capabilities of the device. It returns a new TVSourceCapabilities object that describes the capabilities of the device for receiving and decoding TV or radio services.

No parameters.

Return type: TVSourceCapabilities

getSupportedConstraints

This method makes a request to retrieve the set of constraints supported by the device. It returns a new TVSourceSupportedConstraints object that describes the set of constraints that may be specified when requesting a TVSource object.

No parameters.

Return type: TVSourceSupportedConstraints

getSource

This method makes a request to retrieve a TV/Radio source that matches the specified constraints that are available in the device. It returns a new Promise that will be used to notify the caller about the result of the operation, which is a TVSource obect.

Parameter	Type	Nullable	Optional	Description
option	TVSourceConstraints	✘	✘	Specifies the constraints for the requested TV source.

Return type: Promise<TVSource>

isSourceAvailable

This method returns true if a TV/Radio source that matches the specified constraints is currently available, and false otherwise. Note that the availability of a TVSource will depend on the number of streams being decoded by the device, and may also depend on other factors.

Parameter	Type	Nullable	Optional	Description
option	TVSourceConstraints	✘	✘	Specifies the constraints for the requested TV source.

Return type: boolean

getChannelList

This method makes a request to retrieve the list of TV/Radio channels that matches the specified constraints that are available in the device. It returns a new Promise that will be used to notify the caller about the result of the operation, which is a sequence of TVChannel elements.

Parameter	Type	Nullable	Optional	Description
option	TVSourceConstraints	✘	✘	Specifies the constraints for the requested channel list.

Return type: Promise<sequence<TVChannel>>

addRecording

This method adds a recording request for a given channel with explicitly specified start time and end time, or instead an associated TVProgram object. It returns a new Promise that will be used to notify the caller about the result of the operation, which is a newly-created TVRecording object.
Please note the user agent should have a recording scheduler which handles time conflicts between recording requests. If this method tries to add a new request with a time frame overlapped with some existent ones, and given sufficient resource (i.e. tuner), a new TV/Radio recording should be created and the scheduler should ensure multiple TV/Radio recordings run at the same time. However, if the resource is not sufficient to meet the new request, the Promise should be rejected. Applications may handle this situation with their own strategy, such as explicitly removing the conflicts and re-adding the one to conserve.

Parameter	Type	Nullable	Optional	Description
option	TVAddRecordingOptions	✘	✘	Specifies the options for adding recording.

Return type: Promise<TVRecording>

removeRecording

This method makes a request to remove a given recording. It returns a new Promise that will be used to notify the caller about the result of the operation.

Parameter	Type	Nullable	Optional	Description
id	DOMString	✘	✘	Specifies the ID of the recording to be removed.

Return type: Promise<void>

getRecordings

This method makes a request to retrieve the available TV/Radio recordings according to the given criteria. It returns a new Promise that will be used to notify the caller about the result of the operation.

Parameter	Type	Nullable	Optional	Description
options	TVGetRecordingsOptions	✘	✔	Specifies the options for getting recordings.

Return type: Promise<sequence<TVRecording>>

setParentalControlPin

This method makes a request to set the TV/Radio parental control PIN used for enabling or disabling parental control. It returns a new Promise that will be used to notify the caller about the result of the operation. Note that the Promise may be rejected with an InvalidAccessError if the old PIN does not match the current one.

Parameter	Type	Nullable	Optional	Description
oldPin	DOMString	✘	✘	Specifies the old PIN used for parental control.
newPin	DOMString	✘	✘	Specifies the new PIN used for parental control.

Return type: Promise<void>

setParentalControl

This method makes a request to set the TV/Radio parental control status. It returns a new Promise that will be used to notify the caller about the result of the operation. Note that the Promise may be rejected with an InvalidAccessError if the PIN does not match the current one.

Parameter	Type	Nullable	Optional	Description
pin	DOMString	✘	✘	Specifies the PIN used for parental control.
isLocked	boolean	✘	✘	Specifies the parental control status.

Return type: Promise<void>

getCICards

This method makes a request to retrieve a list of CI (Common Interface) cards available in the TV device (e.g. set-top box). It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of TVCICard elements.

No parameters.

Return type: Promise<sequence<TVCICard>>

Procedures

The addRecording method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a recording request to the TV/Radio recording scheduler according to the options parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let recording be the newly-created TVRecording object.
   2. Invoke resolver's fulfill algorithm with recording as the value argument.

The removeRecording method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the TV/Radio device to remove the given record.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

The getRecordings method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the recording scheduler to retrieve the available TV/Radio recordings according to the options parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let recordings be the array of the retrieved TVRecording elements.
   2. Invoke resolver's fulfill algorithm with recordings as the value argument.

The setParentalControlPin method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to set the new PIN for parental control according to the newPin parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

The setParentalControl method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to set the new status for parental control according to the isLocked parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

The getCICards method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the TV device to retrieve all the CI (Common Interface) cards that are available in the TV device.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let cicards be the array of the retrieved TVCICard elements.
   2. Invoke resolver's fulfill algorithm with cicards as the value argument.

Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the TVManager object.

Attributes

type of type TVSourceType, readonly

MUST return the type of the TV/Radio source.

stream of type TVMediaStream, readonly, nullable

MUST return a TVMediaStream object extended from MediaStream and currently streamed by the source, which can be played by the video element by assigning the TVMediaStream (MediaStream) to the HTMLMediaElement's srcObject attribute and can be recorded by the MediaRecorder.
MUST return null if the source is not streaming any data, which happens when the streaming signal is broken or due to any reason that makes the TV source fail to do so.
Note that the stream instance should be the same even after the current selected TV channel has been changed.

isScanning of type boolean, readonly

MUST indicate whether the source is scanning the TV/Radio channels or not.

currentChannel of type TVChannel, readonly, nullable

MUST return the channel that is currently streamed by the TV/Radio tuner which owns the source. MUST return null if the TV/Radio tuner is not streaming any data.

oncurrentchannelchange of type EventHandler

Handles the currentchannelchange event of type TVCurrentChannelChangeEvent, fired when the method tuneTo or tuneToChannel is invoked to tune the currently streamed TV/Radio channel.

oneitbroadcast of type EventHandler

Handles the eitbroadcast event of type TVEITBroadcastEvent, fired when the Event Information Table (EIT) is broadcast by the TV source.

onemergencyalert of type EventHandler

Handles the emergencyalert event of type TVEmergencyAlertEvent, fired when an emergency, such as earthquake or tsunami, occurs and is broadcast by the TV/Radio source.

onscanningstatechange of type EventHandler

Handles the scanningstatechange event of type TVScanningStateChangeEvent, fired when the state of scanning the TV/Radio channels is changed by the source. E.g., it can be fired when the method startScanning or the method stopScanning starts or stops scanning the TV/Radio channels, or when a channel is found during the channel scan.

Methods

getConstraints

See ConstrainablePattern Interface for the definition of this method.

No parameters.

Return type: TVSourceConstraints

getSettings

See ConstrainablePattern Interface for the definition of this method.

No parameters.

Return type: TVSourceSettings

getChannels

This method makes a request to retrieve all the TV/Radio channels that are available in the source. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of TVChannel elements that belong to the source. And if parental control is enabled, the array of TVChannel elements should exclude the locked channels. Note that the Promise may be rejected with an InvalidStateError if this method gets called during channel scanning.

No parameters.

Return type: Promise<sequence<TVChannel>>

tuneToChannel

This method makes a request to tune to the TV/Radio channel specified by the channel parameter. It returns a new Promise that will be used to notify the caller about the result of the operation. Note that the Promise may be rejected with an InvalidStateError if this method is called during channel scanning, or be rejected with an InvalidAccessError if parental control is enabled and the channel is locked.

Parameter	Type	Nullable	Optional	Description
channel	TVChannel	✘	✘	Specifies the TV/Radio channel to be tuned to.

Return type: Promise<TVMediaStream>

tuneTo

This method makes a request to tune to the TV/Radio channel specified by the tuningParams parameter. It returns a new Promise that will be used to notify the caller about the result of the operation. Note that the Promise may be rejected with an InvalidStateError if this method is called during channel scanning, or be rejected with an InvalidAccessError if parental control is enabled and the channel is locked.

Parameter	Type	Nullable	Optional	Description
tuningParams	DOMString	✘	✘	Specifies the tuning parameters of the TV/Radio channel to be tuned to.

Return type: Promise<TVMediaStream>

startScanning

This method makes a request to start scanning all the TV/Radio channels that are available in the source by the options parameter. It returns a new Promise that will be used to notify the caller about the result of the operation. Note that this method has to be called first at some setup stages, so that the method getChannels can retrieve the channels that have successfully been scanned by the source. Besides, due to some constraints of tuner modules, scanning and streaming are not encouraged to run at the same time.

Parameter	Type	Nullable	Optional	Description
options	TVStartScanningOptions	✘	✔	Specifies the options for scanning the TV/Radio channels. The isRescanned option in the options parameter specifies whether or not the process of scanning the TV/Radio channels has to clear the currently scanned TV/Radio channels before scanning; if it is not passed, this method will rescan all the TV/Radio channels as if it is passed as true.

Return type: Promise<void>

stopScanning

This method makes a request to stop scanning the TV/Radio channels for the source. It returns a new Promise that will be used to notify the caller about the result of the operation.

No parameters.

Return type: Promise<void>

Procedures

The getChannels method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the source to retrieve all the TV/Radio channels that are available in the source.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let channels be the array of the retrieved TVChannel elements.
   2. Invoke resolver's fulfill algorithm with channels as the value argument.

The tuneToChannel method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the source to tune the currently streamed TV/Radio channel according to the channel parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let stream an instance of a TVMediaStream representing the media data of the specified channel.
   2. Invoke resolver's fulfill algorithm with stream as the value argument.

The tuneTo method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the source to tune the currently streamed TV/Radio channel according to the tuningParams parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let stream an instance of a TVMediaStream representing the media data of the channel found at the specified tuning parameters.
   2. Invoke resolver's fulfill algorithm with stream as the value argument.

The startScanning method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the source to start scanning all the TV/Radio channels that are available in the source according to the scanning options specified in the options parameter. If the isRescanned option in the options parameter is not passed or it is passed as true, the user agent MUST clear the currently scanned TV/Radio channels before scanning; if it is passed as false, the user agent will simply scan additional TV/Radio channels which haven't been scanned yet.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

The stopScanning method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the source to stop scanning the TV/Radio channels.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the TVSource object.

TVSourceSupportedConstraints Dictionary

TVSourceSupportedConstraints represents the list of constraints recognized by a User Agent for controlling the Capabilities of a TVSource object. This dictionary is used as a function return value, and never as an operation argument.

dictionary TVSourceSupportedConstraints {
	  boolean deliverySystem = true;
	  boolean height = true;
	  boolean channel = true;
	  boolean tuningStep = true;

};

TVSourceCapabilities Dictionary

TVSourceCapabilities represents the capabilities of a TVSource object

dictionary TVSourceCapabilities {
    sequence <TVSourceType> deliverySystem;
	long     height;
    long     tuningStep;
};

TVSourceConstraints Dictionary

TVSourceConstraints represents the list of constraints recognized by a User Agent for controlling the Capabilities of a TVSource object.

dictionary TVSourceConstraints {
	  sequence<TVSourceType> deliverySystem;
	  ConstrainLong height;
	  TVChannel channel;
	  ConstrainLong tuningStep;

};

TVSourceSettings Dictionary

TVSourceSettings represents the Settings of a TVSource object.

dictionary TVSourceSettings {
	  sequence <TVSourceType> deliverySystem;
	  ConstrainLong height;
	  TVChannel channel;
	  ConstrainLong tuningStep;

};

Constrainable Properties

The names of the initial set of constrainable properties for TVSource are defined below.

The delivery system may be one of the following values of TVSourceType:

enum TVSourceType {
    "dvb-t",
    "dvb-t2",
    "dvb-c",
    "dvb-c2",
    "dvb-s",
    "dvb-s2",
    "dvb-h",
    "dvb-sh",
    "atsc",
    "atsc-m/h",
    "isdb-t",
    "isdb-tb",
    "isdb-s",
    "isdb-c",
    "1seg",
    "dtmb",
    "cmmb",
    "t-dmb",
    "s-dmb",
    "dab",
    "drm",
    "fm",
    "AM"
};

The following constrainable properties are defined to apply only to radio TVSource objects:

Attributes

source of type TVSource, readonly

MUST return the source which the TV/Radio channel belongs to.

type of type TVChannelType, readonly

MUST return the type of the channel.

attributes of type TVChannelAttributes, readonly

MUST return TVChannelAttributes belonging to this TV/Radio channel. "NHK", etc.

name of type DOMString, readonly

MUST return the name of the TV/Radio channel. E.g., "CNN", "NHK", etc.

number of type DOMString, readonly

MUST return the Logical Channel Number (LCN) of the TV/Radio channel. E.g., "12-1", "12-2", etc.

isEmergency of type boolean, readonly

MUST indicate whether the TV/Radio channel is for the emergency purpose.

isEncrypted of type boolean, readonly

MUST indicate whether the TV/Radio channel is encrypted.

casSystemId of type DOMString, readonly, nullable

MUST return the system ID if it requires to use a specific CAS (Conditional Access System) to decrypt the stream from the encrypted TV/Radio channel.

isParentalLocked of type boolean, readonly

MUST indicate whether the TV/Radio channel is locked for parental control.

onparentallockchange of type EventHandler

Handles the parentallockchange event, fired when the parental lock status of the TV/Radio channel is changed.

Methods

getPrograms

This method makes a request to retrieve all the TV/Radio programs that are available in the channel by the options parameter. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of TVProgram elements that belong to the TV/Radio channel.

Parameter	Type	Nullable	Optional	Description
options	TVGetProgramsOptions	✘	✔	Specifies the options for retrieving the TV/Radio programs. If this parameter is not passed, this method will return all the available TV/Radio programs.

Return type: Promise<sequence<TVProgram>>

getCurrentProgram

This method makes a request to retrieve the current TV/Radio program available in the channel. It returns a new Promise that will be used to notify the caller about the result of the operation, which is a TVProgram element that belongs to the channel.

No parameters.

Return type: Promise<TVProgram>

getApplications

This method makes a request to retrieve all the TV/Radio applications that are available in the channel. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of TVApplication elements that belong to the TV/Radio channel.

No parameters.

Return type: Promise<sequence<TVApplication>>

setParentalLock

This method makes a request to set the parental lock status for the channel. It returns a new Promise that will be used to notify the caller about the result of the operation.

Parameter	Type	Nullable	Optional	Description
pin	DOMString	✘	✘	Specifies the PIN used for parental control.
isLocked	boolean	✘	✘	Specifies the parental lock status for the channel.

Return type: Promise<void>

Procedures

The getPrograms method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the channel to retrieve all the TV/Radio programs that are available in the channel according to the retrieving options specified in the options parameter.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let programs be the array of the retrieved TVProgram elements.
   2. Invoke resolver's fulfill algorithm with programs as the value argument.

The getCurrentProgram method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the channel to retrieve the current TV/Radio program available in the channel.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let program be the retrieved TVProgram element.
   2. Invoke resolver's fulfill algorithm with program as the value argument.

The setParentalLock method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to set the new parental lock status for this channel according to the isLocked parameter.
4. If the pin parameter does not match the current PIN or an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to the value argument.

Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the TVChannel object.

Attributes

onattributeschange of type EventHandler

Handles the onattributeschange event, fired when the attributes of the TV/Radio channel are changed.

Attributes

originalNetworkId of type DOMString, readonly

MUST return the identification of the originating broadcast transmission network for this channel. This is the networkID of the operator that originated this channel.

networkId of type DOMString, readonly

MUST return the identification of a broadcast transmission network. On satellite and IP broadband, typically one networkId corresponds to an operator. On cable and terrestrial, where different radio frequencies might be used in different regions, operators typically use one networkId per such region.

transportStreamId of type DOMString, readonly

MUST return the identification of a time-domain multiplex of several programmes carried in Transport Stream (TS) packets. One or more multiplexes can be transmitted on any given radio frequency in a DVB network.

serviceId of type DOMString, readonly

MUST return the identification of a TV, radio or data programme within a TS multiplex. The number of programmes is limited by the capacity of the underlying physical channel.

Attributes

ensembleId of type DOMString, readonly

MUST return the identification of a time-domain multiplex of several programmes carried in DAB ensemble.

serviceId of type DOMString, readonly

MUST return the identification of aDAB radio or data service within a DAB ensemble. The number of programmes is limited by the capacity of the underlying physical channel.

Attributes

type of type TVApplicationType, readonly

MUST return the type of associated application.

applicationData of type object, readonly, nullable

MUST return application specific data. Please note that the detailed syntax and semantic might vary between different broadcasting standards or only known by private agreements.

onapplicationchange of type EventHandler

Handles the onapplicationchange event, fired when the application of the TV/Radio channel is changed.

Attributes

eventId of type DOMString, readonly

MUST return the event ID of the TV/Radio program. It has to be unique only within a TV/Radio channel.

channel of type TVChannel, readonly

MUST return the TV/Radio channel which the program belongs to.

title of type DOMString, readonly

MUST return the title of the TV/Radio program.

startTime of type DOMTimeStamp, readonly

MUST return the start time of the TV/Radio program, in milliseconds relative to 1970-01-01T00:00:00Z.

duration of type DOMTimeStamp, readonly

MUST return the duration of the TV/Radio program, in milliseconds relative to 1970-01-01T00:00:00Z.

shortDescription of type DOMString, readonly, nullable

MUST return the short description of the TV/Radio program.

longDescription of type DOMString, readonly, nullable

MUST return the long description of the TV/Radio program.

parentalRating of type DOMString, readonly, nullable

MUST return the parental rating of the TV/Radio program.

isEncrypted of type boolean, readonly

MUST indicate whether the TV/Radio program is encrypted by a content protection mechanism.

seriesId of type DOMString, readonly, nullable

MUST return the ID of the series (if applicable) which the TV/Radio program belongs to.

Methods

getAudioLanguages

MUST return the audio languages of the TV/Radio program in 3-digit language codes specified by [[!ISO639-2]].

No parameters.

Return type: sequence<DOMString>

getSubtitleLanguages

MUST return the subtitle languages of the TV/Radio program in 3-digit language codes specified by [[!ISO639-2]].

No parameters.

Return type: sequence<DOMString>

getGenres

MUST return the genres of the TV/Radio program. Please note that the classification might vary between different broadcasting standards.

No parameters.

Return type: sequence<DOMString>

Attributes

type of type TVTriggerType, readonly

MUST return the type of the TV/Radio trigger.

title of type DOMString, readonly, nullable

MUST return the human readable title for the TV/Radio trigger.

url of type DOMString, readonly, nullable

MUST return the URL for the TV/Radio trigger.

channel of type TVChannel, readonly, nullable

MUST return the channel associated with the TV/Radio trigger.

stream of type TVMediaStream, readonly, nullable

MUST return the TVMediaStream object that could be played for the TV trigger.

additionalData of type object, readonly, nullable

MUST return the content source information or other supplemental information for the TV trigger. Please note that the detailed data might vary between different broadcasting standards or only known by private agreements.

Attributes

id of type DOMString, readonly

MUST return the ID of the TV/Radio recording.

channel of type TVChannel, readonly

MUST return the associated channel of the TV/Radio recording.

program of type TVProgram, readonly, nullable

MUST return the associated program of the TV/Radio recording if applicable. Please note the recording should keep track of the relevant updates in Event Information Table (EIT) in the case of DVB or ProgramInfo in the case of DAB while TVProgram is specified, and then update correspondent attributes and fire a TVRecordingChangeEvent accordingly. Furthermore, if the updated time frame conflicts with some existent ones, and there's no sufficient resource (i.e. tuner) to meet this, then the recording should change its state to stopped.

startTime of type DOMTimeStamp, readonly

MUST return the start time of the TV/Radio recording, in milliseconds relative to 1970-01-01T00:00:00Z.

endTime of type DOMTimeStamp, readonly

MUST return the end time of the TV/Radio recording, in milliseconds relative to 1970-01-01T00:00:00Z.

state of type TVRecordingState, readonly

MUST return the current state of the TV/Radio recording.

size of type unsigned long long, readonly

MUST return the actual size of the TV/Radio recording. Please note the value should be zero if the TV recording hasn't actually recorded anything.

duration of type DOMTimeStamp, readonly

MUST return the actual duration of the TV/Radio recording, in milliseconds. Please note the value should be zero if the TV recording hasn't actually recorded anything.

description of type DOMString

MUST return the description of the TV/Radio recording.

onrecordingchange of type EventHandler

Handles the recordingchange event of type TVRecordingChangeEvent, fired when the recording time frame or the state of the TV/Radio recording has been changed.

Methods

getStream

This method makes a request to retrieve the recorded content as a TVMediaStream object, which is extended from MediaStream and can be played by the video element by assigning the TVMediaStream to the HTMLMediaElement's srcObject attribute. MUST return null if the TV/Radio recording hasn't actually recorded anything. Note that the Promise may be rejected with an InvalidAccessError if parental control is enabled and the recorded channel is locked.

No parameters.

Return type: Promise<TVMediaStream>

stop

This method makes a request to stop the TV/Radio recording.

No parameters.

Return type: Promise<void>

Procedures

The getStream method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the source to retrieve the recorded content that is available in the TV/Radio recording.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Let stream be the retrieved TVMediaStream object.
   2. Invoke resolver's fulfill algorithm with stream as the value argument.

The stop method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver be its associated resolver.
2. Return promise to the caller.
3. Make a request to the TV/Radio recording to stop it.
4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
5. When the request has been successfully completed:
   1. Invoke resolver's fulfill algorithm without assigning a value to value argument.

Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the TVRecording object.

Methods

getTextTracks

MUST return the text tracks in this stream.

No parameters.

Return type: sequence<TextTrack>

addTextTrack

Parameter	Type	Nullable	Optional	Description
textTrack	TextTrack	✘	✘	The TextTrack object to be added.

Return type: void

removeTextTrack

Parameter	Type	Nullable	Optional	Description
textTrack	TextTrack	✘	✘	The TextTrack object to be removed.

Return type: void

HTMLMediaElement Attributes When Playing a TVMediaStream

The nature of no buffering of the MediaStream places certain restrictions on the behavior and attribute values of the associated HTMLMediaElement and on the operations that can be performed on it. Yet since TVMediaStream is with a buffered mechanism to support basic seekability, it may be less restrictive to some extent, as shown below:

Time-shifting

Applications may utilize TVRecording and TVMediaStream to fulfill time-shifting scenarios. When time-shifting is enabled, it may add a TV/Radio recording for the current playing channel without specifying start time, which makes the recording starts from now on, or instead by specifying the live TV/Radio program. (The user agent should be able to play and record the same channel at the same time.) Then when it comes to switch to the time-shifted content, the TVMediaStream generated from the TV/Radio recording can be assigned to the video or audio element used for playing the current MediaStream. So the application may play with the video or audio element to set proper playback rates, seek to specific time, play/pause the buffered stream, and listen to some correspondent events. And when time-shifting is switched off (i.e. the recorded content has been fast forwarded to the current end), the application should assign the original MediaStream back to the video or audio element. Please note applications may need to regularly clean up old TV/Radio recordings used for time-shifting.

Attributes

state of type TVCICardState, readonly

MUST return the state of the CI card.

casSystemId of type DOMString, readonly

MUST return the CAS (Conditional Access System) system ID for the pertaining CI card.

isInUse of type boolean, readonly

MUST indicate whether the CI card is in use. Note that if multiple cards happen to represent the same casSystemId, at most one of them can have this attribute set.

Dictionary TVStartScanningOptions Members

isRescanned of type boolean

Specifies whether or not the process of scanning the TV/Radio channels has to clear the currently scanned TV/Radio channels before scanning.

Dictionary TVGetProgramsOptions Members

startTime of type DOMTimeStamp

Specifies the start time of a time period which bounds the time slots of TV/Radio programs to be retrieved, in milliseconds relative to 1970-01-01T00:00:00Z.

endTime of type DOMTimeStamp

Specifies the end time of a time period which bounds the time slots of TV/Radio programs to be retrieved, in milliseconds relative to 1970-01-01T00:00:00Z.

genre of type DOMString

Specifies the genre of TV/Radio programs to be retrieved.

Dictionary TVAddRecordingOptions Members

description of type DOMString, required

Specifies the description of the TV/Radio recording.

channel of type TVChannel, required

Specifies the channel to be recorded.

program of type TVProgram, nullable

Specifies the program to be recorded. Please note this could be omitted if the recording time frame can be determined by startTime and endTime.

startTime of type DOMTimeStamp, nullable

Specifies the start time of a recording time frame, in milliseconds relative to 1970-01-01T00:00:00Z. When not specified, it implies the recording should start from now on. Please note this could also be omitted and auto determined if program is specified.

endTime of type DOMTimeStamp, nullable

Specifies the end time of a recording time frame, in milliseconds relative to 1970-01-01T00:00:00Z. When not specified, it implies the recording should continue until a stop() call of TVRecording or the user agent forces it to stop due to resource control. Please note this could also be omitted and auto determined if program is specified.

Dictionary TVGetRecordingsOptions Members

state of type TVRecordingState, nullable

Specifies the state of the TV/Radio recordings to be retrieved.

id of type DOMString, nullable

Specifies the ID of the TV/Radio recording to be retrieved.

Attributes

operation of type TVTunerChangeEventOperation, readonly

MUST return the type of operation that changes the TV/Radio tuner.

id of type DOMString, readonly

MUST return the ID of the TV/Radio tuner that is added/removed.

Attributes

source of type TVSource, readonly, nullable

MUST return the source that is currently configured by the TV/Radio tuner. MUST return null if the TV/Radio source is not configured.

Attributes

programs of type object, readonly

MUST return the available TV programs in the EIT that is broadcast by the TV source. Please note that it needs to be casted into a list of TVProgram instances. The cached value for this array needs to go into an internal slot for the object, and it should be cached there until the next time that the underlying array changes when the cached value will be updated.

Attributes

type of type DOMString, readonly, nullable

MUST return the the nature of the emergency, i.e. “Earthquake”, "Tsunami", “Child Abduction”. Please note that the classification might vary between different broadcasting standards.

severityLevel of type DOMString, readonly, nullable

MUST return the severity level of the emergency alert. Please note that the classification of severity level might vary between different broadcasting standards. MUST return null when the emergency announcement is over.

description of type DOMString, readonly, nullable

MUST return the human readable description of the emergency alert.

channel of type TVChannel, readonly, nullable

MUST return the emergency channel which might be switched to for more information about the emergency.

url of type DOMString, readonly, nullable

MUST return the URL where more information might be available.

Methods

getRegions

MUST return the associated regions of the emergency alert. Please note that it might vary between different broadcasting standards. It could return an empty sequence if the emergency system doesn't reveal detailed geographical scope of the alert to the endpoint.

No parameters.

Return type: sequence<DOMString>

Attributes

state of type TVScanningState, readonly

MUST return the state of channel scanning, which is changed by the TV/Radio source.

channel of type TVChannel, readonly, nullable

MUST return the TV/Radio channel that is scanned by the TV/Radio source. MUST return null if the state is not "scanned".

Attributes

channel of type TVChannel, readonly, nullable

MUST return the TV/Radio channel that is currently streamed by the TV/Radio tuner. MUST return null if the TV/Radio tuner is not streaming any data.

Attributes

id of type DOMString, readonly

MUST return the ID of the updated TV/Radio recording.

isTimeChange of type boolean, readonly

MUST indicate whether the recording time frame of the TV/Radio recording has changed.

isStateChange of type boolean, readonly

MUST indicate whether the state of the TV/Radio recording has changed.

errorName of type DOMString, readonly, nullable

MUST return the name of the DOMException, i.e. "AbortError", if this change involves with an error.

Attributes

state of type TVCICardState, readonly

MUST return the updated state of the card.

casSystemId of type DOMString, readonly

MUST return the CAS (Conditional Access System) system ID of the card.