JAWS Scripts For Discord
Doug Lee
Last Revised January, 2022
This document describes the scripts for Discord and provides
tips for using this application with JAWS.
This document can be opened from within the application via a double press
of JAWSKey+F1 (or Insert+F1)
when the scripts are running.
These scripts are written for both the Discord Windows app and the web client that can be run from
http://discord.com/app.
The scripts are more often tested against the Windows app, however.
Warning:
Discord is an evolving application and is sometimes subject to sudden and significant change. As
a result, the commands and behaviors supported by and documented for these scripts may also be
subject to change or failure without warning if a change in Discord causes scripts to fail.
Table of Contents
System Requirements For JAWS Users
In addition to any system requirements for the application, the following
apply for JAWS users:
- The workstation should be running Windows 10.
- JAWS 17.0 or later should be used. The scripts will not
work with or install into JAWS versions older than 17.0.
JAWS versions older than 2019 have not been carefully tested.
Script Installation Instructions
To install these scripts on a new system:
- Load JAWS if this has not already been done. This will require
administrative privileges on the computer.
- Run JAWS as the user for whom the scripts are to be installed.
This and the following steps must be performed for each user of the computer
who will be using JAWS with these scripts.
- Download and run, or run directly, the installer for these scripts; and follow the on-screen
directions. Be sure to install the scripts in the currently running
JAWS version if a JAWS version list is presented.
- To verify successful installation, type Insert+Q from
within the application. Part of the JAWS spoken response should be a
revision number. If you do not hear a revision number, the scripts are
not correctly loaded.
In some cases, restarting JAWS may fix this issue.
Key Sequences
These scripts incorporate commands that consist of sequences of keystrokes, all beginning with a common prefix, or "command keystroke."
This approach allows many script commands without the risk of conflicting with application keystrokes.
See the "Multi-Key Command Sequences" section of the "Common Script Elements" document for further details, including
how to explore the available script commands (similar to exploring a menu system),
and how to change the Command keystroke if necessary.
By default, the Command keystroke for these scripts is [.
This document may refer to this keystroke as [ or Command;
so, for example, [ Tab and Command Tab both refer to typing the prefix keystroke, then separately the Tab key.
Some sequences may consist of more than two keystrokes, or "levels"; for example, [ d r would refer to typing [, then d, then finally r.
Native Discord Accessibility Features
Discord itself includes various accessibility features as of this writing. Chief among these is a
large set of keyboard shortcuts, documented on the Discord site under
"Windows Discord hotkeys."
Note that Ctrl+Tab and Ctrl+Shift+Tab cycle forward and backward through your servers as well.
Script Commands and Features
These scripts provide the following general commands beyond those provided by the application itself:
- [ S moves to the server tree and activates forms mode if necessary.
The Home link and links to any new items appear at the top of this tree.
- [ D presses the Disconnect button when available on screen.
If more than one is present, this sequence clicks the last one.
This can happen when the user has turned on and back off the camera, in which case there can be two Disconnect buttons that do the same thing (tested in Discord 0.0308 as updated on Monday, October 5, 2020).
- [ B brings up a list of buttons for activation.
This is similar but not identical to the built-in JAWS JAWSKey+Ctrl+B command for listing buttons in an HTML document:
- [ B removes duplicate buttons that are actually names of chat participants.
- [ B activates (presses) the chosen button, whereas JAWSKey+Ctrl+B merely moves the virtual cursor to it.
- [ P reports, when visible on screen, the ping time between this Discord client and the server.
This will only be on screen when you are in a voice channel.
- JAWSKey+Q, along with announcing the active configuration name, will announce the revision number of these scripts.
- Insert+F1, typed twice in quick succession, opens this document in the default browser.
These scripts provide three sets of commands for efficiently reading direct and text chat messages.
The following commands keep track of a current position among messages that will be remembered until changed or until JAWS is restarted or the current Discord window is replaced with another that supports chat navigation.
A position is remembered separately for each Discord chat navigated with this system.
- For those (like this author) who like to keep hands on the home row on a QWERTY keyboard, use the [ key followed by any sequence of H for first available message, J for previous message,
K for the current message, L for the next message, and ; for the last available message.
Typing K twice quickly spells the content of the current message.
Additionally, Shift+H moves to the "Unread" marker in the message history when visible, and Shift+K moves the virtual cursor to the current message, which is useful for messages containing buttons such
as for playing media.
- For those who prefer arrow keys, equivalent navigations are provided: Use the [ key followed by any combination of Home for the first message, Left for the previous message, Numpad5
for the current message, Right for the next message, and End for the last available message.
Shift+Home is the "jump to Unread marker" command in this set, and Shift+Numpad5 moves the virtual cursor to the current message such as for handling media buttons.
Typing Numpad5 twice quickly spells the content of the current message.
This final set of commands reads messages without altering JAWS' idea of which message is "current":
- [ followed by digits will read recent messages:
1 reads the most recent, 2 the next most recent, 9 the ninth most recent, etc.; and [ 0 reads the tenth most recent message.
As with the commands listed above, use Esc when done reading.
Note: These message navigation commands are limited to visible messages due to the way Discord is written; therefore, for example, [ 1 may read the latest displayed message rather than the latest
posted message if the latest post is currently not shown on screen.
Using these commands to read messages near the start or end of the visible messages often will, though, scroll more messages onto the screen automatically.
These scripts also provide the following features:
- Automatic announcement of messages arriving in the currently displayed chat area.
- Indication of buttons that are pressed or selected.
- Better naming for several buttons.
This includes the buttons on video controls within a chat message containing a playable file.
- Identification of a user's assigned roles in the Roles list in a user's modal information dialog popup.
This makes it possible to determine who on a server is an admin, moderator, etc.
- JAWSKey+T, the
SayWindowTitle
JAWS command, says the name of the application and the name of the active chat instead of just saying "Dialog" in many cases.
It may also include any of the following as applicable, in this order:
- In a private channel, the online status of the other participant if displayed.
- For any pending event badges on screen, the name and count from the badge; i.e., a short list of who's said how many things you haven't seen yet.
Counts may not be available as of November 6, 2020.
- Indications of whether the Mute or Deafen switches are currently on.
- The primary screen section name when possible, such as the name of the server shown or "Private channels."
- If you are in a voice channel, the name of that channel including its server name.
- The text of any on-screen notices or alerts, such as the alert that may appear when Discord is not detecting sound on the active microphone.
Alerts announced here may also include success notices for actions and the "Update Ready!" notice when a Discord update is available.
Known Issues
The following issues are known and may be encountered during use of the application with these JAWS scripts.
These issues may be fixed in a future update to the scripts or to the application itself.
Pending event counts may be out of date from time to time in the JAWS virtual view of the Discord window. Typing the screen refresh command, Insert+Esc, will fix this.
When announcing the "Roles" list control in a user information popup dialog,
JAWS may say an extra word like "modal" or "vertical" between "listbox" and the list of roles for a user.
Braille support is not well tested and is likely incomplete.
Revision History
This is the revision history of these scripts, most recent revision first:
Revision 114, January 31, 2022, tested against application version 1.0.9003
Note: This is a significant revision, and installing it correctly requires use of the script
installer rather than just the BX Update approach, for those who frequently use that.
For those who must install the scripts without using the installer, note that there are additions to the
discord_directives.txt
file in this revision.
Finally, note that some commands are removed from this revision as explained below.
Changes:
- The scripts now turn off the JAWS virtual cursor, as is common to do for Electron-based apps such as Discord.
This change permits navigation of message lists, channel lists, etc. with arrows.
It also permits JAWS users to take direct advantage of the accessibility features that Discord has been
incorporating, including keystrokes and specific formats of messages and lists.
You may still activate the virtual cursor by using the Insert+Z JAWS command as necessary.
The virtual cursor is still useful in at least the following situations:
- Setup screens.
- The Home screen, to reach the summary at the bottom of who is in what voice channel on which server.
- The key sequences [ N and Shift+N duplicate the Discord-native keystrokes
F6 and Shift+F6 for moving forward and backward among screen regions. This is for those
whose keyboards do not conveniently support sending function keys such as F6.
- The command sequences for moving to the top of the voice and text categories in the channel list,
[ V and [ C, are removed. These commands relied on the virtual cursor being active, and that
cursor is now turned off by the scripts. Also, these commands relied on default Discord channel naming and
organization schemes, which many server owners choose to replace.
The recommended way to find channels is now to use the new sequence [ N, or the Discord-native
equivalent F6, to move to the channel list; then use Up and Down arrows to
move among channels.
Text and voice channels may be mixed, even within the same category, according to server owner preferences.
- JAWS announces user statuses like "offline" during navigation through the DM list on the Home screen with
the virtual cursor off.
- The auto-complete script code for mentions etc. is removed as Discord happily made this code unnecessary.
- Incoming messages should again announce correctly. For a while, JAWS just announced a colon for an
incoming message.
This change involved a rewrite of how to determine the text of an incoming message, as the structure of
messages changed since initial script publication.
- Arrows in the Mentions tree under Inbox read messages without also repeating numerous messages that are
not in focus.
- Arrows in Inbox > Unreads announce messages instead of just saying "Jump" for a message.
- Messages no longer repeat during chat message navigation when an end of the list is encountered.
- The sound produced on hitting an end of the message list is changed from a system beep to a short click.
Revision 96, January 27, 2021, tested against application version 0.0.308 as updated November 6, 2020
- The JAWS
LeftMouseButton
and RightMouseButton
commands, when issued while the PC or virtual cursor is active, will click at the current virtual cursor position when possible.
This may serve to help with clicking items that are otherwise hard to click.
- Removed the [ Space sequence for clicking buttons, as it no longer seems necessary and is effectively replaced with the above enhancement, with the added benefit of including right-click support as well as
left-click support.
- Removed the special support for the system tray menu, as Discord now natively permits arrows and Enter to work there as expected.
This also removes extra beeps during navigation through context menus such as for a Discord user in a voice channel.
- Updated the autocomplete documentation to mention the need to escape arrows to make them move among options if the JAWS "auto forms mode" behavior is in effect.
- Very minor code update to improve support for JAWS 2021.
Revision 92, December 08, 2020, tested against application version 0.0.308 as updated November 6, 2020
- Mention autocomplete support works in the Discord update from December 7, 2020.
This Discord update improved assistive technology support by replacing non-standard MSAA element roles with standard ones; the scripts just needed an update to adjust to the change.
- Mention autocomplete support is skipped when the virtual cursor is active, so those who prefer the virtual-cursor methods of handling mentions can still do things that way.
Revision 90, November 29, 2020, tested against application version 0.0.308 as updated November 6, 2020
- The system tray context menu is usable: Use Up and Down arrows to select an item and Enter to execute it.
Note that it is still necessary to Alt+Tab to exit the menu.
- JAWS announces autocomplete items when an autocomplete box appears and when the user arrows through its options.
- System messages and messages that contain mentions should read correctly via the chat navigation system.
- When using the chat navigation system, commands that read the current message will spell its content if typed twice quickly.
For example, typing [ and then K twice quickly will spell the current message.
- Locked channels will say "locked."
Note that this does not necessarily mean you are not allowed into the channel; it means the channel is restricted.
- In the November 26, 2020 Discord update, the chat navigation system no longer includes blank entries at the start and end of the visible message range.
Revision 78, November 07, 2020, tested against application version 0.0.308 as updated November 6, 2020
- [ S moves to the server tree and activates forms mode if necessary.
The Home link and links to any new items appear at the top of this tree.
- Fixed Insert+T's ability to report screens with unread content for Discord versions released starting in early November, 2020..
- Incoming chat messages in the current window speak again as they did in older Discord versions.
This fix was actually slipped into the previous (revision 74) release but not announced there.
Revision 74, November 02, 2020, tested against application version 0.0.308 as updated October 30, 2020
This release is largely aimed at addressing some problems that appeared in the Friday, October 30, 2020 Discord release.
This Discord version can be identified by the Home link being part of, rather than above, the server tree.
There are also other features that are not related to the Discord update, as listed below.
- Incoming messages in the current window speak as they did before the October 30 Discord update.
- The chat navigation commands work again.
- The sequence [ Space, when the cursor is on a server tree item and forms mode is active, will activate that server.
This feature is included as a workaround to Discord having stopped doing this on Enter in this Discord update, though the issue is also being addressed in Discord itself in the near future according to reports.
- There is a command for listing buttons for activation.
- The "Control volume" button for a stream is named "Mute/Unmute" because that is the function of the button.
- The command sequence [ O for moving to the Home link is removed, as the Home link is now a graphic within and at the top of, rather than outside and above, the server tree.
- JAWSKey+T includes more warning text, such as when a stream is unable to include audio.
Revision 68, October 25, 2020, tested against application version 0.0.308 as updated October 12, 2020
- These scripts load under more conditions, as Discord seems sometimes to present itself to JAWS differently ("Discord," "discord.com", etc.).
These scripts also load for the http://discord.com/app web Discord app.
- Incoming chat messages in the current window read automatically.
- The chat reading system finally works and has a new command structure.
This system includes means to read chats sequentially while remembering the current position in all available chats at once, means to check the most recent (visible) chat messages without altering position, a way to jump to
the marker above the first unread chat according to Discord itself, and a command for moving the virtual cursor to just above the text of the current chat message, such as in order to handle buttons for playing media within a
chat message.
- When the JAWS virtual cursor is active in a user's modal popup information dialog and it crosses the Roles list, JAWS will announce any roles listed for the user.
This makes it possible to determine who on a server is an admin, moderator, etc.
- [ D presses the Disconnect button when available on screen.
- [ O moves to the Home link.
- The JAWS
SayWindowTitle
command, Insert+T, will include several new items as applicable.
- Added the [ C and [ V commands for moving to the Text chat and Voice channel categories.
(These were then removed in November, 2021 because they were only effective with
the virtual cursor active and on servers where the channel organization was not altered from Discord
defaults.)
- Buttons in video controls within a chat message are named rather than being "Unlabeled."
- Stopped accidentally labeling as "Close" a "Dismiss" button that is already named properly by Discord itself.
- The installer contains version and product information visible from the Details tab in Windows Explorer, to better identify its contents. This update is being applied to all projects.
- A "directives" text file is included that provides information on how to install this set of scripts manually.
See "Handling Directives Files" in the "Common Script Elements" document for further information.
- For those who need to change the Command key, the left bracket ([) by default, the system is significantly improved, so that you need not type the key or key combination out as a name or string of key names. You may
edit the keystroke names before accepting them, but JAWS will type them out for you now.
The system is documented in more detail in the Multi-Key Command Sequence section of my Common Script Elements page.
- Keystroke names in this document are more consistent, and there are other minor documentation improvements.
- Fixed a bug that could cause some localized strings not to be spoken where expected.
- Many more internal code updates not listed individually here.
Revision 16, May 9, 2019, tested against application version 0.0.305
Initial release for Aleric to test:
- The Insert+T fix appears to work.
- [ Space clicks badges and buttons that otherwise don't respond to keystrokes.
- Some Close buttons are named properly.
- Pressed buttons, like Member List, report the "pressed" state as appropriate.
- Chat commands exist but say "Not yet implemented."