Interface ScreenVideoTrackInitConfig

Configurations for the video track for screen sharing. Set these configurations when calling [AgoraRTC.createScreenVideoTrack]IAgoraRTC.createScreenVideoTrack.

interface ScreenVideoTrackInitConfig {
    displaySurface?: "window" | "browser" | "monitor";
    electronScreenSourceId?: string;
    encoderConfig?: string | VideoEncoderConfiguration;
    extensionId?: string;
    optimizationMode?: "motion" | "detail";
    screenSourceType?: ScreenSourceType;
    selfBrowserSurface?: "exclude" | "include";
    surfaceSwitching?: "exclude" | "include";
    systemAudio?: "exclude" | "include";
}

Properties

displaySurface? electronScreenSourceId? encoderConfig? extensionId? optimizationMode? screenSourceType? selfBrowserSurface? surfaceSwitching? systemAudio?

Properties

Optional displaySurface

displaySurface?: "window" | "browser" | "monitor"

Since


   4.17.1

The pre-selected pane in the media picker. See displaySurface for details.

Note: This property is supported on Chrome 107 and later, as well as Edge 107 and later.

Optional electronScreenSourceId

electronScreenSourceId?: string

The sourceId when you share the screen through Electron.

Optional encoderConfig

encoderConfig?: string | VideoEncoderConfiguration

The video encoder configurations for screen sharing.

You can set the video encoder configurations in either of the following ways:

  • Pass the preset video encoder configurations by using [[ScreenEncoderConfigurationPreset]].
  • Pass your customized video encoder configurations by using [[VideoEncoderConfiguration]].
  • Leave this property empty to use the SDK's default value, "1080p_2" (resolution: 1920 × 1080, frame rate: 30 fps, bitrate: 3000 Kbps).

Optional extensionId

extensionId?: string

The extensionId when you share the screen with a Chrome extension.

Optional optimizationMode

optimizationMode?: "motion" | "detail"

Since


   4.2.0

Sets the video transmission optimization mode.

You can call this method during a video call, a live streaming or screen sharing to dynamically change the optimization mode. For example, during the screen sharing, before you change the shared content from text to video, you can change the optimization mode from "detail" to "motion" to ensure smoothness in poor network conditions.

Note: This method supports Chrome only.

Param: mode

The video transmission optimization mode:

  • "detail": Prioritizes video quality.
    • The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
    • In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
  • "motion": Since 4.21.0, the SDK prioritizes video smoothness.
  • In poor network conditions, the SDK reduces the sending bitrate to minimize video freezes.
  • In most cases, the SDK does not reduce the frame rate, but may reduce the sending resolution.

Optional screenSourceType

screenSourceType?: ScreenSourceType

Deprecated

from v4.17.1. Use displaySurface instead.

The type of the source for screen sharing.

Optional selfBrowserSurface

selfBrowserSurface?: "exclude" | "include"

Since


   4.17.1

Whether to allow the user to share the current tab:

  • "include": (Default) Allows the user to share the current tab.
  • "exclude": Prevents the user from sharing the current tab.

See displaySurface for details.

Note:

  • This property is defaulted to "exclude" on Chrome 107. For better compatibility with earlier versions, the SDK changes the default value to "include", which ensures that users can still share the current tab after upgrading to Chrome 107.
  • This property is supported on Chrome 107 and later, as well as Edge 107 and later.

Optional surfaceSwitching

surfaceSwitching?: "exclude" | "include"

Since


   4.17.1

Whether to allow the user to dynamically switch between shared tabs:

  • "include": (Default) The user can dynamically switch between shared tabs.
  • "exclude": The user cannot dynamically switch between shared tabs.

See surfaceSwitching for details.

Note: This property is supported on Chrome 107 and later, as well as Edge 107 and later.

Optional systemAudio

systemAudio?: "exclude" | "include"

Since


   4.17.1

Whether to capture system audio:

  • "include": (Default) Captures system audio.
  • "exclude": Avoids capturing system audio

See systemAudio for details.

Note: This property is supported on Chrome 105 and later (Windows only), as well as Edge 105 and later (Windows only).

Settings

Member Visibility

Theme

On This Page

displaySurfaceelectronScreenSourceIdencoderConfigextensionIdoptimizationModescreenSourceTypeselfBrowserSurfacesurfaceSwitchingsystemAudio