Diagnosing media bug reports

This page tells which data in a media bug report shows the cause, and how to capture a media profile and log.

about:support

Important Modified Preferences

Look for media.*, gfx.* and layers.* prefs that are not at their default. Read the value, not only the name: some of these prefs are normal user choices in Settings.

The prefs that most often explain a media bug control hardware decoding (media.hardware-video-decoding.*), the GPU (layers.acceleration.disabled, gfx.webrender.software), the decoders and the CDMs (media.ffmpeg.*, media.ffvpx-hw.enabled, media.wmf.*, media.eme.*, media.gmp-*) and autoplay (media.autoplay.default). To learn what a pref does and what its default is, read its entry in modules/libpref/init/StaticPrefList.yaml, modules/libpref/init/all.js or browser/app/profile/firefox.js. A pref that none of these files has is no longer used, so its value has no effect.

A pref with mirror: once in modules/libpref/init/StaticPrefList.yaml takes effect only after a restart. A pref with mirror: always takes effect at once. A restart after a pref reset applies all of them.

Decision Log

The Decision Log is in the “Graphics” section. The HARDWARE_VIDEO_DECODING and HARDWARE_VIDEO_ENCODING entries tell if hardware decoding and encoding are available. If they are not, the entry gives the reason (blocklist, pref, driver, missing capability) and a failure code.

Media

The “Media” section has the “Codec Support Information” and the “Content Decryption Modules Information” subsections.

Codec Support Information

This subsection shows software and hardware decode and encode support for each codec (H.264, VP9, AV1, HEVC and more). A codec with no support at all shows a missing decoder, not a configuration problem.

Content Decryption Modules Information

This subsection lists the installed CDMs (Widevine, OpenH264, the Media Foundation CDMs such as PlayReady) and their versions. For an EME bug, it shows if the CDM for the key system is present.

Media logs

In a media log, these signals point to the cause. The log module is in parentheses.

  • NS_ERROR_DOM_MEDIA_* and other NS_ERROR_* codes (all modules).

  • The decoder that Firefox chose, for example WMF, AppleMedia, FFmpeg, ffvpx or VPX (MediaFormatReader, PlatformDecoderModule).

  • State changes of Media Source Extensions (MediaSource, MediaSourceSamples).

  • State changes of MediaDecoderStateMachine (MediaDecoder).

  • Network stalls (MediaResource, MediaCache).

Profiles

A media profile records the threads and markers of the media profiler preset. It has threads such as MediaDecoderStateMachine, MediaSupervisor, MediaPDecoder, MediaPEncoder and the AudioIPC callback threads (AudioIPC Client Callback, AudioIPC Server Callback). On Windows, it has markers such as WMFInit DXVA Status, WMFVDecoderCreation Success and WMFVDecoderCreation Failure. Log markers show text such as DXVA failure or NS_ERROR_DOM_MEDIA_*. A generic CPU, JavaScript or networking profile does not show the media pipeline.

For agents, the profiler-analysis skill reads a Firefox Profiler link, and the profile-capture skill records a new profile. Both skills are in the tree.

Read every media thread

Read all media threads, not only MediaDecoderStateMachine #1: each MediaSupervisor #N, each MediaPDecoder #N, the Renderer thread in the GPU process, and GeckoMain. MediaPDecoder threads are in the RDD process. On Windows, hardware decoding is only in the GPU process, so MediaPDecoder threads are also in the GPU process. Read the CPU use and the wait state. A decoder thread that waits (for example in NtWaitForMultipleObjects or ZwWaitForAlertByThreadId) with large gaps between frames does not get work. That is a different bug from a thread that uses all of its CPU.

Hardware decode failure pattern

Repeated DXVA failure: or NS_ERROR_DOM_MEDIA_* entries on Windows can have these causes:

  1. DXVA has no free decoder slot. The log shows DXVA failure: Too many DXVA videos playing. media.wmf.dxva.max-videos sets the limit, and sites with a feed of videos can keep many videos alive.

  2. CanUseDXVA() returns false for the parameters of this video.

  3. Firefox cannot create the D3D11 device, for example after a driver problem or a GPU reset.

WMFDecoderModule::Supports(), which MediaCapabilities.decodingInfo() uses, does not check the free DXVA slots. So Firefox can report hardware decode support while new decoders fail.

In WMF, H.264 has a software fallback. HEVC, VP9, AV1 and VP8 do not: the decoder returns NS_ERROR_DOM_MEDIA_FATAL_ERR when hardware acceleration is not available.

A hang in the RDD or GPU process

To find out if the sandbox causes a hang or a failure in the RDD or GPU process, start Firefox once with MOZ_DISABLE_RDD_SANDBOX=1 or MOZ_DISABLE_GPU_SANDBOX=1 in the environment. Then start Firefox again without the variable.

What a useful report has

Bug type

Data

Playback failure

The media URL or a sample file, the codec or container, about:support, the platform

Recording

Device information, the getUserMedia constraints, a page or snippet that shows the problem

Web Audio

A minimal snippet that shows the problem, the AudioContext configuration, about:support

WebCodecs

A minimal snippet that shows the problem, the codec configuration, about:support

Performance or audio quality

An about:logging capture with the “Media playback” preset, the platform, the steps

GMP or EME

The key system, the platform, about:support

Capture a media profile and log

about:logging records the media log modules and a profile in one capture. The capture is a profile, not a .moz_log file, and it does not start from profiler.firefox.com.

  1. Open about:logging.

  2. Under “Log module selection”, choose “Media playback” in the “Logging preset:” drop-down.

  3. Under “Logging output”, select “Logging to the Firefox Profiler”.

  4. Click “Start Logging”.

  5. Reload the page, then do the steps that show the problem.

  6. Click “Stop Logging”.

On desktop, the profile then opens on profiler.firefox.com. Its “Upload Local Profile” button gives a share URL. On Android, toolkit.aboutLogging.uploadProfileToCloud is true, so about:logging itself offers to save or upload the profile, and shows a “Share URL” after the upload.

Use the “Graphics” preset in place of, or with, “Media playback” when the problem is in the GPU, compositor or overlay path. Use the “WebRTC” preset for calls and the “WebCodecs” preset for WebCodecs.

Gecko Logging tells how about:logging, its presets and MOZ_LOG work. Reporting a Performance Problem tells how to capture and share a profile from the profiler toolbar button.