Intent to Implement and Ship: Add informative MediaError.message field

[Matthew Wolenetz]

Contact emails

wole...@chromium.org

Spec

https://html.spec.whatwg.org/multipage/embedded-content.html#dom-mediaerror-message

WHATWG HTML5 spec changed in [1].

W3C web-platform-tests includes test in [2].

TAG review process was skipped since this feature is included now in the WHATWG HTML5 spec.

Summary

The MediaError.message DOMString field provides, if available, any additional vendor-specific error message detail to assist web authors debugging media player errors. The format and content of the string is left to vendors. It is populated at the time of MediaError creation.

Motivation

Previously, the MediaError object only allows standardized exposure of a very small enumeration of error codes (https://www.w3.org/TR/html52/semantics-embedded-content.html#error-codes). Web authors have requested greater detail of errors, even if they are exposed in vendor-specific messages.

A common example is that MSE (Media Source Extensions) emits MEDIA_ERR_DECODE and MEDIA_ERR_SRC_NOT_SUPPORTED from a large variety of places in the spec, and differentiating the actual reason for the error is difficult at best. Services that deliver content via HTMLMediaElement (with or without MSE) and that encounter MediaError errors in the user agent frequently need more detail than just MediaError.code from the user agent to diagnose content, web app or user agent problems, especially when those errors are hard-to-reproduce.

Interoperability and Compatibility Risk

This field is additive, and format and content of message is implementation-specific, by design.

Firefox: Shipped

Edge: Public support. They responded positively to a request for input from W3C participants in [3], improving on their existing vendor-prefixed "MediaError.msExtendedCode".

Web developers: Strongly positive signals from YouTube and others at least at FOMS/Demuxed 2016.

Ongoing technical constraints

None

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

Yes

OWP launch tracking bug

https://crbug.com/710617

Link to entry on the feature dashboard

https://www.chromestatus.com/features/4996058069336064

Requesting approval to ship?

Yes. CL is in review currently at https://codereview.chromium.org/2660003003/

[1] https://github.com/whatwg/html/issues/2085
[2] https://github.com/w3c/web-platform-tests/pull/4638

[3] https://lists.w3.org/Archives/Public/www-archive/2016Dec/0000.html

[4] https://github.com/whatwg/html/issues/2085#issuecomment-262634835

[5] https://developer.mozilla.org/en-US/docs/Web/API/MediaError/message

[Rick Byers]

LGTM1

Note the MDN page claims Chrome, Edge and IE 9 have already shipped this (in addition to Firefox).  I assume that's just a bug in MDN?

[Philip Jägenstedt]

LGTM2

I have tested in Edge and updated MDN to reflect that it's currently not supported. Matt, can you update it again to indicate support in Chrome+Opera once this is enabled?

Also filed bugs for EdgeHTML and WebKit:

https://github.com/whatwg/html/issues/2085#issuecomment-293470039

[Jochen Eisinger]

lgtm3

[wole...@google.com]

Thank you for the approvals. rbyers@, thank you for noticing that  the MDN page was previously incorrect. Thank you for updating it and filing bugs on Safari and Edge, foolip@. I will also update it to note Chrome+Opera support for it once this ships.

[wole...@google.com]

It's become apparent during the code review (https://codereview.chromium.org/2660003003/#msg31) that the shape of the new MediaError.message API may be better if standardized as a sequence<DOMString> rather than just a single DOMString. I'm going to reach out on the WHATWG HTML5 standards discussion to see if they agree, and if so, modify this intent, feature, and CL accordingly.

[wole...@google.com]

Discussion of the potential API shape change is occurring now on https://github.com/whatwg/html/issues/2531

[Matt Wolenetz]

API owners, would you be averse to Chrome shipping the existing (single) message API that's currently in the standard, and with a parseable UA-specific-code followed by an optional " : " + UA-specific-message as described in #2531 (comment)?
I agree that having this UA-specific-code also available without parsing in some new field would reinforce the interop of large players aggregating per-UA-codes, leaving the format of the existing message API as-is in the spec.
Discussion of possibly including multiple "messages" in some portion of the API can also proceed separately, but not block the UA-specific-code field API nor implementations (like Chrome and FF) shipping (single) message.

Context:

Much further discussion on potential API shape change has continued at  https://github.com/whatwg/html/issues/2531.

My understanding is that, since Firefox has already shipped the currently specified version of a single DOMString message, and they have also used a specific format within their message that enables both readability and parseability for aggregating UA-specific-error codes (in the form of a code string prefix followed optionally by a ": " and message detail). Though there were concerns initially about Chrome having a message format that might become a de facto standard, it appears Firefox has already done this and is averse to changing the format. I believe we've pretty much reached consensus to follow the currently spec'ed 'message' API, with implementations aiding developers by trying to conform to the general format that Firefox has already shipped.

I expect there to be a further API field added later to the spec, which is just the UA-specific-error-code itself (without any variable message detail), to enable better interop of web apps collecting and aggregating these codes *without* needing to parse the message field. I expect that new field would be in a separate intent, later.

See https://github.com/whatwg/html/issues/2531#issuecomment-295834441 and https://github.com/whatwg/html/issues/2531#issuecomment-295837015 for more detailed summary.

[Jochen Eisinger]

sgtm

[Philip Jägenstedt]

SGTM2. When we are not the first to ship, I think we should err on the side of matching what others have shipped even when not required by the spec or we don't exactly love it. This format seems fine enough to me, but figuring out how to expose multiple message would be great, but that'd be a separate intent then.

[Rick Byers]

SGTM3 - thank's for the thoughtful consideration Matt!

[Matt Wolenetz]

Thank you, everyone, for the reviews.

MediaError.message landed in trunk on Friday (https://crrev.com/ed8e7091b5b0a51a8c0781f95813a5929c1f8110) and just now merged to M59 (https://chromium.googlesource.com/chromium/src.git/+/e9ea56b10a39d0ec3c0fa81962d6cb0702020586).