Abstract

This specification defines an API for sourcing audio and video media, such as TV and radio from broadcast, IPTV, or other sources, with associated channel and program metadata, and allows presentation of the media using the <video> and <audio> HTML elements. The API is agnostic of any underlying audio or video sourcing technologies.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Warning

Work on this document has been discontinued and it should not be considered as stable, referenced or used as a basis for implementation.

The API did not significantly change since publication as Working Draft on 16 March 2017.

Further discussions on scope, use cases and requirements are needed for this work to succeed on the Recommendation track. At the time of publication, these discussions are being held in the Web and TV Interest Group. The TV Control Working Group invites interested parties to join and contribute to that group. Technical work on this document has been discontinued in the meantime and the TV Control Working Group has been closed as a result.

This document was published by the TV Control Working Group as a Working Group Note. Comments regarding this document are welcome. Please send them to public-tvcontrol@w3.org (subscribe, archives).

Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Introduction

This section is non-normative.

This specification defines the TV Control API, which aims to enable web applications to present audio and video media from broadcast TV and radio, IPTV, or other sources, using the <audio> and <video> HTML elements. The API provides access to programme and service information and allows media recordings to be scheduled and replayed.

TV functionality is accessed through the TVManager object which, via the TVSource object allows applications to select and present a TV or Radio channel. Presentation is achieved by obtaining a TVMediaStream object from the TVSource and assigning this to the srcObject attribute of an HTMLMediaElement . The TVMediaStream interface extends MediaStream to allow buffering of the received media, to enable pause/resume and timeshifted playback.

Editor's note

The TVTuner class has been removed from this draft. See this issue for details.

TVManager also allows recordings to be scheduled and replayed, and application control of the parental lock, to prevent unwanted viewing of particular channels or programs.

TVSource gives access to lists of available channels and programs, and allows applications to set the current channel to be presented. TVChannel contains TV and Radio channel attributes, and program schedule information, as a collection of TVProgram objects.

2. Terminology

The following terms are defined in [HTML]:

The Event and EventTarget interfaces are defined in [DOM].

The Promise interface, the concepts of a resolver, a resolver's fulfill algorithm and a resolver's reject algorithm are defined in [ECMAScript].

The MediaStream interface and the ConstrainLong type are defined in [MediaCapture-Streams].

The MediaRecorder interface is defined in [MediaStream-Recording].

4. TVControl Interface

The TVControl interface represents the entry point in to the TV Control API for applications. 

interface TVControl {
    Promise<TVManager> getTVManager();
    Promise<TVManager> getRadioManager();
};

4.1 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>

5. TVManager Interface

The TVManager interface represents the set of operations that can be used to manage the TV/Radio device.

The location of the getChannelList() method is still under discussion: this draft includes versions of this method on both the TVManager and TVSource interfaces. It is highly likely that one of these will be removed in a future draft.

interface TVManager : EventTarget {
    TVSourceCapabilities           getCapabilities();
    TVSourceSupportedConstraints   getSupportedConstraints();
    Promise<TVSource>              getSource(TVSourceConstraints constraints);
    boolean                        isSourceAvailable(TVSourceConstraints constraints);

    Promise<sequence<TVChannel>>   getChannelList(TVSourceConstraints constraints);

    Promise<TVRecording>           addRecording(TVAddRecordingOptions option);
    Promise<void>                  removeRecording(DOMString id);
    Promise<sequence<TVRecording>> getRecordings(optional TVGetRecordingsOptions options);
    Promise<void>                  setParentalControlPin(DOMString oldPin,
                                                         DOMString newPin);
    Promise<void>                  setParentalControl(DOMString pin,
                                                      boolean isLocked);
    Promise<sequence<TVCICard>>    getCICards();
    readonly attribute unsigned long long totalRecordingSize;
    readonly attribute unsigned long long availableRecordingSize;
    readonly attribute boolean            isParentalControlled;
             attribute EventHandler       ontunerchange;
             attribute EventHandler       onrecordingchange;
             attribute EventHandler       onparentalcontrolchange;
             attribute EventHandler       oncicardchange;
};

5.1 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.

5.2 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>>

5.3 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.

5.4 Event handlers

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

Event handler Event name Event type Short description
ontunerchange tunerchange TVTunerChangeEvent Handles the information of the TV/Radio tuner that is added/removed by the device.
onrecordingchange recordingchange TVRecordingChangeEvent Handles the information of the updates for TV/Radio recordings.
onparentalcontrolchange parentalcontrolchange Event Handles the information of the status changes for parental control.
oncicardchange cicardchange TVCICardChangeEvent Handles the information of the status changes of the TV CI (Common Interface) card in the TV device.

6. TVSource Interface

The TVSource interface represents a logical source of TV/Radio channels. This may represent a physical tuner or a "virtual" tuner for channels delivered via IP. The TVSource exposes the list of TVChannel objects available through that source. For devices with more than one type of tuner (e.g. cable and terrestrial), each tuner type may be represented by a different TVSource. 

interface TVSource : EventTarget {
    TVSourceConstraints          getConstraints();
    TVSourceSettings             getSettings();

    Promise<sequence<TVChannel>> getChannels();
    Promise<TVMediaStream>       tuneToChannel(TVChannel channel);
    Promise<TVMediaStream>       tuneTo(DOMString tuningParams);

    Promise<void>                startScanning(optional TVStartScanningOptions options);
    Promise<void>                stopScanning();
    readonly attribute TVSourceType   type;
    readonly attribute TVMediaStream? stream;
    readonly attribute boolean        isScanning;
    readonly attribute TVChannel?     currentChannel;
             attribute EventHandler   oncurrentchannelchange;
             attribute EventHandler   oneitbroadcast;
             attribute EventHandler   onemergencyalert;
             attribute EventHandler   onscanningstatechange;
};

6.1 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.

6.2 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>

6.3 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.

6.4 Event handlers

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

Event handler Event name Event type Short description
oncurrentchannelchange currentchannelchange TVCurrentChannelChangeEvent Handles the information of the currently streamed TV/Radio channel that is tuned by the method tuneTo or tuneToChannel.
oneitbroadcast eitbroadcast TVEITBroadcastEvent Handles the information of the available TV programs in the EIT that is broadcast by the TV source.
onemergencyalert emergencyalert TVEmergencyAlertEvent Handles the information of the emergency alert when an emergency, such as earthquake or tsunami, occurs and is broadcast by the TV/Radio source.
onscanningstatechange scanningstatechange TVScanningStateChangeEvent Handles the information of the state of scanning the TV/Radio channels, which is changed by the source.

6.5 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;

};

6.5.1 Dictionary TVSourceSupportedConstraints Members

deliverySystem of type boolean defaulting to true
Indicates whether the deliverySystem constraint is supported.
height of type boolean defaulting to true
Indicates whether the height constraint is supported.
channel of type boolean defaulting to true
Indicates whether the channel constraint is supported.
tuningStep of type boolean defaulting to true
Indicates whether the tuningStep constraint is supported.

6.6 TVSourceCapabilities Dictionary

TVSourceCapabilities represents the capabilities of a TVSource object 

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

6.6.1 Dictionary TVSourceCapabilities Members

deliverySystem of type sequence <TVSourceType>
See deliverySystem for details. If the device supports multiple delivery systems then the capabilities will consist of a sequence of entries. The order of entries in the sequence is implementation-dependent.
height of type long
See height for details.
tuningStep of type long
See tuningStep for details.

6.7 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;

};

6.7.1 Dictionary TVSourceConstraints Members

deliverySystem of type sequence <TVSourceType>
See deliverySystem for details.
height of type ConstrainLong
See height for details.
channel of type TVChannel
See channel for details.
tuningStep of type ConstrainLong
See tuningStep for details.

6.8 TVSourceSettings Dictionary

TVSourceSettings represents the Settings of a TVSource object. 

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

};

6.8.1 Dictionary TVSourceSettings Members

deliverySystem of type sequence <TVSourceType>
See deliverySystem for details.
height of type long
See height for details.
channel of type TVChannel
See channel for details.
tuningStep of type long
See tuningStep for details.

6.9 Constrainable Properties

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

Property Name Values Notes
deliverySystem sequence <TVSourceType> The delivery system or systems that must be supported.
height ConstrainLong The height or height range, in pixels. As a capability, the range should span the video source's pre-set height values with min being the smallest height and max being the largest height.
channel TVChannel A channel that must be able to be received and decoded by the source.

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"
};
Enumeration description
dvb-t The source works for DVB-T (terrestrial).
dvb-t2 The source works for DVB-T2 (terrestrial).
dvb-c The source works for DVB-C (cable).
dvb-c2 The source works for DVB-C2 (cable).
dvb-s The source works for DVB-S (satellite).
dvb-s2 The source works for DVB-S2 (satellite).
dvb-h The source works for DVB-H (handheld).
dvb-sh The source works for DVB-SH (satellite).
atsc The source works for ATSC (terrestrial/cable).
atsc-m/h The source works for ATSC-M/H (mobile/handheld).
isdb-t The source works for ISDB-T (terrestrial).
isdb-tb The source works for ISDB-Tb (terrestrial, Brazil).
isdb-s The source works for ISDB-S (satellite).
isdb-c The source works for ISDB-C (cable).
1seg The source works for 1seg (handheld).
dtmb The source works for DTMB (terrestrial).
cmmb The source works for CMMB (handheld).
t-dmb The source works for T-DMB (terrestrial).
s-dmb The source works for S-DMB (satellite).
dab The source works for DAB (terrestrial).
drm The source works for DRM (terrestrial).
fm The source works for FM (terrestrial).
AM The source works for AM (terrestrial).

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

Property Name Values Notes
tuningStep ConstrainLong The exact tuning step size (in KHz) supported by the tuner.

7. TVChannel Interface

The TVChannel interface represents a single TV or radio channel and provides metadata about it. Each TVChannel object represents a single channel that is available through one TVSource, for instance a DVB Service or ATSC Virtual Channel. If the same channel is available through two different sources (e.g. over cable and terrestrial) then each TVSource will return a different TVChannel object. 

interface TVChannel : EventTarget {
    Promise<sequence<TVProgram>>     getPrograms(optional TVGetProgramsOptions options);
    Promise<TVProgram>               getCurrentProgram();
    Promise<sequence<TVApplication>> getApplications();
    Promise<void>                    setParentalLock(DOMString pin,
                                                     boolean isLocked);
    readonly attribute TVSource            source;
    readonly attribute TVChannelType       type;
    readonly attribute TVChannelAttributes attributes;
    readonly attribute DOMString           name;
    readonly attribute DOMString           number;
    readonly attribute boolean             isEmergency;
    readonly attribute boolean             isEncrypted;
    readonly attribute DOMString?          casSystemId;
    readonly attribute boolean             isParentalLocked;
             attribute EventHandler        onparentallockchange;
};

7.1 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.

7.2 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>

7.3 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.

7.4 Event handlers

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

Event handler Event name Event type Short description
onparentallockchange parentallockchange Event Handles the information of the parental control status change for the TV/Radio channel.
Editor's note

In general the current API design is agnostic towards the supported underlying transmission and systems technology. Just the TVSourceType enumeration refers to specific technology. However IMHO there must be a mechanism when it comes to returning technology specific data. The idea here is to introduce a general TVChannelAttributes structure which acts as a base interface, from which technology-dependent sub interfaces (in this proposal for DVB and DAB) are derived.

8. TVChannelAttributes Interface

The TVChannelAttributes interface represents a bunch of properties and a set of operations related to technology related functions of different TV/Radio transmission and system specifications. The TVChannelAttributes interface is the parent interface for a hierarchy of technology specific subinterfaces determined by TVSource and its TVSourceType properties. 

interface TVChannelAttributes : EventTarget {
    attribute EventHandler onattributeschange;
};

8.1 Attributes

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

9. TVDVBChannelAttributes Interface

The TVDVBChannelAttributes interface represents DVB channel attributes 

interface TVDVBChannelAttributes : TVChannelAttributes {
    readonly attribute DOMString originalNetworkId;
    readonly attribute DOMString networkId;
    readonly attribute DOMString transportStreamId;
    readonly attribute DOMString serviceId;
};

9.1 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.

10. TVDABChannelAttributes Interface

The TVDABChannelAttributes interface represents DVB channel attributes 

interface TVDABChannelAttributes : TVChannelAttributes {
    readonly attribute DOMString ensembleId;
    readonly attribute DOMString serviceId;
};

10.1 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.
Editor's note

Should we introduce more specific application type interfaces here. e.g. for the DAB/DVB User applications (Slideshow, DL, Journaline, HbbTV, MHEG)? Or are we happy with just delivering the applicationData to the developers.

11. TVApplication Interface

The TVApplication interface represents a bunch of properties and a set of operations related to technology related functions of different TV/Radio applications. The TVApplication interface can be the parent interface for a hierarchy of technology specific subinterfaces TVApplicationType 

interface TVApplication : EventTarget {
    readonly attribute TVApplicationType type;
    readonly attribute object?           applicationData;
             attribute EventHandler      onapplicationchange;
};

11.1 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.

12. TVProgram Interface

The TVProgram interface represents a set of properties and operations related to a TV/Radio program (e.g. a DVB or ATSC Event). An instance of a TVProgram corresponds to one showing of that program: if the same program is shown at two different times or on different channels then each showing is represented by a different TVProgram instance. 

interface TVProgram {
    sequence<DOMString> getAudioLanguages();
    sequence<DOMString> getSubtitleLanguages();
    sequence<DOMString> getGenres();
    readonly attribute DOMString    eventId;
    readonly attribute TVChannel    channel;
    readonly attribute DOMString    title;
    readonly attribute DOMTimeStamp startTime;
    readonly attribute DOMTimeStamp duration;
    readonly attribute DOMString?   shortDescription;
    readonly attribute DOMString?   longDescription;
    readonly attribute DOMString?   parentalRating;
    readonly attribute boolean      isEncrypted;
    readonly attribute DOMString?   seriesId;
};

12.1 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.

12.2 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>

13. TVTriggerCue Interface

The TVTriggerCue interface represents a bunch of properties and a set of operations related to the TV/Radio trigger, which may be used to carry some information via in-band or out-of-band mechanism based on the current playing content. It's inherited from the TextTrackCue interface, which requires startTime and endTime, and can be accessed by the video or audio element by adding the TextTrackCue to the TextTrack associated with the HTMLMediaElement . Besides, the TextTrack can rely on its cuechange event to realize a TV/Radio trigger becomes active or dismissed. 

interface TVTriggerCue : TextTrackCue {
    readonly attribute TVTriggerType  type;
    readonly attribute DOMString?     title;
    readonly attribute DOMString?     url;
    readonly attribute TVChannel?     channel;
    readonly attribute TVMediaStream? stream;
    readonly attribute object?        additionalData;
};

13.1 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.

14. TVRecording Interface

The TVRecording interface represents a bunch of properties and a set of operations related to the TV/Radio recording. The recording should automatically start recording at the specified start time. And it may stop either at the specified end time, by an explicit stop() call, or be interrupted by the user agent due to a channel switch against the required underlying resource (i.e. the same tuner which the recording channel belongs to since watching takes priority over recording), or an error. 

interface TVRecording {
    Promise<TVMediaStream> getStream();
    Promise<void>          stop();
    readonly attribute DOMString          id;
    readonly attribute TVChannel          channel;
    readonly attribute TVProgram?         program;

    readonly attribute DOMTimeStamp       startTime;
    readonly attribute DOMTimeStamp       endTime;
    readonly attribute TVRecordingState   state;
    readonly attribute unsigned long long size;
    readonly attribute DOMTimeStamp       duration;
             attribute DOMString          description;
             attribute EventHandler       onrecordingchange;
};

14.1 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.

14.2 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>

14.3 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.

14.4 Event handlers

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

Event handler Event name Event type Short description
onrecordingchange recordingchange TVRecordingChangeEvent Handles the information of the updates for TV/Radio recordings.

15. TVMediaStream Interface

The TVMediaStream interface is an extended MediaStream with a buffering mechanism to support basic seekability. It can be played by the video or audio element by assigning the TVMediaStream to the HTMLMediaElement 's srcObject attribute.

A TVMediaStream represents the stream data for all components within a channel being presented. It is obtained from a TVSource, and when a TVMediaStream object is created it means that all of the resources needed to receive and present that channel have been successfully allocated. 

interface TVMediaStream : MediaStream {
    sequence<TextTrack> getTextTracks();
    void                addTextTrack(TextTrack textTrack);
    void                removeTextTrack(TextTrack textTrack);
};

15.1 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

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

Attribute Name Attribute Type Valid Values When Using a TVMediaStream Additional considerations
currentSrc DOMString The empty string When srcObject is specified the User Agent MUST set this to the empty string. (Same as MediaStream .)
preload DOMString none A TVMediaStream cannot be preloaded. (Same as MediaStream .)
buffered TimeRanges Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
networkState unsigned short NETWORK_IDLE The media element does not fetch the TVMediaStream so there is no network traffic. (Same as MediaStream .)
readyState unsigned short HAVE_NOTHING, HAVE_ENOUGH_DATA A TVMediaStream may be created before there is any data available, for example when a stream is received from a remote peer. The value of the readyState of the media element MUST be HAVE_NOTHING before the first media arrives and HAVE_ENOUGH_DATA once the first media has arrived. (Same as MediaStream .)
currentTime double Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
duration unrestricted double Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
seeking boolean Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
defaultPlaybackRate double Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
playbackRate double Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
played TimeRanges Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
seekable TimeRanges Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .
loop boolean Same as HTMLMediaElement . Unlock the restriction applied by MediaStream .

15.3 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.

16. TVCICard Interface

The TVCICard interface represents a bunch of properties related to CI (Common Interface) card which is used to decrypt encrypted TV channel. 

interface TVCICard {
    readonly attribute TVCICardState state;
    readonly attribute DOMString     casSystemId;
    readonly attribute boolean       isInUse;
};

16.1 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.

17. TVStartScanningOptions Dictionary

The TVStartScanningOptions dictionary contains the information for scanning the TV/Radio channels. 

dictionary TVStartScanningOptions {
    boolean isRescanned;
};

17.1 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.

18. TVGetProgramsOptions Dictionary

The TVGetProgramsOptions dictionary contains the information for retrieving the TV/Radio programs. 

dictionary TVGetProgramsOptions {

    DOMTimeStamp startTime;
    DOMTimeStamp endTime;
    DOMString    genre;
};

18.1 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.

19. TVAddRecordingOptions Dictionary

The TVAddRecordingOptions dictionary contains the information for adding a TV/Radio recording. 

dictionary TVAddRecordingOptions {
    required DOMString     description;
    required TVChannel     channel;
             TVProgram?    program;
             DOMTimeStamp? startTime;
             DOMTimeStamp? endTime;
};

19.1 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.

20. TVGetRecordingsOptions Dictionary

The TVGetRecordingsOptions dictionary contains the information for retrieving the TV/Radio recordings. 

dictionary TVGetRecordingsOptions {
    TVRecordingState? state;
    DOMString?        id;
};

20.1 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.

21. TVTunerChangeEvent Interface

The TVTunerChangeEvent interface represents the event related to the TV/Radio tuner that is added/removed by the device. 

interface TVTunerChangeEvent : Event {
    readonly attribute TVTunerChangeEventOperation operation;
    readonly attribute DOMString                   id;
};

21.1 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.

22. TVCurrentSourceChangeEvent Interface

The TVCurrentSourceChangeEvent interface represents the event related to the current TV/Radio source that is configured by the method setCurrentSource. 

interface TVCurrentSourceChangeEvent : Event {
    readonly attribute TVSource? source;
};

22.1 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.

23. TVEITBroadcastEvent Interface

The TVEITBroadcastEvent interface represents the event related to the available TV programs in the EIT that is broadcast by the TV source. 

interface TVEITBroadcastEvent : Event {
    readonly attribute object programs;
};

23.1 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.

24. TVEmergencyAlertEvent Interface

The TVEmergencyAlertEvent interface represents the event related to the emergency alert that is broadcast by the TV/Radio source. 

interface TVEmergencyAlertEvent : Event {
    readonly attribute DOMString? type;
    readonly attribute DOMString? severityLevel;
    readonly attribute DOMString? description;
    readonly attribute TVChannel? channel;
    readonly attribute DOMString? url;
    sequence<DOMString> getRegions();
};

24.1 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.

24.2 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>

25. TVScanningStateChangeEvent Interface

The TVScanningStateChangeEvent interface represents the event related to the state of channel scanning, which is changed by the TV/Radio source. 

interface TVScanningStateChangeEvent : Event {
    readonly attribute TVScanningState state;
    readonly attribute TVChannel?      channel;
};

25.1 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".

26. TVCurrentChannelChangeEvent Interface

The TVCurrentChannelChangeEvent interface represents the event related to the currently streamed TV/Radio channel that is tuned by the method tuneTo or tuneToChannel. 

interface TVCurrentChannelChangeEvent : Event {
    readonly attribute TVChannel? channel;
};

26.1 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.

27. TVRecordingChangeEvent Interface

The TVRecordingChangeEvent interface represents the event related to the update of a TV/Radio recording. 

interface TVRecordingChangeEvent : Event {
    readonly attribute DOMString  id;
    readonly attribute boolean    isTimeChange;
    readonly attribute boolean    isStateChange;
    readonly attribute DOMString? errorName;
};

27.1 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.

28. TVCICardChangeEvent Interface

The TVCICardChangeEvent interface represents the event related to the changes in the state of the CI (Common Interface) card. 

interface TVCICardChangeEvent : Event {
    readonly attribute TVCICardState state;
    readonly attribute DOMString     casSystemId;
};

28.1 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.

29. Enumerations

The attribute type in a TVChannel can have one of the following values of TVChannelType: 

enum TVChannelType {
    "tv",
    "radio",
    "data"
};
Enumeration description
tv The channel is broadcast as a regular TV type.
radio The channel is broadcast as a radio type.
data The channel is broadcast as a data type.

The attribute type in a TVApplication can have one of the following values of TVApplicationType: 

enum TVApplicationType {
    "hbbtv",
    "mheg",
    "sls",
    "dl",
    "jl"
};
Enumeration description
hbbtv The application is a tv hbbtv application
mheg The application is a tv mheg application
sls The application radio slideshow application
dl The application radio dynamic label application
jl The application radio journaline application

The attribute operation in the TVTunerChangeEvent which can have one of the following values of TVTunerChangeEventOperation: 

enum TVTunerChangeEventOperation {
    "added",
    "removed"
};
Enumeration description
added A tuner is added.
removed A tuner is removed.

The attribute state in the TVScanningStateChangeEvent can have one the following values of TVScanningState: 

enum TVScanningState {
    "cleared",
    "scanned",
    "completed",
    "stopped"
};
Enumeration description
cleared The currently scanned TV/Radio channels have been cleared. This event may be fired before a channel scan is started.
scanned A TV/Radio channel has been found by the source during the channel scan. The channel attribute in the TVScanningStateChangeEvent object references the channel found.
completed The channel scan has completed.
stopped The channel scan has been stopped.

The attribute type in TVTriggerCue can have one of the following values of TVTriggerType: 

enum TVTriggerType {
    "channel-change",
    "time",
    "content-boundary",
    "fingerprint",
    "watermark",
    "context",
    "segment",
    "caption"
};
Enumeration description
channel-change Triggers when channel is switched.
time Triggers based on date and time.
content-boundary Triggers based on content boundary.
fingerprint Triggers based on content fingerprints.
watermark Triggers based on content watermarks.
context Triggers based on contextual information in content.
segment Triggers based on program chapters or other segments within the program.
caption Triggers based on subtitle captions.

The attribute state in TVRecording if of type TVRecordingState, which can have the following values: 

enum TVRecordingState {
    "scheduled",
    "recording",
    "stopped"
};
Enumeration description
scheduled The state of recording is scheduled.
recording The state of recording is currently on.
stopped The state of recording is stopped from scheduled or canceled from recording.

The attribute state in TVCICard can have one of the following values of TVCICardState: 

enum TVCICardState {
    "inserted",
    "accepted",
    "removed",
    "error"
};
Enumeration description
inserted The CI card is inserted.
accepted The CI card is accepted.
removed The CI card is removed.
error The CI Card has encountered an error.

30. Security and Privacy Considerations

This section is non-normative.

Editor's note

This section will be completed in a future draft of the specification. See this issue for details.

31. Acknowledgements

Thanks to the following people for their contribution to this draft specification, and for providing review feedback: Kazuyuki Ashimura, David Baron, Marco Chen, Daniel Davis, Ryan Davis, Alexander Erk, Jean-Pierre Evain, Francois Daoust, Yoshiharu Dewa, Paul Higgs, Bin Hu, Travis Leithead, Shelly Lin, Sangwhan Moon, Chris Needham, Jon Piesing, Michael Probst.

32. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key word MUST is to be interpreted as described in [RFC2119].

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

A. References

A.1 Normative references

[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMAScript]
ECMAScript Language Specification. Ecma International. URL: https://tc39.github.io/ecma262/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[ISO639-2]
Codes for the representation of names of languages -- Part 2: Alpha-3 code. ISO. 22 October 1998. URL: http://www.iso.org/iso/catalogue_detail?csnumber=4767
[MediaCapture-Streams]
Media Capture and Streams. Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

A.2 Informative references

[MediaStream-Recording]
MediaStream Recording. Miguel Casas-sanchez; James Barnett; Travis Leithead. W3C. 5 April 2017. W3C Working Draft. URL: https://www.w3.org/TR/mediastream-recording/