TurnOver - the OG alternative screenreader for mac is now opensource

An option to avoid GitHub's web interface is to install its command-line tool called gh. I do so using MacPorts, but HomeBrew should have it too.

To install gh using MacPorts, type:

sudo port install gh

And then enter your password when prompted.

Next, generate an ssh key for authentication to GitHub if you don't have one already by typing:

ssh-keygen -t ed25519

And answer all the questions, making sure to remember both the name of the private key file and the passphrase.

Next, append the following to your ~/.ssh/config to make ssh authenticate using the new key:

Host *
    UseKeychain yes
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

Replacing id_ed25519 with the file-name containing your private key.

Next, add the authentication key to the ssh-agent for automatic remote authentication as follows:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Replacing id_ed25519 with the file-name with your private key, and entering the passphrase.

Next, authenticate gh to GitHub by typing:

gh auth login

And following the on-screen instructions.

The following is optional, and will make the mate utility from TextMate the default editor and pager, which are used by both git and gh, so install TextMate if you haven't already and install the mate utility from its preferences.

First, create a bin directory in your home directory by typing:

mkdir ~/bin

Next, create a file in ~/bin/lesser with the following content that removes all terminal control sequences from the output and pipes it to TextMate:

#!/bin/sh
perl -pe 's/\e\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]//g' | col -xb | mate

Next, give executable permissions to the file that you've just created as follows:

chmod 755 ~/bin/lesser

Next, edit your ~/.zprofile and append the following two lines:

export EDITOR='/usr/local/bin/mate -w'
export PAGER=$HOME/bin/lesser

All done. Now you can interact with GitHub almost entirely from the command-line and get the output sent to TextMate.

The following command clones Turnover to a subdirectory in the current directory:

gh repo clone TurnOver-For-Mac/turnover

The following command lists all the issues in Turnover using TextMate as the pager, if you configured it as instructed earlier:

gh issue list

Or you can avoid TextMate and print directly to the console as follows:

gh issue list | cat

For example the following are the issues currently open for Turnover at the time of this comment:

jps@alpha turnover % gh issue list | cat
25  OPEN    Braille: NVDA's braille features (panning moves the cursor, focus context, review cursor, read by paragraph, settings)  idea    2026-10-21T16:14:56Z
14  OPEN    Issue with browsing for files   problem 2026-10-21T13:05:58Z
12  OPEN    Speech rate jumps when CoExist is turned on or off (Eloquence)  problem 2026-10-21T11:07:41Z
11  OPEN    Braille: the TurnOver menu is not shown on the display; it keeps showing the app behind problem 2026-10-21T11:07:39Z
10  OPEN    Braille: with CoExist off the display shows only VoiceOver off and nothing else (Focus 5)   problem2026-10-21T11:07:38Z
4   OPEN    Browse mode: timing of keys in the virtual buffer   problem 2026-10-20T15:25:06Z
3   OPEN    Reader state is hard to isolate in tests    idea    2026-10-20T15:25:05Z
2   OPEN    App-specific exceptions living in shared code   idea    2026-10-20T15:25:03Z
1   OPEN    Keys pile up while a slow page's buffer is built, then run all at once  problem 2026-10-20T15:23:28Z

Issue #1, for example, contains the following:

jps@alpha turnover % gh issue view 1 | cat
title:  Keys pile up while a slow page's buffer is built, then run all at once
state:  OPEN
author: Doll-Eye (Doll Eye)
labels: problem
comments:   0
assignees:  
projects:   
milestone:  
issue-type: 
parent: 
sub-issues: 
sub-issues-completed:   
blocked-by: 
blocking:   
number: 1
--
Seen in Safari on 20 Oct 2026 when Safari stopped answering accessibility questions: each rebuild of the page's reading buffer took about two seconds on the main thread, every key pressed meanwhile queued ("kb:tab answered after 2012 ms: its script runs now", five in a row), and they all ran together when the build finished.

Two parts:
1. Build the buffer without holding the main thread for seconds (a time budget, finishing in the background, or keeping the old buffer while a slow app is rested by AXHealth).
2. Repeats of the same navigation key that waited more than about a second should not all run: run the last one, say that the page was slow.

The log lines above come from InputManager and ScriptHandler.askMain; the buffer is built in WebBuffer/BrowseMode.

All gh commands have dedicated manual pages, so for example if you type:

man gh-issue-view

That will display the manual page for the view subcommand of the issue command, and the same works for git commands too.

Since the man command uses the configured pager, you will also get the manual pages displayed in TextMate, if you configured it earlier.

Personally, one of the things that has prevented me from fully embracing TurnOver, even in apps where it's currently supported, is the fact that it runs alongside, rather than in place of, VoiceOver. Even if the two screen readers function similarly, it's still two separate screen readers running side by side, increasing the potential for bugs, conflicts, and user friction.

NVDA, on the other hand, is a full-featured screen reader, meaning that I can acclimate to one set of commands and concepts when using Windows, and apply them across the operating system. I don't need to think about what screen reader will work in one app versus another, unless I, for example, purposefully quit NVDA and turn on Narrator.

I think if TurnOver could eventually function as a full-featured screen reader, I could see myself using it full time. I know development is only beginning, but I think the ultimate, long-term goal of making it as full-featured as possible across apps could really move the Mac accessibility landscape forward in ways not thought possible a short time ago.

completely aggree, this is the type of things i'd want apple to use.

Is it me, or is this ? buggy as hell? It gets stuck all the time for me, loses focus in apps, fails to interact, fails to announce windows in alt tab and so on.

i shoould get used to how it works. i haven't used it in a long r time, only use it when voiceover desides that it want's to, uh, kinda die? but for what i do it works pretty well even though i don't use it all that much

So, after continuing to try this for a while, I ran over one massive issue, when in a group, focus at times randomly jumps to top, even in the turnover settings dialogs. Others do not seem to have this issue so I suspect that some config or something on my mac causes it, what could it be?

Installed, gave both permissions. Turnover starts speaking. Good so far. Arrow keys don't work. VO keys don't work. ctrl-cmd-comma doesn't get into the Turnover settings, I was planning on trying to change keyboard layouts. ctrl-cmd-period does work to turn it off, but then I don't get VO back. Reboot, try again, same thing. Reboot, again necessary to get VO working again, delete from apps folder.

That was short, at least.

1. How do you get to the dock in NVDA layout? I guess I could just hit cmd-space and use spotlight to find all of my apps, but still.

2. In settings, if I pick speech, the only setting I see is about ducking, I think. I want to change the voice. How do I do that?

3. Speaking of settings, somehow or other all of its windows went away and I had to force quit when I quit Turnover and started Voiceover. SO how do you get out of settings properly? I thought escape would do it, but apparently not.

4. Oh also, other things that happen because of VO keys, e.g. getting to the desktop, so far cmd-tabbing to the Finder window works but is there a way to get to specific places like that?

I will say, though it took a little bit, Voiceover did restart automatically after I quit Turnover. So that's nice.

Just turned over TurnOver. My initial impressions? it's promising but, for some reason, to me it feels a bit sluggish. That might be down to my particular habits, though--I use single-letter quick nav and arrow quick nav a lot in VoiceOver, and using it in TurnOver is rather slow--I keep getting "Please wait" announcements in place like the App Store, for example. I'll keep testing, and anything actionable I'll pipe up.

Another issue. I tried to import my voiceover settings. It goes into VoiceOver Utility, but then it fails because apparently it can't find a voice? I'm using a voice? No idea why it's not working.
It also seems a bit slower when typing stuff, especially browsing by character and word

It also doesn't show me what I have written in Dictation when I have stopped speech. Not sure if this is a turnover issue or dictation issue.

Here are a few things I noticed within the first few minutes of testing:

VoiceOver keeps turning itself back on, even though I explicitly turn it off.

When I invoke the element’s context menu, a menu does open, but it seems to be the desktop context menu rather than the menu for the selected element. It contains options like “New Folder,” “Change Wallpaper,” and “Edit Widgets.”

A second speech voice keeps interrupting TurnOver’s speech. It sounds similar to Eloquence. For example, when I open Safari, this voice reads the webpage content, while TurnOver’s configured voice announces attributes such as links and headings. This happens even though I copied my VoiceOver settings, which are configured to use a single voice.

I also had a look through the source code because I was hoping to help with localization. I couldn’t find any localization files, and it looks like at least some of the user-facing strings are hardcoded in the Swift source. It would be great if localization support could be added.

I am not going through this, I can navigate the settings just fine. No issues at all. I am now full time user of TurnOver.

Here's another issue, left-option does not go to the dock. It does nothing. This is 2.0.22, and I also have the settings issue with tab, i.e. I only get one setting, up/down opens the menu for that setting, e.g. "no", "always". Tab goes right back to the settings list, "general, speech", and so on.

Also, when hitting cmd-space for Spotlight, nothing reads. So you don't actually know that you're in the search field ready to type.

But it doesn't happen all the time, sometimes if I go to the speech settings I won't be able to tab around as normal, but other times it works completely fine.

So, typically I open a program, go to the Dock, and pull up the context menu to select "keep in Dock". This seems not to work with Turnover. Neither does the hotkey recommended in Voiceover *when* in Voiceover.

Frustrating.

Any tips?

Lorien

was loky thinkin bout dropping a 50 but coffei sucks. is there another way to donate? i tried looking at the menu but nothing

yea but people who do wonna report issues are now in a bit of a tuf spot, because github sucks and most people here wouldn't wonna use the termonal so idk. and github is a bit more ment for devs and not the person who only would use this a few times.
but i guess, you can't win eiver way.

I know that github is not the easiest tool to use, especially for non devs. Even as a dev I am still getting my head around parts of it. However, submitting issues on Github really is very easy to do via the web interface, with no terminal use necessary. Here is a quick guide:

1. Create a free account by clicking here if you don't have one already.
2. Then, go to the Turnover Repository. The first heading on that page is "repository navigation", beneath which is a list of links. Choose issues from that list.
3. Beneath the heading "issues" on that page, which is the first level 1 heading, you'll find the New Issue link.
   • You'll also find the search here. It's helpful if you can try a few search terms first, to see if your issue has already been reported.
   • The search form is pre-filled with the words "is:issue state:open". This line is simply a filter that searches for active, open issues. To perform a search, simply put your search term before this line, separated by a single space.
   • For example, searching for the phrase "Braille is:issue state:open" will find all of the open issues with "braille" in their title.
   • The search results appear as level 3 headings, and you can activate any of them to see the issue details.
4. When you click 'New Issue', a dialogue will appear asking you to choose a category. The choices here are self explanatory. Use "something isn't right" for a bug report, use "An idea or request" for a feature suggestion. Submit 1 issue for each singular problem or request.
5. Activating any of those options will present a dialogue with a form where you can provide further details. The questions here, again, are self explanatory. When you have filled in the requested information, press the "create" button at the bottom of the form, and your issue will be created. You will be taken to your issue's page on github, where you can view comments from others, add additional comments, reply to comments, or close the issue.

To make this even easier, you can use these direct links to go straight to the form to open an issue, assuming you are already signed into github. However, please do make use of the search feature, to help ensure we are not overrun with duplicate bug reports.

• Report a bug
• Suggest a feature

Please familiarise yourself with the Contributor Guide and the Code of conduct before submitting your issue. Those pages look busy, but in both cases you'll find the content beneath the final level 1 heading on each page, and the content is contained within an article landmark for easier navigation.

I will occasionally check in on this thread for those who don't want to use Github issues. However, I please ask that you do the following:

1. add a subject to your comment relevant to your report.
2. Provide details that will help reproduce your bug or track it down. Use this as a template:
   • What is the behaviour or issue you are experiencing?
   • What do you expect to happen instead?
   • What steps can we take to reproduce your bug? Include details of any apps you're using.
   • Is there any other relevant information? The specific synth / voice used, make / model of your braille display for example.

Simply criticising the project as "buggy as hell" or failing to provide useful information won't get anything fixed, and is quite demotivating and discouraging for those who are putting our own time and resources into building something here. Remember, this is a few weeks old, and was until recently the work of one person putting in a lot of hours. "Rome wasn't built in a day", as they say.

Before anyone takes this the wrong way, I'm not trying to attack Oliver or discourage development. I've already contributed to the project through PR #13, and Oliver has accepted one of the fixes from that audit. I genuinely want this project to succeed.

However, after looking through the code, I think some of Choom's concerns are worth taking seriously.

1. Concurrency and manual locking

In Sources/TurnOverSpeech/SpeechPlayer.swift, we have:

public final class SpeechPlayer: @unchecked Sendable {
    nonisolated(unsafe) public static var current: SpeechPlayer?
    private let settingsLock = NSLock()

Now, none of these things are inherently wrong.

However, @unchecked Sendable places responsibility for thread safety on the developer rather than having the compiler verify it. nonisolated(unsafe) also bypasses certain Swift concurrency protections.

There are similar patterns in other parts of the codebase.

This doesn't automatically mean there are race conditions, but it does mean additional care and testing are needed, particularly in a screen reader where speech, keyboard input and accessibility events are all interacting.

I think Choom has a reasonable point about using Swift's structured concurrency where practical, rather than relying so heavily on manual synchronisation.

2. Private macOS APIs

In Sources/TurnOverCore/DisclaimedSpawn.swift, there's this:

guard let f = dlsym(
    UnsafeMutableRawPointer(bitPattern: -2),
    "responsibility_spawnattrs_setdisclaim"
) else { return nil }

The implementation also uses unsafeBitCast to convert the returned pointer into a callable function.

From what I can tell, this is intended to prevent helper processes from inheriting TurnOver's accessibility-related permissions.

That's a legitimate security objective.

However, relying on an undocumented macOS symbol comes with compatibility risks. Apple could change or remove that functionality in a future release.

Again, this doesn't necessarily mean the implementation is currently broken, but it deserves attention.

3. Control-channel reliability

This is one of the more concrete problems identified during my earlier audit.

In Sources/TurnOverControl/ControlChannel.swift, the server sends messages like this:

private func send(_ message: [String: Any], to fd: Int32) {
    guard let data = ControlChannel.encode(message) else { return }
    queue.async { [weak self] in
        guard self?.clients[fd] != nil else { return }
        data.withUnsafeBytes { _ = write(fd, $0.baseAddress, data.count) }
    }
}

And broadcasts settings updates like this:

for fd in self.subscribers {
    data.withUnsafeBytes {
        _ = write(fd, $0.baseAddress, data.count)
    }
}

The problem here is that write() isn't guaranteed to send all the requested bytes in one operation.

It can return a partial write.

In these examples, the return value is ignored entirely.

Elsewhere, the client checks whether the number of bytes written matches the requested length, but doesn't retry if the write is incomplete.

Since the control channel exchanges newline-delimited JSON, incomplete writes could potentially result in malformed or incomplete messages.

This is something I'd like to see fixed with proper write loops, error handling and regression tests.

It's also one of the areas Oliver has asked me to resubmit as a separate pull request.

4. Complexity and long-term maintenance

This is probably my biggest concern.

TurnOver has multiple components dealing with speech, keyboard input, accessibility events, VoiceOver handover and recovery when something stops responding.

Some of this complexity is unavoidable. Developing a screen reader is not an easy task.

However, if those components become too tightly connected, fixing one issue can create problems somewhere else.

One example worth investigating further is how the control channel handles asynchronous responses and disconnected clients. Connections are tracked using file descriptors, which the operating system can eventually reuse.

Without appropriate safeguards, delayed operations could potentially interact with a different connection than originally intended.

I'm not claiming I've reproduced that failure, but it's something that deserves proper testing.

5. There are good things in the code too

I don't want to make this sound like TurnOver has absolutely no architecture.

It does have separate modules for speech, accessibility, braille, control communication and other functionality.

The control channel also includes checks intended to verify connecting processes.

There are existing tests, documented architecture concerns and mechanisms intended to restore VoiceOver if TurnOver becomes unresponsive.

So I wouldn't describe the entire project as hopelessly broken.

Overall

My concern isn't that TurnOver doesn't work. It clearly does work for some people, and in certain applications it can provide a better experience than VoiceOver.

My concern is whether the current implementation will remain maintainable as the project grows.

Choom's prediction that the project will eventually collapse is still a prediction, not an established fact.

But after reviewing the source, I don't think his underlying technical concerns should simply be dismissed.

I also think Oliver deserves credit for accepting outside contributions and being willing to improve the implementation. The build-script issue identified in my audit has already been addressed through a separate commit, according to his response to PR #13.

For anyone interested, my original contribution is here:

https://github.com/TurnOver-For-Mac/turnover/pull/13

And the official repository is here:

https://github.com/TurnOver-For-Mac/turnover

I'm a windows user exclusively, but Oliver should be congratulated hugely for this. Sounds amazing, to be honest. A spirit of collaboration and good humour is needed here. Many of you have been very gracious, but don't burn this down, It is outstanding, just to have begun this adventure. Apple should hang their head in shame. I'd urge everyone to contribute, either financially or by helping from a coding perspective by lessening the load on one person. I'd never consider the Mac as a platform due to the current state of Voiceover, but with this, I may very well give It a second look, if this project continues and develops. Great stuff, Oliver.

I agree with others here. Whilst I may have my own doubts over whether the project will succeed and actually be successful or not, plus my own little criticisms and other issues, I still think that we should be thankful that someone has actually tried to mess around with this, AI or not.
what Oliver has done here is absolutely commendable, some may say, even tremendous. What will happen after today we don't know. choom outright saying, the project will fail, in my opinion, is just absolutely beyond outlandish. I mean, it could happen, who am I to say whether it will or not. But it's only been three weeks. At least give it like three months or so before deciding whether a project will fail or not.

Hi All,
A while back, I mentioned on AppleVis that we should probably join forces and put all our energy into TurnOver. But after diving deep into the TurnOver repo and looking closely at the codebase, my perspective shifted a bit, and I wanted to share why.

Don't get me wrong—TurnOver has some impressive features already built out (like the Word support). But when you look under the hood, you can see how easily quick AI-driven coding ('vibecoding') takes a toll. A lot of app-specific rules, component definitions, and custom behaviors are tightly coupled right into the core. For an open-source screen reader that ultimately needs to support hundreds of different apps, that's a massive maintenance headache waiting to happen.

That said, I still believe we shouldn't split our energy across separate projects; uniting under one roof is definitely the right move. But for that to actually work, we need to be honest with ourselves: the project desperately needs a serious architectural refactor.

Instead of hardcoding every little workaround straight into the core, we need to shift toward a clean, data-driven, catalog-based model where app-specific logic lives safely outside the engine.

So, my open question to the team is: do you see this bottleneck as well, and are you ready to commit to a major refactor to build this the right way?