webrtc-share-ext

webrtc-share-ext is a minimal extension (or helper) for enabling screen sharing / desktop capture capabilities in WebRTC-based applications. It provides bridging between a web page and browser-level screen capture APIs (e.g. via a browser extension) in situations where direct getDisplayMedia is insufficient or unavailable.

---

Table of Contents

• Features
• Motivation & Context
• How It Works (Architecture)
• Getting Started
  • Prerequisites
  • Installation
  • Usage / Integration
• API / Methods
• Configuration & Options
• Browser Compatibility & Limits
• Development & Testing
• Contributing
• License

---

Features

• Acts as a bridge to request and control desktop (screen/window) capture for WebRTC flows
• Enables selecting of screens or application windows
• Switching between screen capture and video camera capture if needed
• Simple interface for integrating into WebRTC / peer-connection logic
• Light, minimal — intended to complement existing signaling and WebRTC setup

---

Motivation & Context

Web browsers increasingly support native screen capture via navigator.mediaDevices.getDisplayMedia(). However, in certain contexts (older browsers, more complex capture needs, or environments requiring extension-level permissions), you may need a helper or extension to mediate screen capture.

This extension helps in those cases by:

• Handling extension / privileged APIs (e.g. chrome.desktopCapture.chooseDesktopMedia)
• Mediating between page scripts and background / extension scripts
• Abstracting away low-level complexities so that your WebRTC logic can call higher-level functions

---

How It Works (Architecture)

flowchart TD

A[Web Page (App)] -- postMessage --> B[Extension Background<br/>(desktopCapture API)]
B --> C[Screen/Window Picker UI]
C -->|sourceId / Stream| B
B --> A
A --> D[WebRTC Client<br/>(getUserMedia, RTCPeerConn)]
D --> E[Remote Peer(s)<br/>(via Signaling)]

Loading

1. Web Page (Client Script)

   • Calls a function like requestScreenShare()
   • Sends a postMessage or connects to the extension
   • Waits for a response containing a sourceId or a MediaStream

2. Extension / Background Script

   • Listens for incoming messages
   • Uses chrome.desktopCapture.chooseDesktopMedia to prompt the user
   • Returns the selected sourceId or stream back to the page

3. Page / Client (Continuation)

   • Receives the sourceId or stream
   • Uses it with getUserMedia
   • Attaches resulting MediaStream to a WebRTC peer connection or <video> element

4. Switching / Control

   • May provide functions like switchToScreen() or switchToCamera()
   • WebRTC renegotiation or track replacement is handled on the client side

---

Getting Started

Prerequisites

• A modern Chromium-based browser with extension support
• Basic WebRTC signaling / peer connection setup in your app
• HTTPS context (required for capture APIs)

Installation

1. Clone the repository:

   git clone https://github.com/duttarnab/webrtc-share-ext.git
   cd webrtc-share-ext

2. Install dependencies and build:

   npm install
   npm run build
   
   

3. Load the extension:

   • Go to chrome://extensions/

   • Enable Developer mode

   • Click Load unpacked extension

   • Select the built extension folder (e.g., public/ or dist/)

Usage / Integration

Example in your app:

import { requestScreen, switchToScreen, switchToCamera } from 'webrtc-share-ext';

async function startScreenShare() {
  const stream = await requestScreen();
  document.querySelector("#localVideo").srcObject = stream;
}

// Later if needed:
switchToCamera();

API / Methods

Method	Description	Returns
requestScreen()	Prompts the user to pick a screen/window	MediaStream
switchToScreen()	Switches active stream to screen capture	Updates track
switchToCamera()	Switches active stream back to camera	Updates track
isExtensionAvailable()	Checks if the extension API is usable	boolean

Configuration & Options

• Supported capture types: screen, window, tab

• Can be configured to also capture audio

• Optional constraints (frame rate, resolution)

• Fallback to native getDisplayMedia when available

Browser Compatibility & Limits

• Works best in Chromium-based browsers (Chrome, Edge, Brave)

• Requires HTTPS context for security

• May not be required in modern browsers with getDisplayMedia support

• Extension-based APIs are limited to Chrome-specific environments