본문으로 건너뛰기
Version: 7.1

오디오 경로 제어

iOS에서 PlanetKit은 현재 오디오 출력 경로를 내장 수화기, 내장 스피커폰 또는 외부 헤드셋으로 분류합니다. 내장 스피커폰 출력을 요청하거나 요청을 해제할 수 있으며, 경로가 변경되면 앱에 알립니다.

지원 통화 유형최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)PlanetKit 6.0
Note
  • 오디오 경로 제어는 iOS 전용 기능입니다. macOS에서는 오디오 장치 선택 기능을 사용하세요.
  • PlanetKit은 외부 출력 장치를 직접 선택하지 않으므로, AVRoutePickerView로 사용자가 장치를 선택하도록 하세요.

오디오 경로 값​

PlanetKit은 PlanetKitAudioRoute로 현재 출력 경로를 분류합니다.

값설명
.builtInHandset휴대전화 수화기
.builtInSpeakerphone휴대전화 스피커폰
.externalHeadset유선 또는 Bluetooth 헤드셋
Note
  • PlanetKit은 현재의 PlanetKitAudioRoute를 동기적으로 조회하는 속성은 제공하지 않으며, 출력 경로가 변경될 때 PlanetKitAudioRouteChangeDelegate를 통해 PlanetKitAudioRoute 값을 전달합니다. 자세한 내용은 '오디오 경로 변경 감지'를 참고하세요.
  • 현재 오디오 경로의 포트 수준 입력 및 출력 정보를 확인하려면 Apple의 AVAudioSession.currentRoute API를 사용하세요.

스피커폰으로 전환​

PlanetKitAudioSession.speakerOut(_:)을 사용하여 내장 스피커폰 출력을 요청하거나 그 요청을 해제하세요.

let session = PlanetKitAudioManager.shared.session

// Request speakerphone output asynchronously.
session.speakerOut(true)

// Release the speakerphone request asynchronously and let iOS choose the route.
session.speakerOut(false)

// Read the current output state; pending requests may not yet be reflected.
let isSpeakerOn = session.isSpeakerOut
Note

스피커폰 출력 요청은 일시적인 출력 override이며, 오디오 경로가 변경되면 iOS가 이를 재설정할 수 있습니다. 외부 장치로 경로가 변경되면 PlanetKit은 기존 스피커폰 요청을 다시 적용하지 않습니다. 출력 override의 동작은 Apple QA1754를 참고하세요.

기본 경로 자동 조정​

기본적으로 PlanetKit은 통화에 대해 내장 경로를 자동으로 조정합니다. 통화가 내장 수화기 경로에서 시작하면 음성 통화에서는 수화기 출력을 유지하고, 영상 통화에서는 내장 스피커폰 출력을 요청합니다. 이 자동 조정은 외부 장치를 선택하지 않습니다.

이 자동 조정을 비활성화하려면 PlanetKit을 초기화하기 전에 초기 설정을 구성하세요.

let initialSettings = PlanetKitInitialSettingBuilder()
    .withDisableDefaultAudioRouteKey(disable: true)
    .build()
PlanetKitManager.shared.initialize(initialSettings: initialSettings)

앱에서 PlanetKit이 이러한 내장 경로 자동 조정을 수행하지 않도록 하려는 경우에만 disable을 true로 설정하세요. 기본값은 false입니다. 앱의 스피커폰 요청을 speakerOut(false)로 해제해도 기본 경로 자동 조정은 비활성화되지 않습니다.

자동 조정이 활성화된 경우 영상 통화를 활성화하면 현재 경로가 내장 수화기일 때만 스피커폰 출력을 요청합니다. 내장 스피커폰과 외부 헤드셋 경로인 경우 그대로 유지됩니다. 영상 통화를 비활성화해도 경로가 자동으로 변경되지는 않습니다. 연결된 영상 통화가 외부 헤드셋에서 내장 수화기로 돌아오면 PlanetKit은 스피커폰 출력을 요청합니다.

오디오 경로 변경 감지​

PlanetKit은 오디오 출력이 올바르게 이어지도록 오디오 경로 변경을 내부적으로 처리합니다. 예를 들어 스피커폰 토글 버튼을 갱신하는 등 UI를 업데이트해야 하는 경우에만 이 델리케이트를 구현하세요.

경로가 변경될 때(예: 헤드셋 연결 또는 해제) 알림을 받으려면 PlanetKitAudioRouteChangeDelegate를 등록하세요.

final class MyRouteObserver: PlanetKitAudioRouteChangeDelegate {
    func didAudioRouteChange(current: PlanetKitAudioRoute, previous: PlanetKitAudioRoute) {
        print("Route changed from \(previous) to \(current)")
        // Update UI — e.g., refresh speakerphone button state
    }
}

final class CallViewController: UIViewController {
    // PlanetKit retains route delegates weakly, so retain this observer strongly.
    private let routeObserver = MyRouteObserver()

    func startObservingRouteChanges() {
        PlanetKitAudioManager.shared.addAudioRouteChangeDelegate(routeObserver)
    }

    deinit {
        PlanetKitAudioManager.shared.removeAudioRouteChangeDelegate(routeObserver)
    }
}

델리케이트는 메인 큐에서 호출됩니다.

관련 API​

오디오 경로 제어와 관련된 API는 다음과 같습니다.

열거형​

속성​

메서드​

이벤트​