Announcing Tdsr: A Command Line Screen Reader For Macintosh And GNU/Linux

Earlier this year, the Lighthouse for the Blind and Visually Impaired of San Francisco (known as San Francisco Lighthouse to people who speak standard English) agreed that the support for the Macintosh Terminal app using VoiceOver was an inadequate solution for all but the most minimal of its possible use cases. To remedy this issue, they funded the development of a new little screen reader called tdsr.

Tyler Spivey, author of tdsr, had attempted to port the really old UNIX command line screen reader yasr to Macintosh but as yasr is a rat’s nest of old C code, it proved easier to scrap it and write a new command line screen reader from scratch in Python.

While it’s been rumored that tdsr stands for “Tyler’s Damned Screen Reader,” it does not. In fact, tdsr stands for “Two Day Screen Reader” as Tyler got its first functioning prototype up and running in only two days. A lot more work has gone into tdsr since and users of the bash shell (the one used in Macintosh Terminal but not supported well with VoiceOver) will recognize all of the keystrokes as will users of GNU emacs or emacspeak. I personally use tdsr to maintain my server and when I’m messing around with the little bit of Python programming I try to do.

The importance of tdsr is that a command line is still essential for blind people who write software, study computer science and/or maintain servers and do IT stuff. For years, NVDA on Windows has been the only screen reader to provide truly useful support for a command line (JAWS used to do it well but it’s deteriorated over the years). Thus, most blind programmers, hackers, IT professionals and CS students have had to use Windows or GNU/Linux for their work. With the advent of tdsr, a student assigned a Macintosh can now enjoy the same functionality as their peers using Windows.

We want to get the tdsr story out to as many people in our community as possible. To that end, we hope that readers of this post will help to raise awareness of tdsr and its potential value to professionals, students and hobbyists alike. So, if you have the means and opportunity, please direct people to this post or write articles of your own. Of particular interest and value will be stories of how you are implementing tdsr in your own workflow and projects.

You can check out tdsr on Tyler’s GitHub page() for it. You can download the software (instructions on the GitHub page), install it and, as it comes from our little crew, you get the source code to inspect, learn from, modify or do whatever you like with it short of including it in a piece of proprietary software. While Tyler has written most of it, we’ve received some code contributions from outsiders and one fellow added braille support, something Tyler hadn’t planned on doing himself.

If you've questions about tdsr, feel free to send an email to 3 Mouse Technology and we'll try to get you an answer as quickly as possible. If you are interested in using a command line effectively on OSX, please do check out the software, post comments here and if you find a bug, please report it on the GitHub system to ensure Tyler will see it. If you're a Python programmer and would like to participate in the future of tdsr, you can get the code from GitHub and Tyler will consider all push requests.



Submitted by splyt on Friday, September 8, 2017

Eeeei ... neutral or good news about accessibility on OS X ... here is something I didn't bilieve I would hear again!

Given the authors, the work will be good. I suspect the community should already have ttaken control of accessibility for mac OS destiny cinse Apple itself is failing miserably to do it even with all resources they have.

I will spread the news and it is nice to have my mac again able to allow me to work productively at least in command line mode.

Submitted by Chris Hofstader on Friday, September 8, 2017

I'm sorry about this but when I wrote this little article, I confused it with NVDA Remote Access (another program Tyler authored) and said that a volunteer had added braille support to tdsr. This is in fact not true, the volunteer added braille support to Remote Access, the tdsr volunteer added a number of features that Tyler hadn't included in his original version.

So, tdsr does not in fact have braille support at this time.

Submitted by Greg Wocher on Friday, September 8, 2017

I just got this installed and it is working quite well. It is very simple to use and it reminds me of using something like speak up on the linux terminal. I think this will make working in the terminal a whole lot better. The only hiccup I had was that voiceover on safari was reading one of the installation steps oddly. It was the one for installing requirements.txt. For some reason voiceover was not wanting to read the pip3 install -Ur. Once I figured out what it was saying installation was extremely easy.

Greg Wocher

Submitted by Ekaj on Sunday, September 10, 2017

I might have to check this out at some point, although tbh I haven't messed around much if at all in the OS X terminal. Plus, I've found VoiceOver to be quite good for my needs on here with the exception of getting into the iTunes trash. I've been told that one needs to have access to the terminal in order to recover deleted iTunes tracks, and I happen to have some of those. I also kept all of my CDs though. But I will definitely share this on social media. I agree it's probably very good, but I just might not have all the necessary spoons yet to install it. Lol I am most certainly tech-savvy but perhaps not yet to that extent.

Submitted by Simone Dal Maso on Monday, September 11, 2017

Well, a great thank you to the author of the screen reader.
Unfortunately I know Apple will never solve terminal problems on OSX, they exist from the first day the world was created, so having a tool that allow people to work with terminal is beautiful!

Submitted by PaulMartz on Tuesday, September 12, 2017

Member of the AppleVis Blog Team

This is something I want to check out sooner rather than later. Too much on my plate right now. But thanks for posting about it.

Submitted by Chelsea on Friday, September 22, 2017

Hi All,

I just wanted to pop in and share my TDSR story. First a bit of background:

I have never been one to be afraid of or shy away from Terminal since I switched to the Mac in 2012. Confused by it, maybe, but not afraid of it. Last summer, I took a programming internship at NASA's Ames Research center in Silicon Valley. It was an amazing experience, but Tyler's little tool was not known to me at the time, so I was forced to use voiceOver with the standard terminal app. This worked well enough but was a truly miserable user experience.

A few months later, I had TDSR installed and working perfectly. Terminal became a completely different application for me. I no longer had to use quicknav or any of the other voiceOver jury-rig commands that one has to use to try and get terminal to behave properly. In Apple's parlance, now "It just works!" I even wrote a little automator workflow to open Terminal, run TDSR, and disable voiceOver all with one keyboard command.

Adding TDSR to my Mac toolbox has greatly expanded the things I can now do with this computer...mainly getting into systems-level stuff and Python or Matlab programming. If you are still disheartened by the terminal app, I can recommend a great podcast called Taming the terminal. Enjoy, and I hope you have as much fun with Tyler's little program as I have.

Submitted by Greg Wocher on Saturday, September 23, 2017

In reply to by Chelsea

Could you share your automater workflow here? This sounds like it would be handy. I am going to try learning a bit of python on the Mac.

Greg Wocher

Submitted by nightowl on Saturday, September 23, 2017

First of all, a bit of background on me. I have been using the terminal in Mac OS 10 with Voice Over on a daily basis for almost four years now. I maintain my linux servers via ssh and have used programs like Nano and Vim successfully an without a lot of problems. What I'm curious about is what TDSR provides that I couldn't do with the terminal successfully with voice over. Having looked at the feature list, I don't see much of a difference. I'd be curious to know if the dialog boxes that are sometimes drawn by linux during package installation are easier to manipulate with TDSR. If so, I might consider installing it.

Submitted by PaulMartz on Wednesday, October 4, 2017

Member of the AppleVis Blog Team

Okay, I finally got around to installing this. Thanks for posting to AppleVis and telling us about Tdsr. This will come in handy when ssh'd into my Linux and raspberry pi systems. The RP lacks a screen reader, and the screen reader on my Linux box is unreliable and often refuses to speak. At least I now have a better screen reader for both of those systems.

I like the fact that the key commands are very similar to SpeakUp on Linux.

One thing that's a bit inconvenient - if I'm switching between Safari and Terminal, or between any window and Terminal, it's a bit of a PITA to keep turning VO on and off. But aside from this, great work, and thanks again.

Submitted by PaulMartz on Tuesday, October 10, 2017

Member of the AppleVis Blog Team

In reply to by Greg Wocher

I also created an Automator workflow to help with Terminal and TDSR.

Step 1 in the workflow is to launch an application, and the application is Terminal. This step will launch Terminal if it's not already active, or will move focus to Terminal if it's already running.

Step 2 is to run an AppleScript. Here is the AppleScript I wrote:

on run {input, parameters}
    # Command F5 - Toggle VoiceOver
    tell application "System Events" to key code "96" using {command down}
    tell application "Terminal"
        delay 1
        tell application "System Events" to keystroke "~/tdsr"
        delay 0.5
        # Return key is code 36
        tell application "System Events" to key code "36"
    end tell

    return input
end run

Note that the command to launch TDSR is commented out. Just delete the comment wrappers if you want the script to launch TDSR. When I had this code enabled, it executed TDSR as "~/tdsr" - I had a sym link to TDSR in my home directory. A better way to do this would be to put the TDSR Python script in your PATH.

I commented out the launching of TDSR because I tend to restart my computer like twice a month at most and the rest of the time it's up and running with a Terminal active (or asleep). So initially opening a Terminal and starting TDSR is a rare occurrence. With the "~/tdsr" commented out, the AppleScript merely shuts down VoiceOver.

After I created the workflow, I used the VoiceOver Utility, Keyboard Commander, and associated a keyboard shortcut with the Automator Workflow. So now I just hit Right Alt + D, and that immediately takes me to Terminal and kills VoiceOver automatically. I found this use case to be a better fit for my usage of Terminal, but if you really want your workflow to issue the TDSR command, then go ahead and uncomment the code.

I hope this helps.

Submitted by Ekaj on Tuesday, October 10, 2017

Hello. Thanks to the person who posted a link to Taming the Terminal. I briefly checked it out this morning and I think I'm going for it. It looks pretty complex, but I think I can do it with a lot of practice. As previously mentioned, I've found VoiceOver to be good enough for me but who knows? Perhaps I will give TDSR a go and see what happens.

Submitted by Chris Bruinenberg on Wednesday, November 6, 2019

Hi guys.
Could. i get some help with installing the terminal screen reader?
I have ran home brew but i cant get past the part after i have cloned the directory.