← Back to Blog

Recording Tab Audio in Firefox Without tabCapture

AnnMax · November 15, 202610 min read

The Missing API

TabTape records one browser tab's audio to MP3 or WAV. On Chrome and Edge the architecture is the obvious one: chrome.tabCapture hands you a MediaStream of the whole tab, an offscreen document holds it, an AudioWorklet passes the audio through to the speakers, and PCM blocks are encoded as they arrive.

Firefox has no tabCapture. There is no extension API that returns "the audio of this tab". What Firefox does have is HTMLMediaElement.captureStream() — spelled mozCaptureStream() in its prefixed form — which exposes the audio of a single <video> or <audio> element. So the Firefox build is a different architecture with the same product promise: record what the tab is playing, keep it audible, write it to disk as it arrives.

The Page Bridge

The capture code runs in the page, injected on demand with activeTab + scripting when the user presses Record — there is no declarative content script watching pages. It collects the playing media elements, attaches a capture stream to each, and mixes them through one AudioContext:

if (typeof el.captureStream === 'function') stream = el.captureStream();
else if (typeof el.mozCaptureStream === 'function') stream = el.mozCaptureStream();
...
src = state.ctx.createMediaStreamSource(stream);
src.connect(state.processor);

The processor is a ScriptProcessor-style tap that interleaves the channels and posts ~one-second PCM blocks to the background. The AudioContext is explicitly resumed and its state checked before the session starts — a context created without a user gesture can be suspended, and a suspended context records pure silence while looking perfectly healthy.

Dead Streams and Player Swaps

Two Firefox quirks cost me a day each, and both are now load-bearing comments in the bridge.

Quirk one: the same stream comes back, dead. captureStream() returns the same MediaStream object for a given element. Once its tracks have ended — the video reached its end, the source was swapped — that stream never comes back to life. Re-attaching the element every tick would feed pure silence into the recording. So elements whose tracks ended go into a dead WeakSet and are never retried:

const live = tracks.filter(t => t.readyState === 'live');
if (!live.length) {
  if (tracks.length) state.dead.add(el);
  return;
}

Quirk two: pages swap players. Next episode, SPA route change, autoplay hand-off — the element you attached at start may be gone while a new one plays. A periodic sync() detaches dead streams and attaches newly playing elements. Paused elements are detached but the session stays alive: press play again and the next tick re-attaches. "Paused" and "ended" are different states, and conflating them either kills long recordings or records silence.

A Port That Keeps the Event Page Alive

Firefox MV3 backgrounds are event pages: they unload when idle. A recording that streams PCM into a background which has gone to sleep is a recording into the void. The bridge therefore opens a named runtime port, and the open port is what keeps the event page alive for the whole session:

state.port = chrome.runtime.connect({ name: 'tt-capture' });
state.port.onDisconnect.addListener(() => {
  // The background page was unloaded while the page was still audible;
  // nothing can be encoded any more.
  if (run === state && !state.stopping) stop('disconnected');
});
state.port.postMessage({
  type: 'hello',
  recId: cfg.recId,
  sampleRate: state.ctx.sampleRate,
  channels: 2,
  sources: playing.map(describe)
});

The hello handshake carries the sample rate and channel count so the encoder is configured from the actual AudioContext, not an assumption. If the port dies mid-recording, the only honest outcome is to stop and save what already reached disk — which the chunked storage model makes possible.

Encoding at the Background, Chunks on Disk

The background page owns the encoder: a vendored build of lamejs for MP3, raw PCM for WAV. Two details matter. lamejs's encodeBuffer(left, right) wants separate channel arrays — handing it interleaved data produces garbage — so the bridge's interleaved blocks are de-interleaved per channel before encoding. And every encoded chunk is written to IndexedDB as it arrives, with the meta row marked incomplete until stop.

That is the whole memory story: a two-hour lecture is a sequence of one-second chunks on disk, not a two-hour buffer in RAM. It is also the crash story: if the browser dies mid-recording, the library offers a recover bar that rebuilds a playable file from the chunks that already landed — WAV duration computed from bytes, MP3 from frame parsing.

Trim Without Decoding

Because the storage model is chunked and the formats are parsed, not decoded, trimming never loads the whole file. WAV cuts are byte-exact at sample boundaries; MP3 cuts walk frame headers and slice at frame granularity. A two-hour MP3 trims in milliseconds with no re-encode — the export is the same audio bytes, not a recompressed copy. The same frame parser powers duration display and crash recovery, which is a good hint that the abstraction is right: one parser, three consumers.

What It Cannot Record, Said Plainly

The media-element approach has a honest boundary, and the UI states it instead of hiding it:

Chrome's tabCapture records the whole tab regardless of source; Firefox's bridge records the media the page is playing. Different capability, same promise: the file is yours, on your disk, and nothing was uploaded to get it there.

Related Articles