Presentation - Screen share
Presentation means sharing a screen of a user (presenter) to show a material such as slides to the other call peers. This page describes how to use the presentation function based on the call type.
| Supported call type | Minimum SDK version |
|---|---|
| 1-to-1 call, group call (conference) | PlanetKit 3.0 |
PlanetKit uses HD resolution in its presentation feature, so it can provide an optimized service when the client's network conditions meet or exceed the recommended bandwidth.
1-to-1 call presentation
To start or end a presentation in a 1-to-1 call, use startMyScreenShare() or stopMyScreenShare() of PlanetKitCall.
Related APIs
The following table shows APIs related to screen share in a 1-to-1 call, where a counterpart means a peer to whom to show the presentation.
| Presenter-side API | Description | Counterpart-side API | Description |
|---|---|---|---|
startMyScreenShare(completion:) | Starts screen share by a presenter | peerDidStartScreenShare(_:) | Screen share by a presenter has been started |
| - | - | addPeerScreenShareView(delegate:) | Sets a view instance created by an application |
stopMyScreenShare(completion:), stopMyScreenShare(reason:completion:) | Ends screen share by the presenter | peerDidStopScreenShare(_:reason:) | Screen share by the presenter has been stopped |
| - | - | removePeerScreenShareView(delegate:) | Removes the view instance before release |
After being notified by peerDidStartScreenShare that a presentation has started, the counterpart side must create a view instance and call addPeerScreenShareView() to let PlanetKit render the shared screen.
The presentation video data is automatically streamed to the peer.
1-to-1 call presentation flow
The following diagram shows the flow for starting a presentation in 1-to-1 calls.
The following diagram shows the flow for stopping a presentation in 1-to-1 calls.
Reason to stop screen share
When you call stopMyScreenShare(), you can set one of the reasons defined by application requirements. Allowed values are integers from 0 to 39, and you must define the reasons and values and use them consistently across applications on different platforms. If a valid reason is set, the peerDidStopScreenShare event delivers this value.
Sample code
The following is sample code for the screen share feature in a 1-to-1 call.
For a more complete code example, refer to Screen share in a 1-to-1 call.
Starting screen share
// Start screen share
func startMyScreenShareExample(call: PlanetKitCall) {
call.startMyScreenShare { success in
print("startMyScreenShare result: \(success)")
}
}
Stopping screen share
// Stop screen share
func stopMyScreenShareExample(call: PlanetKitCall) {
call.stopMyScreenShare { success in
print("stopMyScreenShare result: \(success)")
}
}
// Stop screen share with specific reason
// reason: User-defined reason code for stopping screen share
func stopMyScreenShareWithReasonExample(call: PlanetKitCall, reason: Int32) {
call.stopMyScreenShare(reason: reason) { success in
print("stopMyScreenShare(reason=\(reason)) result: \(success)")
}
}
Handling screen share events on the receiver side
extension CallDelegateExample : PlanetKitCallDelegate {
...
func peerDidStartScreenShare(_ call: PlanetKitCall) {
// This is called when the peer started screen share.
// Write you own code here.
}
func peerDidStopScreenShare(_ call: PlanetKitCall, reason: NSNumber?) {
// This is called when the peer stopped screen share.
// Write you own code here.
}
}
Rendering a screen share video on the receiver side
func renderPeerScreenShareVideoExample(call: PlanetKitCall, view: PlanetKitMTKView) {
call.addPeerScreenShareView(delegate: view)
}
Removing a screen share video on the receiver side
func removePeerScreenShareVideoExample(call: PlanetKitCall, view: PlanetKitMTKView) {
call.removePeerScreenShareView(delegate: view)
}
Group call presentation
To start or end a presentation in a group call, use startMyScreenShare() or stopMyScreenShare() of PlanetKitConference.
Related APIs
The following table shows APIs related to screen share in a group call, where counterparts mean participants in a group call to whom to show the presentation.
You can use the methods of PlanetKitPeerControl to control screen share video on a peer's screen share view. For more information on how to use PlanetKitPeerControl, refer to the group call screen share code example.
After being notified by screenShareDidUpdate of PlanetKitConferenceDelegate or didUpdateScreenShare of PlanetKitPeerControlDelegate that a presentation has started (state=ENABLED), the counterpart side must set the view with addPeerScreenShareView() and call startScreenShare() of PlanetKitPeerControl to let PlanetKit render the shared screen.
Unlike 1-to-1 calls, presentation video data is not automatically streamed to participants. Therefore, the counterpart side in group calls must call startScreenShare() of PlanetKitPeerControl to receive the presentation video data.
Group call presentation flow
The following diagram shows the flow for starting a presentation in group calls.
The following diagram shows the flow for stopping a presentation in group calls.
The following diagram shows the flow for a user who joined after a presentation started in a group call.
Reason to stop screen share
When you call stopMyScreenShare(), you can set one of the reasons defined by application requirements. Allowed values are integers from 0 to 39, and you must define the reasons and values and use them consistently across applications on different platforms. If a valid reason is set, the screenShareDidUpdate and didUpdateScreenShare events deliver this value.
Presentation within a subgroup
A presentation feature is available within a subgroup when the presenter subscribed to the subgroup with the "dataSession" attribute set to true. If the presenter starts a presentation within a subgroup scope, the presentation video data is only shared with the members of the subgroup.
To change the destination subgroup of the screen share, use changeMyScreenShareDestination() or changeMyScreenShareDestinationToMainRoom(). For more information, see Subgroup flow - Screen share.
PlanetKit supports the function to receive two screen share streams at the same time. Receiving two presentation videos might cause confusing UX or heavy traffic. However, it can be useful in relation to the subgroup feature.
For example, let's say the first presenter started a presentation to all participants, and the second presenter started a presentation within a subgroup scope. Subgroup members can choose to receive one of them or both by controlling startScreenShare() of PlanetKitPeerControl.
Sample code
The following is sample code for the screen share feature in a group call.
For a more complete code example, refer to Screen share in a group call
Starting screen share
// Start screen share to main room
func startMyScreenShareExample(conference: PlanetKitConference) {
conference.startMyScreenShare(subgroupName: nil) { success in
print("startMyScreenShare result: \(success)")
}
}
// Start screen share to specific subgroup
// subgroupName: Target subgroup name, or nil for main room
func startMyScreenShareToSubgroupExample(conference: PlanetKitConference, subgroupName: String?) {
conference.startMyScreenShare(subgroupName: subgroupName) { success in
print("startMyScreenShare(subgroup=\(subgroupName ?? "main room")) result: \(success)")
}
}
Stopping screen share
// Stop screen share
func stopMyScreenShareExample(conference: PlanetKitConference) {
conference.stopMyScreenShare { success in
print("stopMyScreenShare result: \(success)")
}
}
// Stop screen share with specific reason
// reason: User-defined reason code for stopping screen share
func stopMyScreenShareWithReasonExample(conference: PlanetKitConference, reason: Int32) {
conference.stopMyScreenShare(reason: reason) { success in
print("stopMyScreenShare(reason=\(reason)) result: \(success)")
}
}
Changing screen share destination
// Change screen share destination to a specific subgroup
// subgroupName: Target subgroup name to change to
func changeScreenShareDestinationExample(conference: PlanetKitConference, subgroupName: String) {
conference.changeMyScreenShareDestination(subgroupName: subgroupName) { success in
print("changeMyScreenShareDestination(to=\(subgroupName)) result: \(success)")
}
}
// Change screen share destination to main room
func changeScreenShareDestinationToMainRoomExample(conference: PlanetKitConference) {
conference.changeMyScreenShareDestinationToMainRoom { success in
print("changeMyScreenShareDestinationToMainRoom result: \(success)")
}
}
Handling screen share events on the receiver side
extension ConferenceDelegateExample : PlanetKitConferenceDelegate {
...
func screenShareDidUpdate(_ conference: PlanetKitConference, updated: PlanetKitConferenceScreenShareUpdateParam) {
// This is called when a peer's screen share state changes.
let state = updated.state
if state == .enabled {
print("Peer started screen share")
// Add your own code here
} else {
print("Peer stopped screen share")
// Add your own code here
}
}
}
extension PeerControlDelegateExample : PlanetKitPeerControlDelegate {
...
func didUpdateScreenShare(
_ peerControl: PlanetKitPeerControl,
subgroup: PlanetKitSubgroup,
status: PlanetKitScreenShareStatus,
disabledReason: NSNumber?
) {
// This is called when the peer's screen share state changes.
if status.state == .enabled {
print("Peer screen share enabled")
// Add your own code here
} else {
print("Peer screen share disabled")
// Add your own code here
}
}
}
Starting a screen share video on the receiver side
func startPeerScreenShareVideoExample(peerControl: PlanetKitPeerControl, subgroupName: String?, peerScreenShareView: PlanetKitMTKView) {
view.addSubview(peerScreenShareView)
peerControl.startScreenShare(delegate: peerScreenShareView, subgroupName: subgroupName) { success in
print("startScreenShare result: \(success)")
}
}
Stopping a screen share video on the receiver side
func stopPeerScreenShareVideoExample(peerControl: PlanetKitPeerControl, peerScreenShareView: PlanetKitMTKView) {
peerScreenShareView.removeFromSuperview()
peerControl.stopScreenShare { success in
print("stopScreenShare result: \(success)")
}
}