Make SAPI4 voices use WASAPI

[gexgd0419]

Link to issue number:

None

Summary of the issue:

This PR makes the built-in SAPI4 synthesizer use WASAPI to output audio, so that old code related to WinMM can be removed entirely.

Description of user facing changes

SAPI4 voices should work as usual.

Features supported by WavePlayer, such as audio ducking, leading silence trimming, and keeping audio device awake (#17571) will be able to work with SAPI4 voices.

Description of development approach

Create a class to implement IAudio and IAudioDest, so that it can be used as an audio output destination to replace the SAPI4 built-in MMAudioDest which uses WinMM.

SAPI4 performs audio data output on the main thread. SAPI4 expects audio data writes to be a non-blocking operation, and it should return AUDERR_NOTENOUGHDATA when the buffer is full. Unfortunately, that's not how WavePlayer works, and WavePlayer.feed blocks the current thread until there's enough space in the buffer. So a dedicated thread is created to feed data to WavePlayer, and audio data from SAPI4 will be put in a queue first to prevent blocking the thread. Bookmarks from SAPI4 will be put in the same queue.

WavePlayer.feed returns before the audio is finished playing, but WavePlayer can only check and invoke callback functions when WavePlayer.feed or WavePlayer.sync is called. If we just keep on waiting for the next audio chunk in the queue, WavePlayer will have no chance to call the callback functions when there is no chunk. So WavePlayer.feed should be called periodically, regardless of whether there's audio or bookmark in the queue.

Testing strategy:

Further tests with different SAPI4 synthesizers are needed.

Known issues with pull request:

Some SAPI4 voices do not support custom audio destinations, and this is allowed by the SAPI4 spec. They choose their own way to output the audio, and therefore bypass the WASAPI WavePlayer. In fact, they also don't use MMAudioDest before this PR. This means that:

• WASAPI-related features, such as audio ducking, still cannot work with them.
• They do not follow the audio output device setting in NVDA's settings dialog, and will always output audio on the device they select.

Such voices have TTSFEATURE_FIXEDAUDIO in the feature flag.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

@coderabbitai summary

[AppVeyorBot]

• PASS: Translation comments check.
• PASS: License check.
• PASS: Unit tests.
• PASS: Lint check.
• Build execution time has reached the maximum allowed time for your plan (60 minutes).

See test results for failed build of commit 8fc0fd4c63

[cary-rowen]

This is a great work, and if we can merge this in the 2025.1 dev cycle, we don't have to announce to the community that Sapi4 will be deprecated, thus avoiding possible confusion.

[seanbudd]

Thanks @gexgd0419! We recently decided to extend the life of SAPI 4 for the immediate future anyway, but this change is still much appreciated

[seanbudd]

Could you also remove any mention of the deprecation of SAPI4 including the warning message?

[seanbudd]

Thanks @gexgd0419

[Qchristensen]

Great work and will be appreciated by SAPI 4 users.

[hozosch]

Currently, there's the following Issue in Alpha versions. I don't know if it's known yet, because it persists in the last few versions already, so I'm pointing it out here.
Traceback (most recent call last):
File "comtypes_comobject.pyc", line 176, in call_without_this
File "synthDrivers\sapi4.pyc", line 220, in IAudio_LevelSet
AttributeError: 'NoneType' object has no attribute 'setVolume'
I think this is what causes sapi4 to not work at all. At least, that's what happens on my end.

[cary-rowen]

@hozosch
Can you open an issue separately?

[hozosch]

Yes, but I didn't know if that was such a good idea at first. I didn't want too many unnecessary issues for one topic. But if you so wish, I'll do it.