Copyright © 2014-2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use 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/.
This document is work in progress and is subject to change. The API is being developed based on requirements from the TV Control Working Group, and previously the TV Control Community Group.
An important issue for the Working Group to address is which functions are appropriate to be accessed from general web applications, and the mechanisms that may be needed to address any security and user privacy concerns.
Changes to this document may be tracked at the specification's GitHub repository.
This document was published by the TV Control Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-tvcontrol@w3.org (subscribe, archives). All comments are welcome.
Publication as a First Public Working Draft 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 September 2015 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 TVTuner
and TVSource
objects, allows applications to select and present a TV or radio channel. Presentation is achieved by obtaining a TVMediaStream
object from the TVTuner
and assigning this to the srcObject
attribute of an
HTMLMediaElement
. The TVMediaStream
interface extends MediaStream
to allow buffering of the received media, to enable pause/resume and timeshifted playback.
The purpose and distinction between the TVTuner
and TVSource
objects requires clarification. 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 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]
TVManager
Interface
The TVManager
interface represents a bunch of properties and a set of operations that can be used to manage the TV device.
interface TVManager : EventTarget {
Promise<sequence<TVTuner
>> getTuners ();
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 ontunerchanged;
attribute EventHandler onrecordingchanged;
attribute EventHandler onparentalcontrolchanged;
attribute EventHandler oncicardchanged;
};
totalRecordingSize
of type unsigned long long, readonly availableRecordingSize
of type unsigned long long, readonly isParentalControlled
of type boolean, readonly ontunerchanged
of type EventHandlertunerchanged
event of type
TVTunerChangedEvent
, fired when the TV device detects a TV tuner is added/removed.
onrecordingchanged
of type EventHandlerrecordingchanged
event of type
TVRecordingChangedEvent
, fired when the recording time frame or the state of the TV recording has been changed.
onparentalcontrolchanged
of type EventHandlerparentalcontrolchanged
event, fired when the parental control status is changed.
oncicardchanged
of type EventHandlercicardchanged
event, fired when the CI (Common Interface) card status is changed.
getTuners
Promise
that will be used to notify the caller about the result of the operation, which is an array of TVTuner
elements.
Promise<sequence<TVTuner
>>
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 |
|
✘ | ✘ | 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 |
|
✘ | ✔ | 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.
Promise<sequence<TVCICard
>>
The getTuners
method when invoked MUST run the following steps:
Promise
object and
resolver be its associated resolver
.
value
argument.
TVTuner
elements.
value
argument.
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 |
---|---|---|---|
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.
interface TVTuner : EventTarget {
sequence<TVSourceType
> getSupportedSourceTypes ();
Promise<sequence<TVSource
>> getSources ();
Promise<void> setCurrentSource (TVSourceType
sourceType);
readonly attribute DOMString id;
readonly attribute TVSource
? currentSource;
[SameObject]
readonly attribute TVMediaStream
? stream;
readonly attribute double signalStrength;
readonly attribute boolean isRecordable;
attribute EventHandler oncurrentsourcechanged;
};
id
of type DOMString, readonly currentSource
of type TVSource
, readonly , nullablestream
of type TVMediaStream
, readonly , nullableTVMediaStream
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
.signalStrength
of type double, readonly isRecordable
of type boolean, readonly oncurrentsourcechanged
of type EventHandlercurrentsourcechanged
event of type
TVCurrentSourceChangedEvent
, fired when the method
setCurrentSource
is invoked to configure the current TV source.
getSupportedSourceTypes
sequence<TVSourceType
>
getSources
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<sequence<TVSource
>>
setCurrentSource
sourceType
parameter. It returns a new Promise
that will be used to notify the caller about the result of the operation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
sourceType |
|
✘ | ✘ | Specifies the TV source type for configuring the current TV source. |
Promise<void>
The getSources
method when invoked MUST run the following steps:
Promise
object and
resolver be its associated resolver
.
value
argument.
TVSource
elements.
value
argument.
The setCurrentSource
method when invoked MUST run the following steps:
Promise
object and
resolver be its associated resolver
.
sourceType
parameter.
value
argument.
value
argument.
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 .
|
TVSource
Interface
The TVSource
interface represents a bunch of properties and a set of operations related to the TV source.
interface TVSource : EventTarget {
Promise<sequence<TVChannel
>> getChannels ();
Promise<void> setCurrentChannel (DOMString channelNumber);
Promise<void> startScanning (optional TVStartScanningOptions
options);
Promise<void> stopScanning ();
readonly attribute TVTuner
tuner;
readonly attribute TVSourceType
type;
readonly attribute boolean isScanning;
readonly attribute TVChannel
? currentChannel;
attribute EventHandler oncurrentchannelchanged;
attribute EventHandler oneitbroadcasted;
attribute EventHandler onemergencyalerted;
attribute EventHandler onscanningstatechanged;
};
tuner
of type TVTuner
, readonly type
of type TVSourceType
, readonly isScanning
of type boolean, readonly currentChannel
of type TVChannel
, readonly , nullableoncurrentchannelchanged
of type EventHandlercurrentchannelchanged
event of type
TVCurrentChannelChangedEvent
, fired when the method
setCurrentChannel
is invoked to tune the currently streamed TV channel.
oneitbroadcasted
of type EventHandlereitbroadcasted
event of type
TVEITBroadcastedEvent
, fired when the Event Information Table (EIT) is broadcasted by the TV source.
onemergencyalerted
of type EventHandleremergencyalerted
event of type
TVEmergencyAlertedEvent
, fired when an emergency, such as earthquake or tsunami, occurs and is broadcasted by the TV source.
onscanningstatechanged
of type EventHandlerscanningstatechanged
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.
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 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<sequence<TVChannel
>>
setCurrentChannel
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
channelNumber | DOMString |
✘ | ✘ | Specifies the TV channel number for tuning the currently streamed TV channel. |
Promise<void>
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 TV 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 |
|
✘ | ✔ |
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
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 setCurrentChannel
method when invoked MUST run the following steps:
Promise
object and
resolver be its associated resolver
.
channelNumber
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 channels before scanning; if it is passed as false
, the
user agent will simply scan additional TV 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 |
---|---|---|---|
oncurrentchannelchanged |
currentchannelchanged |
TVCurrentChannelChangedEvent |
Handles the information of the currently streamed TV channel that is tuned by the method
.
|
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.
interface TVChannel : EventTarget {
Promise<sequence<TVProgram
>> getPrograms (optional TVGetProgramsOptions
options);
Promise<TVProgram
> getCurrentProgram ();
Promise<void> setParentalLock (DOMString pin, boolean isLocked);
readonly attribute DOMString networkId;
readonly attribute DOMString transportStreamId;
readonly attribute DOMString serviceId;
readonly attribute TVSource
source;
readonly attribute TVChannelType
type;
readonly attribute DOMString name;
readonly attribute DOMString number;
readonly attribute boolean isEmergency;
readonly attribute boolean isFree;
readonly attribute DOMString? casSystemId;
readonly attribute boolean isParentalLocked;
attribute EventHandler onparentallockchanged;
};
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 source
of type TVSource
, readonly type
of type TVChannelType
, readonly name
of type DOMString, readonly "CNN"
,
"NHK"
, etc.
number
of type DOMString, readonly "12-1"
, "12-2"
, etc.
isEmergency
of type boolean, readonly isFree
of type boolean, readonly casSystemId
of type DOMString, readonly , nullableisParentalLocked
of type boolean, readonly onparentallockchanged
of type EventHandlerparentallockchanged
event, fired when the parental lock status of the TV 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 channel.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
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<sequence<TVProgram
>>
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 TV channel.
Promise<TVProgram
>
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 TV 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 |
---|---|---|---|
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.
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 unsigned long long startTime;
readonly attribute unsigned long long duration;
readonly attribute DOMString? shortDescription;
readonly attribute DOMString? longDescription;
readonly attribute DOMString? rating;
readonly attribute boolean isFree;
readonly attribute DOMString? seriesId;
};
eventId
of type DOMString, readonly channel
of type TVChannel
, readonly title
of type DOMString, readonly startTime
of type unsigned long long, readonly duration
of type unsigned long long, readonly shortDescription
of type DOMString, readonly , nullablelongDescription
of type DOMString, readonly , nullablerating
of type DOMString, readonly , nullableisFree
of type boolean, readonly seriesId
of type DOMString, readonly , nullablegetAudioLanguages
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 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.
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 , nullableurl
of type DOMString, readonly , nullablechannel
of type TVChannel
, readonly , nullablestream
of type TVMediaStream
, readonly , nullableadditionalData
of type object, readonly , nullableTVRecording
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.
interface TVRecording {
Promise<TVMediaStream
> getStream ();
Promise<void> stop ();
readonly attribute DOMString id;
readonly attribute TVChannel
channel;
readonly attribute TVProgram
? program;
readonly attribute unsigned long long startTime;
readonly attribute unsigned long long endTime;
readonly attribute TVRecordingState
state;
readonly attribute unsigned long long size;
readonly attribute unsigned long long duration;
attribute DOMString description;
attribute EventHandler onrecordingchanged;
};
id
of type DOMString, readonly channel
of type TVChannel
, readonly program
of type TVProgram
, readonly , nullableTVRecordingChangedEvent
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 unsigned long long, readonly endTime
of type unsigned long long, readonly state
of type TVRecordingState
, readonly size
of type unsigned long long, readonly duration
of type unsigned long long, readonly description
of type DOMStringonrecordingchanged
of type EventHandlerrecordingchanged
event of type
TVRecordingChangedEvent
, fired when the recording time frame or the state of the TV 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 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 |
---|---|---|---|
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.
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 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 . |
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.
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 TVStartScanningOptions
Dictionary
The TVStartScanningOptions
dictionary contains the information for scanning the TV channels.
dictionary TVStartScanningOptions {
boolean isRescanned;
};
TVStartScanningOptions
MembersisRescanned
of type booleanTVGetProgramsOptions
Dictionary
The TVGetProgramsOptions
dictionary contains the information for retrieving the TV programs.
dictionary TVGetProgramsOptions {
unsigned long long startTime;
unsigned long long endTime;
DOMString genre;
};
TVGetProgramsOptions
MembersstartTime
of type unsigned long longendTime
of type unsigned long longgenre
of type DOMStringTVAddRecordingOptions
Dictionary
The TVAddRecordingOptions
dictionary contains the information for adding a TV recording.
dictionary TVAddRecordingOptions {
required DOMString description;
required TVChannel
channel;
TVProgram
? program;
unsigned long long? startTime;
unsigned long long? endTime;
};
TVAddRecordingOptions
Membersdescription
of type DOMString, requiredchannel
of type TVChannel
, requiredprogram
of type TVProgram
, nullablestartTime
and endTime
.
startTime
of type unsigned long long, nullableprogram
is specified.
endTime
of type unsigned long long, nullablestop()
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.
dictionary TVGetRecordingsOptions {
TVRecordingState
? state;
DOMString? id;
};
TVGetRecordingsOptions
Membersstate
of type TVRecordingState
, nullableid
of type DOMString, nullableTVTunerChangedEvent
Interface
The TVTunerChangedEvent
interface represents the event related to the TV tuner that is added/removed by the TV device.
interface TVTunerChangedEvent : Event {
readonly attribute TVTunerChangedEventOperation
operation;
readonly attribute DOMString id;
};
operation
of type TVTunerChangedEventOperation
, readonly id
of type DOMString, readonly TVCurrentSourceChangedEvent
Interface
The TVCurrentSourceChangedEvent
interface represents the event related to the current TV source that is configured by the method
.
setCurrentSource
interface TVCurrentSourceChangedEvent : Event {
readonly attribute TVSource
? source;
};
source
of type TVSource
, readonly , nullableTVEITBroadcastedEvent
Interface
The TVEITBroadcastedEvent
interface represents the event related to the available TV programs in the EIT that is broadcasted by the TV source.
interface TVEITBroadcastedEvent : 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.
TVEmergencyAlertedEvent
Interface
The TVEmergencyAlertedEvent
interface represents the event related to the emergency alert that is broadcasted by the TV source.
interface TVEmergencyAlertedEvent : 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 , nullableseverityLevel
of type DOMString, readonly , nullabledescription
of type DOMString, readonly , nullablechannel
of type TVChannel
, readonly , nullableurl
of type DOMString, readonly , nullablegetRegions
sequence<DOMString>
TVScanningStateChangedEvent
Interface
The TVScanningStateChangedEvent
interface represents the event related to the state of channel scanning, which is changed by the TV source.
interface TVScanningStateChangedEvent : Event {
readonly attribute TVScanningState
state;
readonly attribute TVChannel
? channel;
};
state
of type TVScanningState
, readonly channel
of type TVChannel
, readonly , nullablestate
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
interface TVCurrentChannelChangedEvent : Event {
readonly attribute TVChannel
? channel;
};
channel
of type TVChannel
, readonly , nullableTVRecordingChangedEvent
Interface
The TVRecordingChangedEvent
interface represents the event related to the update of a TV recording.
interface TVRecordingChangedEvent : 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 , nullableTVCICardChangedEvent
Interface
The TVCICardChangedEvent
interface represents the event related to the changes in the state of the CI (Common Interface) card.
interface TVCICardChangedEvent : Event {
readonly attribute TVCICardState
state;
readonly attribute DOMString casSystemId;
};
state
of type TVCICardState
, readonly casSystemId
of type DOMString, readonly
The attribute type
in the TVSource
can have the following values:
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"
};
Enumeration description | |
---|---|
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:
enum TVChannelType {
"tv",
"radio",
"data"
};
Enumeration description | |
---|---|
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:
enum TVTunerChangedEventOperation {
"added",
"removed"
};
Enumeration description | |
---|---|
added |
A TV tuner is added. |
removed |
A TV tuner is removed. |
The attribute state
in the
TVScanningStateChangedEvent
can have the following values:
enum TVScanningState {
"cleared",
"scanned",
"completed",
"stopped"
};
Enumeration description | |
---|---|
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:
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
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 the following values:
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. |
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.
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.