# Rebuilding the distributed browser libraries

Use the version in `manifest.json`. The JavaScript core and AAC/AC-3/FLAC/MP3
extensions come from Mediabunny 1.65.2. The source ZIP omits unrelated
packages and generated codec binaries. Do not run the upstream
whole-monorepo `npm run build`, which also expects those unrelated packages.

1. Extract the matching `mediabunny-*-source.zip` and run `npm ci --ignore-scripts`
   in its root, using the included `package-lock.json`.
   For the AAC wrapper, apply `aac-encoder.patch` from `packages/aac-encoder`
   with `git apply --include=src/encoder.ts <path-to-aac-encoder.patch>` before building.
2. Rebuild the native codec and C bridge using the instructions in
   `packages/<codec>/README.md`. Use the adjacent FFmpeg or LAME source
   archive, or the pinned upstream libFLAC revision linked in `NOTICE.md`,
   not an unpinned checkout of its latest branch. The generated glue
   goes in that package's `build/` directory: create that directory first, since
   generated build directories are omitted from these source ZIPs. For a fresh
   FFmpeg extraction, skip the upstream `make distclean` step that assumes a prior
   configure/build. The AAC and AC-3 README files pin Emscripten
   4.0.21 (`d6f42310010ddec0753a69bab01a4b33aae255b7`) and its exact flags.
   The FLAC/MP3 README does not pin Emscripten: bit-identical reproduction
   of those codec binaries has not been established.
3. Save the following as `cutt-rebuild.mts` in the extracted Mediabunny root.
   It uses the upstream worker-inlining plugin and browser ESM build settings
   for only the requested library. The preferred source and upstream build
   scripts themselves are unmodified.

```ts
import { build } from "esbuild";
import { inlineWorkerPlugin } from "./scripts/esbuild/inlined-workers.js";

const name = process.argv[2];
if (!["core", "aac-encoder", "ac3", "flac-encoder", "mp3-encoder"].includes(name)) {
  throw new Error("Choose core, aac-encoder, ac3, flac-encoder or mp3-encoder");
}
await build({
  entryPoints: [name === "core" ? "src/index.ts" : `packages/${name}/src/index.ts`],
  outfile: `cutt-rebuilt/${name}.mjs`,
  bundle: true,
  format: "esm",
  target: "es2021",
  legalComments: "eof",
  external: name === "core" ? [] : ["mediabunny"],
  plugins:
    name === "core"
      ? []
      : [
          inlineWorkerPlugin({
            define: { "import.meta.url": '""' },
            legalComments: "eof",
          }),
        ],
});
```

Run `npx tsx cutt-rebuild.mts core`, then rebuild each required extension with
`aac-encoder`, `ac3`, `flac-encoder` or `mp3-encoder`. The AC-3
README requires its included `ffmpeg-ac3-encoder-audio-frame-queue.patch` before
configuring the matching FFmpeg source. Generated ESM modules
are written to `cutt-rebuilt/`. Retain the matching license notices when
distributing modified modules. The codec modules retain the normal `mediabunny`
peer import and public registration API; bind that import to the application's
existing Mediabunny instance when rebundling, so registration uses the same
codec registry. Replacing a codec is not permission to bypass Remotion's license.

The browser application JavaScript is executable object code served to the
browser. A local rebuild or browser developer overrides can replace a library
module; minified chunk export names and imports must be preserved or rebound.
The LGPL libraries' ABI-compatible WASM can also replace the corresponding
inlined WASM payload. Rebuilding or replacing a library is permitted by its
license, including reverse engineering to debug modifications. A complete
application replacement/relink acceptance run is recorded separately from
source availability; this document does not claim it has already passed.

The Remotion packages retain their pinned 4.0.534 version. Apply the adjacent
`web-renderer.patch` from the installed `@remotion/web-renderer` package root and
`media.patch` from the installed `@remotion/media` package root with `git apply`
before bundling the application. These patches modify the distributed ESM code;
no additional decoder, renderer or codec binary is required.

The caption SVG patch aligns bitmap paint origins in canvas device coordinates
after unit translations. This fixes the fractional origin captured in the existing
native parity cases with the pinned Chrome. Reference checked 2026-11-05:
https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-gettransform
and the pinned Remotion 4.0.534 distributed `drawSvg` implementation.

The SVG bitmap clone also samples the parent's current local paint phase when
serializing its viewBox, avoiding stale placement measured before transforms were
removed. The original SVG DOM remains unchanged. The pinned Chromium 157 native
comparison on 2026-11-05 passed all 26 existing frame comparisons and the
representative MP4 checks with unchanged thresholds. This is a synthetic local
comparison, not physical macOS/Windows or all saved-package acceptance.

Apply the adjacent `media.patch` from the installed `@remotion/media` 4.0.540
package root with `git apply` before bundling. This distributed ESM patch changes
only audio resampling: all multichannel signals, including LFE, contribute to the
stereo mix with bounded gains. Existing video sampling stays upstream.
