Friendly Names for Audio Endpoint Devices

In Windows Vista, Windows Server 2008, and later versions of Windows, the audio subsystem supports the notion of an audio endpoint device, for example, speakers, headphones, microphones, and CD players. This new concept of audio endpoints helps create user-friendly audio applications that have user interfaces that refer to the endpoint devices that users directly manipulate. These endpoints have friendly names such as "speakers", "headphones", "microphone", and "CD player" that applications can display in their user interfaces. For more information about endpoint devices, see Audio Endpoint Devices.

The audio subsystem models a Plug and Play (PnP) device on an audio adapter as a KS filter. Data streams enter and exit the filter through KS pins. A bridge pin is a KS pin through which an audio endpoint device connects to a KS filter. For more information about bridge pins, see Audio Filter Graphs.

The audio subsystem obtains information about an audio endpoint device by examining the properties of the bridge pin that the endpoint device connects to. One such property is the pin category property (KSPROPERTY_PIN_CATEGORY). For each KS filter, the adapter driver supplies a table of PCPIN_DESCRIPTOR structures that describe the properties of the KS pins on the filter. The pin category property is stored in the KsPinDescriptor.Name member of the PCPIN_DESCRIPTOR structure. For a bridge pin, the value of the pin category property is a GUID that indicates the "category" of the endpoint device that connects to the bridge pin. For example, the pin-category GUID KSNODETYPE_MICROPHONE indicates that the bridge pin connects to a microphone, the GUID KSNODETYPE_SPEAKER indicates that the bridge pin connects to speakers, and so on. The KSNODETYPE_XXX GUIDs are defined in the Ksmedia.h header file.

The audio subsystem associates a friendly name with the audio endpoint device that connects to a bridge pin. The friendly name is based on the pin category property of the bridge pin. For example, the property value KSNODETYPE_MICROPHONE has the associated friendly name "microphone," the value KSNODETYPE_SPEAKER has the associated friendly name "speakers," and so on.

The audio subsystem maintains a list of pin category GUIDs and their associated friendly names in the system registry. The GUIDs and friendly names are stored in the registry path HKLM\SYSTEM\CurrentControlSet\Control\MediaCategories. For each GUID-name pair in the registry, the GUID string is the key for the registry entry, and the name string is the entry value. The media class installer copies the GUID-name pairs into the registry from the Ks.inf file that is located in the inf subfolder of the main Windows folder (for example, C:\Windows\Inf\Ks.inf). You can view the friendly names assigned to each pin category by inspecting either Ks.inf or the registry.

If none of the friendly names and pin categories defined by the audio subsystem adequately describes your device, you can define your own pin-category GUID and associated friendly name. To ensure that your pin-category GUID is unique, use a utility such as Uuidgen.exe to generate the GUID. Next, modify the INF file that installs your audio adapter to write the pin-category GUID and friendly name to the registry path HKLM\SYSTEM\CurrentControlSet\Control\MediaCategories. The following code example shows a fragment of an INF file that adds two pin-category GUIDs and their associated friendly names to the registry:


AddReg=PinNameRegistration

...

[PinNameRegistration]
HKLM,%MediaCategories%\%GUID.MyNewDevice_1%,Name,,%Pin.MyNewDevice_1%
HKLM,%MediaCategories%\%GUID.MyNewDevice_2%,Name,,%Pin.MyNewDevice_2%

...

[Strings]
MediaCategories="SYSTEM\CurrentControlSet\Control\MediaCategories"

GUID.MyNewDevice_1="{5ca46561-c54c-43d7-9eea-343b7d2e21dc}"
GUID.MyNewDevice_2="{5ca46562-c54c-43d7-9eea-343b7d2e21dc}"

Pin.MyNewDevice_1="First new device"
Pin.MyNewDevice_2="Second new device"

The first pin-category GUID string, GUID.MyNewDevice_1, was generated by Uuidgen.exe. The second GUID string, GUID.MyNewDevice_2, was generated by manually incrementing the ninth character in the first GUID string. Incrementing the GUID value in this way ensures that the second GUID will appear immediately following the first in the registry.

Applications can access the properties of an audio endpoint device by using the device's IPropertyStore interface. The interface uses the property keys defined in the Functiondiscoverykeys_devpkey.h and Mmdeviceapi.h header files to identify the properties. An application can use the PKEY_Device_FriendlyName property key to retrieve the friendly name of an endpoint device. For space-constrained user interfaces, a shorter version of the friendly name can be retrieved by using the PKEY_Device_DeviceDesc property key. For more information about these property keys, see IMMDevice::OpenPropertyStore.

An IPropertyStore interface instance maintains a persistent property store for an audio endpoint device. The property store copies its initial value for the PKEY_Device_DeviceDesc property key from the friendly name string that is associated with the KS pin category GUID in the registry path HKLM\SYSTEM\CurrentControlSet\Control\MediaCategories. Applications can read the PKEY_Device_DeviceDesc property value (the name string) from the property store, but they cannot change the value. However, users can modify the name by using the Windows multimedia control panel, Mmsys.cpl. For example, in Windows Vista, you can use the following steps to modify the name of a rendering endpoint device:

To run Mmsys.cpl, open a Command Prompt window and enter the following command:
Copy
mmsys.cpl
(Alternatively, you can run Mmsys.cpl by right-clicking the speaker icon in the notification area, which is located on the right side of the taskbar, and clicking Playback Devices.)
Click the name of a rendering device, and then click Properties.
In the Properties window, click the General tab. The friendly name should appear in a text box at the top of the property sheet. You can edit the friendly name, and then save your changes by clicking OK.

The preceding steps change the friendly name that is stored in the property store for the audio endpoint device. These steps have no effect on the friendly names associated with other audio endpoint devices that belong to the same KS pin category.

Send comments about this topic to Microsoft

Build date: 11/16/2013