Capabilities API proposal

Here is a proposal for a Capabilities API.  Note that the syntax of what is returned will ultimately be determined by the Hints API.  I have included a brief example return value and answers to questions I expect people will have.

-- dan



interface Capabilities {
  HintList getCapabilities()
};

The getCapabilities method returns a JSON array of profiles representing local capabilities, where each profile is a collection of internally consistent options.  The intent is that the author can select the profiles that are acceptable, rank them in order from most to least preferred, and send the ordered list of acceptable profiles as input to the Hints API.  The Hints API will define the options that are allowed within profiles, as well as defining the HintList type.

Examples:
(Full examples are TBD when we have a Hints API.  These are just to give an idea of what the structure would look like)

This is an example of a HintList, a list of profiles which the app author will subset and priority-order before sending to the Hints API.

[{Video:
    {Purpose: whiteboard,
     Resolution: high},
  Audio:
    {Type: speech,
     Resolution: mobile,
     Handsfree: true}},
 {Video:
    {Purpose: action,
     Bandwidth: lan-internet},
  Audio:
    {Type: music,
     Bandwidth: broadband-high,
     Handsfree: false}},
 {Video:
    {Purpose: face2face,
     Resolution: 720p},
  Audio:
    {Type: speech,
     Bandwidth: broadband-medium,
     Handsfree: true}},
 {Video:
    {Resolution: 1080p,
     Bandwidth: broadband-low},
  Audio:
    {Resolution: landline,
     Bandwidth: streaming-high,
     Handsfree: false}},
 {Video:
    {Purpose: action,
     Resolution: 480p},
  Audio:
    {Resolution: fm,
     Bandwidth: streaming-low}},
 {Video
    {Purpose: face2face,
     Resolution: medium},
  Audio:
    {Type: music,
     Resolution: hi-fi}},
 {Video
    {Purpose: whiteboard,
     Resolution: low},
  Audio:
    {Type: speech,
     Resolution: studio}},
 {Video
    {Purpose: face2face,
     Resolution: high}},
 {Audio:
    {Type: music,
     Bandwidth: broadband-high}}]


FAQ
Why do we need a Capabilities API?
1. Web developers want to be able to grey out/hide capabilities that are not available, such as a webcam or microphone.
2. Web developers may not know which configurations are allowed or feasible.  For example, for a video device it may be possible to specify high quality or low bandwidth, but not both.  It is quite likely that an app author who wants both would rather specify a preference for one than trust the hint system to make the right selection between the two.

Why use a list of profiles to select from, order, and send to the Hints API?
1. This ensures that the profiles provided as hints are feasible and contain compatible and legal options.
2. It allows the author to see precisely the levels of detail available as hints.  For example, one video device might allow resolutions to be specified as 'high', 'medium', 'low', '640x480', and '1024x768'.  Even though these options are not all mutually exclusive, they are all valuable since some authors may wish to use the descriptive labels and others the precise resolutions.
3. This may allow for easy extensibility.  For example, if a video device supports 'avatar mode' and a browser supports that capability, it will appear in the capability profiles and be selectable via hints on that browser.

What about remote capabilities?
1. Remote capabilities can be obtained through separate negotiation between the parties, since each end can obtain its own local capabilities and then communicate, e.g., via the data channel.  There is no need to standardize a specific protocol for obtaining remote capabilities.
2. By leaving the communication of capabilities up to the Javascript application, the application can control how much information is made available to the remote end, thus implementing privacy restrictions appropriate to the application.  The browser can always, of course, restrict the information it provides to ensure that even the local side does not have inappropriate capability information.

Received on Thursday, 19 January 2012 16:05:20 UTC