Devices and Sensors WG - Screen Wake Lock Brightness follow-up

[rakuco]

Main event URL: https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180

This is happening tomorrow; I've written down some notes to get us started and I didn't know where to put them, my apologies if this isn't the best place.

---

Discussing w3c/screen-wake-lock#129 separately, as there was not enough time to address this at TPAC.

• Main event URL: https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180
• Will's proposal: https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-817151517
• Raphael's summary: https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-951078201

Agreement so far

• There is demand from web developers for some form of brightness control.
• getUserMedia() integration does not fully address the use cases described so far and is not a very good fit for this feature.
  • This feature is not doing media capture.
  • Need to ask for camera permission before e.g. entering full screen mode.

<video> and granular brightness control

The <video> use case initially described here is very different from the other use cases described in the GitHub issue. It might be better handled elsewhere and perhaps as a UA-specific control. We can discuss whether it makes sense to try to support it from a Wake Lock perspective, but I'd be careful not to spend too much time on this exclusively.

Opens

• Tie brightness change request to full screen mode and requestFullscreen()?
  • See whatwg/fullscreen#198 and whatwg/fullscreen#185
• Brightness levels
  • How bright is too bright? Consider 100% brightness with HDR displays, for example.
  • Take a granular value or an enum?
  • Related to whether script should be allowed to reduce brightness.
• Permission model
  • Require user activation in WakeLock.request()?
  • Only when changing screen brightness?
  • Explicitly ask user with UI? Is that an implementation detail?
• How to deal with multiple or external displays
  • Is brightness change expected to affect all displays?
• When a lock is held
  • What if users change the brightness level while the lock is held?
  • What if script wants to change brightness level (assuming some granularity in values we accept)?
• Lock release
  • Does the UA have to restore previous brightness level?
  • What about external displays? Do UAs need to keep track of levels for each display?
  • Should script be allowed to hold the lock indefinitely?
• API draft

Other useful information

• Controlling external displays is done via DDC/CI
  • I've managed to control some of my monitor's settings from Linux
  • Whether and how it works depends on monitor's own presets and enabled settings

Implementation support

Contrary to the existing wake lock code that just prevents the screen from being turned off, there is no code for doing this in Chromium. This may take quite some time to write.

OS support

• Android: we currently use KEEP_SCREEN_ON which doesn't change the brightness level, but as mentioned earlier in this issue I guess we could use BRIGHTNESS_OVERRIDE_FULL, but this means using the highest brightness value rather than something that may be high enough (see "how bright is too bright" above). There's also LayoutParams.screenBrightness.
• ChromeOS: the platform code (outside Chromium-the-browser) has good documentation for what it supports (including external displays). There is some code in Chromium to communicate with the platform and control some of those settings here, for example.
• Linux: KDE and GNOME seem to provide some D-Bus interfaces to change the screen brightness, but there's nothing standardized in freedesktop.org.
• OS X: Maybe this UIKit thing? Only available on Mac Catalyst and later.
• Windows: There's a SetMonitorBrightness function that might do it, but I am not sure if it works for non-external displays as well.

[rakuco]

cc'ing event attendees @reillyeon @anssiko @marcoscaceres @beaufortfrancois @tomayac @willmorgan @xfq @larsgk

[marcoscaceres]

This would only be useful for mobile devices and seems very unlikely (or quite surprising) if one could change the brightness on an external display.

As mentioned in the other issue, the framing around “brightness” is a misnomer or red herring, because the use case is about achieving optimal contrast. Brightness obviously plays a role in achieving contrast, but it’s one factor.

[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]

We should probably move the summary back to the main issue.... otherwise we will split the discussion.

[anssiko]

@rakuco @marcoscaceres we've used this repo for meeting planning purposes. Your summary and comments would be good material for the explainer we committed to.

[rakuco]

Quite a few ideas were presented towards the end of the meeting so I don't fully remember what ended up being agreed, but if I recall correctly the expanded version of the resolution ("Create an explainer for Screen.requestMaximumBrightness() as an extension to CSS OM and send it to CSS WG for comment") was to:

1. Create a Google doc to get this explainer to a more stable version.
2. Put that content into an actual explainer on GitHub.
3. Circulate said explainer within the CSS WG, maybe the WHATWG people working on the Fullscreen API spec and move it forward.

I've done 1) with the contents of this issue put together with what we discussed during the meeting and shared the document with the attendees. It's available for viewing and suggestions here: https://docs.google.com/document/d/1skbEBafMjKnYVC7UoJfRgnnhAkp-jx0k_Z4j6eZeOwc/edit?usp=sharing

One thing that's not clear is where to host the explainer once we move off Google Docs.

[beaufortfrancois]

I've left some comments in the doc. Thank you @rakuco for starting this!

[beaufortfrancois]

What is the current status @rakuco?

[anssiko]

I think there's been adequate time to review the Google doc (thanks for all the comments folks, and @rakuco for creating the doc!), so we can proceed with integrating comments, then drop the content into the explainer template and continue iterate there. When satisfied, circulate with the other groups per our resolution.

One thing that's not clear is where to host the explainer once we move off Google Docs.

Given the origins of this proposal are with the Screen Wake Lock API being worked on in the DAS WG, the scope of this proposal seems to fit within the scope of the WG, the proposal has been discussed here since 2018(!) and we seem to have interested stakeholders on board, I'd propose to host the explainer in an existing repo until we figure out where the API itself will land.

My pragmatic proposal would be https://github.com/w3c/screen-wake-lock/brightness-mode/explainer.md or https://github.com/w3c/screen-wake-lock/brightness-mode-explainer.md but feel free to disagree.

My worry is if we push this proposal with its existing history to a new WICG repo now it gets lost in the sea of proposals.

[rakuco]

What is the current status @rakuco?

Sorry for the silence, I ended up getting busy with other stuff and didn't get notified about changes the doc so I was pleasantly surprised when I looked at it again and noticed there had been a lot of activity :-)

I've incorporated most edits into the doc and converted it to Markdown. w3c/screen-wake-lock#334 adds it to the Screen Wake Lock repository for now. Hopefully people keep working on it and it gets into shape soon so we can move on to the next steps.

[anssiko]

We have an explainer and also a WIP spec draft and Chromium CL (see https://github.com/beaufortfrancois/screen-brightness) so it is appropriate to close this with thanks to everyone who helped the effort take its first steps.

For the time being, we're reusing the screen-wake-lock issue tracker with control-screen-brigthness label for this.