Revamp WebCodecs documentation

[sb2702]

Description

As per this discussion, I have revamped the WebCodecs documentation by documenting the high level concepts of the core WebCodecs API, as well as adding 3 specific guides:

• A primer on Video Processing
• Usage guide with code examples for how to practically use the WebCodecs API
• Codec selection guide, how to specify and choose a codec string for use in WebCodecs

Motivation

The existing WebCodecs documentation is very sparse and bare compared to other APIs. Having developed WebCodecs applications for several years, the existing docs are not sufficient as practical guides to using the API.

I built https://webcodecsfundamentals.org/, an actual real-world guide to building production WebCodecs applications, both from my experience and with contributions from other devs who've built popular WebCodecs libraries, which is already referenced in MDN and by Chrome Developer Blog and CanIUse.

The motivation for this PR is to actually put the most substantive, core WebCodecs documentation on MDN itself, including pragmatic, core bits of information such as the need to manage encoder.encodeQueueSize which is not documented anywhere, but which is critical for avoiding application crashes when working with WebCodecs.

Additional details

The underlying discussion

Related issues and pull requests

[github-actions]

Preview URLs (4 pages)

• /en-US/docs/Web/API/WebCodecs_API/Codec_selection
• /en-US/docs/Web/API/WebCodecs_API/Using_the_WebCodecs_API
• /en-US/docs/Web/API/WebCodecs_API/Video_processing_concepts
• /en-US/docs/Web/API/WebCodecs_API

Flaws (1)

Note! 3 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/API/WebCodecs_API
Title: WebCodecs API
Flaw count: 1

• macros:
  • Macro domxref produces link /en-US/docs/Web/API/Canvas which is a redirect

External URLs (36)

URL: /en-US/docs/Web/API/WebCodecs_API
Title: WebCodecs API

• https://github.com/bilibili/web-demuxer (1 time) (Note! This may be a new URL 👀)
• https://mediabunny.dev/ (2 times) (Note! This may be a new URL 👀)
• https://w3c.github.io/webcodecs/ (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/ (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/basics/encoded-video-chunk/ (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/basics/muxing/ (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/datasets/codec-support-table/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/WebCodecs_API/Codec_selection
Title: Codec selection

• https://aomedia.org/ (1 time) (Note! This may be a new URL 👀)
• https://github.com/bilibili/web-demuxer (1 time) (Note! This may be a new URL 👀)
• https://mediabunny.dev/ (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/av01.0.05M.08.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/av01.0.08M.08.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/av01.0.12M.08.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/avc1.42001f.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/avc1.42003e.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/avc1.4d0034.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/avc1.64003e.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/flac.html (2 times) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/hev1.1.6.L120.B0.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/hvc1.1.6.L150.B0.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/hvc1.1.6.L180.B0.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/mp3.html (2 times) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/mp4a.40.2.html (2 times) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/opus.html (2 times) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/pcm-f32.html (2 times) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/vorbis.html (2 times) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/vp09.00.30.08.00.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/vp09.00.40.08.00.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/vp09.00.50.08.00.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/codecs/vp09.00.61.08.00.html (1 time) (Note! This may be a new URL 👀)
• https://webcodecsfundamentals.org/datasets/codec-support-table/ (2 times) (Note! This may be a new URL 👀)
• https://www.w3.org/TR/webcodecs-codec-registry/ (1 time) (Note! This may be a new URL 👀)
• https://zenodo.org/records/19187467 (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/WebCodecs_API/Video_processing_concepts
Title: Video processing concepts

• https://github.com/alfg/quick-dive-into-mp4 (1 time) (Note! This may be a new URL 👀)
• https://mediabunny.dev/ (1 time) (Note! This may be a new URL 👀)
• https://www.w3.org/TR/mse-byte-stream-format-webm/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-05-08 01:28:12)

[dalecurtis]

Generally lgtm. Thanks for doing this!

[hamishwillee]

I hope to look at this next week, if @dipikabh doesn't beat me to it.

[hamishwillee]

@dipikabh @wbamberg If you want to have a look and comment you are welcome to so - but please be aware that I expect to give this a final read over and likely merge on Friday.

@sb2702 I've scanned the changes you made since my last review and they look good. I'd like to scan it with all the changes in place. Should be Friday.

[dipikabh]

@hamishwillee Thanks a lot for reviewing these updates!
I won't be able to get to this, so I'll take myself off the list.

[wbamberg]

@dipikabh @wbamberg If you want to have a look and comment you are welcome to so - but please be aware that I expect to give this a final read over and likely merge on Friday.

What Dipika said. This looks like a great update and I'm sure it has had enough review.

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

The WebCodecs specification supports a particular set of codecs, and individual devices and browsers may only support a subset of those. Encoders and decoders must be configured with fully specified codec strings (such as `"vp09.00.40.08.00"` for VP9 or `"avc1.4d0034"` for H.264) instead of ambiguous codec names like `"vp9"` or `"h264"`. The [Codec selection guide](/en-US/docs/Web/API/WebCodecs_API/Codec_selection) provides guidance on choosing an appropriate codec string (see the [Codec Support Table](https://webcodecsfundamentals.org/datasets/codec-support-table/) (webcodecsfundamentals.org) for a complete list of codec strings and their browser support).

The WebCodecs specification supports a particular set of codecs, and individual devices and browsers may only support a subset of those. Encoders and decoders must be configured with fully specified codec strings (such as `"vp09.00.40.08.00"` for VP9 or `"avc1.4d0034"` for H.264) instead of ambiguous codec names like `"vp9"` or `"h264"`. The [Codec selection guide](/en-US/docs/Web/API/WebCodecs_API/Codec_selection) provides guidance on choosing an appropriate codec string (see the [Codec Support Table](https://webcodecsfundamentals.org/datasets/codec-support-table/) (webcodecsfundamentals.org) for a complete list of codec strings and their browser support).

[hamishwillee]

I've scan read through this again. I started doing a few minor tweaks then realized this was mosly grammar - so ran Claude as a grammar checker.

I'm not an expert by any means but this matches my understanding of the domain. The structure is good and so is the flow.

Upshot, is that I am happy with this. It is clearly much better than what it replaces. Thank you @sb2702 !!!