본문으로 건너뛰기
Version: 7.1

카메라 제어

이 가이드에서는 PlanetKit의 카메라 동작 및 관리 방법을 설명합니다.

  • 비디오 전송, 미리보기 상태, 통화 상태에 따라 PlanetKit이 내부적으로 카메라 켜짐/꺼짐을 결정하는 방식
  • 애플리케이션에서 제어할 수 있는 카메라 기능
지원 통화 유형최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)PlanetKit 5.5

카메라 켜짐/꺼짐 동작​

PlanetKit은 다음 조건 중 하나 이상이 충족되면 카메라를 켭니다.

  • 원격 피어에게 비디오가 전송 중인 경우
  • 하나 이상의 카메라 미리보기가 활성화된 경우

카메라는 두 조건 모두 충족되지 않을 때만 꺼집니다.

조건: 하나 이상의 미리보기가 활성화됨조건: 비디오가 전송 중임결과: 카메라 장치 상태
아니오아니오꺼짐
예아니오켜짐
아니오예켜짐
예예켜짐

다음 기능도 카메라 상태에 영향을 줍니다.

  • 초기 비디오 상태
    • 초기 비디오 전송 상태는 makeCall(), acceptCall(), joinConference(), 또는 enableVideo()에 전달되는 initialMyVideoState 속성/파라미터 값으로 제어합니다.
      • PlanetKitInitialMyVideoState.resume(기본값): 비디오가 활성 상태로 시작되며, 통화 시작 시 카메라가 켜집니다.
      • PlanetKitInitialMyVideoState.pause: 비디오가 일시 정지 상태로 시작되며, resumeMyVideo()가 호출될 때까지 카메라가 꺼진 상태를 유지합니다.
    • 초기 비디오 상태 설정에 관한 자세한 내용은 초기 비디오 상태를 참조하세요.
  • 통화 일시 중지/재개
    • hold()를 호출하면 카메라가 꺼지고 비디오 전송이 비활성화됩니다.
    • unhold()를 호출하면 카메라가 다시 켜지고 비디오 전송이 활성화됩니다.
    • 통화 일시 중지/재개에 관한 자세한 내용은 통화 일시 중지를 참조하세요.
  • 비디오 일시 정지/재개
    • pauseMyVideo()를 호출하면 카메라가 꺼지고 비디오 전송이 비활성화됩니다.
    • resumeMyVideo()를 호출하면 카메라가 다시 켜지고 비디오 전송이 활성화됩니다.
Note

1대1 영상 통화에서 수신자가 통화가 완전히 연결되기 전에 응답자 준비 상태에 진입하면, PlanetKit은 비디오가 네트워크에 전송되기 전에 카메라를 켤 수 있습니다. 이 단계에서도 pauseMyVideo()와 resumeMyVideo()는 카메라를 정상적으로 끄거나 켜지만, 실제 비디오 전송은 준비가 완료된 후에만 시작됩니다.

카메라 제어 기능​

PlanetKitCameraManager는 카메라 장치 전환, 캡처 프리셋 및 프레임 레이트 설정, 미리보기 시작 및 중지, 카메라 관련 이벤트 처리를 위한 카메라 관리 API를 제공합니다.

카메라 전환​

macOS에서는 deviceInfos에서 사용 가능한 카메라의 목록을 조회하고 change(deviceInfo:)를 호출하여 특정 장치를 선택할 수 있습니다.

let cameraManager = PlanetKitCameraManager.shared

// List all available cameras
let cameras = cameraManager.deviceInfos
for camera in cameras {
    print("Camera: \(camera.name) (\(camera.uniqueID))")
}

// Select a specific camera
if let externalCamera = cameras.first(where: { $0.device.deviceType == .external }) {
    try cameraManager.change(deviceInfo: externalCamera)
}

change(deviceInfo:)는 커스텀 비디오 소스가 현재 활성 상태인 경우 PlanetKitNSErrorCode.cameraDeviceCannotBeSetWhileUsingCustomCamera를 throw합니다.

캡처 프리셋 및 프레임 레이트 설정​

change(deviceInfo:)에 전달하기 전에 PlanetKitVideoCaptureDeviceInfo의 preferredPreset과 preferredFrameRate를 설정하세요.

guard let deviceInfo = cameraManager.deviceInfos.first else { return }

// Set preferred capture preset (resolution)
deviceInfo.preferredPreset = .hd1280x720   // default

// Set preferred frame rate
deviceInfo.preferredFrameRate = PlanetKitFrameRate(minFps: 15, maxFps: 30)  // default max: 30fps

try cameraManager.change(deviceInfo: deviceInfo)

preferredPreset은 PlanetKitCameraPreset 유형이며, 이는 AVCaptureSession.Preset의 typealias입니다. 사용 가능한 모든 값은 Apple 개발자 문서를 참조하세요.

장치가 지정된 프리셋을 지원하지 않는 경우, PlanetKit은 가장 가까운 지원 프리셋으로 대신 설정합니다.

카메라 미리보기​

startPreview()와 stopPreview()를 사용하여 통화와 독립적으로 카메라 미리보기를 시작하고 중지할 수 있습니다.

// Start preview — pass a delegate that receives PlanetKitVideoBuffer frames
cameraManager.startPreview(delegate: myVideoOutputDelegate)

// Stop preview
cameraManager.stopPreview(delegate: myVideoOutputDelegate)

장치 변경 이벤트 처리​

카메라가 연결될 때, 연결 해제될 때, 또는 선택될 때 알림을 받으려면 PlanetKitCameraDeviceChangeDelegate를 등록하세요.

Note

PlanetKit은 장치가 연결되거나 연결 해제될 때 내부 카메라 상태를 자동으로 업데이트합니다. 앱 UI를 업데이트해야 하는 경우(예: 장치 선택 목록 새로 고침)에만 이 이벤트 대리자(delegate)를 구현하세요.

class MyCameraObserver: PlanetKitCameraDeviceChangeDelegate {
    func didCameraDeviceConnect(deviceInfo: PlanetKitVideoCaptureDeviceInfo) {
        print("Camera connected: \(deviceInfo.name)")
    }

    func didCameraDeviceDisconnect(deviceInfo: PlanetKitVideoCaptureDeviceInfo) {
        print("Camera disconnected: \(deviceInfo.name)")
        // Switch to another camera if needed
    }

    func didCameraDeviceSelect(deviceInfo: PlanetKitVideoCaptureDeviceInfo, preset: PlanetKitCameraPreset) {
        print("Camera selected: \(deviceInfo.name), preset: \(preset)")
    }
}

let observer = MyCameraObserver()
cameraManager.addDeviceChangeDelegate(observer)

// Remove when no longer needed
cameraManager.removeDeviceChangeDelegate(observer)

네이티브 카메라 장치 접근​

포커스, 줌, 노출은 PlanetKit API로 제공되지 않습니다. 네이티브 수준에서 제어하려면 하부의 AVCaptureDevice에 직접 접근하세요.

if let deviceInfo = cameraManager.currentDeviceInfo {
    let avDevice = deviceInfo.device
    do {
        try avDevice.lockForConfiguration()
        // Example: set exposure mode
        if avDevice.isExposureModeSupported(.continuousAutoExposure) {
            avDevice.exposureMode = .continuousAutoExposure
        }
        avDevice.unlockForConfiguration()
    } catch {
        print("Failed to configure device: \(error)")
    }
}

관련 API​

카메라 제어와 관련된 API는 다음과 같습니다.

클래스/프로토콜​

열거형​

메서드​

이벤트​

관련 문서​