Skip to content

About

A port of the accessibility extension Osara for the Reaper digital audio workstation. It provide speech output to Orca via speech dispatcher.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

OSARA on Linux

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.

Status

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 interrupt flag 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 by install-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.

Building

./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.

Installing

./install-reaper-and-plugin.sh
  • Downloads and installs REAPER to ~/opt/REAPER if 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.so to ~/.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.

Keeping up with upstream

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.

Debugging

./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 to osara/src/linuxa11y_atk.c::role_from_class() and (if state-bearing) osara/src/linuxa11y.cpp::snapshotControlState().
  • text — what GetWindowText returned. 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 — focus if the focused HWND changed; selection if only the inner selection changed.

Troubleshooting

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.

Layout

  • osara/ — fork of upstream OSARA with Linux additions (src/linuxa11y*.{c,cpp,h}, config/linux/reaper-kb.ini, Linux branches in sconstruct / archBuild_sconscript, STL pre-includes in osara.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.

License

The OSARA source under osara/ is GPLv2 (see osara/copying.txt); the Linux additions are GPLv2 too.

Credits

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.

About

A port of the accessibility extension Osara for the Reaper digital audio workstation. It provide speech output to Orca via speech dispatcher.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂