Copyright © 2014-2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
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/.
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.
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
. The HTMLMediaElement
TVMediaStream
interface extends
to allow buffering of the received media, to enable pause/resume and timeshifted playback.
MediaStream
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.
The following terms are defined in [HTML]:
audio
elementEventHandler
Navigator
HTMLMediaElement
TimeRanges
TextTrack
TextTrackCue
video
element
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].
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
();
};
getTVManager
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.
getRadioManager
TVManager
that can be used for interacting with radio services (e.g. delivered via AM, FM or DAB) available through the device.
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
;
};
totalRecordingSize
of type unsigned long long, readonly
availableRecordingSize
of type unsigned long long, readonly
isParentalControlled
of type boolean, readonly
ontunerchange
of type EventHandler
tunerchange
event of type
TVTunerChangeEvent
, fired when the TV/Radio device detects a tuner is added/removed.
onrecordingchange
of type EventHandler
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
parentalcontrolchange
event, fired when the parental control status is changed.
oncicardchange
of type EventHandler
cicardchange
event, fired when the CI (Common Interface) card status is changed.
getCapabilities
TVSourceCapabilities
object that describes the capabilities of the device for receiving and decoding TV or radio services.
TVSourceCapabilities
getSupportedConstraints
TVSourceSupportedConstraints
object that describes the set of constraints that may be specified when requesting a TVSource object.
TVSourceSupportedConstraints
getSource
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. |
isSourceAvailable
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. |
boolean
getChannelList
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. |
addRecording
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.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. |
Promise
<TVRecording
>
removeRecording
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. |
Promise
<void>
getRecordings
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. |
Promise
<sequence<TVRecording
>>
setParentalControlPin
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. |
Promise
<void>
setParentalControl
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. |
Promise
<void>
getCICards
Promise
that will be used to notify the caller about the result of the operation, which is an array of TVCICard
elements.
The addRecording
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
options
parameter.
value
argument.
TVRecording
object.
value
argument.
The removeRecording
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
value
argument.
The getRecordings
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
options
parameter.
value
argument.
TVRecording
elements.
value
argument.
The setParentalControlPin
method when invoked
MUST run the following steps:
Promise
object and resolver be its associated
resolver.
newPin
parameter.
value
argument.
value
argument.
The setParentalControl
method when invoked
MUST run the following steps:
Promise
object and resolver be its associated
resolver.
isLocked
parameter.
value
argument.
value
argument.
The getCICards
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
TVCICard
elements.
value
argument.
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
|
|
Handles the information of the TV/Radio tuner that is added/removed by the device. |
onrecordingchange
|
recordingchange
|
|
Handles the information of the updates for TV/Radio recordings. |
onparentalcontrolchange
|
parentalcontrolchange
|
|
Handles the information of the status changes for parental control. |
oncicardchange
|
cicardchange
|
|
Handles the information of the status changes of the TV CI (Common Interface) card in the TV device. |
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
;
};
type
of type TVSourceType
, readonly
stream
of type TVMediaStream
, readonly, nullable
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
.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.isScanning
of type boolean, readonly
currentChannel
of type TVChannel
, readonly, nullable
null
if the TV/Radio tuner is not streaming any data.
oncurrentchannelchange
of type
EventHandler
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
eitbroadcast
event of type
TVEITBroadcastEvent
, fired when the Event Information Table (EIT) is broadcast by the TV source.
onemergencyalert
of type EventHandler
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
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.
getConstraints
TVSourceConstraints
getSettings
TVSourceSettings
getChannels
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.
tuneToChannel
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. |
Promise
<TVMediaStream
>
tuneTo
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. |
Promise
<TVMediaStream
>
startScanning
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 .
|
Promise
<void>
stopScanning
Promise
that will be used to notify the caller about the result of the operation.
Promise
<void>
The getChannels
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
TVChannel
elements.
value
argument.
The tuneToChannel
method when invoked
MUST run the following steps:
Promise
object and resolver be its associated
resolver.
channel
parameter.
value
argument.
value
argument.
The tuneTo
method when invoked
MUST run the following steps:
Promise
object and resolver be its associated
resolver.
tuningParams
parameter.
value
argument.
value
argument.
The startScanning
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
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.
value
argument.
value
argument.
The stopScanning
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
value
argument.
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
|
|
Handles the information of the currently streamed TV/Radio channel that is tuned by the method
tuneTo or tuneToChannel .
|
oneitbroadcast
|
eitbroadcast
|
|
Handles the information of the available TV programs in the EIT that is broadcast by the TV source. |
onemergencyalert
|
emergencyalert
|
|
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
|
|
Handles the information of the state of scanning the TV/Radio channels, which is changed by the source. |
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;
};
TVSourceSupportedConstraints
Members
deliverySystem
of type boolean defaulting to true
height
of type boolean defaulting to true
channel
of type boolean defaulting to true
tuningStep
of type boolean defaulting to true
TVSourceCapabilities
Dictionary
TVSourceCapabilities
represents the capabilities of a TVSource
object
dictionary TVSourceCapabilities
{
sequence<TVSourceType
> deliverySystem
;
long height
;
long tuningStep
;
};
TVSourceCapabilities
Members
deliverySystem
of type sequence <TVSourceType
>
height
of type long
tuningStep
of type long
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
;
};
TVSourceConstraints
Members
deliverySystem
of type sequence <TVSourceType>
height
of type ConstrainLong
channel
of type TVChannel
tuningStep
of type ConstrainLong
TVSourceSettings
Dictionary
TVSourceSettings
represents the Settings of a
TVSource
object.
dictionary TVSourceSettings
{
sequence<TVSourceType
> deliverySystem
;
ConstrainLong
height
;
TVChannel
channel
;
ConstrainLong
tuningStep
;
};
TVSourceSettings
Members
deliverySystem
of type sequence <TVSourceType>
height
of type long
channel
of type TVChannel
tuningStep
of type long
The names of the initial set of constrainable properties for TVSource are defined below.
Property Name | Values | Notes |
---|---|---|
deliverySystem | sequence <
|
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. |
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
;
};
source
of type TVSource
, readonly
type
of type TVChannelType
, readonly
attributes
of type TVChannelAttributes
, readonly
"NHK"
, etc.
name
of type DOMString, readonly
"CNN"
, "NHK"
, etc.
number
of type DOMString, readonly
"12-1"
, "12-2"
, etc.
isEmergency
of type boolean, readonly
isEncrypted
of type boolean, readonly
casSystemId
of type DOMString, readonly, nullable
isParentalLocked
of type boolean, readonly
onparentallockchange
of type EventHandler
parentallockchange
event, fired when the parental lock status of the TV/Radio channel is changed.
getPrograms
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. |
getCurrentProgram
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.
getApplications
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.
Promise
<sequence<TVApplication
>>
setParentalLock
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. |
Promise
<void>
The getPrograms
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
options
parameter.
value
argument.
TVProgram
elements.
value
argument.
The getCurrentProgram
method when invoked
MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
TVProgram
element.
value
argument.
The setParentalLock
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
isLocked
parameter.
pin
parameter does not match the current PIN or an error occurs invoke resolver's reject
algorithm with error as the value
argument.
value
argument.
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
|
|
Handles the information of the parental control status change for the TV/Radio channel. |
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.
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
;
};
onattributeschange
of type EventHandler
onattributeschange
event, fired when the attributes of the TV/Radio channel are changed.
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
;
};
originalNetworkId
of type DOMString, readonly
networkID
of the operator that originated this channel.
networkId
of type DOMString, readonly
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
serviceId
of type DOMString, readonly
TVDABChannelAttributes
Interface
The TVDABChannelAttributes
interface represents DVB channel attributes
interface TVDABChannelAttributes
: TVChannelAttributes
{
readonly attribute DOMString ensembleId
;
readonly attribute DOMString serviceId
;
};
ensembleId
of type DOMString, readonly
serviceId
of type DOMString, readonly
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.
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
;
};
type
of type TVApplicationType
, readonly
applicationData
of type object, readonly, nullable
onapplicationchange
of type EventHandler
onapplicationchange
event, fired when the application of the TV/Radio channel is changed.
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
;
};
eventId
of type DOMString, readonly
channel
of type TVChannel
, readonly
title
of type DOMString, readonly
startTime
of type DOMTimeStamp, readonly
duration
of type DOMTimeStamp, readonly
shortDescription
of type DOMString, readonly, nullable
longDescription
of type DOMString, readonly, nullable
parentalRating
of type DOMString, readonly, nullable
isEncrypted
of type boolean, readonly
seriesId
of type DOMString, readonly, nullable
getAudioLanguages
sequence<DOMString>
getSubtitleLanguages
sequence<DOMString>
getGenres
sequence<DOMString>
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
interface, which requires
TextTrackCue
startTime
and endTime
, and can be accessed by the
or video
element by adding the audio
to the
TextTrackCue
associated with the
TextTrack
. Besides, the
HTMLMediaElement
can rely on its TextTrack
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
;
};
type
of type TVTriggerType
, readonly
title
of type DOMString, readonly, nullable
url
of type DOMString, readonly, nullable
channel
of type TVChannel
, readonly, nullable
stream
of type TVMediaStream
, readonly, nullable
additionalData
of type object, readonly, nullable
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
;
};
id
of type DOMString, readonly
channel
of type TVChannel
, readonly
program
of type TVProgram
, readonly, nullable
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
endTime
of type DOMTimeStamp, readonly
state
of type TVRecordingState
, readonly
size
of type unsigned long long, readonly
duration
of type DOMTimeStamp, readonly
description
of type DOMString
onrecordingchange
of type EventHandler
recordingchange
event of type
TVRecordingChangeEvent
, fired when the recording time frame or the state of the TV/Radio recording has been changed.
getStream
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.
Promise
<TVMediaStream
>
stop
Promise
<void>
The getStream
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
TVMediaStream
object.
value
argument.
The stop
method when invoked MUST run the following steps:
Promise
object and resolver be its associated
resolver.
value
argument.
value
argument.
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
|
|
Handles the information of the updates for TV/Radio recordings. |
TVMediaStream
Interface
The TVMediaStream
interface is an extended
with a buffering mechanism to support basic seekability. It can be played by the MediaStream
or video
element by assigning the
audio
TVMediaStream
to the
's
HTMLMediaElement
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);
};
getTextTracks
sequence<TextTrack
>
addTextTrack
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
textTrack |
TextTrack
|
✘ | ✘ |
The TextTrack object to be added.
|
void
removeTextTrack
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
textTrack |
TextTrack
|
✘ | ✘ |
The TextTrack object to be removed.
|
void
HTMLMediaElement
Attributes When Playing a
TVMediaStream
The nature of no buffering of the
places certain restrictions on the behavior and attribute values of the associated MediaStream
and on the operations that can be performed on it. Yet since
HTMLMediaElement
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
.)
|
preload
|
DOMString
|
none |
A TVMediaStream cannot be preloaded. (Same as
.)
|
buffered
|
|
Same as .
|
Unlock the restriction applied by
.
|
networkState
|
unsigned short
|
NETWORK_IDLE |
The media element does not fetch the TVMediaStream so there is no network traffic. (Same as
.)
|
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 .)
|
currentTime
|
double
|
Same as .
|
Unlock the restriction applied by
.
|
duration
|
unrestricted double
|
Same as .
|
Unlock the restriction applied by
.
|
seeking
|
boolean
|
Same as .
|
Unlock the restriction applied by
.
|
defaultPlaybackRate
|
double
|
Same as .
|
Unlock the restriction applied by
.
|
playbackRate
|
double
|
Same as .
|
Unlock the restriction applied by
.
|
played
|
|
Same as .
|
Unlock the restriction applied by
.
|
seekable
|
|
Same as .
|
Unlock the restriction applied by
.
|
loop
|
boolean
|
Same as .
|
Unlock the restriction applied by
.
|
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
or
video
element used for playing the current
audio
. So the application may play with the
MediaStream
or 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 audio
back to the
MediaStream
or video
element. Please note applications may need to regularly clean up old TV/Radio recordings used for time-shifting.
audio
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
;
};
state
of type TVCICardState
, readonly
casSystemId
of type DOMString, readonly
isInUse
of type boolean, readonly
casSystemId
, at most one of them can have this attribute set.
TVStartScanningOptions
Dictionary
The TVStartScanningOptions
dictionary contains the information for scanning the TV/Radio channels.
dictionary TVStartScanningOptions
{
boolean isRescanned
;
};
TVStartScanningOptions
Members
isRescanned
of type boolean
TVGetProgramsOptions
Dictionary
The TVGetProgramsOptions
dictionary contains the information for retrieving the TV/Radio programs.
dictionary TVGetProgramsOptions
{
DOMTimeStamp startTime
;
DOMTimeStamp endTime
;
DOMString genre
;
};
TVGetProgramsOptions
Members
startTime
of type DOMTimeStamp
endTime
of type DOMTimeStamp
genre
of type DOMString
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
;
};
TVAddRecordingOptions
Members
description
of type DOMString, required
channel
of type TVChannel
, required
program
of type TVProgram
, nullable
startTime
and endTime
.
startTime
of type DOMTimeStamp, nullable
program
is specified.
endTime
of type DOMTimeStamp, nullable
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.
TVGetRecordingsOptions
Dictionary
The TVGetRecordingsOptions
dictionary contains the information for retrieving the TV/Radio recordings.
dictionary TVGetRecordingsOptions
{
TVRecordingState
? state
;
DOMString? id
;
};
TVGetRecordingsOptions
Members
state
of type TVRecordingState
, nullable
id
of type DOMString, nullable
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
;
};
operation
of type TVTunerChangeEventOperation
, readonly
id
of type DOMString, readonly
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
;
};
source
of type TVSource
, readonly, nullable
null
if the TV/Radio source is not configured.
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
;
};
programs
of type object, readonly
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.
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
();
};
type
of type DOMString, readonly, nullable
severityLevel
of type DOMString, readonly, nullable
null
when the emergency announcement is over.
description
of type DOMString, readonly, nullable
channel
of type TVChannel
, readonly, nullable
url
of type DOMString, readonly, nullable
getRegions
sequence<DOMString>
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
;
};
state
of type TVScanningState
, readonly
channel
of type TVChannel
, readonly, nullable
null
if the state
is not
"scanned"
.
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
;
};
channel
of type TVChannel
, readonly, nullable
null
if the TV/Radio tuner is not streaming any data.
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
;
};
id
of type DOMString, readonly
isTimeChange
of type boolean, readonly
isStateChange
of type boolean, readonly
errorName
of type DOMString, readonly, nullable
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
;
};
state
of type TVCICardState
, readonly
casSystemId
of type DOMString, readonly
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
:
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. |
This section is non-normative.
This section will be completed in a future draft of the specification. See this issue for details.
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.
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.