Update Media Libraries

Overview

This skill helps update vendored third-party media libraries in Firefox. Each library has its own update process documented in its README and moz.yaml files.

Supported Libraries

Fully Automated (mach vendor)

Manual Update Required (Cannot Auto-Update)

Related Skills

If you have local changes to a Rust crate that you want to test before they're merged upstream, use /vendor-local instead. This skill (/update-media-lib) is for pulling the latest upstream release from remote repositories.

Initial Question: Update Type

IMPORTANT: Before starting any work, determine what kind of update the user needs. If the user's request clearly indicates one type (e.g., they provide a commit URL to cherry-pick, or say "update to latest"), skip the question and proceed directly. Otherwise, use AskUserQuestion:

"What type of update do you need?"

• •Full library update - Update the vendored library to a new upstream version
• •Cherry-pick a specific commit - Apply a single upstream commit to the current vendored source

If the user provides a URL to a specific commit or mentions "cherry-pick", go directly to the Cherry-pick Process section. If the user asks to update to a version/tag or to latest, go to the Full Update Process section.

Cherry-pick Process

Cherry-picking applies a single upstream commit directly to the vendored source without running mach vendor. This is useful for backporting security fixes or targeted bug fixes.

1. •Identify the library and commit - Confirm the library and the upstream commit hash/URL
2. •Read moz.yaml - Check media/<lib>/moz.yaml for the current vendored revision and upstream URL
3. •Fetch the upstream diff - Use WebFetch to get the commit diff (e.g., from Googlesource ?format=TEXT for base64-encoded diffs, or from GitHub)
4. •Verify the diff applies cleanly - Read the affected files in the vendored source and confirm the pre-image (context lines) matches
5. •Ask for Bugzilla number - Use AskUserQuestion to get an optional bug number
6. •Apply the changes - Use Edit to apply each hunk from the diff to the corresponding vendored file (e.g., media/<lib>/libvpx/path/to/file.c)
7. •Build and test - Run ./mach build to verify

Commit format for cherry-picks: If bug number provided:

• •Bug XXXXXX - Cherry-pick upstream <library> commit <short-hash>. <commit-subject>

If no bug number:

• •Cherry-pick upstream <library> commit <short-hash>. <commit-subject>

Verifying compatibility across branches: When the user asks whether a cherry-pick applies cleanly on a specific Firefox release (e.g., Firefox 147):

1. •Find the Firefox release date (use WebSearch)
2. •Find which libvpx version was vendored at that time: git log --oneline --before="<date>" -1 -- media/<lib>/moz.yaml
3. •Read the file at that commit: git show <commit>:media/<lib>/path/to/file.c
4. •Compare the pre-image lines from the diff against the file content at that revision

Full Update Process

1. •Identify the library - Confirm which library needs updating
2. •Check limitations - Verify the library can be auto-updated (see table above)
3. •Read the README - Check media/<lib>/README_MOZILLA or README.md for library-specific instructions
4. •Check moz.yaml - Review media/<lib>/moz.yaml for current version and upstream URL
5. •Ask about commit preference - For two-step libraries, ask user if they want one combined commit or two separate commits
6. •Ask for Bugzilla number - Optionally ask user for a bug number to include in commit messages
7. •Run the update command - Execute the appropriate vendor command
8. •Apply patches if needed - Some libraries require a second step for patches
9. •Build and test - Verify the update works

Update Patterns

Two-step with patches

Libraries with local patches use a two-step process:

# Step 1: Update the source (without patches)
./mach vendor media/<lib>/moz.yaml --patch-mode=none

# Step 2: Apply local patches
./mach vendor media/<lib>/moz.yaml --patch-mode=only --ignore-modified

Two-step libraries: libvpx, libaom, libsoundtouch, libspeex_resampler, highway, libcubeb, libpng, libogg, libyuv

IMPORTANT - Commit Workflow: For two-step libraries, ALWAYS ask the user whether they want:

1. •Two separate commits (recommended by upstream README):
   • •First commit: "Update <library> to <version>" (after step 1)
   • •Second commit: "Apply local patches to <library>" (after step 2)
2. •Single combined commit:
   • •One commit after both steps: "Update <library> to <version> and apply local patches"

IMPORTANT - Bugzilla Bug Number: ALWAYS ask the user if they have a Bugzilla bug number for this update. This should be asked alongside the commit preference question using AskUserQuestion.

If user provides a bug number, format commit messages as:

• •Bug XXXXXX - Update <library> to <version>
• •Bug XXXXXX - Apply local patches to <library>

If no bug number is provided, use the standard format without the "Bug XXXXXX - " prefix.

Use AskUserQuestion to get both the commit preference and optional bug number before proceeding.

Simple vendor

Libraries without patches or with auto-applied patches:

# Update to latest
./mach vendor media/<lib>/moz.yaml

# Or update to specific version/commit
./mach vendor media/<lib>/moz.yaml -r <tag-or-commit>

# Or update from a fork
./mach vendor media/<lib>/moz.yaml --repo <repository-url> -r <commit>

Simple vendor libraries: libdav1d, libvorbis, libwebp, libjxl, libnestegg

Commit format for simple vendor: Ask for optional Bugzilla bug number. If provided:

• •Bug XXXXXX - Update <library> to <version>

If no bug number:

• •Update <library> to <version>

Script-based (libopus)

libopus uses a custom update script integrated with mach vendor:

./mach vendor media/libopus/moz.yaml

The update.sh script is automatically invoked during vendoring.

Script-based (libjpeg)

libjpeg uses a custom update script that requires cloning the upstream repository first.

Known issue with patch step: The script runs patch -p0 from media/libjpeg/, but the patch file (mozilla.diff) contains paths like a/media/libjpeg/jmorecfg.h. With -p0, patch looks for a/media/libjpeg/jmorecfg.h relative to current directory, which doesn't exist. This is documented in MOZCHANGES: "fix up any rejects from applying the Mozilla specific patches".

Workaround: After the script fails at the patch step, apply manually with -p1 from Firefox root (strips the a/ prefix).

Update process:

1. •

   Clone libjpeg-turbo to a temporary directory:

   bash

   git clone https://github.com/libjpeg-turbo/libjpeg-turbo.git /tmp/libjpeg-turbo
   

2. •

   Run the update script (patch step will fail - this is expected per MOZCHANGES):

   bash

   ./media/update-libjpeg.sh /tmp/libjpeg-turbo [tag]
   # Example: ./media/update-libjpeg.sh /tmp/libjpeg-turbo 2.1.5.1
   

3. •

   When prompted about patch failure, skip (press Enter or 'y')

4. •

   Apply the patch manually from the Firefox root directory:

   bash

   patch -p1 -i media/libjpeg/mozilla.diff
   

5. •

   Clean up temporary clone:

   bash

   rm -rf /tmp/libjpeg-turbo
   

Version compatibility:

• •Versions 2.x: Compatible with current file structure
• •Versions 3.x: Reorganized source structure (files in src/ subdirectory) - may require additional work

Commit format: Ask for optional Bugzilla bug number. If provided:

• •Bug XXXXXX - Update libjpeg-turbo to <version>

If no bug number:

• •Update libjpeg-turbo to <version>

Rust crates

Rust crates are defined in /toolkit/library/rust/shared/Cargo.toml and vendored into /third_party/rust/. There are two types:

Git-based Rust crates

Crates with a git URL and rev attribute pointing to a specific commit.

Examples:

• •mp4parse_capi - MP4 parser (https://github.com/mozilla/mp4parse-rust)
• •cubeb-coreaudio - macOS audio backend (https://github.com/mozilla/cubeb-coreaudio-rs, default branch: trailblazer)
• •cubeb-pulse - PulseAudio backend (https://github.com/mozilla/cubeb-pulse-rs)
• •audioipc2-client / audioipc2-server - Audio IPC (https://github.com/mozilla/audioipc)

Update process:

1. •

   Find the current revision in /toolkit/library/rust/shared/Cargo.toml:

   toml

   <crate-name> = { git = "https://github.com/...", rev = "<current-rev>", ... }
   

2. •

   Get the new revision (commit hash or tag) from upstream repository

3. •

   Update the rev attribute in Cargo.toml to the new revision

4. •

   Update Cargo.lock to reflect the new revision:

   bash

   cargo update -p <crate-name>
   

5. •

   Run the vendor command:

   bash

   ./mach vendor rust
   # Use --force if needed for large files
   ./mach vendor rust --force
   

6. •

   Verify expected changes in /third_party/rust/<crate-name>*

7. •

   Run cargo vet to check for missing audits:

   bash

   ./mach cargo vet suggest 2>&1 | head -20
   

8. •

   Add required audits if any crates need certification (see crates.io section below for examples)

9. •

   Include supply-chain/audits.toml in the commit if audits were added

Commit format: Ask for optional Bugzilla bug number. If provided:

• •Bug XXXXXX - Update <crate-name> to <revision>

If no bug number:

• •Update <crate-name> to <revision>

Crates.io Rust crates

Crates with a version attribute, pulled from crates.io.

Examples:

• •cubeb-sys - Cubeb native bindings (bundles libcubeb C code)

Update process:

1. •

   Find the current version in /toolkit/library/rust/shared/Cargo.toml:

   toml

   <crate-name> = { version = "<current-version>", ... }
   

2. •

   Check available versions on crates.io:

   bash

   cargo search <crate-name> --limit 1
   

3. •

   Ask the user what version they want to update to. Present the current version, latest available version, and ask for their preferred target version.

4. •

   Update the version attribute in Cargo.toml to the chosen version

5. •

   Update Cargo.lock to reflect the new version:

   bash

   cargo update -p <crate-name>
   

6. •

   Run the vendor command:

   bash

   ./mach vendor rust
   # Use --force if needed for large files
   ./mach vendor rust --force
   

7. •

   Verify expected changes in /third_party/rust/<crate-name>*

8. •

   Run cargo vet to check for missing audits:

   bash

   ./mach cargo vet suggest 2>&1 | head -20
   

9. •

   Add required audits for each crate that needs certification:

   bash

   ./mach cargo vet certify <crate-name> <old-version> <new-version> --criteria safe-to-deploy --accept-all
   

   For example, when updating cubeb crates from 0.30.1 to 0.32.0:

   bash

   ./mach cargo vet certify cubeb 0.30.1 0.32.0 --criteria safe-to-deploy --accept-all
   ./mach cargo vet certify cubeb-backend 0.30.1 0.32.0 --criteria safe-to-deploy --accept-all
   ./mach cargo vet certify cubeb-core 0.30.1 0.32.0 --criteria safe-to-deploy --accept-all
   ./mach cargo vet certify cubeb-sys 0.30.1 0.32.0 --criteria safe-to-deploy --accept-all
   

10. •

    Include supply-chain/audits.toml in the commit

Commit format: Ask for optional Bugzilla bug number. If provided:

• •Bug XXXXXX - Update <crate-name> to <version>

If no bug number:

• •Update <crate-name> to <version>

Limitations and Known Issues

libaom

• •Issue: generate_sources_mozbuild.sh requires python3-venv system package
• •Solution: Install python3-venv before updating: apt install python3-venv

libdav1d

• •Issue: May require manual moz.build updates for new/removed files
• •Post-update: Check moz.build and asm/moz.build for file changes
• •Note: Assembly files with %if ARCH_X86_64 may need conditional handling

libmkv

• •Issue: Cannot be auto-updated - no vendoring section in moz.yaml
• •Reason: Upstream (Chromium libvpx) is abandoned
• •Status: Maintenance only, manual patches required

ffvpx

• •Issue: Cannot use mach vendor
• •Update method: Manual rsync from FFmpeg source
• •Requires: Platform-specific config regeneration for each target (Unix32, Unix64, Darwin, Windows, Android)
• •See: media/ffvpx/README_MOZILLA for detailed instructions

Key Files

For each library:

• •media/<lib>/moz.yaml - Version info, upstream URL, vendoring configuration, patches list
• •media/<lib>/README_MOZILLA or README.md - Detailed update instructions
• •media/<lib>/*.patch - Local patches to apply

Some libraries store source in third_party/:

• •third_party/dav1d/ - dav1d source
• •third_party/aom/ - AOM source
• •third_party/highway/ - highway source
• •third_party/jpeg-xl/ - libjxl source

Post-Update Steps

1. •Build: ./mach build
2. •Lint: ./mach lint
3. •Format: ./mach format
4. •Cargo vet (for Rust crate updates): ./mach cargo vet suggest - add any required audits
5. •Test: ./mach test --auto

Troubleshooting

• •Build failures after update: Check for new source files not added to moz.build
• •Patch failures: Patches may need updating for new upstream changes
• •Assembly errors on win32: Move x86_64-only .asm files to conditional blocks
• •nasm version errors: May need to update minimum nasm version in toolchain
• •python3-venv missing: Install with apt install python3-venv (for libaom)
• •Uncommitted changes error: Use --ignore-modified flag for step 2, or commit between steps
• •Cargo vet missing audit error: Run ./mach cargo vet certify <crate> <old> <new> --criteria safe-to-deploy --accept-all for each crate, then include supply-chain/audits.toml in the commit