Work on the TV Control API specification has moved to the TV Control Working Group in May 2016. This draft specification is kept for archival and no longer maintained. See the latest editor's draft of the Working Group for an up-to-date version of this specification.
The W3C TV control API is based on the technical requirements developed by W3C TV Control API CG.

Changes to this document may be tracked at https://github.com/w3c/tvapi.

Introduction

Note: To be constructed.

This specification may not only focus on video channels but also include pure audio ones.

Terminology

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

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

The concepts queue a task and fire an event are defined in [[!HTML5]].

The terms event handler and event handler event types are defined in [[!HTML5]].

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 is defined in [[!MediaCapture-Streams]].

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

The video element, and HTMLMediaElement, TimeRanges interfaces are defined in [[!HTML5]].

The TextTrack, TextTrackCue, and TrackEvent interfaces are defined in [[!HTML5]]

Navigator Interface

[SameObject] readonly attribute TVManager tv
MUST return the object that exposes the interface to the TV service.

TVManager Interface

The TVManager interface represents a bunch of properties and a set of operations that can be used to manage the TV device.

Promise<sequence<TVTuner>> getTuners ()
This method makes a request to retrieve all the TV tuners that are available in the TV device. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of TVTuner elements.
Promise<TVRecording> 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 recording should be created and the scheduler should ensure multiple TV 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.
TVAddRecordingOptions option
Specifies the options for adding recording.
Promise<void> 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.
DOMString id
Specifies the ID of the recording to be removed.
Promise<sequence<TVRecording>> getRecordings ()
This method makes a request to retrieve the available TV 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.
optional TVGetRecordingsOptions options
Specifies the options for getting recordings.
Promise<void> setParentalControlPin ()
This method makes a request to set the TV 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.
DOMString oldPin
Specifies the old PIN used for parental control.
DOMString newPin
Specifies the new PIN used for parental control.
Promise<void> setParentalControl ()
This method makes a request to set the TV 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.
DOMString pin
Specifies the PIN used for parental control.
boolean isLocked
Specifies the parental control status.
Promise<sequence<TVCICard>> 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.
readonly attribute unsigned long long totalRecordingSize
MUST return the total recording size of the TV device.
readonly attribute unsigned long long availableRecordingSize
MUST return the current available recording size of the TV device.
readonly attribute boolean isParentalControlled
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.
attribute EventHandler ontunerchanged
Handles the tunerchanged event of type TVTunerChangedEvent, fired when the TV device detects a TV tuner is added/removed.
attribute EventHandler onrecordingchanged
Handles the recordingchanged event of type TVRecordingChangedEvent, fired when the recording time frame or the state of the TV recording has been changed.
attribute EventHandler onparentalcontrolchanged
Handles the parentalcontrolchanged event, fired when the parental control status is changed.
attribute EventHandler oncicardchanged
Handles the cicardchanged event, fired when the CI (Common Interface) card status is changed.

Procedures

The getTuners 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 TV tuners 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 tuners be the array of the retrieved TVTuner elements.
    2. Invoke resolver's fulfill algorithm with tuners as the value argument.

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

Event handler Event name Event type Short description
ontunerchanged tunerchanged TVTunerChangedEvent Handles the information of the TV tuner that is added/removed by the TV device.
onrecordingchanged recordingchanged TVRecordingChangedEvent Handles the information of the updates for TV recordings.
onparentalcontrolchanged parentalcontrolchanged Event Handles the information of the status changes for parental control.
oncicardchanged cicardchanged TVCICardChangedEvent Handles the information of the status changes of the TV CI (Common Interface) card in the TV device.

TVTuner Interface

The TVTuner interface represents a bunch of properties and a set of operations related to the TV tuner.

sequence<TVSourceType> getSupportedSourceTypes ()
This method makes a request to retrieve all the types of the supported TV sources for the TV tuner. It returns the types of the supported TV sources.
Promise<sequence<TVSource>> getSources ()
This method makes a request to retrieve all the TV sources that are available in the TV tuner. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of TVSource elements that belong to the TV tuner.
Promise<void> setCurrentSource ()
This method makes a request to configure the current TV source of the TV tuner by the sourceType parameter. It returns a new Promise that will be used to notify the caller about the result of the operation.
TVSourceType sourceType
Specifies the TV source type for configuring the current TV source.
readonly attribute DOMString id
MUST return the ID of the TV tuner.
readonly attribute TVSource? currentSource
MUST return the currently configured TV source.
MUST return null if the TV source is not configured.
[SameObject] readonly attribute TVMediaStream? stream
MUST return a TVMediaStream object extended from MediaStream and currently streamed by the TV tuner, 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 TV tuner is not streaming any data, which happens when the streaming signal is broken or due to any reason that makes the TV tuner fail to do so.
Note that the stream instance should be the same even after the current TV source or its selected TV channel has been changed.
readonly attribute double signalStrength
MUST return the signal strength measured in dBm of the TV tuner. E.g. -31.5.
readonly attribute boolean isRecordable
MUST indicate whether recording on the stream through this TV tuner is supported by the user agent.
attribute EventHandler oncurrentsourcechanged
Handles the currentsourcechanged event of type TVCurrentSourceChangedEvent, fired when the method setCurrentSource is invoked to configure the current TV source.

Procedures

The getSources 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 tuner to retrieve all the TV sources that are available in the TV tuner.
  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 sources be the array of the retrieved TVSource elements.
    2. Invoke resolver's fulfill algorithm with sources as the value argument.

The setCurrentSource 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 tuner to configure the current TV source according to the sourceType 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.

Event handlers

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

Event handler Event name Event type Short description
oncurrentsourcechanged currentsourcechanged TVCurrentSourceChangedEvent Handles the information of the current TV source that is configured by the method setCurrentSource.

TVSource Interface

The TVSource interface represents a bunch of properties and a set of operations related to the TV source.

Promise<sequence<TVChannel>> getChannels ()
This method makes a request to retrieve all the TV channels that are available in the TV 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 TV 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.
Promise<void> setCurrentChannel ()
This method makes a request to tune the currently streamed TV channel by the channelNumber 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.
DOMString channelNumber
Specifies the TV channel number for tuning the currently streamed TV channel.
Promise<void> startScanning ()
This method makes a request to start scanning all the TV channels that are available in the TV 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 TV source. Besides, due to some constraints of tuner modules, scanning and streaming are not encouraged to run at the same time.
optional TVStartScanningOptions options
Specifies the options for scanning the TV channels. The isRescanned option in the options parameter specifies whether or not the process of scanning the TV channels has to clear the currently scanned TV channels before scanning; if it is not passed, this method will rescan all the TV channels as if it is passed as true.
Promise<void> stopScanning ()
This method makes a request to stop scanning the TV channels for the TV source. It returns a new Promise that will be used to notify the caller about the result of the operation.
readonly attribute TVTuner tuner
MUST return the TV tuner which the TV source belongs to.
readonly attribute TVSourceType type
MUST return the type of the TV source.
readonly attribute boolean isScanning
MUST indicate whether the TV source is scanning the TV channels or not.
readonly attribute TVChannel? currentChannel
MUST return the TV channel that is currently streamed by the TV tuner which owns the TV source. MUST return null if the TV tuner is not streaming any data.
attribute EventHandler oncurrentchannelchanged
Handles the currentchannelchanged event of type TVCurrentChannelChangedEvent, fired when the method setCurrentChannel is invoked to tune the currently streamed TV channel.
attribute EventHandler oneitbroadcasted
Handles the eitbroadcasted event of type TVEITBroadcastedEvent, fired when the Event Information Table (EIT) is broadcasted by the TV source.
attribute EventHandler onemergencyalerted
Handles the emergencyalerted event of type TVEmergencyAlertedEvent, fired when an emergency, such as earthquake or tsunami, occurs and is broadcasted by the TV source.
attribute EventHandler onscanningstatechanged
Handles the scanningstatechanged event of type TVScanningStateChangedEvent, fired when the state of scanning the TV channels is changed by the TV source. E.g., it can be fired when the method startScanning or the method stopScanning starts or stops scanning the TV channels, or when a channel is found during the channel scan.

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 TV source to retrieve all the TV channels that are available in the TV 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 setCurrentChannel 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 source to tune the currently streamed TV channel according to the channelNumber 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 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 TV source to start scanning all the TV channels that are available in the TV 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 channels before scanning; if it is passed as false, the user agent will simply scan additional TV 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 TV source to stop scanning the TV 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.

Event handler Event name Event type Short description
oncurrentchannelchanged currentchannelchanged TVCurrentChannelChangedEvent Handles the information of the currently streamed TV channel that is tuned by the method setCurrentChannel.
oneitbroadcasted eitbroadcasted TVEITBroadcastedEvent Handles the information of the available TV programs in the EIT that is broadcasted by the TV source.
onemergencyalerted emergencyalerted TVEmergencyAlertedEvent Handles the information of the emergency alert when an emergency, such as earthquake or tsunami, occurs and is broadcasted by the TV source.
onscanningstatechanged scanningstatechanged TVScanningStateChangedEvent Handles the information of the state of scanning the TV channels, which is changed by the TV source.

TVChannel Interface

The TVChannel interface represents a bunch of properties and a set of operations related to the TV channel.

Promise<sequence<TVProgram>> getPrograms ()
This method makes a request to retrieve all the TV programs that are available in the TV 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 channel.
optional TVGetProgramsOptions options
Specifies the options for retrieving the TV programs. If this parameter is not passed, this method will return all the available TV programs.
Promise<TVProgram> getCurrentProgram ()
This method makes a request to retrieve the current TV program available in the TV 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 TV channel.
Promise<void> setParentalLock ()
This method makes a request to set the parental lock status for the TV channel. It returns a new Promise that will be used to notify the caller about the result of the operation.
DOMString pin
Specifies the PIN used for parental control.
boolean isLocked
Specifies the parental lock status for the TV channel.
readonly attribute DOMString networkId
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.
readonly attribute DOMString transportStreamId
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.
readonly attribute DOMString serviceId
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.
readonly attribute TVSource source
MUST return the TV source which the TV channel belongs to.
readonly attribute TVChannelType type
MUST return the type of the TV channel.
readonly attribute DOMString name
MUST return the name of the TV channel. E.g., "CNN", "NHK", etc.
readonly attribute DOMString number
MUST return the Logical Channel Number (LCN) of the TV channel. E.g., "12-1", "12-2", etc.
readonly attribute boolean isEmergency
MUST indicate whether the TV channel is for the emergency purpose.
readonly attribute boolean isFree
MUST indicate whether the TV channel is free to watch.
readonly attribute DOMString? casSystemId
MUST return the system ID if it requires to use a specific CAS (Conditional Access System) to decrypt the stream from the encrypted TV channel.
readonly attribute boolean isParentalLocked
MUST indicate whether the TV channel is locked for parental control.
attribute EventHandler onparentallockchanged
Handles the parentallockchanged event, fired when the parental lock status of the TV channel is changed.

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 TV channel to retrieve all the TV programs that are available in the TV 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 TV channel to retrieve the current TV program available in the TV 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.

Event handler Event name Event type Short description
onparentallockchanged parentallockchanged Event Handles the information of the parental control status change for the TV channel.

TVProgram Interface

The TVProgram interface represents a bunch of properties and a set of operations related to the TV program.

sequence<DOMString> getAudioLanguages ()
MUST return the audio languages of the TV program in 3-digit language codes specified by [[!ISO639-2]].
sequence<DOMString> getSubtitleLanguages ()
MUST return the subtitle languages of the TV program in 3-digit language codes specified by [[!ISO639-2]].
sequence<DOMString> getGenres ()
MUST return the genres of the TV program. Please note that the classification might vary between different broadcasting standards.
readonly attribute DOMString eventId
MUST return the event ID of the TV program. It has to be unique only within a TV channel.
readonly attribute TVChannel channel
MUST return the TV channel which the TV program belongs to.
readonly attribute DOMString title
MUST return the title of the TV program.
readonly attribute unsigned long long startTime
MUST return the start time (in milliseconds) of the TV program.
readonly attribute unsigned long long duration
MUST return the duration (in milliseconds) of the TV program.
readonly attribute DOMString? shortDescription
MUST return the short description of the TV program.
readonly attribute DOMString? longDescription
MUST return the long description of the TV program.
readonly attribute DOMString? rating
MUST return the rating of the TV program.
readonly attribute boolean isFree
MUST indicate whether the TV program is free to watch.
readonly attribute DOMString? seriesId
MUST return the ID of the series (if applicable) which the TV program belongs to.

TVTriggerCue Interface

The TVTriggerCue interface represents a bunch of properties and a set of operations related to the TV 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 element by adding the TextTrackCue to the TextTrack associated with the HTMLMediaElement. Besides, the TextTrack can rely on its oncuechange event to realize a TV trigger becomes active or dismissed.

readonly attribute TVTriggerType type
MUST return the type of the TV trigger.
readonly attribute DOMString? title
MUST return the human readable title for the TV trigger.
readonly attribute DOMString? url
MUST return the URL for the TV trigger.
readonly attribute TVChannel? channel
MUST return the channel associated with the TV trigger.
readonly attribute TVMediaStream? stream
MUST return the TVMediaStream object that could be played for the TV trigger.
readonly attribute object? additionalData
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.

TVRecording Interface

The TVRecording interface represents a bunch of properties and a set of operations related to the TV 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.

Promise<TVMediaStream> 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 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.
Promise<void> stop ()
This method makes a request to stop the TV recording.
readonly attribute DOMString id
MUST return the ID of the TV recording.
readonly attribute TVChannel channel
MUST return the associated TV channel of the TV recording.
readonly attribute TVProgram? program
MUST return the associated TV program of the TV recording if applicable. Please note the recording should keep track of the relevant updates in Event Information Table (EIT) while program is specified, and then update correspondent attributes and fire a TVRecordingChangedEvent 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.
readonly attribute unsigned long long startTime
MUST return the start time (in milliseconds) of the TV recording.
readonly attribute unsigned long long endTime
MUST return the end time (in milliseconds) of the TV recording.
readonly attribute TVRecordingState state
MUST return the current state of the TV recording.
readonly attribute unsigned long long size
MUST return the actual size of the TV recording. Please note the value should be zero if the TV recording hasn't actually recorded anything.
readonly attribute unsigned long long duration
MUST return the actual duration (in milliseconds) of the TV recording. Please note the value should be zero if the TV recording hasn't actually recorded anything.
attribute DOMString description
MUST return the description of the TV recording.
attribute EventHandler onrecordingchanged
Handles the recordingchanged event of type TVRecordingChangedEvent, fired when the recording time frame or the state of the TV recording has been changed.

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 TV source to retrieve the recorded content that is available in the TV 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 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.

Event handler Event name Event type Short description
onrecordingchanged recordingchanged TVRecordingChangedEvent Handles the information of the updates for TV recordings.

TVMediaStream Interface

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

sequence<TextTrack> getTextTracks ()
MUST return the text tracks in this stream.
void addTextTrack ()
TextTrack textTrack
The TextTrack object to be added.
void removeTextTrack ()
TextTrack textTrack
The TextTrack object to be removed.

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.

Time-shifting

Applications may utilize TVRecording and TVMediaStream to fulfill time-shifting scenarios. When time-shifting is enabled, it may add a TV 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 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 recording can be assigned to the video element used for playing the current MediaStream. So the application may play with the video 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 element. Please note applications may need to regularly clean up old TV recordings used for time-shifting.

TVCICard Interface

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

readonly attribute TVCICardState state
MUST return the state of the CI card.
readonly attribute DOMString casSystemId
MUST return the CAS (Conditional Access System) system ID for the pertaining CI card.
readonly attribute boolean isInUse
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.

TVStartScanningOptions Dictionary

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

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

TVGetProgramsOptions Dictionary

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

unsigned long long startTime
Specifies the start time of a time period which bounds the time slots of TV programs to be retrieved.
unsigned long long endTime
Specifies the end time of a time period which bounds the time slots of TV programs to be retrieved.
DOMString genre
Specifies the genre of TV programs to be retrieved.

TVAddRecordingOptions Dictionary

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

required DOMString description
Specifies the description of the TV recording.
required TVChannel channel
Specifies the channel to be recorded.
TVProgram? program
Specifies the program to be recorded. Please note this could be omitted if the recording time frame can be determined by startTime and endTime.
unsigned long long? startTime
Specifies the start time of a recording time frame. When not specified, it implies the recording should start from now on. Please note this could also be ommited and auto determined if program is specified.
unsigned long long? endTime
Specifies the end time of a recording time frame. 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 ommited and auto determined if program is specified.

TVGetRecordingsOptions Dictionary

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

TVRecordingState? state
Specifies the state of the TV recordings to be retrieved.
DOMString? id
Specifies the ID of the TV recording to be retrieved.

TVTunerChangedEvent Interface

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

readonly attribute TVTunerChangedEventOperation operation
MUST return the type of operation that changes the TV tuner.
readonly attribute DOMString id
MUST return the ID of the TV tuner that is added/removed.

TVCurrentSourceChangedEvent Interface

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

readonly attribute TVSource? source
MUST return the TV source that is currently configured by the TV tuner. MUST return null if the TV source is not configured.

TVEITBroadcastedEvent Interface

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

readonly attribute object programs
MUST return the available TV programs in the EIT that is broadcasted 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.

TVEmergencyAlertedEvent Interface

The TVEmergencyAlertedEvent interface represents the event related to the emergency alert that is broadcasted by the TV source.

readonly attribute DOMString? type
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.
readonly attribute DOMString? severityLevel
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.
readonly attribute DOMString? description
MUST return the human readable description of the emergency alert.
readonly attribute TVChannel? channel
MUST return the emergency channel which might be switched to for more information about the emergency.
readonly attribute DOMString? url
MUST return the URL where more information might be available.
sequence<DOMString> 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.

TVScanningStateChangedEvent Interface

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

readonly attribute TVScanningState state
MUST return the state of channel scanning, which is changed by the TV source.
readonly attribute TVChannel? channel
MUST return the TV channel that is scanned by the TV source. MUST return null if the state is not "scanned".

TVCurrentChannelChangedEvent Interface

The TVCurrentChannelChangedEvent interface represents the event related to the currently streamed TV channel that is tuned by the method setCurrentChannel.

readonly attribute TVChannel? channel
MUST return the TV channel that is currently streamed by the TV tuner. MUST return null if the TV tuner is not streaming any data.

TVRecordingChangedEvent Interface

The TVRecordingChangedEvent interface represents the event related to the update of a TV recording.

readonly attribute DOMString id
MUST return the ID of the updated TV recording.
readonly attribute boolean isTimeChange
MUST indicate whether the recording time frame of the TV recording has changed.
readonly attribute boolean isStateChange
MUST indicate whether the state of the TV recording has changed.
readonly attribute DOMString? errorName
MUST return the name of the DOMException, i.e. "AbortError", if this change involves with an error.

TVCICardChangedEvent Interface

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

readonly attribute TVCICardState state
MUST return the updated state of the card.
readonly attribute DOMString casSystemId
MUST return the CAS (Conditional Access System) system ID of the card.

Enumerations

The attribute type in the TVSource can have the following values:

dvb-t
The TV source works for DVB-T (terrestrial).
dvb-t2
The TV source works for DVB-T2 (terrestrial).
dvb-c
The TV source works for DVB-C (cable).
dvb-c2
The TV source works for DVB-C2 (cable).
dvb-s
The TV source works for DVB-S (satellite).
dvb-s2
The TV source works for DVB-S2 (satellite).
dvb-h
The TV source works for DVB-H (handheld).
dvb-sh
The TV source works for DVB-SH (satellite).
atsc
The TV source works for ATSC (terrestrial/cable).
atsc-m/h
The TV source works for ATSC-M/H (mobile/handheld).
isdb-t
The TV source works for ISDB-T (terrestrial).
isdb-tb
The TV source works for ISDB-Tb (terrestrial, Brazil).
isdb-s
The TV source works for ISDB-S (satellite).
isdb-c
The TV source works for ISDB-C (cable).
1seg
The TV source works for 1seg (handheld).
dtmb
The TV source works for DTMB (terrestrial).
cmmb
The TV source works for CMMB (handheld).
t-dmb
The TV source works for T-DMB (terrestrial).
s-dmb
The TV source works for S-DMB (satellite).

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

tv
The TV channel is broadcasted as a regular TV type.
radio
The TV channel is broadcasted as a radio type.
data
The TV channel is broadcasted as a data type.

The attribute operation in the TVTunerChangedEvent can have the following values:

added
A TV tuner is added.
removed
A TV tuner is removed.

The attribute state in the TVScanningStateChangedEvent can have the following values:

cleared
The currently scanned TV channels have been cleared. This event may be fired before a channel scan is started.
scanned
A TV channel has been found by the TV source during the channel scan. The channel attribute in the TVScanningStateChangedEvent object references the channel found.
completed
The channel scan has completed.
stopped
The channel scan has been stopped.

The attribute type in the TVTriggerCue can have the following values:

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 can have the following values:

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 the following values:

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.

Acknowledgements

The following people have contributed to this draft specification through their participation in the TV Control API Community Group: Kazayuki Ashimura, Marco Chen, Daniel Davis, Francois Daoust, Yoshiharu Dewa, Paul Higgs, Bin Hu, Shelly Lin, Sangwhan Moon, Chris Needham, John Piesing.

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.