Introduction
TV Manager API enables the development of web-based applications to acquire the information from service providers as well as to manage the native TV hardwares (i.e. tuners).
Use Cases
The TV Manager API is aimed to cover the following use cases:
- The web content is able to know the number of tuners on the device, and the broadcasting types (DVB-T, DVB-S, etc.) supported by each of them.
- The TV tuner, which may have its own scanning algorithm provided by the vendor, can scan broadcasting channels. The scanning status and the information of discovered channels are exposed to the web content.
- The web content is able to control/select TV channels with the tuner on the device.
- The web content is able to receive the information of Electronic Program Guide (EPG) as well as the dynamic updates provided by broadcasters/service providers.
- A TV program may have multiple video/audio tracks in the same broadcasting stream.
- The web content may flexibly manipulate multiple tuners. For example, it may only consume one tuner for watching and recording a given channel at the same time. Yet when it comes to switch to another channel to watch, in order not to affect the original recording task against the tuner, the app may take another tuner to do so, if resource permitted.
- The web content may play the broadcasting stream content while browsing through the list of other currently broadcasted programs.
- The web content is able to suffice the scenarios of concurrently displaying multiple streams (i.e. Picture-in-Picture).
- The web content can receive emergency announcements for earthquake, tsunami, fire, etc.
Interfaces UML diagram
Examples
If an application has the privilege to use the TV Manager API, it can use a bunch of basic methods defined in the TVManager to manage the TV device.
The following example shows how to get all the available TV tuners on the TV device, and how to set the current source and listen to events for source changes.
// Retrieve all the available TV tuners.
navigator.tv.getTuners().then(function onsuccess(tuners) {
// Just use the first TV tuner.
var tuner = tuners[0];
// Set the 'oncurrentsourcechanged' event handler.
tuner.oncurrentsourcechanged = function oncurrentsourcechanged(event) {
alert("The current TV source has changed.");
};
// Get the supported TV source types for the TV tuner.
var sourceTypes = tuner.getSupportedSourceTypes();
// Just use the first TV source type.
tuner.setCurrentSource(sourceTypes[0]).then(function onsuccess() {
alert("Succeeded to set the TV source.");
}, function onerror(error) {
alert(error);
});
}, function onerror(error) {
alert(error);
});
The following example shows how to scan and get all the available TV channels from a configured TV source of the TV tuner.
// Assuming a tuner has already been picked and its current source is
// set, variable |currentSource| is used for following illustration.
if (currentSource.isScanning) {
return;
}
// Set the 'onscanningstatechanged' event handler.
currentSource.onscanningstatechanged = function onscanningstatechanged(event) {
var state = event.state;
switch (state) {
case "cleared":
alert("All the TV channels are cleared for rescanning.");
break;
case "scanned":
alert("A new TV channel is scanned: " + event.channel.name);
break;
case "completed":
alert("The scanning process is completed.");
// Retrieve all the available TV channels from the configured
// TV source of the TV tuner.
currentSource.getChannels().then(function onsuccess(channels) {
alert("Succeeded to scan and get all the TV channels.");
}, function onerror(error) {
alert(error);
});
break;
case "stopped":
alert("The scanning process is stopped.");
break;
default:
break;
}
};
// Ask the configured TV source to scan TV channels.
currentSource.startScanning({
isRescanned: true
}).then(function onsuccess() {
alert("The scanning process starts.");
}, function onerror(error) {
alert(error);
});
The following example shows how to get all the available TV programs from the TV channel.
// Assuming a tuner has already been picked and its current source is
// set, variable |currentSource| is used for following illustration.
// Set the 'oneitbroadcasted' event handler.
currentSource.oneitbroadcasted = function oneitbroadcasted(event) {
var newPrograms = event.programs;
// Add or update correspondent programs in |curProgramsOfChannels|
// based on their |eventId|.
};
// Retrieve all the available TV channels from the configured TV
// source of the TV tuner.
currentSource.getChannels().then(function onsuccess(channels) {
channels.forEach(function getProgramsByChannel(channel) {
var channelNumber = channel.number;
// Retrieve all the available TV programs from the TV channel.
channel.getPrograms().then(function onsuccess(programs) {
curProgramsOfChannels[channelNumber] = programs;
}, function onerror(error) {
alert(error);
});
});
}, function onerror(error) {
alert(error);
});
The following example shows how to play the streaming data of a TV
tuner by assigning the MediaStream to a
HTMLMediaElement.
<!DOCTYPE html>
<html>
<head>
<script>
// Retrieve all the currently available TV tuners first.
navigator.tv.getTuners().then(function onsuccess(tuners) {
if (tuners.length == 0) {
return;
}
// Just use the first TV tuner.
var tuner = tuners[0];
var video = document.getElementById("video-player");
video.srcObject = tuner.stream;
}, function onerror(error) {
alert(error);
});
</script>
</head>
<body>
<p><video id="video-player" autoplay></video></p>
</body>
</html>
The following example shows how to switch the TV channel with the channel number, and listen to events for channel changes.
// Assuming a tuner has already been picked and its current source is
// set, variable |currentSource| is used for following illustration.
// Retrieve all the available TV channels from the configured TV
// source of the TV tuner.
currentSource.getChannels().then(function onsuccess(channels) {
if (channels.length == 0) {
return;
}
// Just use the first TV channel.
var channel = channels[0];
var channelNumber = channel.number;
currentSource.oncurrentchannelchanged = function oncurrentchannelchanged(event) {
alert("The current channel has changed.");
};
// Switch the TV channel based on the TV channel number.
currentSource.setCurrentChannel(channelNumber).then(function onsuccess() {
alert("Succeeded to switch the TV channel.");
}, function onerror(error) {
alert(error);
});
}, function onerror(error) {
alert(error);
});