본문으로 건너뛰기
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를 제공합니다.

카메라 장치 유형​

PlanetKit은 다음 카메라 유형을 지원합니다.

유형설명
FRONT전면 카메라
BACK후면 카메라
EXTERNALUSB 외부 카메라(장치 지원 여부에 따라 다름)

카메라 전환​

활성 카메라를 전환하려면 PlanetKitCameraManager에서 cameraType을 설정하세요.

val cameraManager = PlanetKit.getCameraManager()

// Switch to back camera
cameraManager.cameraType = PlanetKitCameraType.BACK

// Switch to front camera
cameraManager.cameraType = PlanetKitCameraType.FRONT

카메라 유형이 변경될 때 알림을 받으려면 CameraTypeChangedListener를 등록하세요.

val cameraTypeChangedListener = PlanetKitCameraManager.CameraTypeChangedListener { cameraType ->
    Log.d(TAG, "Camera type changed to: $cameraType")
}

cameraManager.addCameraTypeChangedListener(cameraTypeChangedListener)

// Unregister when no longer needed
cameraManager.removeCameraTypeChangedListener(cameraTypeChangedListener)

캡처 해상도 설정​

특정 캡처 해상도를 설정하려면 setManualResolution()을 호출하세요. 장치 최적 기본값으로 되돌리려면 setDefaultResolution()을 호출하세요.

// Set resolution to VGA
cameraManager.setManualResolution(PlanetKitCameraResolution.VGA)

// Restore device-optimal default resolution
cameraManager.setDefaultResolution()

사용 가능한 PlanetKitCameraResolution 값은 다음과 같습니다.

값크기
QVGA320×240
VGA640×480
HD1280×960

해상도를 지정하지 않으면 PlanetKit은 장치의 최적 기본값을 사용합니다.

카메라 미리보기​

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

// Start preview
cameraManager.startPreview(videoView)

// Stop preview
cameraManager.stopPreview(videoView)

카메라 상태 이벤트 처리​

카메라 시작, 중지, 오류 이벤트를 수신하려면 StateListener를 등록하세요.

val stateListener = object : PlanetKitCameraManager.StateListener {
    override fun onStart() {
        Log.d(TAG, "Camera started")
    }

    override fun onStop() {
        Log.d(TAG, "Camera stopped")
    }

    override fun onError(@PlanetKitCameraManager.StateListener.ErrorCode code: Int) {
        when (code) {
            PlanetKitCameraManager.StateListener.ERROR_CODE_EVICT -> {
                // Camera was taken over by another app
                Log.w(TAG, "Camera evicted by another app")
            }
            PlanetKitCameraManager.StateListener.ERROR_CODE_OPEN_FAIL -> {
                // Camera failed to open
                Log.e(TAG, "Camera failed to open")
            }
        }
    }
}

cameraManager.setStateListener(stateListener)
Note

카메라 열기에 실패하면 PlanetKit은 onError()를 통해 오류를 보고하지만 통화 연결은 유지합니다. 카메라가 다시 사용 가능해질 때까지 비디오 캡처가 중지됩니다.

USB 카메라(외부 카메라) 가용성 처리​

외부 카메라 가용성과 관련된 이벤트를 수신하려면 UsbCameraAvailabilityListener를 등록하세요. 이벤트를 사용하기 전에 장치가 외부 카메라를 지원하는지 확인하세요.

if (cameraManager.supportDeviceFeatureExternalCamera) {
    val usbListener = PlanetKitCameraManager.UsbCameraAvailabilityListener { isAvailable ->
        if (isAvailable) {
            Log.d(TAG, "External camera connected")
            // Switch to external camera if desired
            cameraManager.cameraType = PlanetKitCameraType.EXTERNAL
        } else {
            Log.d(TAG, "External camera disconnected")
            // Fall back to front or back camera
            cameraManager.cameraType = PlanetKitCameraType.FRONT
        }
    }

    cameraManager.addUsbCameraAvailabilityListener(usbListener)

    // Unregister when no longer needed
    cameraManager.removeUsbCameraAvailabilityListener(usbListener)
}

관련 API​

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

클래스/인터페이스​

열거형​

메서드​

이벤트​

관련 문서​