Screen Brightness API

[willmorgan]

Introduction

When displaying scannable images like barcodes or QR codes, readability by software is assisted by temporarily maximising the screen brightness.

Browser based Web apps currently cannot do this which negatively impacts user experience and accuracy should the screen be needed in tandem with the front facing camera to illuminate or scan something.

Native apps have the ability to set screen brightness with relative ease:

iOS (possibly with M1 Macbooks?) has setBrightness:

UIScreen.mainScreen().brightness = YourBrightnessValue

Android has this three liner:

final WindowManager.LayoutParams lp = getWindow().getAttributes();
lp.screenBrightness = WindowManager.LayoutParams.BRIGHTNESS_OVERRIDE_OFF;
getWindow().setAttributes(lp);

More discussion around how Screen Brightness is needed and how it may interact with other sensors and APIs here:

• Request for Ambient Light Sensor web developer feedback w3c/ambient-light#64 (comment)

Describe the challenge or problem on the web you are proposing we address.

Use Cases (Recommended)

This ability would benefit:

• travel applications, where a user must scan a boarding pass
• locker applications, where a user can scan a barcode to open a locker door containing their purchase
• remote medical, where increasing the screen brightness could assist in remote examination
• biometric security apps, where increasing the screen brightness can help illuminate features to get better imagery from the front facing camera
• increasing contrast for readability for the visually impaired
• gaming and further legitimising WebGL and WebXR
• make up mirror style apps
• basically, any instance where maximising brightness or contrast would be useful

Goals (Optional)

• Provide ability to read current screen brightness from the navigator's current host display.
• Provide ability to request maximum brightness on navigator's current host display, either indefinitely or for a period of time.
• Provide ability to release the request so that the device's brightness returns to its pre-request value (i.e. hand back control to OS).
• Provide ability to emit specific errors to handle cases where such requests are denied or not possible.

Non-goals (Optional)

Proposed Solution

Add object to navigator called screenBrightness:

• brightness: Float returns current brightness percentage in the range of 0.0..1.0
• override({ brightness, maxDuration }): BrightnessLock async function, returning a BrightnessLock when brightness target met, agnostic to implementation (instant or transition).
  • brightness: Float requested screen brightness
  • maxDuration: Number maximum time the lock will be in effect, if unspecified then defaults to vendor value. The BrightnessLock should be released by the requesting userland code before this time elapses, otherwise the vendor must release it.

Add BrightnessLock implementation:

• brightness: Float returns the requested brightness
• release: Promise<Float> reverts to the OS controlled brightness, resolving with the new brightness level which may differ from the state prior to the BrightnessLock
• expires: DOMHighResTimestamp the expiry time according to maxDuration

Add brightness to Feature Policy for use in nested browsing contexts.

Examples (Recommended)

const requestScreenBrightness = async (brightness, maxDuration) => {
    try {
        // would fulfil after the device transitions to the requested brightness, leaving implementation up to vendors: could be instantaneous, could transition
        screenBrightness = await navigator.screenBrightness.override({ brightness, maxDuration })
    } catch (err) {
        // err could be due to battery save mode, possible vendor permissions gating, out of range, etc
        console.error("Screen brightness change failed:", err.message)
        throw err
    }
}

// Hold 100% screen brightness for 3 seconds, then release:
if ('screenBrightness' in navigator) {
    console.log("Requesting increase to 100% from current brightness:", navigator.screenBrightness.brightness)
    const brightnessLock = await requestScreenBrightness(1.0)
    console.log("Brightness changed! Expires in:", brightnessLock.expires - performance.now())
    setTimeout(async () => {
        await brightnessLock.release()
        console.log("Brightness reverted to:", navigator.screenBrightness.brightness)
    }, 3000);
}

Alternate Approaches (Optional)

Extending the Wake Lock API with an option for screenBrightness:

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a screen wake lock.
const requestWakeLock = async () => {
    wakeLock = await navigator.wakeLock.request({
        screenBrightness: 1.0, // 100% brightness
    });
};

// Request a screen wake lock with maximum brightness:
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

Privacy & Security Considerations

What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?
Possible fingerprinting, although the screen brightness should change over time independently of the user's device, according to device ambient light sensor feedback or user control.

Do features in your specification expose the minimum amount of information necessary to enable their intended uses?
Yes.

How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them?
No PII.

How do the features in your specification deal with sensitive information?
No sensitive information.

Do the features in your specification introduce new state for an origin that persists across browsing sessions?
No, any brightness lock should be implicitly released when a page is hidden or closed.

Do the features in your specification expose information about the underlying platform to origins?
Yes, but to a minimal extent. The presence of an API may infer some hardware information, and the time it takes to transition between brightness values may infer hardware and software information.

Do features in this specification allow an origin access to sensors on a user’s device?
Not directly. An argument could be made that reading the untouched value of the brightness may be used as a proxy value for accessing an ambient light sensor, but this wouldn't be very precise.

What data do the features in this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.
The device's screen brightness, specifically that of the display hosting the requesting application.

Do feautres in this specification enable new script execution/loading mechanisms?
No.

Do features in this specification allow an origin to access other devices?
No.

Do features in this specification allow an origin some measure of control over a user agent’s native UI?
No.

What temporary identifiers do the features in this specification create or expose to the web?
Presence of a specific screen brightness value. If it is felt that this is significant, this could be mitigated by a maximum lifetime on the brightness lock, enforced by browser vendors.

How does this specification distinguish between behavior in first-party and third-party contexts?
By default this API should be enabled on top level browsing contexts and by feature policy for nested browsing contexts.

How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode?
Ideally the same, but the brightness getter could reduce precision or return 0.75 by default unless it is overridden with a BrightnessLock.

Does this specification have both "Security Considerations" and "Privacy Considerations" sections?
Yes. Security is an issue due to handing control over a high-battery-usage component to the web, and could be mitigated by browser vendors and operating systems alike, either by denying access for battery reasons, or adding a maximum lock duration.

Do features in your specification enable downgrading default security characteristics?
No.

Let’s Discuss (Optional)

• Does this even need to be readable? If there’s no readable data, there’s less fingerprintable area. Looking at the use cases, settable seems enough.
• Shall we attempt to tackle multiple monitors?
• How should multiple brightness requests be handled?
• Should this be permissions-gated?

[tomayac]

Love this proposal!

Let’s discuss amendment

• Does this even need to be readable? If there’s no readable data, there’s less fingerprintable area. Looking at the use cases, settable seems enough.

[beaufortfrancois]

I agree with @tomayac. Use cases would benefit from simply setting max brightness with a screen wake lock. And with this, no problem of privacy and fingerprinting.

// Request a screen wake lock with maximum brightness:
const wakeLock = await navigator.wakeLock.request({
  maximumScreenBrightness: true,
});

// Release it again after 5s.
setTimeout(() => {
  wakeLock.release();
}, 5000);

[willmorgan]

Integrating into the Wake Lock API would be good, but how to feature detect if the screen brightness option is supported?

[tomayac]

A static method like WakeLock.supportsScreenBrightness() could work. We have a similar method on BarcodeDetector.getSupportedFormats().

[willmorgan]

@tomayac @anssiko Do you have any suggestions on how to take this forward?

[tomayac]

(Catching up after the holidays.)

Do you have any suggestions on how to take this forward?

We'd probably need an engineering champion who would be willing to implement this. Raphael from Intel has been working on Wake Lock. @anssiko, do you know if he could be interested?

[anssiko]

I’ll loop in @rakuco and @kenchris to discuss. We’ll assess the priority of this feature considering Intel’s other spec and implementation commitments.

This feature could be part of Screen Wake Lock API and adopted by DAS WG after adequate WICG incubation.

[willmorgan]

Thanks @anssiko and @tomayac, and happy new year.

Let me know if there's anything I or my company (@iProov) can do, whether it's some use case implementations, testing, or evangelism.

[tomayac]

Let me know if there's anything I or my company (@iProov) can do, whether it's some use case implementations, testing, or evangelism.

Should we have an origin trial to try out, your company would be an ideal candidate to do so, and of course also spread the word about it on something like your company tech blog if you have one. We would probably also be interested in writing a case study if this feature proved useful.

[willmorgan]

Having discussed this at the DAS WG meeting, I think it would be more productive to close this proposal and incorporate it and its feedback into a piece of work that would upgrade the existing Screen Wake Lock API.

Context here: w3c/screen-wake-lock#129 (comment)

[tamascsaba]

It would be really useful. I really support this proposals. 👍

[willmorgan]

It would be really useful. I really support this proposals. 👍

Nice! What would you use a screen brightness API for?

[tamascsaba]

I have a barcode application, people use in patrol stations they got discount when they show the barcode and it would be great increase the brightness when barcode is on the screen.

[beaufortfrancois]

@tamascsaba Nice! Do you mind sharing your web app URL?