A Linux port of OSARA — accessibility for the REAPER digital audio workstation. Upstream OSARA targets Windows and macOS; this project adds the platform pieces needed to make REAPER usable for blind musicians on Linux.
The work attacks an issue open on the OSARA repo since 2018. The platform-abstraction surface for accessibility is actually small (~40 lines on macOS), so most of upstream's 16K lines of code is reusable. The bottleneck was social, not technical.
| Phase | What | State |
|---|---|---|
| 1 | speech-dispatcher backend (minimum viable speaker) | done |
| 2 | timer-based focus poller (read window text on focus change) | done |
| 3a | standalone ATK / AT-SPI probe — prove a non-GTK process can publish accessible objects to Orca | done |
| 3b | integrate ATK bridge into the plugin (fresh AtkObject per focus, role + name + state) | done |
| 3c | AtkText + AtkValue + check / radio state via OsaraControlInfo | done |
| 3d | SWELL tree-view + list-view inner-selection tracking; menu-popup navigation; Linux keymap; Enter→default-button | done |
| 4 | REAPER custom widgets (track list, FX chain, etc.) — out of scope for the platform layer; needs OSARA-side scrapers | open |
What works today:
- Orca speaks REAPER through the AT-SPI bridge — no speech-dispatcher duplicate.
- OSARA's own output (track names, item info, cursor position, toggle reports)
is delivered as AT-SPI announcements, with OSARA's
interruptflag mapped onto AT-SPI politeness so urgent messages cut in and the rest queue. - Controls announce with proper roles: push button, check box ("checked" / "not checked"), radio button, edit, combo box, slider, list, list box, tree, tabs.
- Arrowing inside a container announces the new item — list views, trees, list boxes, combo boxes and tab controls, none of which move focus when their selection changes.
- Opening a dialog announces its title before the first control.
- Menus (File / Edit / View / submenus) announce highlighted items on Up / Down / Home / End and on type-to-jump, including "checked" / "selected" state and whether an item opens a submenu.
- Plain Enter activates the focused dialog button rather than the dialog's default button (SWELL gets this backwards relative to Win32).
- OSARA's keymap is shipped in
osara/config/linux/and installed byinstall-reaper-and-plugin.sh— though it still has to be imported inside REAPER, see above.
What does not work yet:
- REAPER's native track view, FX chain list, MIDI editor — these are custom-drawn widgets that AT-SPI can't see, and upstream OSARA scrapes them on Windows via MSAA. Porting those scrapers to Linux is Phase 4.
- Tab controls announce position ("2 of 5") but not the tab's name: SWELL stores tab labels in private data and exposes no getter for them. See DEVNOTES, "SWELL sharp edges".
- Progress bars announce their role but not their value — SWELL implements
no
PBM_GETPOS. - Menu item state strings ("checked", "submenu") are English-only; they don't go through OSARA's translation layer yet.
- Modal dialogs with bad WM transient hints (e.g., the audio-device-failed popup) can be invisible to the window manager. That's a SWELL bug, not an OSARA one.
./setup.sh # install build deps + fetch WDL, tinygettext, fmt, simpleson
cd osara && scons # builds osara/build/reaper_osara.so
setup.sh detects the package manager (portage, apt, dnf, pacman, zypper) and
installs the right package names for it. To see what it would install without
running it:
./setup.sh --print-deps
Other flags: --deps-only, --no-deps (fetch sources only), and it verifies
the toolchain at the end rather than assuming.
What's needed, in distro-neutral terms: clang/clang++, scons, php (cli), and
development headers for atk, atk-bridge-2.0, glib-2.0 and speech-dispatcher.
php is build-time only — SWELL's swell_resgen.php turns OSARA's .rc files
into the .rc_mac_dlg / .rc_mac_menu headers that reaper_osara.cpp
includes.
./install-reaper-and-plugin.sh
- Downloads and installs REAPER to
~/opt/REAPERif it isn't there already. - Downloads the SWS/S&M extension into REAPER's UserPlugins directory. OSARA supports a number of SWS actions and upstream calls it "highly recommended".
- Copies
reaper_osara.soto~/.config/REAPER/UserPlugins/. - Copies the OSARA keymap to
~/.config/REAPER/KeyMaps/OSARA.ReaperKeyMap.
Flags: --no-reaper, --no-sws, --plugin-only (just refresh the plugin,
which is the usual edit-build-test loop). Architecture is detected, so the
x86_64 / aarch64 / armv7l / i686 builds of both REAPER and SWS are handled.
The keymap is not applied automatically. REAPER only reads it on import:
Options → Preferences → Keyboard/Multitouch → Keyboard shortcuts → Import,
then pick OSARA.ReaperKeyMap. Until you do that, R won't start recording.
osara/ is a vendored copy of upstream OSARA with the Linux port applied on
top, and UPSTREAM records which upstream commit it's based on. To move to a
newer upstream:
./sync-upstream.sh
This rebases the Linux patch (five modified files, four new ones) onto current
upstream master and updates UPSTREAM. If it hits conflicts it stops and tells
you where to resolve them, then ./sync-upstream.sh --continue.
./run-reaper-debug.sh launches REAPER with OSARA_DEBUG=1 and tees stderr
to /tmp/osara-debug.log. Every focus and inner-selection change is logged
with the class name, window text, and inner-selection id — useful for
figuring out why a particular control isn't speaking.
Sample line:
OSARA: focus hwnd=0x351425c0 class='SysTreeView32' text='' innerSel=903657168 changed=focus
Fields:
class— SWELL window class name. If you see something we don't handle (no role announced), this tells you what to add toosara/src/linuxa11y_atk.c::role_from_class()and (if state-bearing)osara/src/linuxa11y.cpp::snapshotControlState().text— whatGetWindowTextreturned. Often empty for list-like widgets; the snapshot code then queries the appropriate SWELL message to fill it in.innerSel— opaque identifier of whichever child is "selected" within the focused container (HTREEITEM for trees, row+1 for list views). Changes drive announcements when focus stays put but arrow keys move the cursor inside the widget.changed—focusif the focused HWND changed;selectionif only the inner selection changed.
Two voices, speech-dispatcher first then Orca. ATK init didn't reach
the AT-SPI bus and we fell back to speech-dispatcher. Check
echo $XDG_SESSION_TYPE (Wayland vs X11) and that at-spi-bus-launcher
is running. Restart REAPER from a terminal and look for
OSARA: ATK init failed in stderr.
Controls announce text but no role. Class isn't in our role table.
Run OSARA_DEBUG=1, note the class='...' value, and either add a row
to role_from_class() or open an issue with the class name.
Tabs work in a dialog but Enter doesn't activate the focused button.
This was fixed in linuxa11y.cpp::handleEnterKey; if it regresses, check
that the translateAccel chain in reaper_osara.cpp still calls
LinuxA11yWrapper::handleEnterKey under the Linux #if.
Submenu items don't speak when arrowing. Confirm the popup class is
__SWELL_MENU (debug log). If a submenu uses a different class (some
plugins might), handleMenuNav skips it.
R doesn't trigger record (it does something else, like Toggle Repeat).
The OSARA keymap wasn't imported. Re-run install-reaper-and-plugin.sh
or import ~/.config/REAPER/KeyMaps/OSARA.ReaperKeyMap manually via
Preferences → Keyboard/Multitouch → Keyboard shortcuts → Import.
For deeper architecture notes — how the AT-SPI bridge works, why fresh AtkObject per focus, the SWELL sharp edges we hit, how to add a new control type — see DEVNOTES.md.
osara/— fork of upstream OSARA with Linux additions (src/linuxa11y*.{c,cpp,h},config/linux/reaper-kb.ini, Linux branches insconstruct/archBuild_sconscript, STL pre-includes inosara.h).atk-probe/— the standalone Phase 3a probe; useful as a minimal reference for "how to publish ATK objects from a non-GTK process".setup.sh,fetch-submodules.sh,install-reaper-and-plugin.sh— build / install scaffolding.run-reaper-debug.sh— debug launcher.
The OSARA source under osara/ is GPLv2 (see osara/copying.txt); the Linux
additions are GPLv2 too.
Upstream OSARA by James Teh / NV Access — https://github.com/jcsteh/osara. Linux port by Cody Thurst, with Claude Code as a pair-programming collaborator.