CameraController

@available(iOS 9.0, *)
@objcMembers
@objc(PESDKCameraController)
open class CameraController : NSObject

The CameraController class provides functions for several camera related tasks, including setup, flash control, and such.

  • When this closure is called, the SDK has determined that location access has not been granted to the host app yet. Within this closure you should then request appropriate permissions from the passed in CLLocationManager object. Location access is used to tag photos with the location where they are taken.

    Attention

    Starting Spring 2019, all apps submitted to the App Store that access user data are required to include a purpose string as soon as location permissions requests appear somewhere in the binary. Since we do not want to force developers integrating the SDK into their app to include a purpose string even with location tagging disabled, this closure was introduced, so that developers can decide for themselves if it is appropriate to request location access. Simply set this property like this: cameraController.locationAccessRequestClosure = { locationManager in locationManager.requestWhenInUseAuthorization() }

    Note

    When this camera controller was instantiated by a CameraViewController object, this property will be set automatically and forward location access requests to CameraViewController.locationAccessRequestClosure.

    Declaration

    Swift

    open var locationAccessRequestClosure: ((CLLocationManager) -> Void)?
  • An instance of a UIView that is used to present the preview.

    Declaration

    Swift

    public let videoPreviewView: UIView
  • An instance of a UIView that hosts the videoPreviewView in the center.

    Declaration

    Swift

    public let videoPreviewViewContainer: UIView
  • The currently active recording mode (i.e. .Photo or .Video). Setting this property before calling setupWithInitialRecordingMode(:) is ignored. The setter asynchronously updates the session, so the getter might not immediately represent the new value. You can observe changes to the value of this property using key-value observing.

    Declaration

    Swift

    open dynamic var recordingMode: RecordingMode { get set }
  • Called when the running state of the camera changes.

    Declaration

    Swift

    open var runningStateChangedHandler: ((Bool) -> Void)?
  • Called when the camera position changes.

    Declaration

    Swift

    open var cameraPositionChangedHandler: ((AVCaptureDevice.Position, AVCaptureDevice.Position) -> Void)?
  • Called when the recording mode changes.

    Declaration

    Swift

    open var recordingModeChangedHandler: ((RecordingMode) -> Void)?
  • Called when the list of available camera positions was changed.

    Declaration

    Swift

    open var availableCameraPositionsChangedHandler: (() -> Void)? { get set }
  • Called when any aspect of the flash changes. hasFlash is true if the current camera has a flash. flashMode represents the currently active flash mode. flashAvailable is true if the flash is available for use.

    Declaration

    Swift

    open var flashChangedHandler: ((Bool, AVCaptureDevice.FlashMode, Bool) -> Void)?
  • Called when any aspect of the torch changes. hasTorch is true if the current camera has a torch. torchMMode represents the currently active torch mode. torchAvailable is true if the torch is available for use.

    Declaration

    Swift

    open var torchChangedHandler: ((Bool, AVCaptureDevice.TorchMode, Bool) -> Void)?
  • Called when a photo is currently being captured or done being captured.

    Declaration

    Swift

    open var capturingStillImageHandler: ((Bool) -> Void)?
  • Called when the session is interrupted or the interruption ended. This can happen when switching to a multi-app layout, introduced in iOS 9 for example.

    Declaration

    Swift

    open var sessionInterruptionHandler: ((Bool) -> Void)?
  • Called when a runtime error occurs.

    Declaration

    Swift

    open var sessionRuntimeErrorHandler: ((NSError) -> Void)?
  • Called when the user did not grant authorization for the camera.

    Declaration

    Swift

    open var authorizationFailedHandler: (() -> Void)?
  • Called when video recording starts.

    Declaration

    Swift

    open var videoRecordingStartedHandler: (() -> Void)?
  • Called when video recording finishes.

    Declaration

    Swift

    open var videoRecordingFinishedHandler: ((URL) -> Void)?
  • Called when video recording fails.

    Declaration

    Swift

    open var videoRecordingFailedHandler: (() -> Void)?
  • Called each second while a video recording is in progress.

    Declaration

    Swift

    open var videoRecordingProgressHandler: ((Int) -> Void)?
  • Called when the size of the preview image within the videoPreviewView changes

    Declaration

    Swift

    open var previewFrameChangedHandler: ((CGRect) -> Void)?
  • Called when the focus point changes.

    Declaration

    Swift

    open var focusPointChangedHandler: ((CGPoint) -> Void)?
  • Called when the focus mode changes.

    Declaration

    Swift

    open var focusModeChangedHandler: ((AVCaptureDevice.FocusMode, AVCaptureDevice.ExposureMode) -> Void)?
  • Called when the focus gets disabled.

    Declaration

    Swift

    open var focusDisabledHandler: (() -> Void)?
  • The video output settings to use for video recording. If nil, the recommended video settings for file type AVFileTypeQuickTimeMovie will be used.

    Declaration

    Swift

    open var videoOutputSettings: [String : AnyObject]?
  • The video output settings to use for video recording. If nil, the recommended audio settings for file type AVFileTypeQuickTimeMovie will be used.

    Declaration

    Swift

    open var audioOutputSettings: [String : AnyObject]?
  • The file type to use for video recording. Default is AVFileTypeQuickTimeMovie.

    Note

    If you change this, you will most likely also want to change videoOutputSettings and audioOutputSettings.

    Declaration

    Swift

    open var videoRecordingFileType: AVFileType
  • The extension to use for video files. Default is mov.

    Declaration

    Swift

    open var videoRecordingFileExtension: String
  • Use this closure to further configure the asset writer that is created for video recording.

    Declaration

    Swift

    open var assetWriterConfigurationClosure: ((AVAssetWriter) -> Void)?
  • An array of camera positions (e.g. .Front, .Back) that you want to support. Setting this property automatically checks if the device supports all camera positions and updates the property accordingly if it does not. Passing an empty array to this property is ignored. Defaults to all available camera positions. Duplicate values result in undefined behaviour.

    Declaration

    Swift

    open var cameraPositions: [AVCaptureDevice.Position] = AVCaptureDevice.devices(for: AVMediaType.video).compactMap {
     $0.position
    }
  • An array of flash modes (e.g. .Auto, .On, .Off) that you want to support. Passing an empty array to this property is ignored. Often not all modes are supported by each camera on a device, in which case only the supported flash modes are used. Defaults to all flash modes. Duplicate values result in undefined behaviour.

    Declaration

    Swift

    open var flashModes: [AVCaptureDevice.FlashMode] { get set }
  • An array of torch modes (e.g. .Auto, .On, .Off) that you want to support. Passing an empty array to this property is ignored. Often not all modes are supported by each camera on a device, in which case only the supported torch modes are used. Defaults to all torch modes. Duplicate values result in undefined behaviour.

    Declaration

    Swift

    open var torchModes: [AVCaptureDevice.TorchMode] { get set }
  • Set to false to disable locking focus when a user taps on the live preview. Default is true.

    Declaration

    Swift

    open var tapToFocusEnabled: Bool { get set }
  • The effect filter that is applied to the live feed.

    Declaration

    Swift

    open var effect: Effect? { get set }
  • The intensity of the filter that is applied to the live feed.

    Declaration

    Swift

    open var effectIntensity: CGFloat { get set }
  • Whether the recorded video should include the applied filter or not.

    Declaration

    Swift

    open var includeEffectInOutput: Bool { get set }
  • Whether the user’s location should be included in photos. This is enabled by default.

    Declaration

    Swift

    open var includeUserLocation: Bool
  • Initializes the camera. This method must be called before calling startCamera(). Any handlers that will be used should be set before calling this method, so that they are called with their initial values.

    Throws

    A CameraControllerError or an NSError if setup fails.

    Declaration

    Swift

    @objc(setupWithInitialRecordingMode:error:)
    open func setup(with recordingMode: RecordingMode) throws

    Parameters

    recordingMode

    The initial recording mode (e.g. .Photo or .Video) to use when initializing the camera.

  • Same as setup(with:) but with an optional completion handler. The completion handler is always invoked on the main thread.

    Throws

    A CameraControllerError or an NSError if setup fails.

    Declaration

    Swift

    @objc(setupWithInitialRecordingMode:completion:error:)
    open func setup(with recordingMode: RecordingMode, completion: (() -> Void)?) throws

    Parameters

    recordingMode

    The initial recording mode (e.g. .photo or .video) to use when initializing the camera.

    completion

    A block to be executed when the camera has finished initialization.

  • Starts the camera. setupWithInitialRecordingMode(:) must be called before calling this method, otherwise this method does nothing. You should also add the videoPreviewView to your view hierachy to see the camera output.

    Declaration

    Swift

    open func startCamera()
  • Stops the camera.

    Declaration

    Swift

    open func stopCamera()
  • Switches the camera to the other position (e.g. .Back -> .Front and .Front -> .Back)

    Declaration

    Swift

    open func toggleCameraPosition()
  • Switches the camera to the desired position (if available)

    Declaration

    Swift

    @objc(switchToCameraAtPosition:)
    open func switchToCamera(at position: AVCaptureDevice.Position)

    Parameters

    position

    The position to switch to.

  • Takes a photo and hands it over to the completion block. The completion block always runs on the main thread. This method loses the image’s metadata.

    Declaration

    Swift

    open func takePhoto(_ completion: @escaping (UIImage?, NSError?) -> Void)

    Parameters

    completion

    A completion block that has an image and an error as parameters. If the image was taken sucessfully the error is nil.

  • Takes a photo and hands it over to the completion block. The completion block always runs on the main thread. Use this method to preserve the image’s metadata.

    Declaration

    Swift

    open func takePhotoAndReturnData(_ completion: @escaping (Data?, NSError?) -> Void)

    Parameters

    completion

    A completion block that has data and an error as parameters. If the image was taken successfully the error is nil.

  • Selects the next light mode. The order is taken from flashModes or torchModes depending on which is active. If the current device does not support a light mode, the next light mode that is supported is used or .off.

    Declaration

    Swift

    open func selectNextLightMode()
  • Zooms the camera by the desired zoom factor.

    Declaration

    Swift

    open func zoom(withDesiredZoomFactor zoomFactor: CGFloat)

    Parameters

    zoomFactor

    The factor to zoom by.

  • An array of AVCaptureDevicePosition raw values wrapped in NSNumbers. Setting this property overrides any previously set values in cameraPositions with the corresponding unwrapped values.

    Declaration

    Swift

    @objc(cameraPositions)
    open var _objCCameraPositions: [NSNumber] { get set }
  • An array of AVCaptureFlashMode raw values wrapped in NSNumbers. Setting this property overrides any previously set values in flashModes with the corresponding unwrapped values.

    Declaration

    Swift

    @objc(flashModes)
    open var _objCFlashModes: [NSNumber] { get set }
  • An array of AVCaptureTorchMode raw values wrapped in NSNumbers. Setting this property overrides any previously set values in torchModes with the corresponding unwrapped values.

    Declaration

    Swift

    @objc(torchModes)
    open var _objCTorchModes: [NSNumber] { get set }