Screen Sharing

Feature Overview

Screen sharing refers to sharing screen content with other audiences in the form of video during video calls or interactive live streaming to enhance interactive experience and improve communication efficiency.

Screen sharing is widely used in the following scenarios:

• In video conferencing scenarios, screen sharing can share the speaker's local files, data, web pages, PPT, and other images with other participants;
• In online classroom scenarios, screen sharing can display the teacher's courseware, notes, lecture content, and other images for students to watch.

Example Source Code Download

Please refer to Download Example Source Code to get the source code.

For related source code, please check the files in the "/ZegoExpressExample/Others/src/main/java/im/zego/others/screensharing" directory.

others
└── screensharing
    └── ScreenSharingActivity.java
...

others
└── screensharing
    └── ScreenSharingActivity.java
...

Prerequisites

Before implementing screen sharing functionality, please ensure:

• Supports Android 5.0 or above, and Android devices or emulators that support audio and video (using real devices is recommended).
• You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
• You have integrated ZEGO Express SDK in your project and implemented basic audio and video streaming functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.

Implementation Flow

The following figure shows the data flow of screen sharing on the Android platform:

1 (Required) Obtain user screen recording authorization

In the project's AndroidManifest.xml file, add screen recording permission configuration. After setting up, a popup will prompt the user whether to allow the app to record the screen before recording, requiring user authorization.

1. The screen recording feature depends on foreground service to keep alive. Go to the "app/src/main" directory of your project, open the "AndroidManifest.xml" file, and add permission declarations.

   • If the target Android SDK version is lower than 34.0.0, you need to set the FOREGROUND_SERVICE permission declaration.

     <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

     <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

   • If the target Android SDK version is 34.0.0 or later, you need to set both FOREGROUND_SERVICE and FOREGROUND_SERVICE_MEDIA_PROJECTION permission declarations.

     <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION"/>

     <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION"/>

2. Declare the foreground service and auxiliary Activity for screen recording.

   Warning

   • If you are using SDK version 3.6.0 or above and integrating through Maven automatically (or manually integrating the ".aar" package), you can skip this step.
   • If you are using SDK version below 3.6.0, you must manually declare the foreground service and auxiliary Activity for screen recording, otherwise you will not be able to start screen recording.

   <application>
   <activity
           android:name="im.zego.internal.screencapture.ZegoScreenCaptureManager$ZegoScreenCaptureAssistantActivity"
           android:exported="false"
           android:configChanges="screenSize|orientation"
           android:screenOrientation="fullUser"
           android:theme="@android:style/Theme.Translucent" />
       <service
           android:name="im.zego.internal.screencapture.ZegoScreenCaptureService"
           android:enabled="true"
           android:exported="false"
           android:foregroundServiceType="mediaProjection">
           <intent-filter>
           <action android:name="android.intent.action.screenshare" />
           </intent-filter>
       </service>
   </application>

   <application>
   <activity
           android:name="im.zego.internal.screencapture.ZegoScreenCaptureManager$ZegoScreenCaptureAssistantActivity"
           android:exported="false"
           android:configChanges="screenSize|orientation"
           android:screenOrientation="fullUser"
           android:theme="@android:style/Theme.Translucent" />
       <service
           android:name="im.zego.internal.screencapture.ZegoScreenCaptureService"
           android:enabled="true"
           android:exported="false"
           android:foregroundServiceType="mediaProjection">
           <intent-filter>
           <action android:name="android.intent.action.screenshare" />
           </intent-filter>
       </service>
   </application>

2 Set capture source to screen sharing source

• The default "video source" for SDK publishing is the camera. If you need to publish a screen sharing source, you need to switch to screen sharing through setVideoSource.

  engine.setVideoSource(ZegoVideoSourceType.SCREEN_CAPTURE, ZegoPublishChannel.MAIN);

  engine.setVideoSource(ZegoVideoSourceType.SCREEN_CAPTURE, ZegoPublishChannel.MAIN);

• The default "audio source" for SDK publishing is the microphone. If you need to publish a screen sharing source, you need to switch to screen sharing through setAudioSource.

  engine.setAudioSource(ZegoAudioSourceType.SCREEN_CAPTURE, ZegoPublishChannel.MAIN);

  engine.setAudioSource(ZegoAudioSourceType.SCREEN_CAPTURE, ZegoPublishChannel.MAIN);

3 Start screen sharing

Call the startScreenCapture interface to share the entire system's screen and capture audio from third-party applications.

engine.startScreenCapture();

engine.startScreenCapture();

Developers can also use the ZegoScreenCaptureConfig parameter to set whether to capture video, whether to capture audio, set the sample rate and sample channel when capturing audio, etc.

ZegoScreenCaptureConfig config = new ZegoScreenCaptureConfig();
config.captureVideo = true;
config.captureAudio = true;
config.audioParam.sampleRate = ZegoAudioSampleRate.ZEGO_AUDIO_SAMPLE_RATE_16K;
config.audioParam.channel = ZegoAudioChannel.STEREO;
// Optional parameter, set the video capture area, must be within the original video data, unit is pixels (px)
config.cropRect = new Rect(left, top, right, bottom);

engine.startScreenCapture(config);

ZegoScreenCaptureConfig config = new ZegoScreenCaptureConfig();
config.captureVideo = true;
config.captureAudio = true;
config.audioParam.sampleRate = ZegoAudioSampleRate.ZEGO_AUDIO_SAMPLE_RATE_16K;
config.audioParam.channel = ZegoAudioChannel.STEREO;
// Optional parameter, set the video capture area, must be within the original video data, unit is pixels (px)
config.cropRect = new Rect(left, top, right, bottom);

engine.startScreenCapture(config);

3.1 Set screen sharing orientation

Screen sharing orientation supports following system orientation and fixed orientation. By default, it follows the system orientation. You can set the orientation parameter in ZegoScreenCaptureConfig to set the screen sharing orientation.

ZegoScreenCaptureConfig config = new ZegoScreenCaptureConfig();
...
config.orientation = ZegoScreenCaptureOrientation.LANDSCAPE; // Fixed landscape
engine.startScreenCapture(config);

ZegoScreenCaptureConfig config = new ZegoScreenCaptureConfig();
...
config.orientation = ZegoScreenCaptureOrientation.LANDSCAPE; // Fixed landscape
engine.startScreenCapture(config);

4 Update screen sharing configuration

Call the updateScreenCaptureConfig interface to update the screen sharing configuration.

ZegoScreenCaptureConfig config = new ZegoScreenCaptureConfig();
config.captureVideo = true;
config.captureAudio = false;
config.audioParam.sampleRate = ZegoAudioSampleRate.ZEGO_AUDIO_SAMPLE_RATE_32K;
config.audioParam.channel = ZegoAudioChannel.STEREO;
config.orientation = ZegoScreenCaptureOrientation.PORTRAIT; // Fixed portrait
// Optional parameter, set the video capture area, must be within the original video data, unit is pixels (px)
config.cropRect = new Rect(left, top, right, bottom);

engine.updateScreenCaptureConfig(config);

ZegoScreenCaptureConfig config = new ZegoScreenCaptureConfig();
config.captureVideo = true;
config.captureAudio = false;
config.audioParam.sampleRate = ZegoAudioSampleRate.ZEGO_AUDIO_SAMPLE_RATE_32K;
config.audioParam.channel = ZegoAudioChannel.STEREO;
config.orientation = ZegoScreenCaptureOrientation.PORTRAIT; // Fixed portrait
// Optional parameter, set the video capture area, must be within the original video data, unit is pixels (px)
config.cropRect = new Rect(left, top, right, bottom);

engine.updateScreenCaptureConfig(config);

5 Listen to screen sharing callback notifications

Developers need to listen to the following callbacks in the IZegoEventHandler class:

• onScreenCaptureStart callback, receive notification of successful screen capture start, convenient for subsequent business processing, such as UI prompts or application redirects, etc.
• onScreenCaptureExceptionOccurred callback, receive notification of exception information during screen sharing, so as to analyze the reasons for screen sharing failure.

public void setEngineEventHandler(){
    engine.setEventHandler(new IZegoEventHandler() {
        @Override
        public void onScreenCaptureExceptionOccurred(ZegoScreenCaptureExceptionType exceptionType) {
            super.onScreenCaptureExceptionOccurred(exceptionType);
            AppLogger.getInstance().receiveCallback("screen capture exception occurred: %s", exceptionType);
        }
        @Override
        public void onScreenCaptureStart() {
            super.onScreenCaptureStart();
            AppLogger.getInstance().receiveCallback("screen capture start");
        }
    });
}

public void setEngineEventHandler(){
    engine.setEventHandler(new IZegoEventHandler() {
        @Override
        public void onScreenCaptureExceptionOccurred(ZegoScreenCaptureExceptionType exceptionType) {
            super.onScreenCaptureExceptionOccurred(exceptionType);
            AppLogger.getInstance().receiveCallback("screen capture exception occurred: %s", exceptionType);
        }
        @Override
        public void onScreenCaptureStart() {
            super.onScreenCaptureStart();
            AppLogger.getInstance().receiveCallback("screen capture start");
        }
    });
}

6 Login to Room and start publishing stream

Call the loginRoom interface, pass in the room ID parameter "roomID" and user parameter "user", to login to the Room.

Call the startPublishingStream interface, pass in the stream ID parameter "streamID", to send the local audio and video stream to remote users.

// Create user
ZegoUser user = new ZegoUser("user1");

// Start logging in to Room
engine.loginRoom("room1", user);
// Start publishing stream
engine.startPublishingStream("stream1");

// Create user
ZegoUser user = new ZegoUser("user1");

// Start logging in to Room
engine.loginRoom("room1", user);
// Start publishing stream
engine.startPublishingStream("stream1");

At this point, we have completed the operation of capturing screen data and sharing it to remote ends through ZEGO Express SDK.

7 Watch remote screen sharing

After completing the above steps, other users can use the startPlayingStream interface to pull the screen sharing stream.

// Play stream, need to pass in the streamID used when the user who initiated screen sharing published the stream
engine.startPlayingStream(streamID, new ZegoCanvas(playView));

// Play stream, need to pass in the streamID used when the user who initiated screen sharing published the stream
engine.startPlayingStream(streamID, new ZegoCanvas(playView));

8 Stop screen sharing

Users can call the stopScreenCapture interface to stop sharing.

engine.stopScreenCapture();

engine.stopScreenCapture();

FAQ

When the Android device is fixed in portrait (auto-rotation disabled), starting screen capture causes popup orientation abnormalities and interface landscape/portrait switching. How to solve this?

Due to the conflict between the device fixed portrait and the App landscape interface, the screen capture causes rapid landscape/portrait switching, triggering system data abnormality and black screen. Solutions:

• Solution 1: Override SDK configuration through tools:replace

  The SDK screen sharing auxiliary Activity default orientation is "fullUser". You need to modify it in the project's AndroidManifest.xml:

  1. Add the "tools" tool namespace in the root node (manifest tag);
  2. Find the above Activity configuration, change its screen orientation (screenOrientation) to "unspecified", and add tools:replace to force override the SDK default configuration. After recompiling, the popup will be consistent with the App landscape, avoiding switching black screen.

• Solution 2: Enable device auto-rotation

  Go to device "Settings > Display > Auto-rotate screen", after enabling, the popup orientation will follow the App landscape, no switching black screen issue.