references/extensions/media-capture.md

GitHub

Media Capture (Tab & Desktop)

Choosing the Right API

Need API
Record the active tab's audio/video chrome.tabCapture.getMediaStreamId()
Let the user choose a screen, window, or tab chrome.desktopCapture.chooseDesktopMedia()

Prefer tabCapture when you only need the current tab — it requires no user chooser dialog and no "tabs" permission. Use desktopCapture only when the user must select what to capture.

Tab Capture

Permissions

{ "permissions": ["tabCapture"] }

Pattern

chrome.tabCapture.getMediaStreamId() runs in the service worker and returns a stream ID. The actual getUserMedia() call must happen in an offscreen document (the SW cannot access media streams directly).

// service-worker.js
chrome.action.onClicked.addListener(async (tab) => {
  const streamId = await chrome.tabCapture.getMediaStreamId({ targetTabId: tab.id });
  // Pass the ID to the offscreen document to call getUserMedia
  await chrome.runtime.sendMessage({ type: 'START_CAPTURE', streamId });
});

// offscreen.js
chrome.runtime.onMessage.addListener((msg) => {
  if (msg.type !== 'START_CAPTURE') return;
  (async () => {
    const stream = await navigator.mediaDevices.getUserMedia({
      audio: { mandatory: { chromeMediaSource: 'tab', chromeMediaSourceId: msg.streamId } },
      video: { mandatory: { chromeMediaSource: 'tab', chromeMediaSourceId: msg.streamId } }
    });
    const recorder = new MediaRecorder(stream, { mimeType: 'video/webm' });
    // ... handle recorder events
  })();
});

Desktop Capture

Permissions

{ "permissions": ["tabs", "desktopCapture"] }

"tabs" is required — chooseDesktopMedia needs a targetTab with its url field populated, which requires the "tabs" permission.

Pattern

// service-worker.js
chrome.action.onClicked.addListener(async (tab) => {
  // ❌ BROKEN — no targetTab
  // chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], cb);

  // ✅ CORRECT — pass the active tab
  chrome.desktopCapture.chooseDesktopMedia(['screen', 'window', 'tab'], tab, (streamId) => {
    if (!streamId) return; // User cancelled
    // Send streamId to offscreen document for getUserMedia
    chrome.runtime.sendMessage({ type: 'START_DESKTOP_CAPTURE', streamId });
  });
});

State Locking — Prevent Double-Start Errors

Both APIs fail if called while a previous capture is still active:

  • tabCapture: "Cannot capture a tab with an active stream"
  • desktopCapture: opens a second chooser dialog on top of the first

Use a state machine stored in chrome.storage.session (survives service worker restarts, cleared on browser close):

// State: 'idle' → 'starting' → 'recording' → 'stopping' → 'idle'
chrome.action.onClicked.addListener(async (tab) => {
  const { recordingState = 'idle' } = await chrome.storage.session.get('recordingState');

  // Ignore clicks during transitions
  if (recordingState === 'starting' || recordingState === 'stopping') return;

  if (recordingState === 'idle') {
    await chrome.storage.session.set({ recordingState: 'starting' });
    try {
      await startRecording(tab);
      await chrome.storage.session.set({ recordingState: 'recording' });
      await chrome.action.setBadgeText({ text: 'REC' });
      await chrome.action.setBadgeBackgroundColor({ color: '#FF0000' });
    } catch (err) {
      console.error('Failed to start recording:', err);
      await chrome.storage.session.set({ recordingState: 'idle' });
    }
  } else if (recordingState === 'recording') {
    await chrome.storage.session.set({ recordingState: 'stopping' });
    try { await stopRecording(); }
    finally {
      await chrome.storage.session.set({ recordingState: 'idle' });
      await chrome.action.setBadgeText({ text: '' });
    }
  }
});

This same pattern applies to chrome.offscreen.createDocument (only one offscreen document is allowed at a time) and any other API that manages an exclusive resource.

Saving Recordings

Offscreen documents cannot call chrome.downloads — send the blob back to the service worker:

// offscreen.js — when recording stops
recorder.ondataavailable = (e) => chunks.push(e.data);
recorder.onstop = async () => {
  const blob = new Blob(chunks, { type: 'video/webm' });
  const url = URL.createObjectURL(blob);
  // Service worker handles the download
  await chrome.runtime.sendMessage({ type: 'SAVE_RECORDING', url });
};

// service-worker.js
chrome.runtime.onMessage.addListener((msg) => {
  if (msg.type !== 'SAVE_RECORDING') return;
  chrome.downloads.download({ url: msg.url, filename: 'recording.webm' });
});

See references/extensions/message-passing.md for the full offscreen document messaging pattern.