Split RESTRICTIONS_CANNOT_BE_MET into two errors

[chrisfillmore]

We are seeing a high rate of RESTRICTIONS_CANNOT_BE_MET in our production application. We recently updated from 2.2.8 -> 2.3.3, but I haven't yet determined if that has had an impact on this error rate. At the moment my concern is that there isn't any information provided about the circumstances surrounding the error.

As far as I can tell, there are only two possible causes:

• Restrictions imposed by the client (e.g min/max resolution, bandwidth, or language preferences)
• Restrictions imposed by the CDM (key status of output-restricted or internal-error)

It would be helpful if we could differentiate between the two. In particular, if the CDM imposed some restriction, it would be nice to know what the key status was. Then I could follow up with our DRM people about what restrictions are imposed by the license.

[ismena]

Yes, it's those two cases.

I think we could split the RESTRICTIONS_CANNOT_BE_MET error into two to distinguish between application and key system restrictions.
Note: to be able to provide key status for the key system restrictions case we will have to propagate it all the way from parsing key ids in player.js where we set variant.allowedByKeySystem.
There is also the case when different variants failed different restrictions (some weren't allowed by an application, some - by key system possibly with different key statuses).

Alternatively we could log the reason when we see an unmet restriction for a variant. This would require minimal changes to the code, but won't be as effective in communicating the cause of the error to the developers.

@chrisfillmore would logging work for you?

@joeyparrish would you schedule this as you see fit?

[chrisfillmore]

Thanks @ismena. Logging would not help because I'm often working backwards from data which tells me that our users encounter this error in the wild, but we don't actually have a reproducible test case (yet).

I see the problem you're describing. Variants may be restricted for a variety of overlapping reasons. It could be that all variants are restricted, but for different reasons.

Perhaps restrictions need to be more formally defined in the player, and the collection of all restrictions can be passed along with the error. This is just a thought, and would need some fleshing out.

[chrisfillmore]

Having said that, splitting the error into two would, on its own, be extremely helpful. :)

[ismena]

In that case we could probably start by splitting the error to help you short term and discuss the possible refactoring to make more information about this available further down the road.

Let me be arrogant and schedule splitting the error for v2.5. If it gets pushed back, you'll know I got in trouble with @joeyparrish ;)

[chrisfillmore]

@joeyparrish I am confirming with our product team but I believe we have two basic requirements:

1. Need to notify the user that they can't connect a non-HDCP-compliant external display
2. Need to notify the user that some variants (e.g. 4K) are restricted

I expect that this would require some non-trivial refactoring in Shaka. Do you think it is feasible for 2.5? I am happy to contribute if we agree on a design (and if product confirms we need this).

[TheModMaker]

I am thinking that it will be too simplistic to throw a different error based on app vs key system restrictions. There can be different variants that are restricted for different reasons and having different error codes would require us to pick which cases to favor and throw a not-so-accurate error message.

How about instead adding something to the data field of the error to indicate what the restrictions were? So you could get error.data[0] and it might be something like:

{
  hasAppRestricted: false,    // App-applied restrictions
  hasMissingKeys: true,       // Don't have the required keys
  hasOutputRestricted: true,  // Key system output restriction
}

The above would indicate that some streams have output restricted and some don't have the required keys. This would allow you to handle them separately and construct an accurate error message/response.

[chrisfillmore]

Edit: reflecting on it some more, I realize you're right. The app may have selected a minimum bitrate of 3Mbps, leaving some playable higher level variants, but high level variants could end up producing an error due to misconfiguration at the headend. Your plan sounds good to me.

Would it be possible to include detailed information? Such as:

• keyId(s) in the event of missing keys
• the key status if output was restricted

Here's what I think:

1. App-level restrictions which lead to no playable variants should result in a failed assertion with no error code. This is developer error IMO; clients should listen for the streaming event to set appropriate min/max bitrates and languages. Is there any reason this shouldn't work?
2. Missing keys and restricted output should have separate error codes. These error scenarios do not seem logically related to me. Missing keys is likely the result of misconfiguration at the headend (assuming the browser and player are behaving as expected), and restricted output is usually (I think) the result of user error (connecting to non-HDCP compliant display, for instance). These should not share an error code IMO.

If (1) is too onerous, then I actually think RESTRICTIONS_CANNOT_BE_MET should be split into three error codes.