Need maximum screen brightness mode

[tomayac]

Apart from low-power mode (#84), this issue makes the case for adding a way to ask for maximum screen brightness mode, for example, to read QR codes (described in this use case issue). Here is a real-world example from Starbucks:

[mounirlamouri]

Isn't this orthogonal to this API? Should it be part of an API to control screen brightness? Do we know how these applications do this in current platforms (Android/iOS)?

[tomayac]

That’s the iOS way: https://developer.apple.com/documentation/uikit/uiscreen/1617830-brightness. I think it makes most sense as part of Wake Locks, as it’s generally considered a system-level thing to change, and native apps only request maximum screen brightness for allowing for codes to be read (iOS Wallet for general cards/tickets, DB Navigator as an example of a German train ticketing app).

[mounirlamouri]

Well, both Android and iOS platforms offer direct access to the screen brightness. We have a Screen interface on the Web. Why not expose this information there?

[marcoscaceres]

It's a strange one... @tomayac implies that it's declarative - because of intent... Could be imperative, but that seems kinda scary that any random web page could start having fun with the brightness.... could also even be a css thing, where you can request the brightness, but then the OS/browser can handle the request based on environmental conditions (e.g., if it's night or day).

[mounirlamouri]

I am not certain that moving the accessibility to maximum is very different from being able to set it to anything. Reading it is a different issue as it will be a fingerprinting surface.

[tomayac]

Judging from what I personally have seen with native apps, the only instance where I have encountered an app override the current system-level brightness is the (QR, bar-) code reading case.

I wouldn’t want (Web) apps to be able to read or modify my screen’s brightness apart from the use case described before. So I would argue for thinking of this as declarative.

[mounirlamouri]

I do not think that setting the brightness to an arbitrary value or setting it to maximum is any different with regards to potential for abuse. Reading brightness would however be a fingerprinting issue. Either way, I think we may be able to find a better home for this use case.

[tomayac]

I think we may be able to find a better home for this use case

@mounirlamouri Are you thinking of exposing a dedicated Web Screen Brightness API? One thing I (hopefully correctly) took away from @marcoscaceres' TPAC session slot (10:15AM on Friday) was that the general direction was to reduce the number of APIs on the Web Platform? Do you want to let individual browser tabs control (i.e., let write, but not read) their brightness?

[tomayac]

CC: @HenrikJoreteg

[mounirlamouri]

I'm all for having less APIs but we shouldn't just move feature requests to other APIs just to avoid creating a new spec and API surface. If we believe the feature is worth having and we can't build it on top of another one, we should create another API. I would say that it would make more sense in the spirit of Marcos' comment to have an API to set the brightness instead of an API to set the screen to full brightness as if we need an API to set the brightness someday, it would create another API surface.

[HenrikJoreteg]

Hey folks! 👋 I'm the dev who first built that barcode screen on the Starbucks PWA.

I just have a couple of points of feedback. In my opinion, this is all in the interest of better supporting an entire class of applications that involve scanning a phone screen with a barcode reader. Insufficient contrast sometimes makes this harder, which is incredibly annoying. In the case of starbucks, if the PWA screen scan fails, then having to switch to the native app, or otherwise problem solve with the barista is incredibly frustrating. It transforms the experience from: "wow this is cool, look what a tech-savvy coffee-drinker I am" into "Crap, this is embarrassing, this app sucks, etc."

The main thing I originally asked for when we brought this up to Dion and others at Google a couple of years ago now was specifically:

1. A permission-gated way to temporarily ask for screen brightness to go to 100%
2. A way to ask the phone to stay awake so you don't pull it up while waiting in queue at starbucks, then find yourself trying to tap the screen to keep it awake while you're waiting for the person in front of you to order their orange mocha frappuccino with extra whip and sprinkles :)

I would imagine an API for this being something along the lines of:

window.requestWakeLock({fullScreenBrightness: true, timeout: 60000})
  .then(() => {
    // lock succeeded!
  })
  .catch(() => {
    // failed or rejected
  })

I really don't think there's a great usecase for reading screen brightness, or setting a specific brightness. It cause fingerprinting issues and frankly, feels like an OS-level concern that the user should get to decide. Again, this is all about enabling reliable scanning of phone screens.

The reason I suggested passing fullScreenBrightness as an option to a primary API of requestWakeLock instead of doing something like requestFullScreenBrightness is because I could see games and such wanting to prevent screens from falling asleep even if the user isn't tapping on the screen. Sometimes there are long in-game videos or animations where avoiding the screen going to sleep would be nice. So doing a wake-lock without adjusting screen brightness seems like a valid use case.

And, I think any time you want to enable screen scanning (barcodes, etc), it makes sense to keep the screen alive as often there's waiting involved, and having the screen go to sleep while actively trying to scan a phone is super annoying.

Anyway, that's just my two cents. I would love to see something along these lines land in browsers. Seems like something that would improve UX on the web for a large number of use cases.

[marcoscaceres]

@HenrikJoreteg, great feedback. Thank you. What you propose makes sense.

[mounirlamouri]

I think we should differentiate these three things:

• is the use case valid for the Web?
• should we design an API resolving this specific use case or resolving this use case among other things?
• should we hard link this feature to Wake Lock?

In my opinion, even though the use case is valid and we should resolve it, it's unclear that it's a good idea going forward to try to resolve this use case specifically. In general, the Web Platform is looking at offering low level APIs as high level APIs end up too limited. I think that we could offer a better API if the app could simply set the brightness from 0 to 1 with pretty much the same threat model. Furthermore, linking the API to Wake Lock creates a similar limitation: even though for scanning use cases (eg. Starbucks), linking the two APIs make sense, as a platform, we need to think beyond this and we shouldn't assume anyone interested to change the brightness wants the screen to stay on.

[jyasskin]

There's a small risk of DoS if we let sites reduce the screen brightness, since users might not then be able to see the screen well enough to undo it. A separate API could, of course, deal with that risk, perhaps by forbidding sites from decreasing the brightness, or by showing a different prompt if the brightness is going down from when it's increasing.

Even after the Extensible Web Manifesto, we sometimes decide to provide a high-level API if it means the permission prompt can be simpler. This doesn't prevent us from also providing the low-level API with a scarier permission prompt.

So, what would the permission prompt look like for the brightness-setting API? Is it as acceptable to ask for forgiveness in that case as it is for wake-locks, given the concern above?

Will the extra complexity in defending against DoS slow down implementation of the lower-level API, when we might be able to get the wake-lock version sooner?

[HenrikJoreteg]

I personally can't think of a single good use case for wanting to set a specific brightness. This is not something I can imagine wanting as a user. To me that feels like a website reaching a hand out of my screen, opening my settings and moving the slider back and forth. As a user, that just seems wrong. That's an OS-level concern.

The only exception I've been able to think of is this screen barcode scenario. And the only reason I would be OK with that, as a user, is because it provides a very specific utility: It temporarily turns my phone into a concert ticket, boarding pass, etc. Under no other circumstances would I want a web app to mess with my screen brightness.

The truth is, even in that scenario I don't love the idea of a website having that power. But I'm perfectly happy to temporarily give it the power to transform my phone into a replacement for a paper boarding pass.

[marcoscaceres]

I have to agree with everything @HenrikJoreteg said. The only use case we have identified is "wake lock" (cooking a recipe, reading a book), and optionally and temporarily requesting full brightness (e.g., Starbucks, Eventbrite, and airline apps) ... we might not even need the timeout, it could just disable when the user performs and action such as turns off the screen, switches tabs, etc.

I also would definitely not want a website screwing around with the brightness level for random reasons, specially because on brightness adapts dynamically to the environment and time of day.

In my mind, the only question is around permission for bumping the brightness up.

[tomayac]

+1 to Henrik's and Marcos' comments. The brightness bump should also definitely require a user gesture, like, for example, opening a view in the app with a barcode (the gesture would be tapping something).

[marcoscaceres]

"triggered by user activation", as the cool spec kids say 😎 (really, 🤓)

[HenrikJoreteg]

There needs to be a corresponding way to cancel the wake lock as well. Maybe the promise returns an object with a .clear() method.

[marcoscaceres]

Would what’s already in the spec not work?

navigator.getWakeLock("screen", {fullBrightness: true}).then(wakeLock => {
  var request = wakeLock.createRequest();
  setTimeout(() => {
    request.cancel();
  }, 1000);
});

[HenrikJoreteg]

@marcoscaceres I'm late to the discussion here forgive me, yes that seems reasonable. 👍

[mounirlamouri]

I have to agree with everything @HenrikJoreteg said. The only use case we have identified is "wake lock" (cooking a recipe, reading a book), and optionally and temporarily requesting full brightness (e.g., Starbucks, Eventbrite, and airline apps) ... we might not even need the timeout, it could just disable when the user performs and action such as turns off the screen, switches tabs, etc.

Designed an API only based on use cases and not trying to expand from them seems dangerous and may end up with design flaws. Offering a larger ability will trigger new use cases we did not think of. One issue that may happen in the future is that full brightness will end up way too bright on some phones. With HDR getting more popular, display brightness will increase and we could end up in a situation where full brightness will simply be way too bright in some cases.

Also, brightness changes on mobile OSes, as far as I can tell, are specific to the application (Activity, on Android, I believe). Similarly, brightness changes should only apply to the tab, ideally in fullscreen even. I wouldn't worry much about applications trying to change the brightness as they wouldn't have an effect unless they are visible and the UA could put min values to make sure they don't attempt to keep the screen black.

[HenrikJoreteg]

@mounirlamouri if full brightness is too bright then how would you propose an app deal with this? Are you suggesting it would be better perhaps to set a target brightness in lumens?

In my opinion, the best APIs are where you clearly and succinctly express intent. So perhaps rather than arbitrarily saying "full brightness" what if it was something along the lines of "optimizeForScanning"? Or even "optimizeForContrast"

[marcoscaceres]

@mounirlamouri wrote:

Designed an API only based on use cases and not trying to expand from them seems dangerous and may end up with design flaws. Offering a larger ability will trigger new use cases we did not think of.

I'm sympathetic to this argument - but the potential to abuse and user annoyance as we described above is too obvious and great. Fine grained control is definitely not something we would consider implementing in Firefox.

I wouldn't worry much about applications trying to change the brightness as they wouldn't have an effect unless they are visible and the UA could put min values to make sure they don't attempt to keep the screen black.

I worry :( I don't think I can sell this internally.

@HenrikJoreteg wrote:

In my opinion, the best APIs are where you clearly and succinctly express intent. So perhaps rather than arbitrarily saying "full brightness" what if it was something along the lines of "optimizeForScanning"? Or even "optimizeForContrast"

I guess we could go down this route, but we've only come up with the a single purpose. We could make a working assumption that "optimizeForContrast" is the default, and then enhance the API if we come up with other things (based on actual apps needing to do actual things - like StarBucks).

[HenrikJoreteg]

I'm all for the simplest option. Are we aware of any scenario where max brightness would be a bad thing?

[marcoscaceres]

So, played with a few native apps. I don’t think we want a permission prompt. It should just be “triggered by user activation” (if the OS allows it).

[jyasskin]

Amusingly, if the "screen" wakelock is implemented on Android with https://developer.android.com/reference/android/view/WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON, as https://developer.android.com/reference/android/os/PowerManager.html#SCREEN_DIM_WAKE_LOCK recommends, we'll get max-brightness automatically. Maybe the web should follow along and have high-brightness implied by "screen".

[mounirlamouri]

The documentation is slightly confusing. It doesn't give max brightness but keeps the brightness as it is. This in in opposition to the solution that reduces the brightness but never shuts down the screen.

[beaufortfrancois]

• As far as I can see, nobody seems to be particularly interested in lowering the brightness level: the use cases listed so far all seem to benefit from raising the brightness level, temporarily or not.

Media players would need to control brightness level from 0 to 100%, not just raising it.

[rakuco]

• As far as I can see, nobody seems to be particularly interested in lowering the brightness level: the use cases listed so far all seem to benefit from raising the brightness level, temporarily or not.

Media players would need to control brightness level from 0 to 100%, not just raising it.

I wonder if this should be <video>'s concern or even some UA-specific control for media playback? It's hard to say what WebKit's actual implementation in that patch will look like, but it looks closer to the latter.

[beaufortfrancois]

If this comes to <video> I believe web developers using custom video players will want it as well.

[marcoscaceres]

For <video> + brightness, we might need to have a discussion with a wider set of stakeholders (although we have a good set of people here already). It does feel outside the scope of this work tho.

I think there is still something to be done about declaratively boosting brightness (exclusively on mobile) when acquiring a screen wake lock… though I’m not 100% convinced it shouldn’t be gated on being in full screen mode. 🧐

[beaufortfrancois]

FYI I've pinged @mwatson2 from Netflix for their input.

[mwatson2]

For Netflix's part, we think granular brightness control for video could be useful. For desktop monitors, brightness controls are not always easily accessible so offering an obvious easy control could have value. Most laptops have easily accessible keys for screen brightness, so in that context offering users another control may not be as valuable.

The brightness setting that is appropriate for desktop computing may not be the same one that is best for video viewing, especially if the user has an HDR display and is going to turn down the ambient lighting for viewing, be further from the display etc.

And, then, on the use-case for barcode readers on mobile devices, 100% brightness may not be the best setting if the device has a very bright HDR display. It may just be much brighter then necessary, rather than functionally too bright, but the device is potentially going to be in that state for a while as the people ahead order their frappa-mocha-whatevers. Perhaps if there is to be a boolean option for that use-case it should be spelled out that what is required is that the brightness / contrast be set such that a barcode can be easily read in a wide range of environments.

[marcoscaceres]

Thanks @mwatson2!

I think you've totally nailed it: we've been thinking about brightness as the means to create contrast, when we should have left it to the UA/OS to determine the ultimate contrast: the OS and UA is in a better position than the developer to create the optimal display contrast by taking into consideration various sources/sensors (e.g., ambient light), environmental conditions, type of display, user/a11y preferences, and even time of day.

And.... now I have an excuse to buy a HDR display 😄.

For screen wake lock, I'd supportive of a adding a simple "needs high contrast" optional flag.

[rakuco]

For screen wake lock, I'd supportive of a adding a simple "needs high contrast" optional flag.

Hmm, I wonder if that's actually doable from an implementation perspective though. Some OSes seem to at most allow setting a specific brightness value or percentage, but I'm not sure there's an equivalent to "find out what the best value for high contrast is and use that".

[marcoscaceres]

Hmm, I wonder if that's actually doable from an implementation perspective though. Some OSes seem to at most allow setting a specific brightness value or percentage, but I'm not sure there's an equivalent to "find out what the best value for high contrast is and use that".

The way I'm imagining it being implemented is that, for instance, if the OS doesn't provide anything, the browser can initially just set the brightness to max brightness (least effort, gets the job done!)... however, as "computers get smarter"™️ this could get incrementally better/smarter over time by the browser or OS accessing more sensor data without exposing that to the web page.

[rakuco]

The way I'm imagining it being implemented is that, for instance, if the OS
doesn't provide anything, the browser can initially just set the brightness
to max brightness (least effort, gets the job done!)... however, as
"computers get smarter"™️ this could get incrementally better/smarter over
time by the browser or OS accessing more sensor data without exposing that
to the web page.

"How bright is too bright" is something we need to discuss, but this sounds more doable and does make sense :-)

[marcoscaceres]

Just adding another data-point... I'm unsure if it's a thing on mobile, but displays allow adjusting both brightness and contrast:

Was also thinking what might be worth exploring is if requesting high contrast with the screen wake lock should trigger "prefers-contrast: more" of MQ5... that could be kinda interesting.

At least... it might be good to also bounce this off @frivoal or other CSS folks.

[marcoscaceres]

Looking at contrast controls on MacOS/Accessibility:

[frivoal]

Was also thinking what might be worth exploring is if requesting high contrast with the screen wake lock should trigger "prefers-contrast: more" of MQ5... that could be kinda interesting.

I suspect the answer should be no. This is not a user preference or an environmental factor, this is just a (temporary) state of the application, so there's not reason to restyle everything. And even if restyling was desired for a particular app, the switch is triggered by the app, not the user, so it already knows about this state change and doesn't need a MQ to learn about it. If you think we should investigate that further, could you file an issue into the csswg repo?

[marcoscaceres]

Thanks @frivoal (and great points)! We are currently putting together a design doc that explains the use cases we are exploring with respect to brightness and trying to make a case for what we need. We will definitely want to get feedback from the CSS WG.

[anssiko]

CSS WG review requested: w3c/csswg-drafts#6990

[svgeesus]

One issue that may happen in the future is that full brightness will end up way too bright on some phones. With HDR getting more popular, display brightness will increase and we could end up in a situation where full brightness will simply be way too bright in some cases.

HDR simply cannot be punted down the road or you will have an unusable, even dangerous, API.

For HDR, the appropriate term is media white which is comfortably viewable full screen differs, vastly, from the peak white which is blindingly white, can only be displayed on a small area, and will trigger high power usage.

For SDR, plain ordinary #FFFFFF white is the same ad `media white'.

[svgeesus]

the browser can initially just set the brightness to max brightness (least effort, gets the job done!

For SDR, maybe (but increasingly, that is likely to be too bright).

[willmorgan]

@svgeesus

HDR simply cannot be punted down the road or you will have an unusable, even dangerous, API.

For HDR, the appropriate term is media white which is comfortably viewable full screen differs, vastly, from the peak white which is blindingly white, can only be displayed on a small area, and will trigger high power usage.

I wonder how "too bright" is defined. Can we protect this from abuse using feature policy and permission gating?

I have an HDR phone which goes to full brightness when displaying barcodes going about daily life, as well as some larger HDR phones which are pretty bright - do these fit your designation of unusable/dangerous? If yes, in what way? Is that mitigated in native environments?

[max-keviv]

Hi all, I am looking to increase the brightness in mobile web page for QR ticket Scanning, but couldn't find any web api for this, is there any work around this possible

[tomayac]

There has been a lot of discussion around this feature request, which resulted in an Explainer, but no browser implements this. I'm also not sure there's universal agreement on the currently proposed API shape.

[anssiko]

@max-keviv thanks for your use case proposal. A QR scanning use case was identified and documented in the earlier Explainer for a programmatic API. Additional use cases were discussed in #341 Perhaps a bit confusingly, the latest Explainer for an alternative declarative approach is a separate document and doesn't incorporate any use cases.

Please review both the explainers and let us know your preference and share any additional information if we're not already capturing you use case. I remain optimistic we will see this new capability in browsers given sustained demand. In my experience some web features just take longer to bake in for various reasons. Your feedback do make a difference.

[max-keviv]

@anssiko sure thanks, I had gone through both the Explainer, I believe my use-case is well covered in the both the Explainer while the earlier explainer looks more intuitive the latest explainer offer more clean approach but I'm not sure how well we can know

if device does not support partial screen brightness boosting or not

[anssiko]

@max-keviv thanks for your review and feedback. While the explainers lack the level of detail (by design) to answer your question explicitly, my hunch is the intent of the latest explainer is to make that an implementation detail. That is, on implementations that do support partial screen brightness boosting that is the preferred means, and if not supported, then increase the overall screen brightness. This design allows the implementations to evolve over time while keeping the API contract intact. This is quite typical design pattern for Web APIs in general. If this type of higher-level abstraction does not support your use case, we'd like to hear that so we can look into other means to accomplish what you need.