Audio Device Settings

SIP Endpoint SDK for .NET uses a complex set of criteria for determining how to select its audio input and output devices. The following sections describe:

• The basic priority settings for audio input and output devices
• The rules that are used to select an audio device, auto-answer a call, and reject a call
• The ways in which various combinations of settings affect audio device selection, auto-answer, and call rejection

Basic Priority

Headsets and other audio input devices are configured by using the following parameters:

• headset_name
• audio_in_device
• audio_out_device

You can set the priority for these devices by changing the order of their entries in the configuration file. If none of the audio devices that are accessible to the endpoint match the device names in the configuration file, the SDK will pick up the first available devices from the WebRTC lists for audio devices.

Examples

In the following example, the Plantronics C320 has a higher priority than the Plantronics D100, since it appears first in the file:

<setting name="headset_name" value="Plantronics C320"/>
<setting name="headset_name" value="Plantronics D100"/>

Selection Rules

The following rules are used to select an audio device, auto-answer a call, and reject a call.

Audio Device Selection

The procedure for audio device selection is applied on startup and every time any changes are made to device presence (such as when a new device is plugged in or an existing device is removed):

1. The first device in the applicable list that is present in the system is selected when possible. This device (or devices) will either be specified by headset_name or by audio_in_device and audio_out_device, depending on whether use_headset has been enabled.
2. If none of the configured devices are present (or if the configuration list is empty), then the SDK will select the audio devices using the priority that has been provided by WebRTC, based on the order of the available devices in its device list.

Auto-Answer

In cases where either of the following conditions is met, the auto-answer functionality is blocked (a policy of should answer returns unknown, although a manual answer is still possible):

• use_headset is set to 1, and none of the devices listed in the headset_name settings is currently present (but session rejection is not applicable, that is, reject_session_when_headset_na has been set to 0)
• The SDK was unable to find any usable microphone or speaker device (applicable to cases when use_headset is set to 0)

Finally, when auto_answer is set to 1 and the auto-answer functionality is not blocked (and the call was not already rejected), the SDK answers the incoming call automatically (the should answer policy returns true). If auto_accept_video is set to 1, then both audio and video streams are accepted, otherwise the call is answered as audio-only, even if video is present in the offer.

Rejecting A Call

For backward compatibility with previous releases, a call can only be rejected when both of the following conditions are met (a policy of should answer returns false):

• Both use_headset and reject_session_when_headset_na are set to 1
• None of the devices listed in the headset_name settings is currently present

When these conditions are met, an incoming call is rejected with a SIP response code as configured in the sip_code_when_headset_na setting. If the setting is missing or the value does not belong to the valid range of 400 to 699, then the default of 480 (Temporarily Unavailable) is used.

In addition, when these conditions are met, the SDK will refuse to initiate any new calls, that is, it will reject outgoing calls.

Note that the availability of a fallback device (selected by Step 2 in the Audio Device Selection section) does not affect call rejection.

Combinations of Settings

The following combinations of settings affect audio device selection, auto-answer, and call rejection in the ways described below.

use_headset=1

Headset is Available The SDK considers a headset to be available if a headset was found by name in the list of headset_name entries. (The highest priority device in the list is selected). Outgoing calls can be initiated.	auto_answer=1	Incoming calls are answered automatically: As audio if auto_accept_video=0 As audio with video if the call has video and auto_accept_video=1
	auto_answer=0	Incoming calls are answered manually and the user explicitly selects whether or not video streams should be accepted (using the has_video parameter supplied in the gs_session_info argument)
Headset is Not Available The SDK decides that no headset is available if a headset was not found by name in the list of headset_name entries. An audio device is still assigned, if possible (that is, if any supported devices are present in the system), using the first available audio input and output devices from the list compiled by WebRTC.	No auto-answer is possible in this sub-case, so the auto_answer setting is not used	reject_session_when_headset_na=1 Incoming calls are automatically rejected Outgoing calls are blocked
		reject_session_when_headset_na=0 Incoming calls can be answered manually—it is assumed that the agent will plug the headset in (or use an available non-headset device, if applicable) before answering the call Outgoing calls can be initiated—it is the agent's responsibility to ensure that the appropriate audio devices are available before the call is answered by the remote side

use_headset=0

Audio devices are configured using the names from the audio_in_device and audio_out_device settings. The SDK selects the highest-priority input and output devices from that list or, if no valid devices are found in that list, from the first available devices in the list compiled by WebRTC. Outgoing calls can be initiated.

Both microphone and speaker are available	auto_answer=1	Incoming calls are answered automatically: As audio if auto_accept_video=0 As audio with video if the call has video and auto_accept_video=1
	auto_answer=0	Incoming calls are answered manually and the user explicitly selects whether or not video streams should be accepted (using the has_video parameter supplied in the gs_session_info argument)
Either microphone or speaker is not available Incoming calls can be answered manually—it is assumed that the agent will plug in the headset (or use an available non-headset device, if applicable) before answering the call Outgoing calls can be initiated—it is the agent's responsibility to ensure that the appropriate audio devices are available before the call is answered by the remote side	No auto-answer is possible in this sub-case, so the auto_answer setting is not used	Auto-rejection is not applicable, so the reject_session_when_headset_na setting is not used