startScreenShare

startScreenShare(options?): Promise<void>

Starts sharing the local screen. The browser shows its own surface picker; the promise settles once the share’s leg is connected.

A call carries at most one screen share. Read screenShareStatus before calling and treat 'starting' and 'stopping' as busy — starting a second share throws rather than replacing the live one.

The call itself is unaffected when acquisition fails: a screen-share failure is never fatal.

Parameters

Returns

Promise<void>

Throws

• ScreenShareAlreadyActiveError — this call is already sharing a screen. Call stopScreenShare before starting another.
• AuxiliaryLegCancelledError — stopScreenShare() removed the share before its leg finished connecting.
• AuxiliaryLegTimeoutError — the leg did not connect within its budget. The picker is human time and sits outside that budget; only the connect that follows it is bounded.
• The raw getDisplayMedia error. A dismissed picker or a permission denial rejects with a NotAllowedError DOMException — inspect error.name to tell benign cancels apart from real failures.

Examples

await selfParticipant.startScreenShare();

Sharing a tab together with its audio:

await selfParticipant.startScreenShare({ audio: true });

Distinguishing a dismissed picker from a real failure:

import { ScreenShareAlreadyActiveError } from '@signalwire/js';
try {
  await selfParticipant.startScreenShare({ audio: true });
} catch (error) {
  if (error instanceof ScreenShareAlreadyActiveError) {
    await selfParticipant.stopScreenShare();
  } else if (error.name === 'NotAllowedError') {
    // The user dismissed the picker — nothing to report.
  } else {
    throw error;
  }
}

See

• screenShareStatus$ — reactive state.
• stopScreenShare — end the share.
• Gated by SelfCapabilities.screenshare.