Add an option to use Word's native math speech in Word documents by RyanMcCleary · Pull Request #19700 · nvaccess/nvda

RyanMcCleary · 2026-02-26T03:52:45Z

Link to issue number:

Closes #19670

Summary of the issue:

A bug in Microsoft Word is causing math objects to be spoken inconsistently, sometimes using MathCAT and at other times using Word's native math speech.

Description of user facing changes:

An option is added to the math settings panel to use native math speech while in Word. When checked, MathCAT is disabled while in Word and re-enabled when another application gains focus.

Description of developer facing changes:

N/A

Description of development approach:

Handlers were added in winword.py for the gainFocus, loseFocus, and terminate events that disable and re-enable MathCAT.
Two new functions were added to mathPres/__init__.py: disable and enable, which save and restore the three global provider objects.

Testing strategy:

I set MathCAT's rate to the minimum value and pause factor to the maximum value to make it easy to tell if math is being spoken using word's native math or MathCAT. After that, I tested the following:

Opened a word document containing math, navigated through it, and noted that MathCAT was being used.
After checking "Use Word's native math speech in Word documents" in the math settings panel and returning to the word document, I observed the math being read at a faster rate with no long pauses, indicating that word's native math was being used.
To check that the behavior in applications other than word is unchanged, I opened a webpage containing MathML in chrome, navigated through it, and MathCAT was being used. I then switched back and forth between word and Chrome again, and consistently saw that MathCAT was being used in Chrome and native math in Word.

Known issues with pull request:

No known issues.

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.

… appmodule

Copilot

Pull request overview

This pull request addresses issue #19670 where math speech in Microsoft Word was inconsistently switching between MathCAT and Word's native math speech. The solution adds a new user option to disable MathCAT while in Word, allowing Word's native math speech to be used instead.

Changes:

Added disable() and enable() functions to mathPres/__init__.py to save and restore math presentation providers
Added event handlers in winword.py to disable/enable math providers when Word gains/loses focus
Added a new configuration option and UI checkbox in the Math settings panel
Added user documentation for the new option

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
source/mathPres/init.py	Added disable() and enable() functions to manage math presentation providers with proper state guards
source/appModules/winword.py	Added event handlers to disable MathCAT when Word gains focus and re-enable when focus is lost or app terminates
source/config/configSpec.py	Added useWordNativeMath boolean configuration option under math.other section
source/gui/settingsDialogs.py	Added checkbox in Math settings panel to control the new option
user_docs/en/userGuide.md	Added documentation for the new option in the Math settings section

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

seanbudd

Thanks

Co-authored-by: Sean Budd <seanbudd123@gmail.com>

…word-native-math

seanbudd

Nice, thanks @RyanMcCleary

CyrilleB79 · 2026-04-02T15:20:59Z

This option is called "Use native math speech in Word and Outlook" and is in the Speech section.

Though, the user guide description of this options is:

When enabled, NVDA uses Microsoft Word's built-in math presentation (speech, braille, and interaction) instead of MathCAT when reading and interacting with equations in Word documents.

If the option impacts speech, braille and interaction/navigation, it should be renamed and put out of the speech section.
If instead it only impacts speech, the UG should be reworded.

@RyanMcCleary which one is true?

RyanMcCleary · 2026-04-02T15:33:43Z

If the option impacts speech, braille and interaction/navigation, it should be renamed and put out of the speech section.
If instead it only impacts speech, the UG should be reworded.

@RyanMcCleary which one is true?

It's the former: the option does impact speech, braille and interaction/navigation.

seanbudd · 2026-04-07T01:02:58Z

Can a new issue or PR be opened to fix this?

RyanMcCleary · 2026-04-07T01:09:52Z

Sure, do we want this fix to go into 2026.1?

seanbudd · 2026-04-07T01:12:30Z

yes please

RyanMcCleary added 4 commits February 22, 2026 17:06

Add useWordNativeMath option

dfba814

Merge remote-tracking branch 'upstream/beta' into word-native-math

f43cacc

Add disable and enable functions in mathPres and call them in winword…

add9c94

… appmodule

Update user docs

322c097

RyanMcCleary marked this pull request as ready for review February 26, 2026 04:05

RyanMcCleary requested review from a team as code owners February 26, 2026 04:05

RyanMcCleary requested review from Qchristensen, Copilot and seanbudd February 26, 2026 04:05

Copilot started reviewing on behalf of RyanMcCleary February 26, 2026 04:05 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

Comment thread user_docs/en/userGuide.md Outdated

Comment thread source/config/configSpec.py Outdated

RyanMcCleary and others added 2 commits February 25, 2026 23:20

Update user_docs/en/userGuide.md

dd153a8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update source/config/configSpec.py

1cf3e69

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

seanbudd added the conceptApproved Similar 'triaged' for issues, PR accepted in theory, implementation needs review. label Feb 26, 2026

seanbudd reviewed Feb 26, 2026

View reviewed changes

Comment thread source/gui/settingsDialogs.py Outdated

Comment thread source/config/configSpec.py Outdated

Comment thread source/mathPres/__init__.py Outdated

Comment thread source/gui/settingsDialogs.py Outdated

Comment thread user_docs/en/userGuide.md Outdated

seanbudd marked this pull request as draft February 26, 2026 06:28

RyanMcCleary and others added 8 commits February 26, 2026 01:44

Update source/gui/settingsDialogs.py

d182e53

Co-authored-by: Sean Budd <seanbudd123@gmail.com>

Update source/config/configSpec.py

bfb55d6

Co-authored-by: Sean Budd <seanbudd123@gmail.com>

Update source/gui/settingsDialogs.py

e365d4a

Co-authored-by: Sean Budd <seanbudd123@gmail.com>

Fix user docs entry per review

774d0d0

Terminate the mathPres module instead of disabling it temporarily

dfe1ebb

Merge branch 'word-native-math' of github.com:RyanMcCleary/nvda into …

359ae02

…word-native-math

Updated translation comment

c3daffa

Fixed configSpec comment

cd1b3c7

RyanMcCleary marked this pull request as ready for review February 26, 2026 07:24

seanbudd approved these changes Feb 26, 2026

View reviewed changes

seanbudd added this to the 2026.1 milestone Feb 26, 2026

seanbudd merged commit 67ad1ff into nvaccess:beta Feb 26, 2026
6 checks passed

seanbudd mentioned this pull request Feb 27, 2026

MathCAT not working for Vietnamese user? #19598

Closed

CyrilleB79 mentioned this pull request Feb 27, 2026

MathCAT speech should not happen inside of a Word math object #19670

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add an option to use Word's native math speech in Word documents#19700

Add an option to use Word's native math speech in Word documents#19700
seanbudd merged 14 commits into
nvaccess:betafrom
RyanMcCleary:word-native-math

RyanMcCleary commented Feb 26, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

seanbudd left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanbudd left a comment

Uh oh!

Uh oh!

CyrilleB79 commented Apr 2, 2026

Uh oh!

RyanMcCleary commented Apr 2, 2026

Uh oh!

seanbudd commented Apr 7, 2026

Uh oh!

RyanMcCleary commented Apr 7, 2026

Uh oh!

seanbudd commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

RyanMcCleary commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Link to issue number:

Summary of the issue:

Description of user facing changes:

Description of developer facing changes:

Description of development approach:

Testing strategy:

Known issues with pull request:

Code Review Checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

seanbudd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seanbudd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CyrilleB79 commented Apr 2, 2026

Uh oh!

RyanMcCleary commented Apr 2, 2026

Uh oh!

seanbudd commented Apr 7, 2026

Uh oh!

RyanMcCleary commented Apr 7, 2026

Uh oh!

seanbudd commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

RyanMcCleary commented Feb 26, 2026 •

edited

Loading

seanbudd left a comment •

edited

Loading