Add WASAPI toggle to SAPI5 (#18352)

Closes #18309.

Summary of the issue:
Users cannot turn off WASAPI for SAPI5 yet.

Description of user facing changes:
Add a synthesizer setting called `useWasapi`, which is displayed as a
checkbox labeled `Use modern audio output system (WASAPI)` in the voice
settings when the built-in SAPI5 synthesizer is selected.

Description of developer facing changes:
None

Description of development approach:
A new `SynthSetting` based on `BooleanDriverSetting` called `useWasapi`
is added and defaults to `True`. It is not in the settings ring.

Legacy SAPI5 code are re-introduced to be used when WASAPI for SAPI5 is
disabled.

Testing strategy:
Tested manually.

Author: gexgd0419

source/gui/settingsDialogs.py

@@ -1669,8 +1669,17 @@ def driver(self):
 	def getSettings(self) -> AutoSettings:
 		return self.driver
 
-	def _getSettingControlHelpId(self, controlId):
-		standardSettings = ["voice", "variant", "rate", "rateBoost", "pitch", "inflection", "volume"]
+	def _getSettingControlHelpId(self, controlId: str) -> str:
+		standardSettings = [
+			"voice",
+			"variant",
+			"rate",
+			"rateBoost",
+			"pitch",
+			"inflection",
+			"volume",
+			"useWasapi",
+		]
 		if controlId in standardSettings:
 			capitalizedId = controlId[0].upper() + controlId[1:]
 			return f"{self.helpId}{capitalizedId}"

source/synthDriverHandler.py

@@ -221,6 +221,18 @@ def InflectionSetting(cls, minStep=1):
 			displayName=pgettext("synth setting", "Inflection"),
 		)
 
+	@classmethod
+	def UseWasapiSetting(cls) -> BooleanDriverSetting:
+		"""Factory function for creating 'Use WASAPI' setting."""
+		return BooleanDriverSetting(
+			"useWasapi",
+			# Translators: Label for a setting in voice settings dialog.
+			# "WASAPI" is an acronym for an audio output framework, and should be translated as-is.
+			_("Use modern audio output system (WASAPI)"),
+			availableInSettingsRing=False,
+			defaultVal=True,
+		)
+
 	@abstractmethod
 	def speak(self, speechSequence):
 		"""

source/synthDrivers/sapi5.py

@@ -9,6 +9,7 @@
 import locale
 from collections import OrderedDict, deque
 from typing import TYPE_CHECKING
+import audioDucking
 from comInterfaces.SpeechLib import ISpEventSource, ISpNotifySource, ISpNotifySink
 import comtypes.client
 from comtypes import COMError, COMObject, IUnknown, hresult
@@ -35,6 +36,14 @@
 from ._sonic import SonicStream, initialize as sonicInitialize
 
 
+class _SPAudioState(IntEnum):
+	# https://docs.microsoft.com/en-us/previous-versions/windows/desktop/ms720596(v=vs.85)
+	CLOSED = 0
+	STOP = 1
+	PAUSE = 2
+	RUN = 3
+
+
 class SpeechVoiceSpeakFlags(IntEnum):
 	# https://docs.microsoft.com/en-us/previous-versions/windows/desktop/ms720892(v=vs.85)
 	Async = 1
@@ -181,6 +190,10 @@ def ISpNotifySink_Notify(self):
 
 	def StartStream(self, streamNum: int, pos: int):
 		synth = self.synthRef()
+		if synth._audioDucker:
+			if audioDucking._isDebug():
+				log.debug("Enabling audio ducking due to starting speech stream")
+			synth._audioDucker.enable()
 		# The stream has been started. Move the bookmark list to _streamBookmarks.
 		if streamNum in synth._streamBookmarksNew:
 			synth._streamBookmarks[streamNum] = synth._streamBookmarksNew[streamNum]
@@ -189,26 +202,31 @@ def StartStream(self, streamNum: int, pos: int):
 
 	def Bookmark(self, streamNum: int, pos: int, bookmark: str, bookmarkId: int):
 		synth = self.synthRef()
-		if not synth.isSpeaking:
+		if not synth.isSpeaking or not synth.player:
 			return
 		# Bookmark event is raised before the audio after that point.
 		# Queue an IndexReached event at this point.
 		synth.player.feed(None, 0, lambda: self.onIndexReached(streamNum, bookmarkId))
 
 	def EndStream(self, streamNum: int, pos: int):
 		synth = self.synthRef()
-		# Flush the stream and get the remaining data.
-		synth.sonicStream.flush()
-		audioData = synth.sonicStream.readShort()
-		synth.player.feed(audioData, len(audioData) * 2)
-		synth.player.idle()
+		if synth.player:
+			# Flush the stream and get the remaining data.
+			synth.sonicStream.flush()
+			audioData = synth.sonicStream.readShort()
+			synth.player.feed(audioData, len(audioData) * 2)
+			synth.player.idle()
 		# trigger all untriggered bookmarks
 		if streamNum in synth._streamBookmarks:
 			for bookmark in synth._streamBookmarks[streamNum]:
 				synthIndexReached.notify(synth=synth, index=bookmark)
 			del synth._streamBookmarks[streamNum]
 		synth.isSpeaking = False
 		synthDoneSpeaking.notify(synth=synth)
+		if synth._audioDucker:
+			if audioDucking._isDebug():
+				log.debug("Disabling audio ducking due to speech stream end")
+			synth._audioDucker.disable()
 
 	def onIndexReached(self, streamNum: int, index: int):
 		synth = self.synthRef()
@@ -231,6 +249,7 @@ class SynthDriver(SynthDriver):
 		SynthDriver.RateBoostSetting(),
 		SynthDriver.PitchSetting(),
 		SynthDriver.VolumeSetting(),
+		SynthDriver.UseWasapiSetting(),
 	)
 	supportedCommands = {
 		IndexCommand,
@@ -259,6 +278,11 @@ def check(cls):
 		except:  # noqa: E722
 			return False
 
+	ttsAudioStream = (
+		None  #: Holds the ISPAudio interface for the current voice, to aid in stopping and pausing audio
+	)
+	_audioDucker: audioDucking.AudioDucker | None = None
+
 	def __init__(self, _defaultVoiceToken=None):
 		"""
 		@param _defaultVoiceToken: an optional sapi voice token which should be used as the default voice (only useful for subclasses)
@@ -267,7 +291,9 @@ def __init__(self, _defaultVoiceToken=None):
 		self._pitch = 50
 		self._rate = 50
 		self._volume = 100
-		self.player = None
+		self._useWasapi = True
+		self.player: nvwave.WavePlayer | None = None
+		self.sonicStream: SonicStream | None = None
 		self.isSpeaking = False
 		self._rateBoost = False
 		self._initTts(_defaultVoiceToken)
@@ -318,6 +344,9 @@ def _get_volume(self) -> int:
 	def _get_voice(self):
 		return self.tts.voice.Id
 
+	def _get_useWasapi(self) -> bool:
+		return self._useWasapi
+
 	def _get_lastIndex(self):
 		bookmark = self.tts.status.LastBookmark
 		if bookmark != "" and bookmark is not None:
@@ -335,6 +364,9 @@ def _percentToRate(self, percent):
 
 	def _set_rate(self, rate):
 		self._rate = rate
+		if not self.sonicStream:
+			self.tts.Rate = self._percentToRate(rate)
+			return
 		if self._rateBoost:
 			# When rate boost is enabled, use sonicStream to change the speed.
 			# Supports 0.5x~6x speed.
@@ -360,25 +392,26 @@ def _set_volume(self, value):
 		self._volume = value
 		self.tts.Volume = value
 
-	def _initTts(self, voice=None):
-		self.tts = comtypes.client.CreateObject(self.COM_CLASS)
-		if voice:
-			# #749: It seems that SAPI 5 doesn't reset the audio parameters when the voice is changed,
-			# but only when the audio output is changed.
-			# Therefore, set the voice before setting the audio output.
-			# Otherwise, we will get poor speech quality in some cases.
-			self.tts.voice = voice
+	def _initAudioDevice(self):
+		# SAPI5 automatically selects the system default audio device, so there's no use doing work if the user has selected to use the system default.
+		# Besides, our default value is not a valid endpoint ID.
+		if (outputDevice := config.conf["audio"]["outputDevice"]) != config.conf.getConfigValidation(
+			("audio", "outputDevice"),
+		).default:
+			for audioOutput in self.tts.GetAudioOutputs():
+				# SAPI's audio output IDs are registry keys. It seems that the final path segment is the endpoint ID.
+				if audioOutput.Id.endswith(outputDevice):
+					self.tts.audioOutput = audioOutput
+					break
 
-		self.tts.AudioOutput = self.tts.AudioOutput  # Reset the audio and its format parameters
+	def _initWasapiAudio(self):
 		fmt = self.tts.AudioOutputStream.Format
 		wfx = fmt.GetWaveFormatEx()
 		# Force the wave format to be 16-bit integer (which Sonic uses internally).
 		# SAPI will convert the format for us if it isn't supported by the voice.
 		wfx.FormatTag = nvwave.WAVE_FORMAT_PCM
 		wfx.BitsPerSample = 16
 		fmt.SetWaveFormatEx(wfx)
-		if self.player:
-			self.player.close()
 		self.player = nvwave.WavePlayer(
 			channels=wfx.Channels,
 			samplesPerSec=wfx.SamplesPerSec,
@@ -394,6 +427,39 @@ def _initTts(self, voice=None):
 		sonicInitialize()
 		self.sonicStream = SonicStream(wfx.SamplesPerSec, wfx.Channels)
 
+	def _initLegacyAudio(self):
+		if audioDucking.isAudioDuckingSupported():
+			self._audioDucker = audioDucking.AudioDucker()
+		from comInterfaces.SpeechLib import ISpAudio
+
+		try:
+			self.ttsAudioStream = self.tts.audioOutputStream.QueryInterface(ISpAudio)
+		except COMError:
+			log.debugWarning("SAPI5 voice does not support ISPAudio")
+			self.ttsAudioStream = None
+
+	def _initTts(self, voice: str | None = None):
+		self.tts = comtypes.client.CreateObject(self.COM_CLASS)
+		if voice:
+			# #749: It seems that SAPI 5 doesn't reset the audio parameters when the voice is changed,
+			# but only when the audio output is changed.
+			# Therefore, set the voice before setting the audio output.
+			# Otherwise, we will get poor speech quality in some cases.
+			self.tts.voice = voice
+
+		if self.player:
+			self.player.close()
+			self.player = None
+		self.sonicStream = None
+		self.ttsAudioStream = None
+		self._audioDucker = None
+
+		self._initAudioDevice()
+		if self.useWasapi:
+			self._initWasapiAudio()
+		else:
+			self._initLegacyAudio()
+
 		# Set event notify sink
 		self.tts.EventInterests = (
 			SpeechVoiceEvents.StartInputStream | SpeechVoiceEvents.Bookmark | SpeechVoiceEvents.EndInputStream
@@ -417,6 +483,12 @@ def _set_voice(self, value):
 		self._set_rate(self._rate)
 		self._set_volume(self._volume)
 
+	def _set_useWasapi(self, value: bool):
+		if value == self._useWasapi:
+			return
+		self._useWasapi = value
+		self.voice = self.voice  # reload the current voice
+
 	def _percentToPitch(self, percent):
 		return percent // 2 - 25
 
@@ -550,19 +622,91 @@ def outputTags():
 
 		text = "".join(textList)
 		flags = SpeechVoiceSpeakFlags.IsXML | SpeechVoiceSpeakFlags.Async
-		streamNum = self.tts.Speak(text, flags)
+		if self.useWasapi:
+			streamNum = self.tts.Speak(text, flags)
+		else:
+			streamNum = self._speak_legacy(text, flags)
 		# When Speak returns, the previous stream may not have been ended.
 		# So the bookmark list is stored in another dict until this stream starts.
 		self._streamBookmarksNew[streamNum] = bookmarks
 
+	def _speak_legacy(self, text: str, flags: int) -> int:
+		"""Legacy way of calling SpVoice.Speak that uses a temporary audio ducker."""
+		# Ducking should be complete before the synth starts producing audio.
+		# For this to happen, the speech method must block until ducking is complete.
+		# Ducking should be disabled when the synth is finished producing audio.
+		# Note that there may be calls to speak with a string that results in no audio,
+		# it is important that in this case the audio does not get stuck ducked.
+		# When there is no audio produced the startStream and endStream handlers are not called.
+		# To prevent audio getting stuck ducked, it is unducked at the end of speech.
+		# There are some known issues:
+		# - When there is no audio produced by the synth, a user may notice volume lowering (ducking) temporarily.
+		# - If the call to startStream handler is delayed significantly, users may notice a variation in volume
+		# (as ducking is disabled at the end of speak, and re-enabled when the startStream handler is called)
+
+		# A note on the synchronicity of components of this approach:
+		# SAPISink.StartStream event handler (callback):
+		# the synth speech is not blocked by this event callback.
+		# SAPISink.EndStream event handler (callback):
+		# assumed also to be async but not confirmed. Synchronicity is irrelevant to the current approach.
+		# AudioDucker.disable returns before the audio is completely unducked.
+		# AudioDucker.enable() ducking will complete before the function returns.
+		# It is not possible to "double duck the audio", calling twice yields the same result as calling once.
+		# AudioDucker class instances count the number of enables/disables,
+		# in order to unduck there must be no remaining enabled audio ducker instances.
+		# Due to this a temporary audio ducker is used around the call to speak.
+		# SAPISink.StartStream: Ducking here may allow the early speech to start before ducking is completed.
+		if audioDucking.isAudioDuckingSupported():
+			tempAudioDucker = audioDucking.AudioDucker()
+		else:
+			tempAudioDucker = None
+		if tempAudioDucker:
+			if audioDucking._isDebug():
+				log.debug("Enabling audio ducking due to speak call")
+			tempAudioDucker.enable()
+		try:
+			return self.tts.Speak(text, flags)
+		finally:
+			if tempAudioDucker:
+				if audioDucking._isDebug():
+					log.debug("Disabling audio ducking after speak call")
+				tempAudioDucker.disable()
+
 	def cancel(self):
 		# SAPI5's default means of stopping speech can sometimes lag at end of speech, especially with Win8 / Win 10 Microsoft Voices.
 		# Therefore  instruct the audio player to stop first, before interupting and purging any remaining speech.
 		self.isSpeaking = False
-		self.player.stop()
-		self.sonicStream.flush()
-		self.sonicStream.readShort()  # discard data left in stream
+		if self.player:
+			self.player.stop()
+			self.sonicStream.flush()
+			self.sonicStream.readShort()  # discard data left in stream
+		if self.ttsAudioStream:
+			self.ttsAudioStream.setState(_SPAudioState.STOP, 0)
 		self.tts.Speak(None, SpeechVoiceSpeakFlags.Async | SpeechVoiceSpeakFlags.PurgeBeforeSpeak)
+		if self._audioDucker:
+			if audioDucking._isDebug():
+				log.debug("Disabling audio ducking due to setting output audio state to stop")
+			self._audioDucker.disable()
 
 	def pause(self, switch: bool):
-		self.player.pause(switch)
+		if self.player:
+			self.player.pause(switch)
+		# SAPI5's default means of pausing in most cases is either extremely slow
+		# (e.g. takes more than half a second) or does not work at all.
+		# Therefore instruct the underlying audio interface to pause instead.
+		if self.ttsAudioStream:
+			oldState = self.ttsAudioStream.GetStatus().State
+			if switch and oldState == _SPAudioState.RUN:
+				# pausing
+				if self._audioDucker:
+					if audioDucking._isDebug():
+						log.debug("Disabling audio ducking due to setting output audio state to pause")
+					self._audioDucker.disable()
+				self.ttsAudioStream.setState(_SPAudioState.PAUSE, 0)
+			elif not switch and oldState == _SPAudioState.PAUSE:
+				# unpausing
+				if self._audioDucker:
+					if audioDucking._isDebug():
+						log.debug("Enabling audio ducking due to setting output audio state to run")
+					self._audioDucker.enable()
+				self.ttsAudioStream.setState(_SPAudioState.RUN, 0)

user_docs/en/userGuide.md

@@ -1921,6 +1921,24 @@ This option is a slider which goes from 0 to 100 - 0 being the lowest volume and
 
 This option is a slider that lets you choose how much inflection (rise and fall in pitch) the synthesizer should use to speak with.
 
+##### Use modern audio output system (WASAPI) {#SpeechSettingsUseWasapi}
+
+This option enables audio output via the Windows Audio Session API (WASAPI).
+This may improve the responsiveness of some voices.
+However, some voices might not work with the current WASAPI implementation.
+If you find that the voice you are using stops working, you may disable this option.
+
+Note that the following features depend on WASAPI, and will be disabled if WASAPI is turned off.
+
+* For Microsoft Speech API version 4 voices:
+  * Audio ducking
+  * Leading silence trimming
+  * Keep audio device awake
+* For Microsoft Speech API version 5 voices:
+  * Rate boost
+  * Leading silence trimming
+  * Keep audio device awake
+
 ##### Automatic Language switching {#SpeechSettingsLanguageSwitching}
 
 This checkbox allows you to toggle whether NVDA should switch speech synthesizer languages automatically if the text being read specifies its language.