Accessibility testing - musescore/MuseScore GitHub Wiki

• Screen reader support
  • Popular screen readers
  • Screen reader modifier key
  • JAWS and NVDA
  • Development
  • Controlling speech output
  • Accessibility Tree
• 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.

MuseScore 4's new accessibility system provides a good level of support for all of these screen readers. MuseScore 3 only supported NVDA, but support was excellent, so it's worth trying MuseScore 3 with NVDA to get an idea for the features that are still missing in MuseScore 4.

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/Return	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

• On laptops and small keyboards, the fn modifier may be required to simulate missing keys:
  • Insert is usually fn+Delete or fn+Return.
  • Page Up, Page Down, Home and End are usually fn and Up, Down, Left or Right respectively.
• On Linux, Super means either the Windows or Cmd key depending on whether you have a Windows- or Mac-style keyboard.
• If NVDA's desktop shortcut is installed then you can launch it with Ctrl+Alt+N, otherwise you can set this up manually.

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) that must be pressed in order to send subsequent keystrokes to the screen reader instead of to the focussed application. 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.

Despite Windows having a built-in screen reader (Narrator), the vast majority of blind users still rely on JAWS or NVDA, so it's important that we continue to test with all of these screen readers.

JAWS is a paid product but it has a free demo mode. When you launch JAWS without a license, it will prompt you to restart your computer to use the 40 minute demo mode. However, if you simply ignore the dialog (don't close it) then you can continue using JAWS for a minute or two without restarting, which is enough time to test a feature in MuseScore. JAWS will quit after the minute is up, but you can relaunch it again immediately and use it for another minute (e.g. to test another feature).

If you opted to install NVDA's desktop shortcut then you can launch it with Ctrl+Alt+N. If not, you can set this up manually using the process below. The same process can be used to create a keyboard shortcut for JAWS.

1. Create a shortcut file that points to the NVDA or JAWS executable.
   1. Locate the executable in C:\Program Files.
   2. Right-click on the executable and choose Copy.
   3. Go to your desired location for the shortcut, such as:
      • Desktop
      • Start Menu, just for you: %APPDATA%\Microsoft\Windows\Start Menu\Programs
      • Start Menu, for all users: %ProgramData%\Microsoft\Windows\Start Menu\Programs
   4. Right-click and choose Paste shortcut.
2. Assign a shortcut key to your new shortcut file.
   1. Right click on the shortcut file and choose Properties.
   2. Under the Shortcut tab, use the option to assign a shortcut key, such as:
      • NVDA: Ctrl+Alt+N
      • JAWS: Ctrl+Alt+J.

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).

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.

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

TODO.

TODO.