Allow the volume of NVDA sounds to be set within NVDA.

[jcsteh]

Link to issue number:

Better solution for #1409. Addresses #14896 (comment). Also addresses feedback I received on Mastodon regarding the NVDA sounds volume not appearing in the Windows Volume Mixer in some versions of Windows.

Summary of the issue:

1. In Support for audio output using WASAPI #14697, I split NVDA speech and sounds into two separate Windows audio sessions to allow independent control of their levels. However, some users want these levels to be linked.
2. In Add setting to have the volume of NVDA sounds follow the voice volume. #14896, I made it possible to have the sounds volume follow the voice volume. However, as per Add setting to have the volume of NVDA sounds follow the voice volume. #14896 (comment), some synths don't set the volume in a linear way, so the volumes don't match.
3. It was reported to me on Mastodon that in Windows 11 Insider builds, the "NVDA sounds" volume doesn't show up in the Windows Volume Mixer unless you actively play a sound while the Volume Mixer is running. This is not very intuitive, and if this is behaviour Microsoft intends to keep, it isn't going to work well for our users.
4. Having the volume of NVDA sounds controlled outside of NVDA is a little cumbersome.

Description of user facing changes

1. There will now only be one entry for NVDA in the Windows Volume Mixer which will control all NVDA audio.
2. There will be a slider in NVDA Advanced Settings to control the volume of sounds.

Description of development approach

1. Removed the ability to set a WASAPI session and volume.
2. Added a method to set the volume of a stream. This also allows you to set the volume of individual channels, though that's not used yet.
3. Added a slider in Advanced Settings to control the volume of NVDA sounds. This is disabled if the sound volume is following the voice volume.

Testing strategy:

All the tests from #14896, plus:

1. Disabled "Volume of NVDA sounds follows voice volume".
2. Lowered the NVDA sounds volume to 10%.
3. Switched between focus and browse modes to verify that sounds played quieter.
4. Increased the NVDA sounds volume to 100%.
5. Switched between focus and browse modes to verify that sounds played louder.
6. Enabled "Volume of NVDA sounds follows voice volume".
7. Set the voice volume to 50%.
8. Switched between focus and browse modes to verify that sounds played quieter.

Known issues with pull request:

No user facing issues. However:

1. I'm wondering whether I should make AudioPurpose, the purpose argument to WavePlayer and the setVolume method private (underscore prefixed) for now. I don't anticipate any further changes, but nor did I anticipate changes to the previous session API. Making it private would allow us to ensure this is stable internally before making it part of the public API. This might be overkill though.
2. This does change the WavePlayer API in beta (but not in release). I don't think that's considered API breaking if this gets merged to beta, but it's worth noting. It will be a problem if we don't merge this to beta.

Change log entries:

In this entry in New features:

- You can now separately control the volume of NVDA sounds.
This can be done using the Windows Volume Mixer. (#1409)

The second line should be adjusted to say:
This can be done in Advanced settings. (#1409)

Code Review Checklist:

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

[brunoprietog]

Thanks!

[seanbudd]

Generally looks good to me

[seanbudd]

Thanks @jcsteh

[CyrilleB79]

@jcsteh what about config spec and profiles?

When merging WASAPI I had warned about the "audio" section not being in BASE_ONLY_SECTIONS. For WASAPI on/off, it did not matter since this parameter is only looked at when starting NVDA.

But what about other parameters of audio section? Are they meant to be profile dependant?

Also, is there any plan to move all those audio settings out of the advanced settings panel? I think that we should not wait for years before moving them in their own section. I understand however that WASAPI checkbox and all parameter depending of it remain in Advanced settings for NVDA 2023.2.

[jcsteh]

But what about other parameters of audio section? Are they meant to be profile dependant?

I don't see any reason they should be profile independent, though I'm not sure whether they all currently behave properly when you switch profiles. I can't see any reason the volume settings shouldn't switch properly across profiles.

Also, is there any plan to move all those audio settings out of the advanced settings panel? I think that we should not wait for years before moving them in their own section.

I don't have a specific plan to do this, but yes, I agree they should probably be moved out of Advanced Settings once WASAPI is no longer a configurable option; i.e. once WASAPI is always enabled.

[Qchristensen]

Looks good. This issue comes up from time to time, so it will make a number of users happy, thanks!