How to build a Chrome recording extension

Demo Video

Building a Chrome extension that records a Google Meet tab sounds straightforward, until you try to build it. Chrome doesn’t let webpages capture system audio for all OSes, and background scripts can’t hold active media streams. If you want to record the actual video and audio your user experiences in the Google Meet tab without a picker, there is exactly one supported path: a Chrome extension using chrome.tabCapture.

This guide walks through that implementation step-by-step. When you’re done, you’ll have a working extension that records:

• Video from the Google Meet tab
• System/tab audio (everyone else)
• Microphone audio (the user speaking)

All mixed together and saved as a clean .webm.

To make that possible, we have to use extension-only media capture APIs because Chrome doesn’t grant standard JavaScript websites without special privileges access to tab audio without a picker.

However, those APIs come with a couple of important rules we need to design around:

• The recording stream is tied to the Google Meet tab and will stop if the tab is closed or Chrome revokes capture
• Microphone access must come from a user-initiated action

The good news? Every one of these constraints has a solution. In this tutorial, we’ll build a recorder that respects Chrome’s rules while still capturing everything the user sees and hears. You can follow along and test out the extension for yourself by cloning my chrome recording extension repo.

Extension architecture

A Chrome extension can only record reliably if you structure it around Chrome’s media-capture rules which can be found in API docs and the Chrome extension documentation created by Google. Three specific constraints shape my design:

1. Microphone access only succeeds inside a user-visible extension page triggered by a user gesture.
2. Media streams must be handled in a DOM-enabled environment, not in the background.
3. The captured stream is bound to the Google Meet tab and may end immediately if the tab is reloaded or permissions change.

Those rules are non-negotiable, so I architected the extension to respect them rather than attempting to hack around them. The division of responsibility looks like this:

This gives me a clean control flow:

When implemented correctly, the user clicks Start Recording, continues their conversation normally in Google Meet, clicks Stop Recording, and the file downloads locally. Everything else happens behind the scenes.

To improve the user experience, you can automate stop behavior by injecting a content script into the tab where the meeting is taking place (in this case the Google Meet tab). The script can detect the standard end-of-meeting state (for example, the “You left the call” screen) and signal the background service worker to stop recording automatically. That is not covered in this tutorial as it is an extension of the core functionality.

Code: File overview

I built core files that we’ll walk through together:

All the supporting files (manifest, build config) exist solely to enable this architecture.

With the structure laid out, we can move on to the fun part: capturing the Google Meet tab itself.

How to capture video + system audio from a specific tab

Chrome doesn’t hand your extension a media stream directly. Different parts of an extension have different powers:

• The background context, which runs as a service worker, can run logic even when no windows are open, but it has no DOM and can’t hold active media streams
• The offscreen document, a hidden, DOM-enabled page, does have a DOM and can record audio/video, but only while it’s explicitly opened

So I split responsibilities between two scripts I wrote:

• background.ts runs in the background context. It requests tab-capture permission and coordinates state.
• offscreen.ts runs inside the offscreen document. This file actually captures audio/video using getUserMedia() (which requires a DOM) and MediaRecorder.

Chrome enforces this separation as a security boundary. The background script can ask for access to a tab, but it can’t touch the stream itself. This split ensures that only a visible, user-initiated extension component can handle real media, preventing background or webpage code from spying.

How tab capture actually works

Chrome’s tabCapture works in two stages:

1. The background.ts requests a temporary stream ID. Chrome only grants this after a user gesture (a direct user action like clicking a button). The stream ID is not media, it only works inside extension contexts. Think of it as a user permission token: it proves the user approved capturing the given tab, and it can’t be reused elsewhere.
2. The offscreen document redeems the stream ID for the actual tab audio and video that you can mix and record using getUserMedia(). This exchange is only possible in a DOM-enabled environment because getUserMedia() requires a visible, user-authorized page where Chrome can safely manage permissions and security indicators.

Everything else in the flow builds on this division of responsibility:

• The service worker (background.ts) asks Chrome for permission and coordinates the session.
• offscreen.ts turns that permission into real audio/video and records it.

//@title background.ts - getting the stream ID
async function getStreamIdForTab(tabId: number): Promise<string> {
  return new Promise((resolve, reject) => {
    chrome.tabCapture.getMediaStreamId(
      { targetTabId: tabId },
      streamId => streamId ? resolve(streamId) : reject(new Error('Failed to get streamId'))
    );
  });
}

The offscreen document then requests the actual stream:

//@title offscreen.ts - using the stream ID
const baseStream = await navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: 'tab',
      chromeMediaSourceId: streamId,
      // Attempt to keep audio audible while recording
      googDisableLocalEcho: false
    }
  },
  video: {
    mandatory: {
      chromeMediaSource: 'tab',
      chromeMediaSourceId: streamId,
      maxWidth: 1920,
      maxHeight: 1080,
      maxFrameRate: 30
    }
  }
});

At this point, we have video tracks and remote/system audio, but we’re still missing a key piece: microphone audio. Because Google Meet does not loop the local mic output back into the tab, we’ll have to come up with a way to get the audio for the user(s) running the Chrome extension another way.

How to capture your microphone

If you speak into your microphone in a Google Meet call, you will not hear yourself, and neither will the tab capture stream. Google Meet deliberately suppresses local voice playback to prevent echo. But for this extension, I need the user’s voice just as much as everyone else’s, so I capture the mic directly:

const micStream = await navigator.mediaDevices.getUserMedia({ audio: true });

Microphone access must be granted from a visible, user-initiated extension page. The most reliable UX involves:

• Showing an Enable Microphone button in the popup
• If the permission prompt doesn’t appear, automatically opening a dedicated setup page in a visible tab and retrying there

Chrome may deny microphone prompts from the popup due to system settings or permission blocks. The fallback UI prevents silent failures and allows users to capture microphone audio if the happy path isn’t hit.

We’ll put the full permission UX in the appendix. For now, the key takeaway is that if the popup request fails silently, fall back to a visible tab.

Once we have the mic stream and the tab stream, we can merge them.

Merging tab audio and microphone audio using Web Audio API

Now that I have audio from the tab and the mic, I’ll use the Web Audio API as my audio mixer. Because MediaRecorder, the browser API that turns a MediaStream into a recorded file, can only record one audio track per stream, I’ll mix the tab and mic audio together. First I convert each audio source into a MediaStreamSource node which the browser can route. Then I mix the mic and tab audio into a single track (MediaStreamDestination). Finally, I attach that mixed audio to the original tab’s video track.

When we’re done, we’ll have one MediaStream that includes:

• Google Meet tab video
• Google Meet tab audio
• Local microphone audio

all ready to send into MediaRecorder.

//@title offscreen.ts - mixing tab and mic audio
function mixAudio(tabStream: MediaStream, micStream: MediaStream) {
  const ctx = new AudioContext();
  const dst = ctx.createMediaStreamDestination();

  ctx.createMediaStreamSource(tabStream).connect(dst);
  ctx.createMediaStreamSource(micStream).connect(dst);

  return new MediaStream([
    ...tabStream.getVideoTracks(),
    ...dst.stream.getAudioTracks()
  ]);
}

Make sure not to mute or stop the MediaStream in your code. Chrome interprets a disabled audio track as no sound/silence, so your recording won’t include remote voices.

With a single combined MediaStream in hand, I can move on to recording everything the user sees and hears.

Recording and saving the .webm using Chrome recording APIs

Once we’ve mixed the tab and microphone audio into a single MediaStream, the offscreen document handles recording using the MediaRecorder API. This is the only part of the extension that continuously receives raw audio/video, so keeping that work inside the offscreen document prevents interruptions when Chrome suspends background service workers under Manifest V3.

Manifest V3 (MV3) replaces background pages (which were used in Manifest V2) with service workers. Service workers are essentially scripts that can wake, do short tasks, and then sleep. These workers can’t access the DOM, can be paused by Chrome at any time, and sometimes suspend when idle, which is why all live media work has to happen inside a DOM-enabled context like the offscreen document.

Here’s the minimal setup for recording inside offscreen.ts:

//@title offscreen.ts
recorder = new MediaRecorder(finalStream, {
  mimeType: 'video/webm; codecs=vp8,opus'
});

const chunks: BlobPart[] = [];

recorder.ondataavailable = e => chunks.push(e.data);

recorder.onstop = () => {
  const blob = new Blob(chunks, { type: recorder.mimeType });
  const blobUrl = URL.createObjectURL(blob);
  port.postMessage({ type: 'OFFSCREEN_SAVE', blobUrl, filename });
};

When the user clicks Stop Recording in the popup, the message travels through the same chain we established earlier. The popup script (popup.ts) captures the user’s click and sends a message to the background service worker (background.ts). The background forwards that message to the offscreen document (offscreen.ts), which is the only context with access to the live MediaRecorder. Once the offscreen script receives the stop signal, it calls recorder.stop(), compiles the recorded chunks into a single Blob, creates a temporary Blob URL, and sends that back to the background worker. The background then uses Chrome’s downloads API to save the file locally:

//@title background.ts
chrome.downloads.download({
  url: blobUrl,
  filename,
  saveAs: true
});

This flow keeps the long-lived media work isolated inside the offscreen document, while the background service worker handles coordination and saving. That separation prevents lost recordings when Chrome suspends the background worker and ensures only user-initiated actions control capture.

A subtle but important detail: I do not call URL.revokeObjectURL(blobUrl) immediately. If the Blob URL is revoked before Chrome’s download stream begins, you will end up with a corrupted or empty file. The safest pattern is:

1. Trigger the download
2. Wait for the onChanged download-state event
3. Revoke the URL only after Chrome reports progress

We’ll include the full cleanup function in the appendix.

With recording and download wired up, the full session lifecycle is now in place. The user clicks Start Recording, continues using Google Meet normally, and then clicks Stop Recording to receive a clean .webm that includes everything they saw and heard including the tab’s video, the remote participants’ audio, and their own microphone.

All of this processing happens inside the offscreen document so the background worker can sleep without interrupting the recording. Still, Chrome’s recording APIs can be unpredictable, Chrome’s rules are strict, permissions change, and tabs do unexpected things. I’ll walk through some failure modes and go over how to handle them gracefully.

What can go wrong (and how not to panic)

Even with a well-structured architecture, Chrome’s tab-capture APIs come with quirks and edge cases that can look alarming the first time you hit them.

If you clone this repo (or build a similar extension using Chrome’s capture APIs), here are the issues you’re most likely to see and what they actually mean:

Each of these can be mitigated by the way I structured the extension:

• Keep recording logic inside the offscreen document, so background sleep doesn’t interrupt capture.
• Communicate state changes via messages, not polling.
• Route the captured audio back to AudioContext.destination so that the user can hear the Google Meet audio.
• Listen for onended events on video tracks and stop and save cleanly if Chrome terminates the stream.

Chrome extension constraints

Some issues can’t be fixed because they stem from Chrome’s security and UX model in Manifest V3:

• Users must click to start: Chrome requires a user gesture to request tab capture and microphone access. There’s no compliant, reliable way to auto-start when a meeting begins.
• Capture is bound to one tab: If the user closes the Google Meet tab, capture ends permanently. You must request a new stream ID and start a new recording.
• Switching tabs can cause gaps: If the user switches away, Google Meet’s video and tab audio may freeze or go silent until they return (the microphone continues) due to Chrome throttling the background rendering. When they come back, capture resumes, but the missing segment is gone.
• No cross-app or multi-tab recording: Extensions can’t record multiple meetings at the same time. Each recording session must be user-initiated and tied to one active tab.
• Browser-only recording: Chrome extensions can only capture media that plays inside the browser. This makes them a good fit for Google Meet, which runs in Chrome, but not for Zoom, Microsoft Teams, or Slack, which most users join through their desktop apps rather than in a web tab.
• Limited to Chromium-based browsers: This architecture relies on Chromium’s chrome.tabCapture and Manifest V3 APIs, so it works only in Chrome, Edge, Brave, and other Chromium browsers. Firefox supports screenshots only, not live tab capture, and Safari lacks the APIs I used entirely. For true cross-browser recording, you’ll need to rely on desktop recording, a meeting bot, a picker-based UX, or use APIs native to the various meeting platforms.
• Codec support depends on browser version: The MediaRecorder API supports only the codecs that Chrome’s current build exposes. For example, most versions record reliably with video/webm; codecs=vp8,opus, while newer releases add VP9 or AV1 support. Testing your target machines and Chrome versions is essential before depending on a specific codec.

const type = 'video/webm; codecs=vp8,opus';
if (!MediaRecorder.isTypeSupported(type)) {
  console.warn(`${type} not supported on this browser`);
} else {
  console.log(`${type} supported`);
}

If your preferred codec isn’t supported, default to vp8,opus, which is available on nearly all Chrome builds and compatible with most WebM players.

When you outgrow an extension

If the constraints above are deal breakers, and you need recordings that survive tab changes, start automatically, or record meetings joined through a desktop client, you’ve reached the boundary of what Chrome extensions can do.

At that point, the solution isn’t another workaround; it’s a different architecture.

For situations where you need to survive tab changes or have recording start automatically, a meeting bot API or a desktop recording SDK. Both options run outside the browser and avoid tab focus and Manifest V3 constraints entirely.

The implementation above delivers a reliable, compliant Chrome recorder.
From here, you can refine it further by adding auto-stop handlers, performance tuning, or better UX feedback.
See the appendix for code examples and optimization tips.

Conclusion

A Chrome extension reaches the practical limit of what Chrome’s recording APIs allow: capturing a single Google Meet tab on-device with system/tab audio and microphone mixed into a clean .webm. It works well when someone clicks Start Recording and stays in the tab until the meeting ends.

The problem is that people forget. They miss the button, refresh the tab, or close the extension mid-meeting. And because Chrome extensions only capture media inside the browser, they can’t record calls running in desktop apps like Zoom, Teams, or Slack.

For situations that require more flexibility, using Recall.ai’s Meeting Bot API and Desktop Recording SDK can be great solutions. Both can capture the same data as a Chrome extension and more, but they run outside the browser, and can automatically start and stop recording meetings. Both products work with Zoom, Google Meet, Microsoft Teams, Webex, Slack and more. While you can’t fully automate away human error in most cases, a meeting bot form factor or a desktop app form factor significantly reduce the chances of missed or incomplete recordings.

Whether or not a Chrome extension fits your use case, hopefully this tutorial and the accompanying GitHub repo are helpful resources in finding a solution that works for you. Good luck building and, as always, feel free to reach out if you have any questions.

//@title offscreen.ts — detect stream end from the captured tab
finalStream.getVideoTracks().forEach(track => {
  track.onended = () => {
    port.postMessage({ type: 'STREAM_ENDED' });
  };
});

//@title background.ts — propagate a single stop signal to the UI
port.onMessage.addListener(msg => {
  if (msg.type === 'STREAM_ENDED') {
    chrome.runtime.sendMessage({ type: 'STOP_RECORDING' });
  }
});

//@title popup.ts — reflect the real state to the user
chrome.runtime.onMessage.addListener(msg => {
  if (msg.type === 'STOP_RECORDING') {
    updateUI({ state: 'stopped', reason: 'Tab closed or navigated' });
  }
});

//@title background.ts
chrome.action.setBadgeText({ text: 'REC' });
chrome.action.setBadgeBackgroundColor({ color: '#e74c3c' });

//@title background.ts
async function logEvent(type, details) {
  await fetch('https://your-analytics-endpoint.example.com/log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type, details, timestamp: Date.now() })
  });
}

//@title popup.ts
chrome.storage.sync.set({ preferredResolution: '1080p' });

//@title offscreen.ts
recorder.start(1000); // emit data every second

//@title offscreen.ts
video: { mandatory: { maxWidth: 1920, maxHeight: 1080, maxFrameRate: 30 } }

//@title background.ts
chrome.offscreen.closeDocument();

//@title offscreen.ts — onended handler
videoTrack.onended = async () => {
  const { streamId } = await chrome.runtime.sendMessage({ type: 'REACQUIRE_STREAM_ID' });
  const next = await captureWithStreamId(streamId);
  await prepareAndRecord(next); // creates next .webm segment
};

// Replace the tab’s input on reload
const newTab = await captureWithStreamId(newId);
currentVideo.srcObject = newTab;
tabAudioNode.disconnect();
tabAudioNode = ctx.createMediaStreamSource(newTab);
tabAudioNode.connect(audioDst);