Interface for TV control and managment.

TV Control API

24 May 2013

Authors

Summary of Methods

Interface Method
TVManager
TVDisplayManager void setChannel(Channel channel, TVDisplaySuccessCB successCallback, TVErrorCB errorCallback)
TVTunerManager void getTVSources(TVManagerSuccessCB successCallback, TVErrorCB errorCallback)

Introduction

The interface provides means to acquire a list of tv sources, channels and their streams.

The TV channel streams can be displayed in HTMLVideoElement object. Alternatively the API provides means to control channel management of the native hardware TV, by allowing to set a channel or watch for channel changes that are invoked otherwise.

Interfaces and Dictionaries

Interface TVManager

This is the top-level interface for the TV API that provides access to tuner and display managers.

WebIDL
interface TVManager : Service {
  readonly attribute TVDisplayManager display;
  readonly attribute TVTunerManager tuner;
};

The TVManager interface is a discoverable interface through the webinos Discovery API findServices() method and thus inherits the Discovery API Service interface.

Interface TVDisplayManager

Interface to manage what's currently displayed on TV screen.

WebIDL
interface TVDisplayManager : EventTarget {

   attribute Channel? currentChannel;
 

  void setChannel(Channel channel, TVDisplaySuccessCB successCallback, optional TVErrorCB errorCallback);


  [TreatNonCallableAsNull]
             attribute EventHandler onchannelchange;
};

This interface is useful when an app doesn't want to show the broadcast itself, but let the TV natively handle playback, i.e. not in a web context. Useful to build an control interface that allows channel switching.

Code example
  <p>Currently shown on TV: <span id='tv'>Undetermined</span></p>
  <script>
  var channel; // holding a previously obtained channel object.
  // tvService is the TV service, discovered through the webinos Discovery API, that has been selected by the user
  tvService.display.setChannel(channel, success);
  var ontv = document.getElementById('tv');
  function success(channel) {
    ontv.normalize();
    ontv.removeChild(ontv.childNodes[0]);
    ontv.appendChild(document.createTextNode(channel.name));
  }
  </script>
 

Attributes

Channel? currentChannel

The channel currently displayed; null if no channel is tuned.

EventHandler onchannelchange

Event that fires when the channel is changed.

Changing channels could also be invoked by other parties, e.g. a hardware remote control. A channelchange event will be fired any time a channel is being changed.

Code example
  <p>Currently shown on TV: <span id='tv'>Undetermined</span></p>
  <script>
  // tvService is the TV service, discovered through the webinos Discovery API, that has been selected by the user
  tvService.display.addEventListener('channelchange', channelchanged);
  var ontv = document.getElementById('tv');
  function channelchanged(channel) {
    ontv.normalize();
    ontv.removeChild(ontv.childNodes[0]);
    ontv.appendChild(document.createTextNode(channel.name));
  }
  </script>
 

Methods

setChannel

Switches the channel natively on the TV (same as when a hardware remote control would be used).

Signature
void setChannel(Channel channel, TVDisplaySuccessCB successCallback, optional TVErrorCB errorCallback);
Parameters
  • channel
    • Optional: No.
    • Nullable: No
    • Type: Channel
    • Description: The TV channel to switch to.
  • successCallback
    • Optional: No.
    • Nullable: No
    • Type: TVDisplaySuccessCB
    • Description: The callback to notify the caller that the channel change succeeded.
  • errorCallback
    • Optional: Yes.
    • Nullable: No
    • Type: TVErrorCB
    • Description: The callback called in case the channel could not be switched or an error occured.

Interface TVTunerManager

Get a list of all available TV tuners.

WebIDL
interface TVTunerManager {

  void getTVSources(TVManagerSuccessCB successCallback, optional TVErrorCB errorCallback);
};
Code example
  <label>Pick a TV Source: <select id='source'>
  <option>None</option>
  </select></label>
  <label>Pick a  channel: <select id='channel'>
  <option>None</option>
  </select></label>
  <video id='display' width='640' height='400' poster='nochannel.png'></video>
  <script>
  // tvService is the TV service, discovered through the webinos Discovery API, that has been selected by the user
  tvService.tuner.getTVSources(successCB);
  var tvsourceselector = document.getElementById('source');
  var channelselector = document.getElementById('channel');
  var v = document.getElementById('display');
  var currentTVSource;
  var tvsources = [];
  function successCB(sources) {
    tvsources = sources;
    for (var i in sources) {
      var o = document.createElement('option');
      o.value = i;
      o.appendChild(document.createTextNode(sources[i].name);
      tvsourceselector.appendChild(o);
    }
  }
  tvsourceselector.addEventListener('change', function (e) {
    currentTVSource = tvsources[e.target.value];
    // start showing first channel
    if (currentTVSource.channelList.length) {
      v.src = currentTVSource.channelList[0].stream;
      for (var i in currentTVSource.channelList) {
          var channel = currentTVSource.channelList[i];
          var o = document.createElement('option');
          o.appendChild(document.createTextNode(channel.name);          
          o.value = i;
          channelselector.appendChild(o);
    }
  }, false);
  channelselector.addEventListener('change', function (e) {
     if (e.target.value) {
       v.src = currentTVSource.channelList[e.target.value].stream;
     }
  }, false);
  </script>
 

Methods

getTVSources

Get a list of all available TV sources.

Signature
void getTVSources(TVManagerSuccessCB successCallback, optional TVErrorCB errorCallback);
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No
    • Type: TVManagerSuccessCB
    • Description: Callback that receives all available TV sources, e.g. tuners.
  • errorCallback
    • Optional: Yes.
    • Nullable: No
    • Type: TVErrorCB
    • Description: Callback called in case something goes wrong.

Dictionary TVSource

TV source: a list of channels with a name.

WebIDL
dictionary TVSource {

  DOMString name;
  

  Channel[] channelList;
};

Dictionary Members

DOMString name

The name of the source.

The name should describe the kind of tuner this source represents, e.g. DVB-T, DVB-C.

Channel[] channelList

List of channels for this source.

Dictionary Channel

The Channel Interface

WebIDL
dictionary Channel {

  ChannelType channelType;
  

   DOMString name;
  

   DOMString? longName;
  

   MediaStream stream;
  
};

Channel objects provide access to the video stream.

Dictionary Members

ChannelType channelType

The type of channel.

Type of channel

DOMString name

The name of the channel.

The name of the channel will typically be the call sign of the station. To be used in cases if there is less space than needed for displaying the long name, e.g in horizontal lists or other compact channel list display modes. Thus, a name may be an acronym or abbreviation of the long name (longName attribute).

DOMString? longName

The long name of the channel.

The long name or fully spelt name of the channel if transmitted. Can be undefined if not available.

MediaStream stream

The video stream.

The stream attribute represents a valid source for a HTMLVideoElement. The MediaStream object itself is defined by the W3C at Media Capture and Streams API

Callbacks

TVDisplaySuccessCB

Callback function when current channel changed successfully.

WebIDL
callback TVDisplaySuccessCB = void (Channel channel);
Signature
void TVDisplaySuccessCB(Channel channel);
Parameters
  • channel
    • Optional: No.
    • Nullable: No
    • Type: Channel
    • Description:

TVManagerSuccessCB

Callback for found TV sources.

WebIDL
callback TVManagerSuccessCB = void (TVSource[] sources);
Signature
void TVManagerSuccessCB(TVSource[] sources);
Parameters
  • sources
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: An array of TVSource objects representing available tuners.

TVErrorCB

Error callback for errors when trying to get TV sources or setting a channel and something goes wrong.

WebIDL
callback TVErrorCB = void (DOMError error);
Signature
void TVErrorCB(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: DOMError object is detailing what went wrong; e.g. "NotFoundError" as name attribute of the error object if channel is invalid. An error with "NetworkError" or "TimeoutError" as value for the name attribute may occur if the service gets (temporarily) unreachable.

Enums

ChannelType

Type of channels

WebIDL
enum ChannelType { "tv", "radio"};

Values

tv
radio

Features

This section lists the URIs used to declare the features of this API. The feature URIs are used by the developer in:

  • The application's config.xml file to declare requested features.
  • As identifier for serviceType in the webinos Discovery API's findServices() method.
http://webinos.org/api/tv

Full WebIDL

WebIDL
interface TVManager : Service {
  readonly attribute TVDisplayManager display;
  readonly attribute TVTunerManager tuner;
}; 


interface TVDisplayManager : EventTarget {

   attribute Channel? currentChannel;
 

  void setChannel(Channel channel, TVDisplaySuccessCB successCallback, optional TVErrorCB errorCallback);


  [TreatNonCallableAsNull]
             attribute EventHandler onchannelchange;
};


callback TVDisplaySuccessCB = void (Channel channel);


interface TVTunerManager {

  void getTVSources(TVManagerSuccessCB successCallback, optional TVErrorCB errorCallback);
};


callback TVManagerSuccessCB = void (TVSource[] sources);


callback TVErrorCB = void (DOMError error);



dictionary TVSource {

  DOMString name;
  

  Channel[] channelList;
};


enum ChannelType { "tv", "radio"};


dictionary Channel {

  ChannelType channelType;
  

   DOMString name;
  

   DOMString? longName;
  

   MediaStream stream;
  
};