Merge d005acc into 690103a

SaschaCowley · web-flow · commit 876001990ea0 · 2025-02-14T14:13:28.000+11:00
diff --git a/source/config/profileUpgradeSteps.py b/source/config/profileUpgradeSteps.py
@@ -459,14 +459,14 @@ def _friendlyNameToEndpointId(friendlyName: str) -> str | None:
 	:param friendlyName: Friendly name of the device to search for.
 	:return: Endpoint ID string of the best match device, or `None` if no device with a matching friendly name is available.
 	"""
-	from utils.mmdevice import _getOutputDevices
+	from utils.mmdevice import getOutputDevices
 	from pycaw.constants import DEVICE_STATE
 
 	states = (DEVICE_STATE.ACTIVE, DEVICE_STATE.UNPLUGGED, DEVICE_STATE.DISABLED, DEVICE_STATE.NOTPRESENT)
 	for state in states:
 		try:
 			return next(
-				device for device in _getOutputDevices(stateMask=state) if device.friendlyName == friendlyName
+				device for device in getOutputDevices(stateMask=state) if device.friendlyName == friendlyName
 			).id
 		except StopIteration:
 			# Proceed to the next device state.
diff --git a/source/gui/settingsDialogs.py b/source/gui/settingsDialogs.py
@@ -3035,7 +3035,7 @@ def makeSettings(self, settingsSizer: wx.BoxSizer) -> None:
 		# Translators: This is the label for the select output device combo in NVDA audio settings.
 		# Examples of an output device are default soundcard, usb headphones, etc.
 		deviceListLabelText = _("Audio output &device:")
-		self._deviceIds, deviceNames = zip(*mmdevice._getOutputDevices(includeDefault=True))
+		self._deviceIds, deviceNames = zip(*mmdevice.getOutputDevices(includeDefault=True))
 		self.deviceList = sHelper.addLabeledControl(deviceListLabelText, wx.Choice, choices=deviceNames)
 		self.bindHelpEvent("SelectSynthesizerOutputDevice", self.deviceList)
 		selectedOutputDevice = config.conf["audio"]["outputDevice"]
diff --git a/source/nvwave.py b/source/nvwave.py
@@ -38,19 +38,13 @@
 import NVDAHelper
 import core
 import globalVars
-from pycaw.utils import AudioUtilities
 from speech import SpeechSequence
 from speech.commands import BreakCommand
 from synthDriverHandler import pre_synthSpeak
 
-from utils.mmdevice import _getOutputDevices
-
 
 __all__ = (
 	"WavePlayer",
-	"getOutputDeviceNames",
-	"outputDeviceIDToName",
-	"outputDeviceNameToID",
 	"decide_playWaveFile",
 )
 
@@ -92,42 +86,6 @@ class AudioPurpose(Enum):
 	SOUNDS = auto()
 
 
-def getOutputDeviceNames() -> list[str]:
-	"""Obtain the names of all audio output devices on the system.
-	:return: The names of all output devices on the system.
-	..note: Depending on number of devices being fetched, this may take some time (~3ms)
-	"""
-	return [name for ID, name in _getOutputDevices()]
-
-
-def outputDeviceIDToName(ID: str) -> str:
-	"""Obtain the name of an output device given its device ID.
-	:param ID: The device ID.
-	:return: The device name.
-	"""
-	device = AudioUtilities.GetDeviceEnumerator().GetDevice(id)
-	return AudioUtilities.CreateDevice(device).FriendlyName
-
-
-def outputDeviceNameToID(name: str, useDefaultIfInvalid: bool = False) -> str:
-	"""Obtain the device ID of an output device given its name.
-	:param name: The device name.
-	:param useDefaultIfInvalid: `True` to use the default device if there is no such device, `False` to raise an exception.
-	:return: The device ID.
-	:raise LookupError: If there is no such device and `useDefaultIfInvalid` is `False`.
-	..note: Depending on number of devices, and the position of the device in the list, this may take some time (~3ms)
-	"""
-	for curID, curName in _getOutputDevices():
-		if curName == name:
-			return curID
-
-	# No such ID.
-	if useDefaultIfInvalid:
-		return AudioUtilities.GetSpeakers().GetId()
-	else:
-		raise LookupError("No such device name")
-
-
 def playWaveFile(
 	fileName: str,
 	asynchronous: bool = True,
@@ -211,7 +169,7 @@ def isInError() -> bool:
 wasPlay_callback = CFUNCTYPE(None, c_void_p, c_uint)
 
 
-class WasapiWavePlayer(garbageHandler.TrackedObject):
+class WavePlayer(garbageHandler.TrackedObject):
 	"""Synchronously play a stream of audio using WASAPI.
 	To use, construct an instance and feed it waveform audio using L{feed}.
 	Keeps device open until it is either not available, or WavePlayer is explicitly closed / deleted.
@@ -278,20 +236,20 @@ def __init__(
 		self._player = NVDAHelper.localLib.wasPlay_create(
 			outputDevice,
 			format,
-			WasapiWavePlayer._callback,
+			WavePlayer._callback,
 		)
 		self._doneCallbacks = {}
 		self._instances[self._player] = self
 		self.open()
 		self._lastActiveTime: typing.Optional[float] = None
 		self._isPaused: bool = False
-		if config.conf["audio"]["audioAwakeTime"] > 0 and WasapiWavePlayer._silenceDevice != outputDevice:
+		if config.conf["audio"]["audioAwakeTime"] > 0 and WavePlayer._silenceDevice != outputDevice:
 			# The output device has changed. (Re)initialize silence.
 			if self._silenceDevice is not None:
 				NVDAHelper.localLib.wasSilence_terminate()
 			if config.conf["audio"]["audioAwakeTime"] > 0:
 				NVDAHelper.localLib.wasSilence_init(outputDevice)
-				WasapiWavePlayer._silenceDevice = outputDevice
+				WavePlayer._silenceDevice = outputDevice
 		# Enable trimming by default for speech only
 		self.enableTrimmingLeadingSilence(
 			purpose is AudioPurpose.SPEECH and config.conf["speech"]["trimLeadingSilence"],
@@ -303,7 +261,7 @@ def __init__(
 
 	@wasPlay_callback
 	def _callback(cppPlayer, feedId):
-		pyPlayer = WasapiWavePlayer._instances[cppPlayer]
+		pyPlayer = WavePlayer._instances[cppPlayer]
 		onDone = pyPlayer._doneCallbacks.pop(feedId, None)
 		if onDone:
 			onDone()
@@ -339,7 +297,7 @@ def open(self):
 			)
 			WavePlayer.audioDeviceError_static = True
 			raise
-		WasapiWavePlayer.audioDeviceError_static = False
+		WavePlayer.audioDeviceError_static = False
 		self._setVolumeFromConfig()
 
 	def close(self):
@@ -567,7 +525,6 @@ def _onPreSpeak(self, speechSequence: SpeechSequence):
 				break
 
 
-WavePlayer = WasapiWavePlayer
 fileWavePlayer: Optional[WavePlayer] = None
 fileWavePlayerThread: threading.Thread | None = None
 
@@ -592,7 +549,7 @@ def initialize():
 
 
 def terminate() -> None:
-	if WasapiWavePlayer._silenceDevice is not None:
+	if WavePlayer._silenceDevice is not None:
 		NVDAHelper.localLib.wasSilence_terminate()
 	getOnErrorSoundRequested().unregister(playErrorSound)
 
diff --git a/source/utils/mmdevice.py b/source/utils/mmdevice.py
@@ -3,6 +3,8 @@
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
 
+"""Tools for interacting with Windows' MMDevice API."""
+
 from collections.abc import Generator
 from typing import NamedTuple, cast
 
@@ -11,16 +13,21 @@
 from pycaw.utils import AudioUtilities
 
 
-class _AudioOutputDevice(NamedTuple):
+class AudioOutputDevice(NamedTuple):
+	"""An MMDevice audio render endpoint."""
+
 	id: str
+	"""The unique identifier of the audio endpoint."""
+
 	friendlyName: str
+	"""The user-friendly name of the audio endpoint."""
 
 
-def _getOutputDevices(
+def getOutputDevices(
 	*,
 	includeDefault: bool = False,
 	stateMask: DEVICE_STATE = DEVICE_STATE.ACTIVE,
-) -> Generator[_AudioOutputDevice]:
+) -> Generator[AudioOutputDevice]:
 	"""Generator, yielding device ID and device Name.
 	.. note:: Depending on number of devices being fetched, this may take some time (~3ms)
 
@@ -31,7 +38,7 @@ def _getOutputDevices(
 	:return: Generator of :class:`_AudioOutputDevices` containing all enabled and present audio output devices on the system.
 	"""
 	if includeDefault:
-		yield _AudioOutputDevice(
+		yield AudioOutputDevice(
 			id=cast(str, config.conf.getConfigValidation(("audio", "outputDevice")).default),
 			# Translators: Value to show when choosing to use the default audio output device.
 			friendlyName=_("Default output device"),
@@ -44,6 +51,6 @@ def _getOutputDevices(
 		device = AudioUtilities.CreateDevice(endpointCollection.Item(i))
 		# This should never be None, but just to be sure
 		if device is not None:
-			yield _AudioOutputDevice(device.id, device.FriendlyName)
+			yield AudioOutputDevice(device.id, device.FriendlyName)
 		else:
 			continue
diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py
@@ -47,7 +47,7 @@
 from utils.displayString import (
 	DisplayStringEnum,
 )
-from utils.mmdevice import _AudioOutputDevice
+from utils.mmdevice import AudioOutputDevice
 
 
 class Config_FeatureFlagEnums_getAvailableEnums(unittest.TestCase):
@@ -918,26 +918,26 @@ def test_updateToDifferentValue(self):
 		self.assertEqual(self.profile, {"someBool": False})
 
 
-_DevicesT: typing.TypeAlias = dict[DEVICE_STATE, list[_AudioOutputDevice]]
+_DevicesT: typing.TypeAlias = dict[DEVICE_STATE, list[AudioOutputDevice]]
 
 
 def getOutputDevicesFactory(
 	devices: _DevicesT,
-) -> Callable[[DEVICE_STATE], Generator[_AudioOutputDevice]]:
-	"""Create a callable that can be used to patch utils.mmdevice._getOutputDevices."""
+) -> Callable[[DEVICE_STATE], Generator[AudioOutputDevice]]:
+	"""Create a callable that can be used to patch utils.mmdevice.getOutputDevices."""
 
-	def getOutputDevices(stateMask: DEVICE_STATE, **kw) -> Generator[_AudioOutputDevice]:
+	def getOutputDevices(stateMask: DEVICE_STATE, **kw) -> Generator[AudioOutputDevice]:
 		yield from devices.get(stateMask, [])
 
 	return getOutputDevices
 
 
 class Config_ProfileUpgradeSteps_FriendlyNameToEndpointId(unittest.TestCase):
 	DEFAULT_DEVICES: _DevicesT = {
-		DEVICE_STATE.ACTIVE: [_AudioOutputDevice("id1", "Device 1")],
-		DEVICE_STATE.UNPLUGGED: [_AudioOutputDevice("id2", "Device 2")],
-		DEVICE_STATE.DISABLED: [_AudioOutputDevice("id3", "Device 3")],
-		DEVICE_STATE.NOTPRESENT: [_AudioOutputDevice("id4", "Device 4")],
+		DEVICE_STATE.ACTIVE: [AudioOutputDevice("id1", "Device 1")],
+		DEVICE_STATE.UNPLUGGED: [AudioOutputDevice("id2", "Device 2")],
+		DEVICE_STATE.DISABLED: [AudioOutputDevice("id3", "Device 3")],
+		DEVICE_STATE.NOTPRESENT: [AudioOutputDevice("id4", "Device 4")],
 	}
 
 	def test_noDuplicates(self):
@@ -952,10 +952,10 @@ def test_orderOfPrecedence(self):
 		"""Test that, when there are devices with duplicate names in different states, the one with the preferred state is returned."""
 		FRIENDLY_NAME = "Device friendly name"
 		devices: _DevicesT = {
-			DEVICE_STATE.ACTIVE: [_AudioOutputDevice("idA", FRIENDLY_NAME)],
-			DEVICE_STATE.DISABLED: [_AudioOutputDevice("idD", FRIENDLY_NAME)],
-			DEVICE_STATE.NOTPRESENT: [_AudioOutputDevice("idN", FRIENDLY_NAME)],
-			DEVICE_STATE.UNPLUGGED: [_AudioOutputDevice("idU", FRIENDLY_NAME)],
+			DEVICE_STATE.ACTIVE: [AudioOutputDevice("idA", FRIENDLY_NAME)],
+			DEVICE_STATE.DISABLED: [AudioOutputDevice("idD", FRIENDLY_NAME)],
+			DEVICE_STATE.NOTPRESENT: [AudioOutputDevice("idN", FRIENDLY_NAME)],
+			DEVICE_STATE.UNPLUGGED: [AudioOutputDevice("idU", FRIENDLY_NAME)],
 		}
 		with self.subTest("Friendly name is active"):
 			self.performTest(*devices[DEVICE_STATE.ACTIVE][0], devices)
@@ -981,11 +981,11 @@ def test_noDevices(self):
 		self.performTest(friendlyName="Anything", expectedId=None, devices=devices)
 
 	def performTest(self, expectedId: str | None, friendlyName: str, devices: _DevicesT):
-		"""Patch utils.mmdevice._getOutputDevices to return what we tell it, then test that friendlyNameToEndpointId returns the correct ID given a friendly name.
+		"""Patch utils.mmdevice.getOutputDevices to return what we tell it, then test that friendlyNameToEndpointId returns the correct ID given a friendly name.
 		The odd order of arguments is so you can directly unpack an AudioOutputDevice.
 		"""
 		with patch(
-			"utils.mmdevice._getOutputDevices",
+			"utils.mmdevice.getOutputDevices",
 			autospec=True,
 			side_effect=getOutputDevicesFactory(devices),
 		):
@@ -995,10 +995,10 @@ def performTest(self, expectedId: str | None, friendlyName: str, devices: _Devic
 class Config_upgradeProfileSteps_upgradeProfileFrom_13_to_14(unittest.TestCase):
 	def setUp(self):
 		devices: _DevicesT = {
-			DEVICE_STATE.ACTIVE: [_AudioOutputDevice("id", "Friendly name")],
+			DEVICE_STATE.ACTIVE: [AudioOutputDevice("id", "Friendly name")],
 		}
 		self._getOutputDevicesPatcher = patch(
-			"utils.mmdevice._getOutputDevices",
+			"utils.mmdevice.getOutputDevices",
 			autospec=True,
 			side_effect=getOutputDevicesFactory(devices),
 		)
diff --git a/user_docs/en/changes.md b/user_docs/en/changes.md
@@ -165,6 +165,7 @@ Add-ons will need to be re-tested and have their manifest updated.
   * Added the `matchFunc` parameter to `addUsbDevices` which is also available on `addUsbDevice`.
     * This way device detection can be constrained further in cases where a VID/PID-combination is shared by multiple devices across multiple drivers, or when a HID device offers multiple endpoints, for example.
     * See the method documentation as well as examples in the albatross and brailliantB drivers for more information.
+* Added a new function, `utils.mmdevice.getOutputDevices`, to enumerate audio output devices. (#17678)
 * Added a new extension point `pre_synthSpeak` in `synthDriverHandler`, which will be called before the speech manager calls `speak` of the current synthesizer.
 
 #### API Breaking Changes
@@ -183,8 +184,11 @@ As the NVDA update check URL is now configurable directly within NVDA, no replac
   * `SymphonyDocument.script_toggleTextAttribute` to `SymphonyDocument.script_changeTextFormatting`
 * The `space` keyword argument for `brailleDisplayDrivers.seikantk.InputGesture` now expects an `int` rather than a `bool`. (#17047, @school510587)
 * The `[upgrade]` configuration section including `[upgrade][newLaptopKeyboardLayout]` has been removed. (#17191)
-* Due to the retirement of NVDA's winmm support (#17496, #17532):
-  * The following symbols have been removed from `nvwave`: `CALLBACK_EVENT`, `CALLBACK_FUNCTION`, `CALLBACK_NULL`, `HWAVEOUT`, `LPHWAVEOUT`, `LPWAVEFORMATEX`, `LPWAVEHDR`, `MAXPNAMELEN`, `MMSYSERR_NOERROR`, `usingWasapiWavePlayer`, `WAVEHDR`, `WAVEOUTCAPS`, `waveOutProc`, `WAVE_MAPPER`, `WHDR_DONE`, `WinmmWavePlayer`, and `winmm`.
+* Due to the retirement of NVDA's winmm support (#17496, #17532, #17678):
+  * The following symbols have been removed from `nvwave` without replacements: `CALLBACK_EVENT`, `CALLBACK_FUNCTION`, `CALLBACK_NULL`, `HWAVEOUT`, `LPHWAVEOUT`, `LPWAVEFORMATEX`, `LPWAVEHDR`, `MAXPNAMELEN`, `MMSYSERR_NOERROR`, `usingWasapiWavePlayer`, `WAVEHDR`, `WAVEOUTCAPS`, `waveOutProc`, `WAVE_MAPPER`, `WHDR_DONE`, `WinmmWavePlayer`, and `winmm`.
+  * The following symbols have been removed from `nvwave`: `getOutputDeviceNames`, `outputDeviceIDToName`, `outputDeviceNameToID`.
+  Use `utils.mmdevice.getOutputDevices` instead.
+  * `nvwave.WasapiWavePlayer` has been renamed to `WavePlayer`.
   * `gui.settingsDialogs.AdvancedPanelControls.wasapiComboBox` has been removed.
   * The `WASAPI` key has been removed from the `audio` section of the config spec.
   * The output from `nvwave.outputDeviceNameToID`, and input to `nvwave.outputDeviceIDToName` are now string identifiers.
