본문으로 건너뛰기
Version: 7.1

오디오 장치 선택

macOS에서는 PlanetKit의 PlanetKitAudioManager를 사용하여 1대1 통화와 그룹 통화의 오디오 장치를 조회하고 마이크와 스피커를 각각 선택할 수 있습니다.

지원 통화 유형최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)PlanetKit 6.0
Note
  • PlanetKit은 시작할 때 마이크와 스피커에 사용할 기본 장치를 각각 선택하며, 일반적으로 macOS 기본 장치를 선택합니다. 시스템 기본 장치가 통합 장치(aggregate device)이거나 조회할 수 없는 경우에는 장치 목록에서 해당 용도의 입력 또는 출력 채널이 있는 첫 번째 비통합 장치를 선택하려고 시도합니다. 적합한 장치가 없으면 아무 장치도 선택되지 않습니다.
  • 오디오 장치 선택은 macOS 전용 기능입니다. iOS에서는 오디오 경로 제어를 사용하세요.

사용 가능한 장치 조회​

전체 오디오 장치 목록을 조회하려면 PlanetKitAudioManager의 devices 속성을 확인하세요. 사용자가 마이크나 스피커로 선택할 수 있는 장치를 표시하려면 isCapturable 또는 isPlayable로 목록을 필터링하세요. 입력 또는 출력 채널이 있다고 해서 반드시 해당 용도로 선택할 수 있는 것은 아닙니다.

let audioManager = PlanetKitAudioManager.shared

let microphones = audioManager.devices.filter { $0.isCapturable }
let speakers = audioManager.devices.filter { $0.isPlayable }

for device in microphones {
    print("Microphone: \(device.name ?? "Unknown") (\(device.deviceID))")
}
for device in speakers {
    print("Speaker: \(device.name ?? "Unknown") (\(device.deviceID))")
}

장치를 확인할 때는 다음 PlanetKitAudioDevice 속성을 사용하세요.

속성설명
deviceID장치 식별자
name장치 표시 이름(있는 경우)
inputChannelCount, outputChannelCount입력 및 출력 채널 수
isCapturable, isPlayablePlanetKit이 장치를 마이크 또는 스피커로 선택할 수 있는지 여부
isAggregateTypePlanetKit에서 마이크 또는 스피커로 선택할 수 없는 통합 장치인지 여부

현재 선택된 장치 확인​

장치 목록에서 현재 선택된 마이크와 스피커를 확인하려면 PlanetKitAudioSession의 micDevice와 speakerDevice 속성을 조회하세요. 각 속성은 해당 용도로 선택된 장치가 없거나 해당 용도의 커스텀 마이크나 스피커가 활성화되어 있으면 nil을 반환합니다. nil 값만으로 오디오 캡처 또는 재생이 비활성화되었는지 판단할 수는 없습니다.

let session = PlanetKitAudioManager.shared.session

if let mic = session.micDevice {
    print("Current microphone: \(mic.name ?? "Unknown")")
}
if let speaker = session.speakerDevice {
    print("Current speaker: \(speaker.name ?? "Unknown")")
}

장치 선택​

목록에서 가져온 장치를 PlanetKitAudioSession의 change(micDevice:completion:) 또는 change(speakerDevice:completion:) 메서드에 전달하세요. 완료 핸들러는 메인 큐에서 실행되며, 오류가 nil이면 변경에 성공한 것입니다.

let audioManager = PlanetKitAudioManager.shared
let session = audioManager.session

if let microphone = audioManager.devices.first(where: { $0.isCapturable }) {
    session.change(micDevice: microphone) { error in
        if let error = error {
            print("Could not select microphone: \(error)")
        }
    }
}

if let speaker = audioManager.devices.first(where: { $0.isPlayable }) {
    session.change(speakerDevice: speaker) { error in
        if let error = error {
            print("Could not select speaker: \(error)")
        }
    }
}

요청한 용도로 선택할 수 없는 장치(통합 장치 포함)를 전달하면 완료 핸들러에 오류가 전달되고 기존 선택은 유지됩니다. 해당 용도의 커스텀 마이크나 스피커를 사용 중일 때도 장치 변경이 실패합니다.

장치 선택 해제​

PlanetKitAudioSession의 change(micDevice:completion:) 또는 change(speakerDevice:completion:) 메서드에 nil을 전달하면 마이크 또는 스피커의 선택을 해제할 수 있습니다. 선택 해제는 음 소거와 별개이며 기본 장치로 돌아가는 동작도 아닙니다.

let session = PlanetKitAudioManager.shared.session

session.change(micDevice: nil) { error in
    if let error = error {
        print("Could not deselect microphone: \(error)")
    }
}

session.change(speakerDevice: nil) { error in
    if let error = error {
        print("Could not deselect speaker: \(error)")
    }
}

완료 핸들러에서 성공을 확인한 뒤에는 해당 micDevice 또는 speakerDevice가 nil입니다. 이후 장치 목록이 변경되면 PlanetKit이 선호하는 기본 장치를 다시 선택할 수 있습니다.

PlanetKit 기본 장치로 되돌리기​

기본 장치로 되돌릴 용도마다 PlanetKitAudioSession의 setPreferredDefaultDevice(type:)를 호출하세요.

let session = PlanetKitAudioManager.shared.session

// Asynchronously switches to the preferred default microphone device.
session.setPreferredDefaultDevice(type: .mic)

// Asynchronously switches to the preferred default speaker device.
session.setPreferredDefaultDevice(type: .speaker)

PlanetKit은 현재 macOS 기본 장치가 적합하면 이를 사용합니다. 그 장치가 통합 장치이거나 사용할 수 없으면 목록에서 해당 채널이 있는 첫 번째 비통합 장치를 사용합니다. 선택 대상은 isCapturable 또는 isPlayable도 충족해야 하며, 그렇지 않으면 기존 선택이 유지됩니다. 이 메서드에는 완료 핸들러가 없습니다. 처리 결과는 micDevice 또는 speakerDevice를 조회하거나 장치 변경 이벤트를 관찰하여 확인하세요.

macOS 기본 장치가 변경되어도 앱에서 이미 선택한 장치가 계속 사용 가능하다면 PlanetKit은 현재 장치 선택을 유지합니다.

장치 변경 감지​

PlanetKitAudioManager의 addDeviceChangeDelegate(_:)를 호출하여 PlanetKitAudioDeviceChangeDelegate를 등록하면 장치 목록, 현재 선택된 장치 또는 macOS 기본 장치가 바뀔 때 장치 선택 UI를 업데이트할 수 있습니다. 데이터 소스(data source) 변경 콜백은 선택 사항이며, 내장 스피커와 헤드폰처럼 서로 다른 입력 소스나 출력 대상을 제공하는 내장 장치에 적용됩니다.

델리게이트 콜백에서 장치 선택 UI 등 화면 요소를 변경할 때는 DispatchQueue.main.async를 사용해 메인 큐에서 업데이트하세요.

final class AudioDeviceObserver: NSObject, PlanetKitAudioDeviceChangeDelegate {
    func didAudioDevicesUpdate(devices: [PlanetKitAudioDevice]) {
        print("Available devices: \(devices.count)")
    }

    func didAudioDeviceChange(device: PlanetKitAudioDevice?, type: PlanetKitAudioDeviceType) {
        print("Current \(type) changed to \(device?.name ?? "none")")
    }

    func didAudioDefaultSystemDeviceChange(device: PlanetKitAudioDevice?, type: PlanetKitAudioDeviceType) {
        print("macOS default \(type) changed to \(device?.name ?? "none")")
    }

    func didAudioDeviceDataSourceChange(device: PlanetKitAudioDevice, dataSource: UInt32) {
        print("Data source for \(device.name ?? "Unknown"): \(dataSource)")
    }
}

let observer = AudioDeviceObserver()
PlanetKitAudioManager.shared.addDeviceChangeDelegate(observer)

// Keep observer alive while registered. When no longer needed:
PlanetKitAudioManager.shared.removeDeviceChangeDelegate(observer)

선택한 장치가 분리된 경우​

기본 설정에서는 장치 목록에서 선택한 마이크나 스피커가 사라지면 PlanetKit이 해당 용도의 PlanetKit 기본 장치로 전환을 시도합니다.

PlanetKit은 전환을 시도하기 전에 didAudioDevicesUpdate(devices:)로 변경된 장치 목록을 알립니다. 이 콜백에서 사용 가능한 장치 목록을 갱신하되, 그때 조회한 micDevice 또는 speakerDevice를 최종 선택으로 간주하지 마세요. 현재 장치 선택 상태를 표시하는 UI는 didAudioDeviceChange(device:type:) 콜백에서 갱신하세요.

관련 API​

오디오 장치 선택과 관련된 API는 다음과 같습니다.

클래스와 프로토콜​

열거형​

속성​

메서드​

이벤트​