Skip to main content
Version: 7.1

Audio device selection

On Windows, PlanetKit lets you list and select microphone and speaker devices for 1-to-1 and group calls through AudioManager.

Supported call typeMinimum SDK version
1-to-1 call, group call (conference)PlanetKit 6.0
Note

PlanetKit does not initially select a microphone or speaker. The Windows default devices can be queried separately; changing the Windows default does not by itself replace a device already selected in PlanetKit.

Get an audio manager instance​

After initializing PlanetKit, call GetAudioManager() on PlanetKitManager to obtain an AudioManager:

auto pAudioManager = PlanetKit::PlanetKitManager::GetInstance()->GetAudioManager();

List available devices​

To list currently active microphones and speakers, call GetMicList() and GetSpeakerList() with separate AudioDeviceInfoArray values. Check each return value before using the corresponding list. To inspect a device's ID, name, or type, call GetID(), GetName(), or GetDeviceType() on its AudioDeviceInfo.

PlanetKit::AudioDeviceInfoArray microphones;
PlanetKit::AudioDeviceInfoArray speakers;

if (pAudioManager->GetMicList(microphones)) {
    for (size_t i = 0; i < microphones.Size(); ++i) {
        auto device = microphones.At(i);
        std::wcout << L"Microphone: " << device->GetName().c_str()
                   << L" (" << device->GetID().c_str() << L")" << std::endl;
    }
}

if (pAudioManager->GetSpeakerList(speakers)) {
    for (size_t i = 0; i < speakers.Size(); ++i) {
        auto device = speakers.At(i);
        std::wcout << L"Speaker: " << device->GetName().c_str()
                   << L" (" << device->GetID().c_str() << L")" << std::endl;
    }
}

Check the current selection​

To check the current selections, call GetCurrentMic() to obtain a MicOptional and GetCurrentSpeaker() to obtain a SpeakerOptional. Check HasValue() before accessing either selected device. For a microphone or speaker selected from the device list, use GetDeviceInfo() to inspect its AudioDeviceInfo.

auto currentMic = pAudioManager->GetCurrentMic();
if (currentMic.HasValue()) {
    auto info = currentMic.Value()->GetDeviceInfo();
    if (info) {
        std::wcout << L"Current microphone: " << info->GetName().c_str() << std::endl;
    }
}

auto currentSpeaker = pAudioManager->GetCurrentSpeaker();
if (currentSpeaker.HasValue()) {
    auto info = currentSpeaker.Value()->GetDeviceInfo();
    if (info) {
        std::wcout << L"Current speaker: " << info->GetName().c_str() << std::endl;
    }
}

An optional with no value means no device is selected for that type.

Select a device​

Pass an AudioDeviceInfoPtr from the corresponding list to ChangeMic() or ChangeSpeaker(). Each method returns the selected microphone or speaker on success, or an optional with no value on failure.

PlanetKit::AudioDeviceInfoArray microphones;
if (pAudioManager->GetMicList(microphones) && microphones.Size() > 0) {
    auto selectedMic = pAudioManager->ChangeMic(microphones.At(0));
    if (!selectedMic.HasValue()) {
        std::wcerr << L"Could not select microphone" << std::endl;
    }
}

PlanetKit::AudioDeviceInfoArray speakers;
if (pAudioManager->GetSpeakerList(speakers) && speakers.Size() > 0) {
    auto selectedSpeaker = pAudioManager->ChangeSpeaker(speakers.At(0));
    if (!selectedSpeaker.HasValue()) {
        std::wcerr << L"Could not select speaker" << std::endl;
    }
}

If you pass speaker information to ChangeMic() or microphone information to ChangeSpeaker(), the call fails without changing the previous selection. If a replacement device cannot start during an active call or conference, the method returns an optional with no value and the selection for that type becomes empty.

Select a Windows default device​

To query the Windows multimedia-role defaults, call GetDefaultMicInfo() and GetDefaultSpeakerInfo(). These calls do not change the current selection. Pass a returned device to the appropriate change method when you want to select it.

auto defaultMic = pAudioManager->GetDefaultMicInfo();
if (defaultMic.HasValue()) {
    auto selectedMic = pAudioManager->ChangeMic(defaultMic.Value());
}

auto defaultSpeaker = pAudioManager->GetDefaultSpeakerInfo();
if (defaultSpeaker.HasValue()) {
    auto selectedSpeaker = pAudioManager->ChangeSpeaker(defaultSpeaker.Value());
}
Note

A Windows default-device change notification reports the console-role default, which can differ from the multimedia-role device returned by these queries.

Deselect a device​

To clear the microphone or speaker selection, call ChangeMic() or ChangeSpeaker() without an argument. This is separate from muting and does not select the Windows default device.

pAudioManager->ChangeMic();
pAudioManager->ChangeSpeaker();

After either call, the corresponding GetCurrentMic() or GetCurrentSpeaker() result has no value.

Choose a microphone when starting a call​

When starting a call or conference through PlanetKitManager, pass a MicOptional argument to MakeCall(), VerifyCall(), or JoinConference(). To use the microphone you selected earlier, pass the result of GetCurrentMic(). If you pass NullOptional, PlanetKit clears the previous microphone selection and starts without one. To keep a call or conference running without a microphone, enable SetAllowCallWithoutMic(true) or SetAllowConferenceWithoutMic(true) on the corresponding start parameters.

Observe device changes​

Implement IAudioDeviceEvent and register it through RegisterAudioDeviceEvent() to receive device additions, removals, and Windows default-device changes. Each callback provides device information, including its ID and input or output type.

class AudioDeviceObserver : public PlanetKit::IAudioDeviceEvent {
public:
    void OnDefaultAudioDeviceChanged(PlanetKit::AudioDeviceInfoPtr device) override {
        if (device) {
            std::wcout << L"Default device changed: " << device->GetID().c_str() << std::endl;
        }
    }

    void OnAudioDeviceAdded(PlanetKit::AudioDeviceInfoPtr device) override {
        if (device) {
            std::wcout << L"Device added: " << device->GetID().c_str() << std::endl;
        }
    }

    void OnAudioDeviceRemoved(PlanetKit::AudioDeviceInfoPtr device) override {
        if (device) {
            std::wcout << L"Device removed: " << device->GetID().c_str() << std::endl;
        }
    }
};

AudioDeviceObserver observer;
bool registered = pAudioManager->RegisterAudioDeviceEvent(&observer);

Keep observer alive while registered, and call DeregisterAudioDeviceEvent() before destroying it. Registration fails if another audio-device listener is already registered. When a selected device is removed, PlanetKit clears that selection before calling OnAudioDeviceRemoved(); query the current device and select a replacement if needed.

APIs related to audio device selection are as follows.

Classes​

Methods​

Events​