# Video

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

You can programmatically control user video for an ongoing session using the methods provided by the Video SDK.

> **Note:** Prior to using video, you will need to request permissions to use the camera. See the rest of this page for details and [Requesting authorization to capture and save media](https://developer.apple.com/documentation/avfoundation/capture_setup/requesting_authorization_to_capture_and_save_media) for more.

## Video controls

Using the SDK functions, users in a session can be provided with controls for managing their video. Session hosts can manage their own video as well the video of other users in the session.

Some common features that you might want to include in your app could be an option to enable or disable a user's video. Prior to changing the video control, you may also need to obtain data about the state of each users' present it in the UI of your app.

The following are some examples that you can refer to when implementing features related to video controls.

### Display or hide a user's video

Video can be controlled on a per-user basis. First, you should check the current video status of the user:

```swift
// Get videoStatus of User.
let videoStatus = user.getVideoCanvas()?.videoStatus()
// Check if User's video is on.
let isVideoOn = user.getVideoCanvas()?.videoStatus()?.on
```

```objectivec
// Get videoStatus of User.
ZoomVideoSDKVideoStatus *videoStatus = [user videoStatus];
// Check if User's video is on.
BOOL isVideoOn = [[user videoCanvas] videoStatus].on;
```

If the user's video is not already enabled, you can start video using `startVideo`, provided by the `ZoomVideoSDKVideoHelper`:

```swift
// Get the ZoomVideoSDKVideoHelper to perform video actions.
if let videoHelper = ZoomVideoSDK.shareInstance()?.getVideoHelper() {
    // Start local User's video.
    videoHelper.startVideo()
}
```

```objectivec
// Get the ZoomVideoSDKVideoHelper to perform video actions.
ZoomVideoSDKVideoHelper *videoHelper = [[ZoomVideoSDK shareInstance] getVideoHelper];
if (videoHelper) {
    // Start local User's video.
    [videoHelper startVideo];
}
```

To stop displaying the video of a user, use `stopVideo`:

```swift
// Get the ZoomVideoSDKVideoHelper to perform video actions.
if let videoHelper = ZoomVideoSDK.shareInstance()?.getVideoHelper() {
    // Stop local User's video.
    videoHelper.stopVideo()
}
```

```objectivec
// Get the ZoomVideoSDKVideoHelper to perform video actions.
ZoomVideoSDKVideoHelper *videoHelper = [[ZoomVideoSDK shareInstance] getVideoHelper];
if (videoHelper) {
    // Stop local User's video.
    [videoHelper stopVideo];
}
```

## Render a user's video

The **Video SDK** allows you to render the video of each user who join a session. To do so, you'll have to:

1. Retrieve the `ZoomVideoSDKUser` object related to each user as they join the session.
2. Obtain the video canvas from each user and render their video.

## Render a user's video canvas

Now that you have access to user information represented by the `ZoomVideoSDKUser` object, you must retrieve the `ZoomVideoSDKVideoCanvas` of each user whose video you would like to render and pass a `UIView` into the canvas to subscribe to that user's video.

```swift
// Get User's videoCanvas.
if let usersVideoCanvas = user.getVideoCanvas() {
    // Set video aspect.
    let videoAspect = ZoomVideoSDKVideoAspect.panAndScan
    // Subscribe User's videoCanvas to render their video stream.
    usersVideoCanvas.subscribe(with: view, andAspectMode: videoAspect)
}
```

```objectivec
// Get User's videoCanvas.
ZoomVideoSDKVideoCanvas *usersVideoCanvas = [user getVideoCanvas];
// Set video aspect.
ZoomVideoSDKVideoAspect videoAspect = ZoomVideoSDKVideoAspect_PanAndScan;
// Subscribe User's videoCanvas to render their video stream.
[usersVideoCanvas subscribeWithView:view andAspectMode:videoAspect];
```

You can provide any of the following options to the `videoAspect`
property in order to set the aspect mode of the video:

| Type                                  | Description                                                                                                                                                                                                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ZoomVideoSDKVideoAspect_Original`    | Displays original video without any modifications like edit, cropping or zoom.                                                                                                                                                                                            |
| `ZoomVideoSDKVideoAspect_Full_Filled` | Stretches video stream to fill video canvas.                                                                                                                                                                                                                              |
| `ZoomVideoSDKVideoAspect_LetterBox`   | For video streams with 16:9 aspect ratios shown on a 4:3 screen, black bars will be added to the top and bottom to fit the canvas.For video streams with a 4:3 aspect ratio shown on a 16:9 screen, black bars will be added to the left and the right to fit the canvas. |
| `ZoomVideoSDKVideoAspect_PanAndScan`  | For video streams with 16:9 aspect ratios shown on a 4:3 screen, the left and right of the screen will be cropped to fit the canvas.For video streams with 4:3 aspect ratios shown on a 16:9 screen, the top/bottom of the screen will be cropped.                        |

### Stop rendering user's video

To stop rendering a user's content, you must unsubscribe from the user's video by calling the `unsubscribe()` method as shown below:

```swift
// Get User's videoCanvas.
if let usersVideoCanvas = user.getVideoCanvas() {
    // Unsubscribe User's videoCanvas to render their video stream.
    usersVideoCanvas.unSubscribe(with: view)
}
```

```objectivec
// Get User's videoCanvas.
ZoomVideoSDKVideoCanvas *usersVideoCanvas = [user getVideoCanvas];
// Unsubscribe User's videoCanvas to render their video stream.
[usersVideoCanvas unSubscribeWithView:view];
```

## Use virtual background

Use [`ZoomVideoSDKVirtualBackgroundHelper`](https://marketplacefront.zoom.us/sdk/custom/ios/interface_zoom_video_s_d_k_virtual_background_helper.html) to enable virtual backgrounds. First determine whether the device supports it using `isSupportVirtualBackground`. If the device supports it, use the helper functions to add, get, set, and remove virtual backgrounds.

To add virtual backgrounds:

1. Use `addVirtualBackgroundItem` to add a virtual background item.
2. Use `getVirtualBackgroundItemList` to get a list of available virtual background items.
3. Choose a virtual background item from the list and use `setVirtualBackgroundItem` to set the virtual background.

Use `removeVirtualBackgroundItem` to remove the virtual background or set the virtual background to None. Use `getSelectedVirtualBackgroundItem` to get the current selected background.

```swift
// Check if virtual background is supported
func isSupportVirtualBackground() -> Bool

// Add virtual background item
func addVirtualBackgroundItem(image: UIImage?) -> ZoomVideoSDKVirtualBackgroundItem?

// Remove virtual background item
func removeVirtualBackgroundItem(imageItem: ZoomVideoSDKVirtualBackgroundItem?) -> ZoomVideoSDKError

// Get virtual background item list
func getVirtualBackgroundItemList() -> [ZoomVideoSDKVirtualBackgroundItem]?

// Set virtual background item
func setVirtualBackgroundItem(imageItem: ZoomVideoSDKVirtualBackgroundItem?) -> ZoomVideoSDKError

// Get selected virtual background
func getSelectedVirtualBackgroundItem() -> ZoomVideoSDKVirtualBackgroundItem?
```

```objectivec
// Check if virtual background is supported
- (BOOL) isSupportVirtualBackground

// Add virtual background item
- (ZoomVideoSDKVirtualBackgroundItem *_Nullable) addVirtualBackgroundItem: (UIImage *_Nullable) image

// Remove virtual background item
- (ZoomVideoSDKError) removeVirtualBackgroundItem: (ZoomVideoSDKVirtualBackgroundItem *_Nullable) imageItem

// Get virtual background item list
- (NSArray< ZoomVideoSDKVirtualBackgroundItem * > *_Nullable) getVirtualBackgroundItemList

// Set virtual background item
- (ZoomVideoSDKError) setVirtualBackgroundItem: (ZoomVideoSDKVirtualBackgroundItem *_Nullable) imageItem

// Get selected virtual background
- (ZoomVideoSDKVirtualBackgroundItem *_Nullable) getSelectedVirtualBackgroundItem
```

## Video quality preference

When network bandwidth is limited, you can adjust video quality preferences between resolution and frame rate. For example, you can choose to preserve the video sharpness or smoothness. If bandwidth is not a concern, you can receive the best quality video using a high video resolution and maximum frame rate.

Set your video quality preferences with the [ZoomVideoSDKVideoPreferenceSetting](https://marketplacefront.zoom.us/sdk/custom/ios/interface_zoom_video_s_d_k_video_preference_setting.html).

### Video preference modes

Choose from the following modes, depending on what you'd like to prioritize:

-   **Balance mode.** Zoom will do what is best under the current bandwidth situation and make adjustments as needed. You don't need to set any additional parameters for this mode. This mode is suitable for video conference usage. This is the default preference.
-   **Smoothness mode.** Preserves the frame rate as much as possible. If network bandwidth degrades, Zoom will sacrifice video resolution to preserve the frame rate. This prioritizes a smooth video frame transition.
-   **Sharpness mode.** Preserves the resolution as much as possible. If network bandwidth degrades, Zoom will sacrifice the frame rate to preserve video resolution. This prioritizes a sharp video image.
-   **Custom mode.** Allows you to provide the minimum and maximum frame rate. Use this mode if you have an understanding of your network behavior and a clear idea of how to adjust the frame rate to achieve the desired video quality. You can also use this mode to influence bandwidth usage by increasing or decreasing the maximum frame rate setting. Given a resolution, a lower maximum frame rate results in less bandwidth usage. Note that if the bandwidth cannot be sustained by following the minimum and maximum frame rates, the system will drop down to the next lower resolution.

See the reference documentation for details.

### Use cases

Video quality preferences are useful when the primary focus is not the image of a person attending the session, but on other video images where smoothness or sharpness is preferred.

Aside from video conferencing, you may want to set video quality preferences for:

-   Transmission of medical X-ray images.
-   Transmission of video captured by endoscopic cameras during a medical operation.
-   Live sporting event broadcasts, such as co-watching or broadcasting a football game.

## Callbacks

The following is an example video callback.

### Get notified when a user's video status has changed

```swift
func onUserVideoStatusChanged(_ helper: ZoomVideoSDKVideoHelper?, user userArray: [ZoomVideoSDKUser]?) {
    // UserArray contains the users that had a video status change.
    // Use helper to perform actions on a user.
    if let userArray = userArray {
        for user in userArray {
            // Use .getVideoCanvas.videoStatus.on to check if a user's video is on or off.
            if let isUserVideoOn = user.getVideoCanvas()?.videoStatus()?.on {
                if isUserVideoOn {
                    // User's video is on.
                }
            }
        }
    }
}
```

```objectivec
- (void)onUserVideoStatusChanged:(ZoomVideoSDKVideoHelper *)helper user:(NSArray<ZoomVideoSDKUser *> *)userArray {
    // UserArray contains the users that had a video status change.
    // Use helper to perform actions on a user.
    for (int i = 0; i < userArray.count; i++) {
                // Use .getVideoCanvas.videoStatus.on to check if a user's video is on or off.
        if (userArray[i].getVideoCanvas.videoStatus.on) {
            // User's video is on.
        }
    }
}
```