MuseScore

Table of Contents

Summary
Screen reader support

Popular screen readers
Modifier key
JAWS and NVDA
Development
Controlling speech output
Accessibility Tree

Colors and Contrast

High Contrast themes

Summary

Screen reader support
Colors and Contrast
- High Contrast themes

MuseScore 4 has a completely new UI, and it also has completely new accessibility systems for blind and low vision users, as well as users who experience reduced color perception (color blindness).

Users who are blind rely on screen reader programs to describe what is happening on the screen. See Screen Reader Accessibility in MuseScore 3 (video) for a demonstration of this process in action. If you want to try it yourself, there's a good chance that you have a built-in screen reader installed already, so you just need to press the relevant shortcut key to turn it on.

Screen Reader (platform)	Availability (licensing)	On/off shortcut	Modifier key	Settings shortcut
Orca (Linux GNOME)	Built-in (open source)	`Super`+`Alt`+`S`	`Orca` = `Insert` / `Caps Lock`	`Orca`+`Space` or run `orca --setup`
VoiceOver (macOS)	Built-in (proprietary)	`Cmd`+`F5`	`VO` = `Ctrl`+`Alt/Option` / `Caps Lock`	`VO`+`F8`
Narrator (Windows)	Built-in (proprietary)	`Windows`+`Ctrl`+`Enter`	`Narrator` = `Caps Lock`	`Windows`+`Ctrl`+`N`
NVDA (Windows)	Free (open source)	Off only: `NVDA`+`Q` Toggle speech: `NVDA`+`S`	`NVDA` = `Insert` / `Caps Lock`	`NVDA`+`N`
JAWS (Windows)	Paid (proprietary)	Off only: `JAWS`+`F4`	`JAWS` = `Insert` / `Caps Lock`	`JAWS`+`J`

Modifier key

All screen readers have a special "override" or "escape" modifier key named after themself (VoiceOver's key is abbreviated to just "VO"). This modifier simply refers to an actual key on your keyboard (often Insert or Caps Lock by default) that must be pressed in order to send subsequent keystrokes to the screen reader instead of the application (e.g. to NVDA instead of MuseScore). So when you see NVDA+N in the table above, that actually means to press Insert+N unless you have chosen to use a different key as modifier in NVDA's settings.

All screen readers provide an option to use Caps Lock as the modifier key (Orca and JAWS refer to this setting as "Laptop mode" or "Keyboard layout: Laptop" respectively). If you do lots of testing with different screen readers then you might want to consider using Caps Lock as the modifier for all of them. If you need Caps Lock's regular functionality (i.e. to type capital letters), press it twice in quick succession, or use Shift and a letter key instead. Alternatively, simply turn off the screen reader because the modifier is only active while the screen reader is running.

JAWS and NVDA

Windows' built-in screen reader Narrator has improved dramatically in recent years but most blind users still rely on JAWS or NVDA. It is important that we continue to test with all of these screen readers, particularly NVDA as that was the only screen reader supported in MuseScore 3.

JAWS is a paid product and it's rather expensive so you probably don't want to pay to use it just for testing and development purposes. A free trial is sometimes available, or you can develop with Narrator and NVDA and then ask our blind users to test with JAWS for us.

There isn't a shortcut key to turn on JAWS or NVDA, but you can create one as follows:

Create a shortcut file on your Desktop (or elsewhere) that points to the NVDA or JAWS executable in C:\Program Files.
- The easiest way is to right-click on the executable, choose Copy, and then Paste shortcut in the new location, such as on your Desktop or inside your Start Menu folder (%APPDATA%\Microsoft\Windows\Start Menu\Programs).
Right click on the new shortcut file, choose Properties, and use the option to assign a shortcut key.
- You could use Ctrl+Alt+N for NVDA and Ctrl+Alt+J for JAWS.

Development

See FOSDEM 2020: Accessibility in MuseScore (video) for an overview of accessibility concepts and development practice.

Basically, MuseScore needs to provide screen readers with accurate information about all objects in the UI, including:

UI controls (buttons, checkboxes, radio buttons, combo boxes, etc).
Items within views (list items, tree view items, table cells).
- In particular, items (elements) in the score view (notes, rests, text, symbols, etc).

Controlling speech output

MuseScore doesn't tell the screen reader exactly what to say. Instead, it lets the screen reader know:

What objects are available and how they are related (i.e. the Accessibility Tree).
The name of each object, and the object's description if there is one.
What role each object has (button, text, checkbox, list item, etc.).
What state each object is in (selected or deselected, enabled or disabled, etc.).

Most important of all, MuseScore tells the screen reader which object currently has keyboard focus.

It's up to the screen reader to decide how much of this information it wants to share with the user. The name and role are nearly always spoken (e.g. "Load button" or "Button: Load"). Other information might be shared only if certain conditions are met, like if it has changed since the object last had keyboard focus. The exact output depends on the screen reader and its verbosity settings, which can be adjusted by the user.

On the rare occasion that we do need to tell the screen reader exactly what to say, such as a status message like "Download complete.", this usually involves creating a dummy accessible object with the following properties:

Name: "Download complete." (i.e. the status message itself).
Description: "" (i.e. an empty string).
Role: Text, Item, Label or any silent role.
State: None, Default, or any silent state.

The aim is to get the screen reader to say the name and nothing else, which may require a bit of trial and error with different roles and states until you find values that are not spoken (it may require different roles or states on each platform). In MuseScore 3 it was necessary to make the dummy object an actual UI object, like a invisible button or text label just there for accessibility purposes, but in MuseScore 4 it should be possible to create accessible objects that do not correspond to real objects in the UI.

Accessibility Tree

Accessible UI objects exist in a strict hierarchy where each object has exactly one parent object and zero or more child objects. The root object is either MuseScore's main application window or another dialog, and it has no parent. The accessibility tree must be consistent for accessibility to work, so if Object A identifies Object B as one of its children then Object B must identify Object A as its sole parent. These free tools enable you to explore the accessibility tree to check that parent-child relationships are consistent and refer to the objects you expect.

Accerciser for Linux
Accessibility Insights for Windows

Colors and Contrast

TODO.

High Contrast themes

TODO.

Testing

Manual testing
Automatic testing
- Unit Tests
- Visual Tests

Translation

Compilation

Beyond compiling

Architecture general

Audio

Audio overview

Engraving

References