Add offscreen user media sample

functional-samples/cookbook.offscreen-user-media/README.md

@@ -0,0 +1,34 @@
+This recipe shows how to use User Media in an Extension Service Worker using the [Offscreen document][1].
+
+## Context
+
+- The extension aims to capture audio from the user in the context of extension (globally) via a media recorder in the offscreen document.
+- Service worker no longer have access to window objects and APIs. Hence, it was difficult for the extension to fetch permissions and capture audio.
+- Offscreen document handles permission checks, audio devices management and recording using navigator API and media recorder respectively.
+
+## Steps
+
+1. User presses START/STOP recording from extension popup
+2. Popup sends message to background service worker.
+3. If STOP, Service worker sends message to offscreen to stop mediarecorder.
+4. If START, Service worker sends message to the active tab's content script to intiate recording process.
+5. The content script sends message to offscreen to check audio permissions.
+   - If GRANTED, send message to offscreen to start media recorder.
+   - If DENIED, show alert on window
+   - If PROMPT,
+     - inject an IFrame to request permission from the user.
+     - Listen to the user'e response on the iFrame
+     - If allowed, move to GRANTED step. Else, DENIED.
+
+## Running this extension
+
+1. Clone this repository.
+2. Load this directory in Chrome as an [unpacked extension][2].
+3. Open the Extension menu and click the extension named "Offscreen API - User media".
+
+Click on the extension popup for START and STOP recording buttons.
+
+Inspect the offscreen html page to view logs from media recorder and audio chunk management.
+
+[1]: https://developer.chrome.com/docs/extensions/reference/offscreen/
+[2]: https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked

functional-samples/cookbook.offscreen-user-media/background.js

@@ -0,0 +1,133 @@
+/**
+ * Path to the offscreen HTML document.
+ * @type {string}
+ */
+const OFFSCREEN_DOCUMENT_PATH = 'offscreen/offscreen.html';
+
+/**
+ * Reason for creating the offscreen document.
+ * @type {string}
+ */
+const OFFSCREEN_REASON = 'USER_MEDIA';
+
+/**
+ * Listener for extension installation.
+ */
+chrome.runtime.onInstalled.addListener(handleInstall);
+
+/**
+ * Listener for messages from the extension.
+ * @param {Object} request - The message request.
+ * @param {Object} sender - The sender of the message.
+ * @param {function} sendResponse - Callback function to send a response.
+ */
+chrome.runtime.onMessage.addListener((request) => {
+  switch (request.message.type) {
+    case 'TOGGLE_RECORDING':
+      switch (request.message.data) {
+        case 'START':
+          initateRecordingStart();
+          break;
+        case 'STOP':
+          initateRecordingStop();
+          break;
+      }
+      break;
+  }
+});
+
+/**
+ * Handles the installation of the extension.
+ */
+async function handleInstall() {
+  console.log('Extension installed...');
+  if (!(await hasDocument())) {
+    // create offscreen document
+    await createOffscreenDocument();
+  }
+}
+
+/**
+ * Sends a message to the offscreen document.
+ * @param {string} type - The type of the message.
+ * @param {Object} data - The data to be sent with the message.
+ */
+async function sendMessageToOffscreenDocument(type, data) {
+  // Create an offscreen document if one doesn't exist yet
+  try {
+    if (!(await hasDocument())) {
+      await createOffscreenDocument();
+    }
+  } finally {
+    // Now that we have an offscreen document, we can dispatch the message.
+    chrome.runtime.sendMessage({
+      message: {
+        type: type,
+        target: 'offscreen',
+        data: data
+      }
+    });
+  }
+}
+
+/**
+ * Initiates the stop recording process.
+ */
+function initateRecordingStop() {
+  console.log('Recording stopped at offscreen');
+  sendMessageToOffscreenDocument('STOP_OFFSCREEN_RECORDING');
+}
+
+/**
+ * Initiates the start recording process.
+ */
+function initateRecordingStart() {
+  chrome.tabs.query({ active: true, lastFocusedWindow: true }, ([tab]) => {
+    if (chrome.runtime.lastError || !tab) {
+      console.error('No valid webpage or tab opened');
+      return;
+    }
+
+    chrome.tabs.sendMessage(
+      tab.id,
+      {
+        // Send message to content script of the specific tab to check and/or prompt mic permissions
+        message: { type: 'PROMPT_MICROPHONE_PERMISSION' }
+      },
+      (response) => {
+        // If user allows the mic permissions, we continue the recording procedure.
+        if (response.message.status === 'success') {
+          console.log('Recording started at offscreen');
+          sendMessageToOffscreenDocument('START_OFFSCREEN_RECORDING');
+        }
+      }
+    );
+  });
+}
+
+/**
+ * Checks if there is an offscreen document.
+ * @returns {Promise<boolean>} - Promise that resolves to a boolean indicating if an offscreen document exists.
+ */
+async function hasDocument() {
+  // Check all windows controlled by the service worker if one of them is the offscreen document
+  const matchedClients = await clients.matchAll();
+  for (const client of matchedClients) {
+    if (client.url.endsWith(OFFSCREEN_DOCUMENT_PATH)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Creates the offscreen document.
+ * @returns {Promise<void>} - Promise that resolves when the offscreen document is created.
+ */
+async function createOffscreenDocument() {
+  await chrome.offscreen.createDocument({
+    url: OFFSCREEN_DOCUMENT_PATH,
+    reasons: [OFFSCREEN_REASON],
+    justification: 'To interact with user media'
+  });
+}

functional-samples/cookbook.offscreen-user-media/contentScript.js

@@ -0,0 +1,79 @@
+/**
+ * Listener for messages from the background script.
+ * @param {Object} request - The message request.
+ * @param {Object} sender - The sender of the message.
+ * @param {function} sendResponse - Callback function to send a response.
+ * @returns {boolean} - Whether the response should be sent asynchronously (true by default).
+ */
+chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+  switch (request.message.type) {
+    case 'PROMPT_MICROPHONE_PERMISSION':
+      // Check for mic permissions. If not found, prompt
+      checkMicPermissions()
+        .then(() => {
+          sendResponse({ message: { status: 'success' } });
+        })
+        .catch(() => {
+          promptMicPermissions();
+          const iframe = document.getElementById('PERMISSION_IFRAME_ID');
+          window.addEventListener('message', (event) => {
+            if (event.source === iframe.contentWindow && event.data) {
+              if (event.data.type === 'permissionsGranted') {
+                sendResponse({
+                  message: { status: 'success' }
+                });
+              } else {
+                sendResponse({
+                  message: {
+                    status: 'failure'
+                  }
+                });
+              }
+              document.body.removeChild(iframe);
+            }
+          });
+        });
+      break;
+
+    default:
+      // Do nothing for other message types
+      break;
+  }
+  return true;
+});
+
+/**
+ * Checks microphone permissions using a message to the background script.
+ * @returns {Promise<void>} - Promise that resolves if permissions are granted, rejects otherwise.
+ */
+function checkMicPermissions() {
+  return new Promise((resolve, reject) => {
+    chrome.runtime.sendMessage(
+      {
+        message: {
+          type: 'CHECK_PERMISSIONS',
+          target: 'offscreen'
+        }
+      },
+      (response) => {
+        if (response.message.status === 'success') {
+          resolve();
+        } else {
+          reject(response.message.data);
+        }
+      }
+    );
+  });
+}
+
+/**
+ * Prompts the user for microphone permissions using an iframe.
+ */
+function promptMicPermissions() {
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('hidden', 'hidden');
+  iframe.setAttribute('allow', 'microphone');
+  iframe.setAttribute('id', 'PERMISSION_IFRAME_ID');
+  iframe.src = chrome.runtime.getURL('requestPermissions.html');
+  document.body.appendChild(iframe);
+}

functional-samples/cookbook.offscreen-user-media/manifest.json

@@ -0,0 +1,25 @@
+{
+  "name": "Offscreen API - User media",
+  "version": "1.0",
+  "manifest_version": 3,
+  "description": "Shows how to record audio in a chrome extension via offscreen document.",
+  "background": {
+    "service_worker": "background.js"
+  },
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["contentScript.js"]
+    }
+  ],
+  "action": {
+    "default_popup": "popup/popup.html"
+  },
+  "permissions": ["offscreen", "activeTab", "tabs"],
+  "web_accessible_resources": [
+    {
+      "resources": ["requestPermissions.html", "requestPermissions.js"],
+      "matches": ["<all_urls>"]
+    }
+  ]
+}

functional-samples/cookbook.offscreen-user-media/offscreen/offscreen.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Offscreen Document</title>
+    <script src="./offscreen.js"></script>
+  </head>
+  <body></body>
+</html>