feat: Custom Pixel Ratio

[wseymour15]

Description

An optional customPixelRatio parameter. This enables the ABR algorithm to act as if the player dimensions were multiplied by a number greater than 0. The benefits of this are to manipulate the player to select higher renditions if better quality video is required, or lower renditions if it is desired to save on bandwidth.

Example:
if you have a player where the dimension is 540p, with a custom pixel ratio of 2, a rendition of 1080p or a lower rendition closest to this value will be chosen.

Specific Changes proposed

• Expect an optional customPixelRatio option.
• Multiply the pixelRatio used in our ABR by this value.
• Tests regarding rendition selection
• Documentation

Requirements Checklist

• Feature implemented / Bug fixed
• If necessary, more likely in a feature request than a bug fix
  • Unit Tests updated or fixed
  • Docs/guides updated
  • [ ] Example created (starter template on JSBin)
• Reviewed by Two Core Contributors

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 86.27%. Comparing base (c50ba7e) to head (bce68d9).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1497   +/-   ##
=======================================
  Coverage   86.26%   86.27%           
=======================================
  Files          43       43           
  Lines       10877    10884    +7     
  Branches     2501     2504    +3     
=======================================
+ Hits         9383     9390    +7     
  Misses       1494     1494           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[gkatsev]

shouldn't this use the customPixelRatio directly, unconditionally? That way, there won't be double counting if both useDevicePixelRatio and customPixelRatio are set.

[wseymour15]

This seems like a fairly rare case, but worth mentioning. I figured that if someone set both useDevicePixelRatio = true and customPixelRatio = 2, we would want the final pixel ratio to be cumulative. I could see the case where someone would want to save bandwidth or force higher renditions on top of whatever the device pixel ratio is.

Let me know if this seems wrong, but I do agree with @mister-ben that I can document this better.

[gkatsev]

To me, only using the customPixelRatio seems like a simpler and more straight forward direction. "If it's set, we're going to use this value".
Completely sidesteps needing to worry about the compounding effect. And if someone wanted to do so, they could set it themselves.

[wseymour15]

Fair enough, I do not feel strongly either way. I made updates so we overwrite any previous pixel ratio with this value 👍

[mister-ben]

It might be good to explain in the docs how it works when useDevicePixelRatio is also set. It looks like they're cumulative.

[dzianis-dashkevich]

@wseymour15, great work!