Implementation of advance configuration for NVDA ft #6788 @derekriemer

[kaveinthran]

I'd like to revisit the idea of an advanced configuration manager for NVDA, originally proposed by Derek Riemer in issue #6788 in January 2017.

The issue was recently closed with the explanation that NV Access does not want to encourage or support hidden configuration items, and that improving the existing settings dialog would be preferable.

I can understand that position, particularly the concern about exposing settings that might break NVDA or require additional maintenance. However, I am not entirely convinced that improving the existing settings dialog and providing an advanced configuration manager need to be mutually exclusive.

Before we dismiss the idea altogether, I think there are some interesting technical, practical and philosophical questions worth exploring. Is there still a need for such a manager? What configurations are currently inaccessible through the normal settings interface? Why were they left out? Would exposing selected configurations help users, developers, testers and support volunteers? And, perhaps most importantly, can we design something that balances user autonomy with the legitimate concerns of maintainability and safety?

I am opening this discussion not to insist that NVDA must implement the original proposal, but to understand whether there is a useful feature here that deserves reconsideration.

1. What problem are we actually trying to solve?

NVDA already provides a fairly comprehensive settings interface, including an Advanced category. I think this is an important starting point.

However, not every configurable behaviour necessarily belongs in the ordinary settings interface. Some options may be relevant only to particular hardware, applications, unusual accessibility requirements, troubleshooting situations or experimental features.

There is a distinction between a setting that should be available to everyone, one that should be available only to experienced users, and an internal implementation detail that should not be exposed as a supported configuration at all.

I wonder whether we have been treating these as essentially the same category when discussing hidden settings.

Consider a situation in which a user experiences a particular problem with braille, speech output, focus tracking or an application-specific behaviour. A developer might identify a configuration option that could help diagnose or work around it. If that option is not available through the interface, the user may need to edit a configuration file manually, use the Python console, or follow specific instructions from someone familiar with NVDA's internals.

Would a controlled configuration interface make that process easier, safer and more reproducible?

It could also make it easier for community contributors to identify potentially useful settings, test proposed changes and provide meaningful feedback.

Of course, an editor cannot solve problems caused by settings that are not actually configurable, or by behaviours requiring changes to NVDA's code. I don't think we should overstate its usefulness.

2. What can we learn from Firefox, Chrome and similar applications?

The obvious comparison is Firefox's about:config.

Firefox has a conventional settings interface for ordinary users, but it also provides a separate configuration editor through which experienced users can search, inspect, modify and reset preferences.

Mozilla acknowledges that changing these preferences can affect browser stability, security and performance. It does not present the configuration editor as an ordinary settings interface, nor does it promise that every advanced modification will remain supported indefinitely.

Chrome takes a somewhat different approach through chrome://flags, which exposes experimental features rather than serving as a general-purpose preference editor. Chrome explicitly warns that flags may change or disappear and should not be relied upon as permanent settings.

These approaches are not identical, and I don't think NVDA should blindly copy either one.

What interests me is the underlying philosophy: a product can provide a stable, curated interface for ordinary users while allowing more experienced users to exercise additional control, with appropriate warnings and limitations.

I would argue that this distinction is particularly relevant to assistive technology.

Blind users have different combinations of hardware, speech synthesizers, braille displays, applications, languages and workflows. A behaviour that works well for the majority may create significant difficulties for a small group. In such cases, having some flexibility can make an enormous difference.

At the same time, NVDA occupies a more critical position than many ordinary applications. A broken browser preference is inconvenient; a configuration change that prevents a screen reader from producing speech or braille can leave someone unable to recover independently.

That risk needs to be central to the design, not treated as an afterthought.

3. What configurations should we consider?

Rather than immediately proposing an editor that exposes every key in NVDA's configuration files, I think we should first audit which settings are currently accessible, which are internal, and which might genuinely benefit from an advanced interface.

Some possible areas for investigation include:

A. Speech and audio

• Synthesizer-specific configuration that may not be represented by existing controls.
• Speech responsiveness and timing parameters.
• Audio-device behaviour and compatibility workarounds.
• Experimental speech processing behaviour.
• Diagnostics for speech interruptions or unexpected output.

B. Braille

• Driver-specific configuration and troubleshooting options.
• Advanced detection or connection behaviour.
• Braille input and output processing.
• Device-specific workarounds.
• Diagnostic information relevant to braille performance.

C. Accessibility APIs and application compatibility

• UI Automation and other accessibility API behaviours.
• Application-specific compatibility workarounds.
• Focus tracking and event-processing behaviour.
• Experimental or transitional compatibility features.
• Configuration relevant to troubleshooting problematic applications.

D. Browse mode, navigation and text processing

• Caret movement and event-handling parameters.
• Advanced browse-mode behaviours.
• Text interpretation and speech processing.
• Unicode-related behaviour.
• Settings useful for diagnosing unusual navigation problems.

E. Development, experimentation and diagnostics

• Feature flags and experimental implementations.
• Targeted logging and diagnostic configurations.
• Temporary workarounds being evaluated by developers.
• Settings relevant to reproducing bugs.
• Configuration changes that may help compare different implementations.

These are areas for investigation, not a verified list of settings missing from NVDA's current interface. Many already have controls in the ordinary or Advanced settings panels.

I would especially welcome contributions from developers who understand NVDA's configuration specification and can identify actual examples of configuration keys that are not currently reachable through the graphical interface.

For each candidate, it would be useful to establish:

1. The configuration key and its purpose.
2. Whether it is already accessible elsewhere.
3. The specific user or developer need it addresses.
4. Whether the setting is stable, experimental, deprecated or internal.
5. The risks of modifying it.
6. Whether it should be exposed in ordinary settings, an advanced manager, or nowhere.
7. Whether it can be modified safely without restarting NVDA.

Without this exercise, we risk either proposing an editor without a demonstrated need or rejecting one without properly examining the potential use cases.

4. Should every configurable setting be officially supported?

I think this is probably the most important question.

The closing comment on #6788 raises the concern that exposing hidden configuration items would encourage their use and create an expectation of support.

That is understandable. Once users discover an option, some may reasonably expect it to keep working across releases.

But does exposing a configuration value necessarily mean committing to support it indefinitely?

Could we instead distinguish between several categories?

Stable configuration: Settings intended for regular use, documented and supported through the ordinary interface.

Advanced supported configuration: Settings intended for specialised use, with documented behaviour and reasonable compatibility expectations, but not necessarily appropriate for the main settings dialog.

Experimental configuration: Options provided for testing or feedback, explicitly subject to change or removal.

Internal configuration: Implementation details that should remain outside a public editor, or perhaps be visible only for inspection and diagnostics.

Sensitive configuration: Settings whose modification presents unacceptable security, accessibility or recovery risks and which should not be editable through the manager.

Such a classification would require engineering judgement and maintenance. It would not magically eliminate support obligations. But it might provide a more transparent boundary than simply treating every non-GUI option as something users should not be encouraged to access.

I am also curious whether the existence of an advanced interface could actually reduce some support difficulties by making configuration changes easier to inspect, reverse and reproduce.

5. How might an advanced configuration manager work?

Derek's original proposal was already quite thoughtful. It envisaged a searchable list of configuration keys and their values, appropriate editing controls, and the ability to remove entries.

I think that remains a useful foundation, although the design would need to reflect how NVDA has evolved since 2017.

Some possibilities worth discussing:

Discoverability and navigation

• A searchable list of approved configuration entries.
• Filtering by category, keyword, configuration profile or status.
• Clear indication of default and modified values.
• Descriptions explaining what each option does.
• Links to relevant documentation or GitHub discussions.
• Keyboard and braille-friendly navigation.
• An option to inspect all available entries without enabling editing.

Editing and validation

• Appropriate controls for different value types: checkboxes, edit fields, numeric controls and selection lists.
• Validation against configuration specifications.
• Clear warnings before changing high-risk settings.
• Indication of whether changes take effect immediately or require a restart.
• Detection of settings that are deprecated or no longer recognised.
• Restrictions on editing internal or security-sensitive values.

Recovery and reversibility

This, to me, is absolutely essential.

• Restore the default value of an individual setting.
• Review changes before applying them.
• Export a record of modifications.
• Provide a straightforward way to undo recent changes.
• Back up the relevant configuration before modifying it.
• Recover from configurations that prevent normal NVDA operation.
• Avoid making changes that could leave users without accessible speech or braille feedback.

I would be particularly interested in whether a safe testing mode could be implemented, in which changes are temporary until explicitly saved.

Configuration profiles

Another interesting possibility is integration with NVDA's configuration profiles.

Could users inspect the effective value of a setting, determine whether it comes from the default configuration or a particular profile, and remove an override without editing files manually?

This was already part of the discussion in the original issue, where the possibility of removing unused configuration keys from profiles was raised.

Such functionality might be useful independently of whether we eventually support a broader advanced editor.

Accessibility of the manager itself

Any proposed manager should be fully accessible from the beginning.

I would favour a conventional NVDA dialog with predictable keyboard navigation, meaningful control labels, searchable entries and clear announcements of changes.

A powerful advanced interface is not especially useful if operating it is unnecessarily complicated.

6. What about security, performance and maintenance?

I don't want to minimise these issues.

An unrestricted editor could create genuine problems:

• Users could accidentally disable or disrupt essential accessibility functionality.
• Certain combinations of settings might behave unpredictably.
• Internal configuration structures could change between releases.
• Add-ons might introduce configuration entries with different assumptions.
• Developers could face additional support and compatibility expectations.
• A general-purpose editor might encourage users to rely on experimental workarounds rather than reporting underlying bugs.

However, these concerns also suggest possible design requirements.

We could limit editing to explicitly approved configuration entries, provide risk classifications, validate values, prevent unsafe combinations and make recovery straightforward.

An editor might initially support only a small selection of advanced configurations rather than attempting to expose the complete configuration system.

An even smaller first step could be a read-only configuration inspector that helps users and developers understand what is currently configured, without permitting changes.

This would allow us to investigate the usefulness of the idea before committing to its more complicated aspects.

There is also an important security boundary: a configuration manager should not provide an alternative route around secure mode, administrator restrictions or other deliberate protections.

7. Why not just improve the existing settings dialog?

I agree that the existing dialog should continue to improve. Important, stable and commonly used settings should be accessible through it.

But I am not convinced that putting every potentially useful setting there would necessarily make NVDA easier to use.

There are trade-offs in either direction.

An increasingly large settings interface can become difficult to navigate, while hiding every specialised option can make troubleshooting and customisation unnecessarily complicated.

Perhaps the better question is not which of these approaches we should choose, but whether they can serve different purposes.

The main settings dialog could remain the curated, stable and recommended interface.

An advanced configuration manager could serve specialised users and developers, with appropriate restrictions and explicitly different expectations.

A useful design principle might be that settings with sufficiently widespread and stable use should eventually graduate from the advanced interface into the ordinary settings dialog.

Conversely, experimental settings could be removed when their purpose has been fulfilled.

This could make advanced configuration part of a deliberate development process rather than a permanent collection of obscure options.

8. Could this be useful for NVDA development itself?

One possibility I find especially interesting is the relationship between advanced configuration and testing.

NVDA already uses advanced settings and feature flags in some areas. Developers sometimes need users to test particular behaviours or compare implementations.

Could a configuration manager make that process more systematic?

For example, an issue report could identify the relevant configuration options and their current values. A developer could recommend a temporary change, and the user could test it without manually modifying configuration files.

A diagnostic report might include selected configuration metadata, subject to privacy safeguards.

For experimental features, a manager could also explain what an option is intended to test and provide a link to the associated issue or documentation.

Of course, this should not become a substitute for fixing underlying defects. Nor should experimental settings be treated as permanent solutions.

But it might make certain kinds of collaboration between developers and experienced users easier.

9. Is there still community interest, and would anyone work on it?

This is something I would genuinely like to find out.

The original issue attracted interest in 2017, including discussion about where the editor should be located, who should use it and how dangerous changes could be prevented.

A great deal has changed in NVDA since then, so I don't think we should assume that the original implementation is still appropriate.

Equally, I don't think the absence of an implementation over the intervening years necessarily demonstrates that the idea is no longer useful.

I would be interested in hearing from:

• Users who have encountered situations where an inaccessible configuration option created difficulties.
• Developers familiar with NVDA's configuration system and its limitations.
• Add-on authors who have developed interfaces for specialised settings.
• People involved in testing experimental features or investigating difficult bugs.
• Contributors interested in designing or implementing a prototype.
• NV Access, particularly regarding what support and maintenance boundaries would make such an approach acceptable.

If there is sufficient interest, perhaps the first practical contribution could be an inventory of potentially relevant configurations, followed by a narrowly scoped proof of concept.

10. Questions for the community

I'd particularly appreciate thoughts on the following.

1. Need: Have you ever needed to inspect or modify an NVDA configuration that was unavailable through the settings interface? What was the situation?

2. Inventory: Which actual configuration keys would justify inclusion? Could we compile a verified list rather than relying on hypothetical examples?

3. Scope: Should an advanced manager expose only approved settings, or should experienced users also have read-only access to a broader configuration inventory?

4. Support: Is it possible to distinguish between exposing an option and committing to support its behaviour indefinitely? If so, how should that distinction be communicated?

5. Design: Would a Firefox-style searchable configuration editor be useful, or would a smaller, curated advanced settings interface be more appropriate?

6. Safety: What safeguards are essential, particularly given that NVDA users depend on the software to recover from problems?

7. Profiles: Would better inspection and management of configuration profiles be a more useful starting point?

8. Development: Could the manager provide meaningful benefits for debugging, feature testing and reproducing issues?

9. Implementation: Is anyone interested in developing a prototype, or contributing to the configuration inventory, design or testing?

10. Project direction: What would NV Access consider acceptable criteria for an advanced configuration interface, and are there technical or architectural reasons why even a restricted implementation would be undesirable?

Closing thoughts

I don't think the answer should automatically be to expose every hidden setting. There are good reasons why some configuration options remain internal, and NVDA's reliability must remain a priority.

But I also think there is a meaningful difference between discouraging unsafe configuration changes and making advanced functionality inaccessible altogether.

For a screen reader used across so many different environments, the ability to customise, experiment, troubleshoot and recover independently is not a trivial consideration.

The original issue may have been closed, but I hope the broader design question is still open.

I would much rather see us establish what the real needs are, examine the technical limitations, and decide collectively whether a safe and maintainable approach is possible.

Even if the eventual conclusion is that NVDA should not have an advanced configuration manager, I think that conclusion would be much stronger if it emerged from an informed discussion of actual use cases and implementation trade-offs rather than simply assuming the two alternatives are mutually exclusive.

References

• Original proposal: Implement an Advanced configuration editor for NVDA #6788
• NVDA technical design overview: https://github.com/nvaccess/nvda/blob/master/projectDocs/design/technicalDesignOverview.md
• NVDA user guide: https://download.nvaccess.org/releases/beta/documentation/en/userGuide.html
• Firefox configuration editor: https://support.mozilla.org/en-US/kb/about-config-editor-firefox
• Firefox advanced customisation and support limitations: https://support.mozilla.org/en-US/kb/firefox-advanced-customization-and-configuration
• Chrome flags documentation: https://developer.chrome.com/blog/browser-flags
• Related NVDA discussion about settings discoverability: Add links or key information to the settings screens? #20283

[Qchristensen]

Hi @kaveinthran, firstly, thanks for taking the time to share your feedback!

This is very long, vague and abstract. Questioning closing an issue is perfectly valid WHERE you can demonstrate there is still a genuine screen-reader need going unmet. Equally proposing discussion on a new idea is also quite valid, but again, towards meeting a specific need. Whether that need is "This program is not accessible", "I think we could do this feature better" or "I need to do XYZ and it would be great if NVDA was more efficient at it". In this case, you've mentioned broad categories, but not specifics - for instance, you mentioned things like how essential it is to be able to revert settings - great - which settings that you can't already do? If something particular, like resetting the speech dictionary, let's create an issue for that (I think there already is one), if you have an idea for how it could be possible to revert EVERY setting at a granular level, let's have a discussion about that specific thing. The same for "braille", "speech" and the other general things.

In the case of the advanced configuration manager proposal, that was first raised in 2017. In NVDA 2019.1, we introduced the Advanced settings panel. This arguably covers most of the options which might be useful in the originally proposed advanced configuration editor and potentially makes the idea redundant. If that isn't the case - no-one had raised it until now (and it seems not out of need, only by being prompted by the issue finally being closed).

The original proposal has been uncommented on since that time - which to me seems to indicate that the advanced settings panel does indeed meet the original need, as no-one has since asked for anything similar - either there or via any other channel that I recall seeing.

As we noted when closing the issue today, "we don't want to encourage/support hidden config items. Instead we should try to improve the existing settings dialog". Indeed, if there are any NVDA settings options which DON'T have an existing option in the existing dialog, AND which you have a genuine use case to change, please do raise an issue for that specific thing.

I know this is a discussion and not an issue, but I'm still looking for what is the problem you are trying to solve here?

[kaveinthran]

@Qchristensen thanks for taking the time to reply the discussion.
I agree that most of my suggestions here are very abstract, and admittedly very long, sorry for that.
I am spesifically not suggesting anything on myself, as in deed I don't know what other parameters that are available in code level that's not exposed to end-users.
and, I created the discussion so that I can hear from others if in deed it would be useful to have the advance configuration manager to enable granular tinkering of the screen reader.
Agreed that there's no discussion for about 9 years in this topic. Partly, it can be due to the large pull of NVDA issues that are available, and it also can be due to not having any need for this feature.
This second point is worth testing, hence I created the discussion to hear from other contributors.
thanks

[cary-rowen]

For screen reader users, the learning curve for NVDA is not low. I don't agree with this feature. I believe advanced users can always troubleshoot or diagnose issues using their own expertise, but for beginner users, even with an advanced settings manager or whatever else, they would still be completely clueless. NVAccess has limited manpower, and the original issue hasn't had any activity for a long time, so I don't think there's anything wrong with closing that original issue.