Update the interface after the result
Attach success and failure handling to the returned promise, or await it within appropriate error handling. Keep a pending state while the request is unresolved, show the playing state after success, and retain a usable manual control after failure.
The proposed flow is request, pending, then confirmed success or recorded failure. Do not hide the only Play button immediately after issuing the call. MDN notes that permission-related handling can delay the result, so an immediate assumption can misrepresent a request that the browser has not yet accepted.
Distinguish two documented rejection paths
The HTML Standard specifies NotAllowedError when the media element is not allowed to play. It separately specifies NotSupportedError when the element already has the source-not-supported media error. MDN describes browser or operating-system permission restrictions and an unsupported source among the relevant cases.
Log the exact exception name, triggering action and source identity. A permission refusal does not identify a codec failure. Conversely, repeatedly granting autoplay is not a demonstrated remedy for a source the browser cannot support. Other failures can exist, so preserve unexpected names rather than forcing every rejection into these two categories.
Offer a recovery that matches the evidence
For a permission-related refusal, keep an explicit user-activated Play action available and explain that playback needs interaction when that is the observed restriction. Repeat the request through that action and record its outcome. Do not silently loop the same automatic request as though repetition establishes permission.
For source-related evidence, inspect the exact resource and the player’s supported format path. Keep the original failure attached to that resource. A filename extension alone is insufficient to identify its video, audio and container combination, and this article does not claim to perform a compatibility test.
Make developer diagnostics reviewable
Use a minimal authorised reference item and retain browser version, call timing, whether the action came from a user gesture, promise outcome and visible interface state. Keep sensitive source credentials out of any public report.
No browser code was executed for this article. Its value is the state distinction: requested, accepted and visibly playing must not be collapsed into one event. A later playback failure is also a separate observation from the initial play promise having resolved.
Sources and scope
Scope notes distinguish published documentation, supplied information and editorial methods. They do not report a hands-on service test.
- WHATWG: play method and pending promises — Current primary HTML Standard, NotAllowedError/NotSupportedError branches and playing notification promise resolution.
- MDN: play promise guidance — Maintainer developer documentation for asynchronous result, possible delay and UI handling; proposed diagnostic sequence is not executed code.
