This specification defines a set of System Level APIs to allow Web applications retrieve information from the underlying system.

This document defines APIs to retrieve the status of generic hardware features from the system. Future versions of the specification can extend the set of hardware features supported.

The specification is scoped to address generic hardware features that apply to a wide range of different device types. Hardware capabilities that apply only to a specific class of devices are out of scope. For device class specific features, there exists separate specifications such as the Battery Status API, the Network Information API, and the Screen Orientation API, for example.

Introduction

The Device Capabilities API provides web apps a way to retrieve device and system information from the underlying operating system. Device capabilities vary a great deal across the wide range of devices applications run on. This API lets applications take advantage of the capabilities of the device the application is running on. For example, knowing the number of CPU cores allows Web applications to determine an appropriate number of Web Workers to create for a worker pool for a compute intensive task.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

The concept queue a task is defined in [[!HTML5]].

Security and Privacy Considerations

The API defined in this specification is used to retrieve information from the underlying system. The information disclosed has impact on privacy and fingerprinting, and therefore a conforming implementation of this specification MUST provide a mechanism that protects the user's privacy. The mechanism MUST ensure that no information is retrievable without the user's express permission.

DeviceCapabilities Interface

The system attribute of the Navigator interface MUST return an instance of the DeviceCapabilities interface.

readonly attribute DeviceCapabilities system

When one of the capability methods (described in the table below) is invoked on a DeviceCapabilities object, the user agent MUST run the following steps:

  1. Let promise be a new Promise [[!DOM]] object and resolver its associated resolver.
  2. Return promise and run the remaining steps asynchronously.
  3. Retrieve an instance of the capability data interface corresponding to the invoked capability method.
  4. If an error occurs, run these substeps and then terminate these steps:
    1. Let error be a new DOMError object whose name is "UnknownError",
    2. Run resolver's internal reject algorithm with error as value.
  5. If the capability data retrieval operation successfully completes, run these substeps:
    1. Let data be the instance of the capability data interface from the retrieval operation.
    2. Run resolver's internal fulfill algorithm with data as value.
Promise getCPUInfo()
Promise getMemoryInfo()
Promise getStorageInfo()
Promise getDisplayInfo()
Promise getAVCodecs()
attribute EventHandler onstorageattach
attribute EventHandler onstoragedetach
attribute EventHandler ondisplayconnect
attribute EventHandler ondisplaydisconnect

The following are the capability methods and their corresponding capability data interfaces:

description capability method capability data interface
Retrieve the specific information for CPU getCPUInfo() SystemCPU
Retrieve the memory information getMemoryInfo() SystemMemory
Retrieve the storage information getStorageInfo() SystemStorage
Retrieve the display information getDisplayInfo() SystemDisplay
Retrieve the audio and video codec information getAVCodecs() SystemAVCodecs

SystemStorageEvent Interface

readonly attribute StorageUnit storage
readonly attribute StorageUnit storage

SystemDisplayEvent Interface

readonly attribute DisplayUnit display
readonly attribute DisplayUnit display

When a new storage is attached to the system, the user agent MUST queue a task to fire an event named storageattach at the DeviceCapabilities object using the SystemStorageEvent interface that also meets these conditions:

When a new storage is detached from the system, the user agent MUST queue a task to fire an event named storagedetach at the DeviceCapabilities object using the SystemStorageEvent interface that also meets these conditions:

When a new display is connected to the system, the user agent MUST queue a task to fire an event named displayconnect at the DeviceCapabilities object using the SystemDisplayEvent interface that also meets these conditions:

When a display is disconnected from the system, the user agent MUST queue a task to fire an event named displaydisconnect at the DeviceCapabilities object using the SystemDisplayEvent interface that also meets these conditions:

Capability Data Interfaces

SystemCPU Interface

An example for monitoring the CPU load at 1 second interval regularly as below:

function watchCPU() {
  navigator.system.getCPUInfo().then(
      function(info) { console.log("CPU load: " + info.load); },
      function(error) { console.log("error occurred: " + error.message); });
}
setTimeout(watchCPU, 1);
            
readonly attribute unsigned int numOfProcessors
readonly attribute DOMString archName
readonly attribute float load

The numOfProcessors attribute MUST return a number representing the number of logical processors of the system.

The archName attribute MUST return a string representing the CPU architecture of the system, e.g. "x86", "x86_64", "armv6", "armv8".

The load attribute MUST return a number representing the current CPU load of logical processors, as a number in the range 0.0 (minimum) to 1.0 (maximum).

SystemMemory Interface

An example for monitoring the free memory change at 5 seconds interval regularly as below:

function monitorFreeMemory() {
  navigator.system.getMemoryInfo().then(
      function(info) { console.log("available bytes: " + info.availCapacity); },
      function(error) { console.log("error occurred: " + error.message); });
}
setTimeout(monitorFreeMemory, 5);
          
readonly attribute unsigned long capacity
readonly attribute unsigend long availCapacity

The capacity attribute MUST return a number representing the total capacity of system memory, in bytes.

The availCapacity attribute MUST return a number representing the available capacity of system memory, in bytes.

SystemStorage Interface

readonly attribute StorageUnit[] storages

The storages attribute MUST return an array of StorageUnit objects representing storage devices attached to the system.

StorageUnit interface

readonly attribute DOMString id
readonly attribute DOMString name
readonly attribute StorageUnitType type
readonly attribute unsigned long capacity
fixed
removable
unknown

The id attribute MUST return the unique identifier of the storage unit.

The name attribute MUST return a human-readable string intended to identify the storage unit for the user.

The type attribute MUST return "fixed" if the storage unit is a fixed non-removable storage, "removable" if the storage device is a user removable, otherwise "unknown".

The capacity attribute MUST return a number representing the total capacity of storage unit, in bytes.

SystemDisplay Interface

readonly attribute DisplayUnit[] displays

The displays attribute MUST return an array of DisplayUnit objects representing display devices attached to the system.

DisplayUnit interface

The DisplayUnit interface inherits availWidth, availHeight, width, height, colorDepth, and pixelDepth from the Screen interface [[!CSSOM]].
readonly attribute DOMString id
readonly attribute DOMString name
readonly attribute boolean primary
readonly attribute boolean external
readonly attribute unsigned int deviceXDPI
readonly attribute unsigned int deviceYDPI

The id attribute MUST return the unique identifier of the display.

The name attribute MUST return a human-readable string intended to identify the display for the user.

The primary attribute MUST return true, if the display is the primary display of the system.

The external attribute MUST return true, if the display is external i.e. not an integral part of the system.

The deviceXDPI attribute MUST return the number of pixels per inch along the x-axis.

The deviceYDPI attribute MUST return the number of pixels per inch along the y-axis.

SystemAVCodecs Interface

Exposing codec information to web applications provides a fingerprinting vector. An alternative approach is to let the User Agent choose the most appropriate media content using the HTMLSourceElement's type hints.

Exposes information about the audio/video codecs available on the device

readonly attribute AudioCodec[] audioCodecs
readonly attribute VideoCodec[] videoCodecs

The audioCodecs attribute MUST return an array of AudioCodec objects representing the audio codecs supported by the device.

The videoCodecs attribute MUST return an array of VideoCodec objects representing the video codecs supported by the device.

AudioCodec Interface

readonly attribute DOMString format

The format attribute MUST return a string representing the audio encoding format, e.g. "MP3", "G.711", "MIDI", "MP4".

VideoCodec Interface

readonly attribute DOMString format
readonly attribute boolean hwAccel
readonly attribute boolean encode

The format attribute MUST return a string representing the video encoding format, e.g. "H.264", "MPEG4".

The hwAccel attribute MUST return true, if the video decoding is hardward accelerated, false otherwise.

The encode attribute MUST return true, the device can encode the video in this format, false otherwise.

Use Cases and Requirements

Stream Video Content to Device

51% of the online video content in US is user generated.It typically is uploaded to a web site like YouTube or Facebook in some user generated format. This content can be accessed from different client devices which may have media players that supports different set of codecs. This implies some level of transcoding that needs to be done for the user to be able to vide the media stream. Depending on the client device capabilities and network capacity, the cloud app can decide what format to transmit to the client:

  1. It can stream the encoded stream if the client device has computation or hardware acceleration for decoding.
  2. It can stream an encoded stream in a format not supported by the media player on the client, but the client has the computation or hardware acceleration capability for transcoding.
  3. It can decide to transcode on the server if the client lacks either of above capabilities.
  4. It can decide to decode the video stream and deliver a bit stream for a very low-end device.
Encoding video on the device : local vs cloud

The user wants to share a large family video to others via cloud service provider. Before uploading video, an application may need to intelligently split up the work of encoding video between the local device, based on its capabilities, and a web service in the cloud that encodes video. The video codecs information could help application decide to encode the large video to a small one if the device has the video encoding capability as desired.

Acknowledgements

Thanks to Anssi Kostiainen for input, thorough reviews and feedback to this draft.