CameraController
@objcMembers
@objc(PESDKCameraController)
open class CameraController : NSObject
extension CameraController: NSKeyValueObservingCustomization
extension CameraController: CLLocationManagerDelegate
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 aCameraViewController
object, this property will be set automatically and forward location access requests toCameraViewController.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 thevideoPreviewView
in the center.Declaration
Swift
public let videoPreviewViewContainer: UIView
-
The currently active recording mode (i.e.
.Photo
or.Video
). Setting this property before callingsetupWithInitialRecordingMode(:)
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
@objc open dynamic var recordingMode: RecordingMode { get set }
-
Called when the
running
state of the camera changes.Declaration
Swift
open var runningStateChangedHandler: ((_ running: Bool) -> Void)?
-
Called when the camera position changes.
Declaration
Swift
open var cameraPositionChangedHandler: ((_ previousPosition: AVCaptureDevice.Position, _ newPosition: AVCaptureDevice.Position) -> Void)?
-
Called when the recording mode changes.
Declaration
Swift
open var recordingModeChangedHandler: ((_ recordingMode: 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
istrue
if the current camera has a flash.flashMode
represents the currently active flash mode.flashAvailable
istrue
if the flash is available for use.Declaration
Swift
open var flashChangedHandler: ((_ hasFlash: Bool, _ flashMode: AVCaptureDevice.FlashMode, _ flashAvailable: Bool) -> Void)?
-
Called when any aspect of the torch changes.
hasTorch
istrue
if the current camera has a torch.torchMMode
represents the currently active torch mode.torchAvailable
istrue
if the torch is available for use.Declaration
Swift
open var torchChangedHandler: ((_ hasTorch: Bool, _ torchMode: AVCaptureDevice.TorchMode, _ torchAvailable: Bool) -> Void)?
-
Called when a photo is currently being captured or done being captured.
Declaration
Swift
open var capturingStillImageHandler: ((_ capturing: 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: ((_ interrupted: Bool) -> Void)?
-
Called when a runtime error occurs.
Declaration
Swift
open var sessionRuntimeErrorHandler: ((_ error: 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: ((_ fileURL: 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: ((_ seconds: Int) -> Void)?
-
Called when the size of the preview image within the
videoPreviewView
changesDeclaration
Swift
open var previewFrameChangedHandler: ((_ previewFrame: CGRect) -> Void)?
-
Called when the focus point changes.
Declaration
Swift
open var focusPointChangedHandler: ((_ point: CGPoint) -> Void)?
-
Called when the focus mode changes.
Declaration
Swift
open var focusModeChangedHandler: ((_ focusMode: AVCaptureDevice.FocusMode, _ exposureMode: 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 typeAVFileTypeQuickTimeMovie
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 typeAVFileTypeQuickTimeMovie
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 changevideoOutputSettings
andaudioOutputSettings
.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)?
-
The current selected camera position. If
nil
the camera is not initialized.Declaration
Swift
open var cameraPosition: AVCaptureDevice.Position? { get }
-
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 behavior.Declaration
Swift
open var cameraPositions: [AVCaptureDevice.Position] { get set }
-
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 istrue
.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.Declaration
Swift
@objc(setupWithInitialRecordingMode:error:) open func setup(with recordingMode: RecordingMode) throws
-
Same as
setup(with:)
but with an optional completion handler. The completion handler is always invoked on the main thread.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 thevideoPreviewView
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
.
-
Starts the video recording. This only works if
recordingMode
is set to .Video. You should set appropriate blocks forvideoRecordingStartedHandler
,videoRecordingFailedHandler
,videoRecordingFinishedHandler
andvideoRecordingProgressHandler
. The finished handler gets passed aNSURL
to the path of the recorded video file. Please note that you are responsible for deleting that file when you no longer need it.Declaration
Swift
open func startVideoRecording()
-
Stops video recording. This only works if you previously started video recording.
Declaration
Swift
open func stopVideoRecording()
-
Selects the next light mode. The order is taken from
flashModes
ortorchModes
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 inNSNumber
s. Setting this property overrides any previously set values incameraPositions
with the corresponding unwrapped values.Declaration
Swift
@objc(cameraPositions) open var _objCCameraPositions: [NSNumber] { get set }
-
An array of
AVCaptureFlashMode
raw values wrapped inNSNumber
s. Setting this property overrides any previously set values inflashModes
with the corresponding unwrapped values.Declaration
Swift
@objc(flashModes) open var _objCFlashModes: [NSNumber] { get set }
-
An array of
AVCaptureTorchMode
raw values wrapped inNSNumber
s. Setting this property overrides any previously set values intorchModes
with the corresponding unwrapped values.Declaration
Swift
@objc(torchModes) open var _objCTorchModes: [NSNumber] { get set }