Editorial review: Add docs for MediaTrackSettings.screenPixelRatio

[chrisdavidmills]

Description

Chrome 136+ supports the MediaTrackSettings.screenPixelRatio property, on desktop only. See https://chromestatus.com/feature/6738236535472128 for details.

This PR adds a ref page for the new property.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs

• /en-US/docs/Web/API/MediaTrackSettings/screenPixelRatio
• /en-US/docs/Web/API/MediaTrackSettings
• /en-US/docs/Web/API/Screen_Capture_API

Flaws (2)

Note! 2 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/MediaTrackSettings
Title: MediaTrackSettings
Flaw count: 2

• macros:
  • Can't resolve /en-US/docs/Web/API/MediaTrackSettings/resizeMode
  • Can't resolve /en-US/docs/Web/API/MediaTrackConstraints/resizeMode

(comment last updated: 2025-07-04 08:58:42)

[guidou]

lgtm % link to the spec

[guidou]

spec link: https://w3c.github.io/mediacapture-screen-share/#dfn-screenpixelratio

[chrisdavidmills]

spec link: https://w3c.github.io/mediacapture-screen-share/#dfn-screenpixelratio

I added spec/browser compat data for this feature in mdn/browser-compat-data#27092, so that data should appear as soon as we resolve what to do with the issue highlighted in the description.

I think in the meantime this PR can be put forward to the editorial review stage. Thanks for the tech review, @guidou!

[wbamberg]

I found this page quite hard to understand.

There's a very technical description of the property, repeated word for word, twice:

a double-precision floating point value indicating the ratio of the size of a CSS pixel on the capturing screen by the vertical size of a pixel on the captured display surface

The "value" has an additional sentence which is a direct quote from the spec.

The description seems to be taken from the chromestatus entry, and I kind of understand it, on its own, but there's nothing there that connects the general explanation with how exactly I could use this property to meet the use case described.

It also has hedging terms like "The logical resolution is normally lower than the physical resolution". What is "normally" doing here? When is it, when isn't it? And how is this reflected by the screenPixelRatio property? That is, how can examining the value of screenPixelRatio tell me whether it is or not? The definition of this property doesn't mention physical resolution at all.

My understanding of this property is something like:

If a user has the display zoomed in, then the physical resolution is greater than the logical resolution. In a case like this, it's a more efficient use of bandwidth for the sender to capture the video at the logical resolution and send the video at that resolution, and for the recipient to then reapply the zoom when they receive the video stream.

The screenPixelRatio property describes the ratio of the physical size of a pixel to its logical size, and therefore enables the application to work out how much of a zoom has been applied, and then constrain the video to the logical size.

Is that about right? If so I think it's important to say this. It's important to connect the technical definition of the property with the use case given in the description.

[chrisdavidmills]

I found this page quite hard to understand.

@wbamberg thanks for your thoughtful comment here. I agree that the wording is a bit complicated. I've pushed another commit that simplifies and de-duplicates, and also takes your wording into account.

[wbamberg]

This first sentence is quite complex, but AIUI "by" is the word used to connect the two values being compared in the ratio, right? Why "by"? Usually I'd expect the connector in a ratio to be "to". And AIUI the value is positive if the physical size is greater than the logical size, so wouldn't that make it "the ratio of [physical size] to [logical size]", i.e. the physical would come first?

See e.g. https://en.wikipedia.org/wiki/Ratio:

if there are eight oranges and six lemons in a bowl of fruit, then the ratio of oranges to lemons is eight to six (that is, 8:6, which is equivalent to the ratio 4:3). Similarly, the ratio of lemons to oranges is 6:8 (or 3:4) and the ratio of oranges to the total amount of fruit is 8:14 (or 4:7).

I also think it would be helpful to clarify the connection between "CSS pixel" and "logical size", and "vertical size of a pixel" and "physical size". This intro and the value talks only about the first set of terms, and the description talks only about the second set. I assume they are the same(?) but as a reader I should not have to make that assumption.

[wbamberg]

Is the underlying issue here only about zoom levels? If so, it would be nice if this concept were introduced here, and the connection made between zoom levels and different values for this property.

[chrisdavidmills]

Right, OK, you've made some good points here. I've adjusted the wording as suggested, and made the terminology more consistent.

I've also tested it slightly more thoroughly, adjusted the description of why the difference in ratio occurs, and added some example value explanations.

[wbamberg]

Suggested change

	A video-conferencing app can save bandwidth and CPU when the captured screen is zoomed in on the sender side by:
	If the screen in the sender is zoomed in, then the physical resolution is greater than the logical resolution, and a video-conferencing app can therefore save bandwidth and CPU by:

[chrisdavidmills]

used, but tweaked a little bit.

[wbamberg]

Sorry if this is a stupid q, but how does the receiver side know whether/how much to reapply the zoom?

[chrisdavidmills]

You'd send the screenPixelRatio value over with the captured stream, and then zoom the video by that amount on the receiving end.

[wbamberg]

This could also use some more explanation IMO.

We could say something like:

In this example, the application defines a constant RESOLUTION_LIMIT, which represents the scaling factor beyond which which the sending application should send video at the logical resolution rather than the physical resolution.

When screenPixelRatio exceeds this limit, the application uses the screenPixelRatio value to calculate the logical resolution from the physical resolution, and then constrains video capture to the logical resolution.

[chrisdavidmills]

Sure, added, but tweaked.

[wbamberg]

Suggested change

	if (track.screenPixelRatio > RESOLUTION_LIMIT) {
	if (settings.screenPixelRatio > RESOLUTION_LIMIT) {

I think?

[chrisdavidmills]

Yup, good spot. Updated.

[wbamberg]

Can all be const.

[chrisdavidmills]

Good call; updated

[wbamberg]

Thanks for your work on this Chris, I'm approving.

But, what do you want to do about BCD? At the moment the spec and BCD sections look pretty sad.

I read mdn/browser-compat-data#27092 and mdn/browser-compat-data#27119.

It is tricky because yes, BCD doesn't represent dictionaries, and this makes sense really because there's no compat story about "just data" - data doesn't do anything, and when nothing is done, there's no compat story.

What I would do here is:

• not include BCD for this page
• add a subfeature to getSettings that captures the fact that the returned object includes screenPixelRatio, and tie the BCD to that. I don't know if there's a convention for adding subfeatures like "the returned object has property foo set".

[chrisdavidmills]

Thanks a lot @wbamberg, these are good suggestions

What I would do here is:

* not include BCD for this page

I've removed the BCD section for now, and added a direct spec-urls entry to the frontmatter so that the spec table shows up.

* add a subfeature to [`getSettings`](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings) that captures the fact that the returned object includes `screenPixelRatio`, and tie the BCD to that. I don't know if there's a convention for adding subfeatures like "the returned object has property `foo` set".

I'll investigate doing this as my next port of call, and see what the BCD folk say about it.