curiousdannii
Improve screen reader support
I'm totally blind and have been searching for a universal interpreter that's very screen reader accessible on all platforms. This seems like it could work, but there are issues with automatic reading which I hope can be fixed in the near future. For these tests, I'm using the free NVDA screen reader from https://nvaccess.org on Windows 11 24H2 with Firefox 141.
The most annoying issue is the echoing back of typed commands. For example, here's what NVDA tells me while playing Curses after typing the l command to look around.
" > l Attic The attics, full of low beams and awkward angles, begin here in a relatively tidy area which extends north, south and east. The wooden floorboards seem fairly sound, just as well considering how heavy all these teachests are. But the old wiring went years ago, and there's no electric light. A hinged trapdoor in the floor stands open, and light streams in from below. >
edit multi line blank"
There are a couple problems with this command as you can see. First, it lists the command in the output which I find distracting. Second, it always repeats the information about the edit field and that it's blank, though I believe this issue may be NVDA specific and not related to the program. It can be eliminated by putting NVDA into sleep mode, but this introduces another problem. While NVDA is in sleep mode, the automatic output can't be interrupted by typing another command. A possible way to fix this is to change the way Parchment outputs information. It appears it's currently using ARIA live regions, so perhaps switching to assertive mode would fix this by interrupting what's being spoken and forcing the screen reader to immediately begin speaking the new information. Having said that, this might bother some users, so if feasible, consider adding an accessibility settings menu to toggle this behavior. While we're on the subject of an accessibility settings section, consider making my above issue with echoing commands another toggle. I personally don't like it, but some people might. Giving people more choice is always a good thing.
The next issue involves automatic reading of menus. Let's use Curses as the example. I'm going to paste another example of the output, but be aware it's very long. This is what I get after typing help.
" RETURN = read subject Q = resume game Information is available on the following subjects: > Instructions giving some basic information Commands detailing some common commands Credits game credits Release release notes Legal legal disclaimers Inform advertising the compiler Inform Archive and the interactive fiction archive
N = next subject P = previous RETURN = read subject Q = resume game Information is available on the following subjects: > Instructions giving some basic information Commands detailing some common commands Credits game credits Release release notes Legal legal disclaimers Inform advertising the compiler Inform Archive and the interactive fiction archive
Curses N = next subject P = previous RETURN = read subject Q = resume game Information is available on the following subjects: > Instructions giving some basic information Commands detailing some common commands Credits game credits Release release notes Legal legal disclaimers Inform advertising the compiler Inform Archive and the interactive fiction archive
status bar
edit multi line blank
Curses N = next subject P = previous RETURN = read subject Q = resume game Information is available on the following subjects: Credits game credits Release release notes Legal legal disclaimers Inform advertising the compiler Inform Archive and the interactive fiction archive
Curses N = next subject P = previous RETURN = read subject Q = resume game Information is available on the following subjects: > Commands detailing some common commands Credits game credits Release release notes Legal legal disclaimers Inform advertising the compiler Inform Archive and the interactive fiction archive
Curses N = next subject P = previous RETURN = read subject Q = resume game Information is available on the following subjects: Instructions giving some basic information > Commands detailing some common commands Credits game credits Release release notes Legal legal disclaimers Inform advertising the compiler Inform Archive and the interactive fiction archive
edit multi line blank
Basic commands consist either of a verb on its own, or a verb with one or more nouns. For instance, to see where you are type "look". Some verbs can also have more elaborate forms; for instance you could also look at, inside or under something. "Curses" understands about 1200 English words, so most reasonable synonyms are allowed. To pick something up, "take thing" and to drop it again, "drop thing". To see what you have, type "take inventory" or just "inventory". You can move about with commands such as "go west", or just "west" for short. (It is assumed that you are blessed with an excellent sense of direction.) Some commands can act on more than one thing. You can "drop all", which will drop everything (except things you're wearing), for instance. Or if you found a packing case with a number of things in, you could type such things as: remove everything but the blue key get all the coins except ten, twenty and fifty (Containers may also be emptied or emptied into each other.) If you are not explicit enough, sometimes the game can infer what you mean, but at other times it will ask for further details. It might have replied to the first line above by saying (from the yellow packing case) so that you know what has been assumed on your behalf. If there had been two blue keys you might reasonably have meant, it would reply with something like Which do you mean, the blue doorkey or the Blue Moon Agency key? You may either tell it which, or else give up and do something else instead. If you don't mind which key, you can always say something such as: drop a key into the slot and the game will make a sensible choice and tell you what it was. "Curses" sometimes assumes commands which you implicitly make, but always tells you what they are in brackets. For instance: >look up bach in book (first taking the Encyclopaedia of Composers) (putting the tuning fork in the rucksack to make room) "J. S. Bach (1685-1750) had a pet aardvark called Nigel... "it" refers to the last thing manipulated, "him" and "her" to anyone obvious in the room; "pronouns" will tell you what they currently mean, if in doubt. "again" repeats the last command. You can "save", "restore" or "restart" the game at any time, or indeed "quit" or ask for your "score", which also tells the time. "fullscore" or "full" gives a breakdown of the score. As an aide-memoire the command "objects" tells you where you left things you once had, and "places" says where you have been. If you want to check that your copy of the game file is intact (and not, for instance, corrupted by some file-transfer process you used to get it), you can "verify" it. These commands do not take up any game time, and nor does anything the game didn't understand. Some jaundiced players tire of long descriptions of places, and they can type "short" (or "superbrief") to make the game only give short ones. Amnesiac players, on the other hand, may like to use "long" (or "verbose") to give only long ones. Either kind can go back to the usual state of affairs with "normal" (or "brief"). There are also two kinds of inventory: "inventory wide" and "inventory tall". This Advanced story file employs special effects such as bold face names of rooms and a more elaborate status line than usual. Also, less than altogether relevant quotations pop up from time to time. If these effects do not seem to work properly on your machine, or are just downright annoying, they can be turned off with "plain" and on again with "pretty". From time to time you will be told that your score has changed: this can be turned off with "notify off", turned on again with "notify on" or made even more common by "notify full" (which even tells you about scores accruing from visits to places, unusual items discovered and the like). Simple typing mistakes can sometimes be corrected just by typing "oops" followed by the word you had intended to type, so for instance: drop fish in buket oops bucket The game knows several useful abbreviations: i for inventory, ne for northeast (and so on), l for look, g for again, o for oops, x for examine, z for wait (short for "zzz" - sorry about that). You can sometimes enter larger objects you find. You might well be able to get in a tractor, for instance, though driving it around might be harder. From time to time, you will wish to speak to other people. If you only have a single word to say, you could use commands like answer yes say boo to goose (Text in quotation marks is not allowed.) The game will usually guess who you want to talk to if you miss off the name. A better way to talk, which allows more complicated remarks, is to use commands such as goose, boo wine waiter, give me the bill ask professor about turtles though the waiter may have better things to do, and the professor might be quite mad. Some documents may be consulted in this game. For this, try commands such as look up chlorine consult periodic table about argon You can give several commands in a row by use of "then" (or full stops, commas or "and" in some contexts): so, for instance, e, s, get fish then inventory e.e.open door.s There are, of course, many other commands for more specialised circumstances. A final word of warning: cursing is strictly forbidden in this game. [Please press SPACE.]
Parchment 2025.1.14 document 
Basic commands consist either of a verb on its own, or a verb with one or more nouns. For instance, to see where you are type "look". Some verbs can also have more elaborate forms; for instance you could also look at, inside or under something. "Curses" understands about 1200 English words, so most reasonable synonyms are allowed. To pick something up, "take thing" and to drop it again, "drop thing". To see what you have, type "take inventory" or just "inventory". You can move about with commands such as "go west", or just "west" for short. (It is assumed that you are blessed with an excellent sense of direction.) Some commands can act on more than one thing. You can "drop all", which will drop everything (except things you're wearing), for instance. Or if you found a packing case with a number of things in, you could type such things as: remove everything but the blue key get all the coins except ten, twenty and fifty (Containers may also be emptied or emptied into each other.) If you are not explicit enough, sometimes the game can infer what you mean, but at other times it will ask for further details. It might have replied to the first line above by saying (from the yellow packing case) so that you know what has been assumed on your behalf. If there had been two blue keys you might reasonably have meant, it would reply with something like Which do you mean, the blue doorkey or the Blue Moon Agency key? You may either tell it which, or else give up and do something else instead. If you don't mind which key, you can always say something such as: drop a key into the slot and the game will make a sensible choice and tell you what it was. "Curses" sometimes assumes commands which you implicitly make, but always tells you what they are in brackets. For instance: >look up bach in book (first taking the Encyclopaedia of Composers) (putting the tuning fork in the rucksack to make room) "J. S. Bach (1685-1750) had a pet aardvark called Nigel... "it" refers to the last thing manipulated, "him" and "her" to anyone obvious in the room; "pronouns" will tell you what they currently mean, if in doubt. "again" repeats the last command. You can "save", "restore" or "restart" the game at any time, or indeed "quit" or ask for your "score", which also tells the time. "fullscore" or "full" gives a breakdown of the score. As an aide-memoire the command "objects" tells you where you left things you once had, and "places" says where you have been. If you want to check that your copy of the game file is intact (and not, for instance, corrupted by some file-transfer process you used to get it), you can "verify" it. These commands do not take up any game time, and nor does anything the game didn't understand. Some jaundiced players tire of long descriptions of places, and they can type "short" (or "superbrief") to make the game only give short ones. Amnesiac players, on the other hand, may like to use "long" (or "verbose") to give only long ones. Either kind can go back to the usual state of affairs with "normal" (or "brief"). There are also two kinds of inventory: "inventory wide" and "inventory tall". This Advanced story file employs special effects such as bold face names of rooms and a more elaborate status line than usual. Also, less than altogether relevant quotations pop up from time to time. If these effects do not seem to work properly on your machine, or are just downright annoying, they can be turned off with "plain" and on again with "pretty". From time to time you will be told that your score has changed: this can be turned off with "notify off", turned on again with "notify on" or made even more common by "notify full" (which even tells you about scores accruing from visits to places, unusual items discovered and the like). Simple typing mistakes can sometimes be corrected just by typing "oops" followed by the word you had intended to type, so for instance: drop fish in buket oops bucket The game knows several useful abbreviations: i for inventory, ne for northeast (and so on), l for look, g for again, o for oops, x for examine, z for wait (short for "zzz" - sorry about that). You can sometimes enter larger objects you find. You might well be able to get in a tractor, for instance, though driving it around might be harder. From time to time, you will wish to speak to other people. If you only have a single word to say, you could use commands like answer yes say boo to goose (Text in quotation marks is not allowed.) The game will usually guess who you want to talk to if you miss off the name. A better way to talk, which allows more complicated remarks, is to use commands such as goose, boo wine waiter, give me the bill ask professor about turtles though the waiter may have better things to do, and the professor might be quite mad. Some documents may be consulted in this game. For this, try commands such as look up chlorine consult periodic table about argon You can give several commands in a row by use of "then" (or full stops, commas or "and" in some contexts): so, for instance, e, s, get fish then inventory e.e.open door.s There are, of course, many other commands for more specialised circumstances. A final word of warning: cursing is strictly forbidden in this game. [Please press SPACE.] edit multi line out of edit "
The first problem is the menu information is repeated multiple times. It should only be presented once rather than spamming the screen reader with duplicate information. Second, observe that the entire menu output is repeated once I press n to select the next option in the menu. The screen reader should only speak the name of the option I'm moving to, which in this case should simply be "Commands detailing some common commands". Instead, it repeats the entire output again and then indicates that option is selected by adding the > symbol before it. It also repeated the particular help section twice after I pressed enter to read it. Finally, is it possible to add a keyboard shortcut that automatically speaks the status bar information for a game using a live region? It's currently necessary to manually use the screen reader navigation commands to find it at the bottom of the output which isn't efficient.
I hope all of this makes sense. I'm not a programmer, but I'll do my best to help, so please let me know if you need more information and/or have any questions. I want Parchment to be as screen reader friendly as possible, and we're very close to that goal.
Thank you for writing this, it's always so helpful to get detailed feedback from screen reader users!
First, it lists the command in the output which I find distracting.
This is one that can probably be pretty easily handled. While it's up to the game what it outputs (it could skip outputting the player's input or even change it to something else), the usual case will be just copying it. So I could make it track the last input and set that input to aria-hidden="true" if it's identical. They only downside would be that screen reader users then wouldn't be able to tell when a game just didn't output it at all, though that's not likely to happen.
it always repeats the information about the edit field and that it's blank
How are other text boxes presented in NVDA? Could a label perhaps help? Or aria-placeholder?
It appears it's currently using ARIA live regions, so perhaps switching to assertive mode would fix this by interrupting what's being spoken and forcing the screen reader to immediately begin speaking the new information.
I doubt this would end up better. The main window is currently set to aria-live="polite", which seems to be following best practices. You may not be aware, but a game can have multiple buffer windows (like the main window) and if they were all set to assertive then the output could be jumbled. (Actually multiple live regions might be treated like an error by some screen readers.)
The first problem is the menu information is repeated multiple times. It should only be presented once rather than spamming the screen reader with duplicate information.
That is just an inherent problem with how Inform and other IF systems create menus. But I would eventually like to add a function that would detect menus and turn them into clickable links: https://github.com/curiousdannii/asyncglk/issues/16
Second, observe that the entire menu output is repeated once I press n to select the next option in the menu.
That is odd, I'll have to investigate to see why it's doing it.
Finally, is it possible to add a keyboard shortcut that automatically speaks the status bar information for a game using a live region? It's currently necessary to manually use the screen reader navigation commands to find it at the bottom of the output which isn't efficient.
Status (grid) windows are tricky to handle as they're not a log that a screen reader can simply present the additions. This makes it hard to come up with any sensible strategy. A traditional game would have the room name and turn counter/score. When you move rooms you're almost certainly going to have that info in the main window first, and repeating it wouldn't be useful. If we tried to read out just the parts that changed that would usually be the turn counter, but there'd be no label, so after each turn you'd just hear a single out of context number. Hearing when the score changes would be useful, but it's close to impossible to reliably detect which part of the status window is a score compared to something else.
It gets even more complicated for games with multi-line status windows - they might update only some of those lines. Some games show a compass rose in the status window for example, and there's no way that those could be usefully read out by a screen reader. So I judged the best option would be to just set the status window to aria-live="off", which will prevent the player from hearing a bunch of useless junk each turn, but would still let them navigate to it if they wanted to. (Though if the status window has 4 or more lines it will be set to aria-live="polite", as in those cases it's probably being used as a regular window, so the updates are more important. That's what happens in menus, though it also has the effect of reading the whole window each time.)
In theory we could add a keyboard shortcut to read the status window, though I wouldn't know how to communicate that to players.
Is it possible to somehow add navigation shortcuts for screen readers? If we could make it easier to jump to the status window then back to the end of the main window that would probably be helpful.
Could just make some kind of shortcut or a way to read the area below the input box. Most games have their status lines there. I'm not really sure how some complicated games place their lines though. Also, there's this thingy that puts me into some kind of grouping whenever I move a room or so. It's easily fixed by pressing enter somewhere below the input box. I'm just curious what causes it.
Thanks for responding so quickly. I suspect the edit blank issue isn't related to the program at all, but NVDA itself. It's probably trying to communicate to you that the box is now empty after you press enter which clears it. This behavior is the same in other web applications such as Lectrote. I'm not a programmer, but I thought ARIA placeholder provides a hint for the currently focused item, so I'm not sure this would solve the problem. The only workaround I've found thus far is putting NVDA in sleep mode which eliminates the message entirely and just makes it speak the region information, hence why I thought setting the output window to assertive would be a good idea so you could easily interrupt the speech feedback without turning off sleep mode. If there's some kind of ARIA attribute that eliminates control information entirely, that could work, but I'm not aware of such a thing.
I didn't realize there were multiple windows in the interface. That must mean they're easily identifiable visually, but not so much if you're reading the content with a screen reader. It might be a good idea to set the live region to off as you said and let the player manually move to the status bar to review the information. I'll try to give some basic context around how screen readers interact with web content. NVDA/JAWS on Windows and Orca on Linux have two different modes for working with web interfaces. Focus mode lets all keyboard commands pass through to the program itself which is usually what you want in something like Parchment. I move to the box to type commands and leave the screen reader in focus mode. It automatically speaks the output of commands. This is how it works normally if you aren't using a screen reader as far as I can tell. If I want to review information, I switch to Browse mode by pressing escape from the edit box or using the dedicated command which is the NVDA modifier key and space bar by default. In this mode, the screen reader intercepts most keyboard commands to let you navigate. For example, up/down arrows move by line, left/right by characters, Control-left/right by words, etc. Pressing different letter keys allow you to navigate by specific HTML elements. For example, h for heading, Shift-h to go back, d for landmarks, e for edit fields, etc. If you want to allow a screen reader user to jump to a specific section, one possibility is using landmarks or headings. Clearly mark where the status window starts, and a screen reader user can quickly jump there if desired using the quick navigation commands. VoiceOver on Mac and ChromeVox for ChromeOS have navigation commands, but the good thing here is that you don't necessarily have to switch between different modes when working with web content unless you want to for ease of navigation. Essentially, they let you interact directly with web applications by default, passing regular keystrokes through, but they still have special commands to navigate by different HTML elements.
That's interesting about the help menu being a window. It explains why it's read over and over each time it updates. Is it possible to create different ARIA regions for the command selection indicator, the content that's displayed when you press enter, and the menu itself? This way, you could choose which ones update and are spoken by the reader. Only update the command section when pressing n or p so that it would say something like this. After pressing n, the screen reader announces "Introduction" to indicate the focus moved to that option in the menu. Pressing n again would say something like "Commands". Pressing p would announce the introduction message because focused returned to that option.
Don't forget you can always test things for yourself as well. NVDA is free, so there's no barrier to using it unlike JAWS which is very expensive and only runs in 40-minute mode if you don't activate it. Let me know if you have additional questions, and I'll do my best to answer. I'm sorry I'm not as knowledgeable as I could be on the programming side, but I hope this helps.