카메라 제어

이 가이드에서는 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를 제공합니다.

카메라 전환

iOS에서는 switchPosition()을 호출하여 전면 카메라와 후면 카메라 간에 전환하거나, change(deviceInfo:)를 호출하여 deviceInfos에서 특정 장치를 선택할 수 있습니다.

let cameraManager = PlanetKitCameraManager.shared

// Toggle between front and back
cameraManager.switchPosition()

// Or switch to a specific device
if let backCamera = cameraManager.deviceInfos.first(where: { $0.cameraPosition == .back }) {
    try cameraManager.change(deviceInfo: backCamera)
}

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)

카메라 인터럽트 처리

iOS에서는 다른 앱(예: FaceTime 또는 카메라 앱)이 영상 장치를 점유하거나, 앱이 백그라운드로 이동하거나, 시스템에 발열이 심한 상태일 때 카메라 인터럽트가 발생합니다. 알림을 받으려면 PlanetKitCameraInterruptDelegate를 등록하세요.

Note

PlanetKit은 미디어 파이프라인이 계속 실행되도록 카메라 인터럽트를 내부적으로 처리합니다. 앱 UI에서 반응해야 하는 경우(예: "영상 일시 중지" 오버레이 표시)에만 이 이벤트 대리자(delegate)를 구현하세요.

class MyCameraInterruptHandler: PlanetKitCameraInterruptDelegate {
    func camDidInterruptBegin(_ reason: AVCaptureSession.InterruptionReason) {
        print("Camera interrupted: \(reason)")
        // Update UI to indicate video is paused
    }

    func camDidInterruptEnd() {
        print("Camera interruption ended, capture resumed")
        // Restore UI
    }
}

let handler = MyCameraInterruptHandler()
cameraManager.addInterruptReceiver(handler)

// Remove when no longer needed
cameraManager.removeInterruptReceiver(handler)

네이티브 카메라 장치 접근

포커스, 줌, 노출은 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는 다음과 같습니다.

클래스/프로토콜

• PlanetKitCameraManager
• PlanetKitVideoCaptureDeviceInfo
• PlanetKitFrameRate

• PlanetKitCameraInterruptDelegate

열거형

• PlanetKitCameraPosition
• PlanetKitCameraPreset
• PlanetKitNSErrorCode

메서드

• PlanetKitCameraManager의 shared
• PlanetKitCameraManager의 deviceInfos
• PlanetKitCameraManager의 currentDeviceInfo
• PlanetKitCameraManager의 change(deviceInfo:)
• PlanetKitCameraManager의 startPreview(delegate:)
• PlanetKitCameraManager의 stopPreview(delegate:)
• PlanetKitVideoCaptureDeviceInfo의 cameraPosition
• PlanetKitVideoCaptureDeviceInfo의 preferredPreset
• PlanetKitVideoCaptureDeviceInfo의 preferredFrameRate
• PlanetKitVideoCaptureDeviceInfo의 device
• PlanetKitFrameRate의 init(minFps:maxFps:)
• PlanetKitNSErrorCode의 cameraDeviceCannotBeSetWhileUsingCustomCamera

• PlanetKitCameraManager의 switchPosition()
• PlanetKitCameraManager의 addInterruptReceiver(_:)
• PlanetKitCameraManager의 removeInterruptReceiver(_:)

이벤트

• PlanetKitCameraInterruptDelegate의 camDidInterruptBegin(_:)
• PlanetKitCameraInterruptDelegate의 camDidInterruptEnd()

관련 문서

• 초기 비디오 상태
• 1대1 영상 통화
• 그룹 영상 통화
• 영상 통화 활성화
• 통화 일시 중지
• 응답자 준비 상태
• 커스텀 비디오 소스
• 가상 배경