Add option to mute Remote Access when not controlling the remote computer (#18630)

Closes #18104

Summary of the issue:
It is often disruptive to hear what is happening on the remote computer
when controling the local computer. As such, users want the ability to
automatically mute output from the remote computer when controling the
local computer.

Description of user facing changes:
Added an option to mute the remote computer when controlling the local
computer. If enabled:
* Mutes the remote computer when first connecting as leader;
* Automatically mutes the remote computer when switching from remote to
local control.
This option is disabled by default.

Description of developer facing changes:
None

Description of development approach:
* Refactored `_remoteClient.client.RemoteClient.toggleMute` to rely on
an internal use only method that only toggles the mute state, without
performing error checks or producing user output.
* When connecting as leader, toggle to muted using the internal method
if we should mute when controling the local machine.
* Use the public method to toggle mute when switching from remote to
local control (done so there is clear output, just as is done when
switching the other way).
* Added a config item to the config spec that mediates this behaviour..
Also added to the Remote Access settings panel.

Testing strategy:
Connected and disconnected as leader with this setting enabled and
disabled and ensured it behaved as expected.

Known issues with pull request:
None

Author: SaschaCowley

source/_remoteClient/client.py

@@ -128,15 +128,18 @@ def toggleMute(self):
 			# Translators: Presented when attempting to mute or unmute Remote Access when connected as the controlled computer.
 			ui.message(pgettext("remote", "Not the controlling computer"))
 			return
-		self.localMachine.isMuted = not self.localMachine.isMuted
-		self.menu.muteItem.Check(self.localMachine.isMuted)
+		self._doToggleMute()
 		# Translators: Displayed when muting speech and sounds from the remote computer
 		MUTE_MESSAGE = _("Muted remote")
 		# Translators: Displayed when unmuting speech and sounds from the remote computer
 		UNMUTE_MESSAGE = _("Unmuted remote")
 		status = MUTE_MESSAGE if self.localMachine.isMuted else UNMUTE_MESSAGE
 		ui.delayedMessage(status)
 
+	def _doToggleMute(self):
+		self.localMachine.isMuted = not self.localMachine.isMuted
+		self.menu.muteItem.Check(self.localMachine.isMuted)
+
 	def pushClipboard(self):
 		"""Send local clipboard content to the remote computer.
 
@@ -360,6 +363,8 @@ def connectAsLeader(self, connectionInfo: ConnectionInfo):
 		self.leaderTransport = transport
 		if self.menu:
 			self.menu.handleConnecting(connectionInfo.mode)
+		if configuration.getRemoteConfig()["ui"]["muteOnLocalControl"] and not self.localMachine.isMuted:
+			self._doToggleMute()
 
 	@alwaysCallAfter
 	def onConnectedAsLeader(self):
@@ -565,6 +570,8 @@ def _switchToLocalControl(self) -> None:
 		self.releaseKeys()
 		# Translators: Presented when keyboard control is back to the controlling computer.
 		ui.message(pgettext("remote", "Controlling local computer"))
+		if configuration.getRemoteConfig()["ui"]["muteOnLocalControl"] and not self.localMachine.isMuted:
+			self.toggleMute()
 
 	def _switchToRemoteControl(self, gesture: KeyboardInputGesture) -> None:
 		"""Switch to controlling the remote computer."""

source/config/configSpec.py

@@ -362,6 +362,7 @@
 		__many__ = string(default="")
 	[[ui]]
 		confirmDisconnectAsFollower = boolean(default=True)
+		muteOnLocalControl = boolean(default=False)
 """
 
 #: The configuration specification

source/gui/settingsDialogs.py

@@ -3402,6 +3402,17 @@ def makeSettings(self, sizer: wx.BoxSizer):
 		self.bindHelpEvent("RemoteConfirmDisconnect", self.confirmDisconnectAsFollower)
 		enabledInSecureMode.add(self.confirmDisconnectAsFollower)
 
+		self.muteOnLocalControl = remoteSettingsGroupHelper.addItem(
+			wx.CheckBox(
+				self.remoteSettingsGroupBox,
+				# Translators: A checkbox in Remote Access settings to mute speech and sounds from the remote computer
+				# when controlling the local computer.
+				label=pgettext("remote", "&Mute when controlling the local computer"),
+			),
+		)
+		self.bindHelpEvent("RemoteMuteOnLocalControl", self.muteOnLocalControl)
+		enabledInSecureMode.add(self.muteOnLocalControl)
+
 		self.autoconnect = remoteSettingsGroupHelper.addItem(
 			wx.CheckBox(
 				self.remoteSettingsGroupBox,
@@ -3540,6 +3551,7 @@ def _setFromConfig(self) -> None:
 		self.port.SetValue(str(controlServer["port"]))
 		self.key.SetValue(controlServer["key"])
 		self.confirmDisconnectAsFollower.SetValue(self.config["ui"]["confirmDisconnectAsFollower"])
+		self.muteOnLocalControl.SetValue(self.config["ui"]["muteOnLocalControl"])
 		self._setControls()
 
 	def _onEnableRemote(self, evt: wx.CommandEvent):
@@ -3604,6 +3616,7 @@ def onSave(self):
 		oldEnabled = self.config["enabled"]
 		self.config["enabled"] = enabled
 		self.config["ui"]["confirmDisconnectAsFollower"] = self.confirmDisconnectAsFollower.GetValue()
+		self.config["ui"]["muteOnLocalControl"] = self.muteOnLocalControl.GetValue()
 		controlServer = self.config["controlServer"]
 		selfHosted = self.clientOrServer.GetSelection()
 		controlServer["autoconnect"] = self.autoconnect.GetValue()

user_docs/en/changes.md

@@ -23,6 +23,7 @@ Localisation data for emojis has been added for Belarusian and Bosnian.
   * Minimum and last tested version will now be also shown in the details area for an add-on in the Available Add-ons tab. (#18440, @nvdaes)
   * Installation date will now be also shown in the details area for external add-ons. (#18560, @CyrilleB79)
 * A new unassigned command has been added to send `control+alt+delete` when controlling another computer via NVDA Remote Access. (#18105)
+* A new setting has been added to automatically mute Remote Access when controlling the local computer. (#18630)
 
 ### Changes
 

user_docs/en/userGuide.md

@@ -3174,6 +3174,15 @@ This option controls whether confirmation is required before disconnecting from
 When checked, NVDA will ask for confirmation before disconnecting.
 When unchecked, NVDA will disconnect immediately without confirmation.
 
+##### Mute when controlling the local computer {#RemoteMuteOnLocalControl}
+
+This option controls whether you can hear speech and sounds from the remote computer when controlling the local computer.
+
+When checked, Remote Access will be muted automatically when first connecting as the controlling computer, and when switching to controlling the local computer.
+When unchecked, Remote Access sessions start unmuted, and must be muted explicitly.
+
+You can still manually mute or unmute Remote Access when controlling the local computer [via the Remote Access menu](#RemoteAccessUsage), or by assigning a custom gesture using the [Input Gestures dialog](#InputGestures).
+
 ##### Automatically connect after NVDA starts {#RemoteAutoconnect}
 
 This option allows you to automatically establish a Remote Access session when NVDA starts.