Skip to content
About Blog Learn Explore Patterns Case studies

Debug media playback errors on the web

Apr 12, 2022
Appears in: Media
François Beaufort
François Beaufort
GitHub

Debugging HTML media elements, such as <video> and <audio>, can be hard as decoder implementations vary in what they consider errors (hardware decoders generally being the most strict), especially when a playback may use more esoteric features of a particular codec. Luckily for us, there are a variety of tools we can leverage to help.

Objective

The goal of this section is to give you some tools to debug media playback errors on the web.

When debugging media playback errors, the first thing we usually check out is the MediaError error attribute on the HTML media element. This attribute is a high level hint of what caused the media playback error. The property MediaError.code returns a numeric value which represents the kind of error that occurred on a media element. The other property MediaError.message may provide a string with some diagnostic information from the browser.

const video = document.querySelector('video');
video.addEventListener('error', () => {
console.log('Error code: ' + video.error.code);
console.log('Error message: ' + video.error.message);
});

These properties are most useful for telemetry analysis, and may not always provide enough information to debug playback errors. For privacy reasons, the full error text must sometimes be omitted.

To access complete error information use the Chrome DevTools "Media Panel" to view media logs. You will find plenty of information such as events, warnings, and error messages that will give you some good hints of the media playback errors.

Screenshot of the Media Panel in Chrome DevTools
Media Panel in Chrome DevTools.

You can also use the FFmpeg free application to check media file integrity thanks to this command:

ffmpeg -err_detect explode -i <file> -f null -

Here are some errors you could get with these commands for a video file with invalid codec:

[mov,mp4,m4a,3gp,3g2,mj2 @ 0x7fc62df05380] Could not find codec parameters for stream 0 (Video: none (zzzz / 0x7A7A7A7A), none(smpte170m/smpte170m/bt709, progressive), 320x240, 4 kb/s): unknown codec
Consider increasing the value for the 'analyzeduration' (0) and 'probesize' (5000000) options
[matroska,webm @ 0x7fd45b705380] Unknown EBML doctype '0000'
[matroska,webm @ 0x7f8d17904d40] Element at 0x8b ending at 0x10400000095 exceeds containing master element ending at 0x9b
Truncating packet of size 9069 to 94

The MP4Box.js / ISOBMFF Box Structure Viewer is a useful tool to debugging bitstream issues. It does require already understanding MP4 to use though.

Finally, some video stream analysis professional tools like VQAnalyzer, Elecard StreamEye, and Codecian CodecVisa, may be worth your money.

Media
Last updated: Apr 12, 2022 — Improve article
Return to all articles
Share
subscribe

Contribute

  • File a bug
  • View source

Related content

  • developer.chrome.com
  • Chrome updates
  • Case studies
  • Podcasts
  • Shows

Connect

  • Twitter
  • YouTube
  • Google Developers
  • Chrome
  • Firebase
  • Google Cloud Platform
  • All products
  • Terms & Privacy
  • Community Guidelines

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies.