Source code
Revision control
Copy as Markdown
Other Tools
# Media module instructions
Scoped guidance for `dom/media/`. The global `../AGENTS.md` still applies.
These rules do not apply to vendored code, for example
`platforms/ffmpeg/ffmpeg*/`, `platforms/ffmpeg/libav*/` and
`webrtc/transport/third_party/`.
## Read first
Before you change media code, look for a design doc of that area in
`dom/media/docs/` and read it. `dom/media/docs/index.md` lists the docs.
Read `dom/media/docs/Diagnostics.md` when you read a media bug report.
## Review checklists
- Read the checklists in `dom/media/docs/review/` (memory safety, threading,
async lifecycle, IPC, spec correctness) while you write a change, not only
when you review one.
## Find the cause
- Fix the cause, not the symptom. If an assertion fails, find why the state
became reachable. Do not add a guard that tolerates the state.
- For behavior that a web page can see, follow the spec steps. Fix the code
where Firefox does not match the spec, and keep the assertion.
`dom/media/docs/Specs.md` lists the spec for each media area.
- If no real flow can break an invariant, assert it with `MOZ_ASSERT`. Do not
add a clamp or a warning log for it.
- Handle and log a failure that can really occur, for example bad input from
IPC or a decoder error.
## Threads and task queues
- Most media objects belong to one thread or task queue and assert it, for
example `MOZ_ASSERT(OnTaskQueue())` in `MediaDecoderStateMachine` and
`MediaFormatReader`. Keep the change on that thread.
- To reach another thread, dispatch a task or chain a `MozPromise`. Prefer
this to a lock.
- For state that you share with a thread that cannot take a dispatched task,
for example the cubeb callback thread in `AudioStream`, use a lock and
annotate the state with `MOZ_GUARDED_BY`. Follow the rules for the real-time
audio callback in `dom/media/docs/review/threading.md`.
## Async shutdown
- A promise callback or a dispatched task can run after shutdown. Disconnect
each `MozPromiseRequestHolder` at shutdown, and check the shutdown state
before you use the object.
## Process boundaries
- Remote decoders run in the RDD process, the GPU process or a utility
process. CDMs run in the GMP process or in the MFMediaEngineCDM utility
process. The code is in `dom/media/ipc/` and `dom/media/gmp/`.
- Do not trust a size, an index or a state that comes from another process.
Check it where it arrives.
## Platform code
- `platforms/wmf/` builds only on Windows, `platforms/apple/` only on macOS
and iOS, and `platforms/android/` only on Android.
- `platforms/ffmpeg/ffvpx/` builds on all platforms. The system FFmpeg code
builds on all platforms except Windows and Android.
## Logging
- Log with the module and the macro that the file already uses, for example
`gMediaDecoderLog` or `gAudioSinkLog`. Log each new state change. Do not log
a value that a nearby line already logs.
- `xpcom/docs/logging.md` tells how `MOZ_LOG` and about:logging work.
## Prefs
- Most media prefs are in `modules/libpref/init/StaticPrefList.yaml`. Some are
in `modules/libpref/init/all.js`. Some desktop-only defaults are in
`browser/app/profile/firefox.js`, for example `media.gmp-widevinecdm.enabled`.
- A test sets a pref with `SpecialPowers.pushPrefEnv`, or in the `prefs` list
of its test manifest.
## Tests
- Put a new test next to the existing tests of the code you change. To find
them, search for tests that use the same API, class or file, and look for a
`test/`, `tests/`, `gtest/` or `crashtests/` folder in the subsystem.
- Add the test to the manifest of that folder, for example a `mochitest*.toml`,
`browser.toml`, `chrome.toml`, `crashtests.list`, `reftest.list`, or the
`moz.build` of a gtest folder.
- Choose the kind of test by what it checks:
- Behavior that a web page can see: a mochitest, or a WPT when a spec
defines the behavior.
- A crash: a crashtest.
- C++ internals: a gtest.
- Privileged code or telemetry: a browser or chrome mochitest.
- When no folder of the subsystem fits, put mochitests and crashtests in
`dom/media/test/` and gtests in `dom/media/gtest/`.
- WPT paths are under `testing/web-platform/tests/`. A Gecko-only WPT goes in
`testing/web-platform/mozilla/tests/`.
- The media files for the mochitests in `dom/media/test/` are listed in
`dom/media/test/manifest.js`.