W3C home > Mailing lists > Public > public-device-apis-log@w3.org > April 2021

Re: [screen-wake-lock] Need maximum screen brightness mode (#129)

From: Will Morgan via GitHub <sysbot+gh@w3.org>
Date: Sat, 10 Apr 2021 15:12:10 +0000
To: public-device-apis-log@w3.org
Message-ID: <issue_comment.created-817151517-1618067528-sysbot+gh@w3.org>
After the DAS WG meetings this week I've spent more time to reading through the comments here in full, trying to condense them into a few key actions to take this forward:

### Actions required

  * Identify any further distinct use cases beyond barcode scanning, or at least try and identify scenarios in society where barcodes are now especially relevant.
  * Avoid proliferation of specialised or "atomic" APIs to do a single thing. With that in mind, I think the best thing to do is to close my Screen Brightness API proposal and focus on this Wake Lock integration instead.
  * Define the extent of control of this API, specifically around how the OS and user can moderate and retain control of the brightness settings.
  * Decide what the API changes needed for this look like, and how they relate to the existing spec.

### Use cases

  * 🐑 Barcode scanning
  * 🌈 Biometric based security / authentication / KYC solutions
  * 🎨 Colour sensitivity tests - maximising brightness so that colour blindness can be assessed - this actually affects a lot of people.
  * 💅 Makeup/mirror apps - maximising brightness so I can do my hair, face and nails without a mirror, which is so 20th century.
  * ❓ Any more info from @dontcallmedom, @brainfoolong, @CheloXL around their use cases would be useful! 😄 
  * 💉 In the UK, Israel and many other countries, a lot of work around vaccine status credentials is being done, where a QR code seems to be the preferred form of quickly asserting the credential. Providing this capability to the Web rather than forcing people to use apps, which are being scrutinised in society for their own privacy issues, would have real impact. Think about the collective time saved in getting a good scan first time rather than forcing people to fumble around or use paper! 😱 

### Extent of control

Instead of providing a number, the following values are available (thanks @marcoscaceres - [op](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-665357952)):

  - default: use the current brightness, and (if possible) don't allow the screen to dim - (OSs power settings probably override this).
  - auto: use the current brightness, but let the OS do whatever it wants with regards to dimming.
  - full: request full brightness, and let the OS do whatever it wants.

I have some suggestions that might make it more flexible for vendors to implement according to their mantras:

  * Change "auto" to "dim" for clarity. This would maximise battery life on handhelds.
  * Change "full" to "maximise" to acknowledge that user agents may place an upper limit on screen brightness when "full" really isn't needed. For example, there is no need to maximise screen brightness if the phone's ambient light sensor detects that you're in a dark room. Or perhaps the user has set an upper bound in accessibility settings.

We can bring these values under a new enum called `WakeLockBrightnessControl`.

### API changes

Staying coupled to the [WakeLockType](https://w3c.github.io/screen-wake-lock/#the-wakelocktype-enum) of screen, it looks like the following would keep most folks happy:

// Optimise brightness:
await navigator.wakeLock.request("screen", { brightness: "maximise" })
// Optimise battery
await navigator.wakeLock.request("screen", { brightness: "dim" })
// Use the default or don't express a preference:
await navigator.wakeLock.request("screen")

As an aside, if there is a strong preference for controlling brightness without a wake lock then perhaps we should consider an additional `WakeLockType` of `brightness`.

To feature detect the availability of the additional parameter, we could implement an additional method on [WakeLock](https://w3c.github.io/screen-wake-lock/#the-wakelock-interface) called `getCapabilities`:

if ("wakeLock" in navigator && navigator.wakeLock.getCapabilities) {
  const capabilities = navigator.wakeLock.getCapabilities()
  if ("brightness" in capabilities) {
      // We can try maximise/dim/default!
  console.log("You can request wake lock with the following options:", capabilities)

In vendors implementing this change, `getCapabilities` would return a `WakeLockCapabilities` type:

    "brightness": WakeLockBrightnessControl[], // i.e. ["default", "dim", "maximise"]

This would give developers the ability to know if they were able to try and influence the screen brightness. These values will always be returned regardless of battery status to avoid fingerprinting, but would serve to futureproof any additional values that may become necessary in the future.

### Summary

It looks like we're close here, and rather than starting a brand new API from scratch, reimplementing the good work that has already been done, and repeating the thoughtful conversations and debates had already, it makes sense to extend Wake Lock to include screen brightness control "hints" that are short lived and benefit from the framework that's already been established.

  * I think that 2021 is likely the year where including screen brightness in some form is going to be helpful for the world, to avoid person-years of fumbling around in our wallets for change or coupons, viewing lottie animations of how to increase your screen brightness manually and then forgetting to turn it down later, and all the awkwardness that these situations entail.
  * I haven't done this before so would appreciate advice on how many use case examples are required in order to advance this.
  * Thoughts on the API additions welcome - I think I've captured the existing feedback here in a way that can gracefully extend and enhance the current Wake Lock function.

Looking forward to working further to take this forward and help out in any way I can!

GitHub Notification of comment by willmorgan
Please view or discuss this issue at https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-817151517 using your GitHub account

Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config
Received on Saturday, 10 April 2021 15:12:12 UTC

This archive was generated by hypermail 2.4.0 : Monday, 4 July 2022 12:47:58 UTC