Using the Orca Screen Reader in Kicksecure Virtual Machines

Introduction[edit]

...a free, open source, flexible, and extensible screen reader that provides access to the graphical desktop via user-customizable combinations of speech and/or braille. Orca works with applications and toolkits that support the assistive technology service provider interface (AT-SPI), which is the primary assistive technology infrastructure for the Solaris and Linux operating environments.

This documentation has been written by a sighted developer without the input of a blind person for testing purposes. Therefore some written advice might be incorrect, such as instructions concerning the use of sudo vs dsudo. ^[1]

Installation[edit]

Install package(s) orca following these instructions

Platform specific notice.

Kicksecure: No special notice.
Kicksecure-Qubes: In Template.

Update the package lists and upgrade the system .

sudo apt update && sudo apt full-upgrade

Install the orca package(s).

Using apt command line --no-install-recommends option is in most cases optional.

sudo apt install --no-install-recommends orca

Platform specific notice.

Kicksecure: No special notice.
Kicksecure-Qubes: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .

Done.

The procedure of installing package(s) orca is complete.

Orca Configuration[edit]

Prerequisites[edit]

Orca (or any other) screenreader must already be functional on the host operating system. This is unrelated to Kicksecure and outside the scope of this documentation. The user should be familiar and comfortable with the host screenreader.

It is also recommended to learn VirtualBox basics outside of any reference to Kicksecure; that is, using VirtualBox with any other operating system. Otherwise, any blind users simultaneously utilizing VirtualBox and Kicksecure for the first time might face serious challenges.

These instructions have not tested whether the VirtualBox host user interface is itself accessible; this functionality is out of scope.

Bridges Functionality[edit]

Orca was only recently integrated into Kicksecure, therefore support for using Orca in combination with Tor Bridges is not perfect yet -- please post a feature request if that is desirable. Bridge users should refer to the footnote for a workaround. ^[2]

Initial Setup[edit]

1. Agree to Kicksecure legal terms.

Acknowledge that you have read, understood and agreed to our Terms of Service and License Agreement.

2. Start Kicksecure using the VirtualBox host user interface normally.

Depending on system performance it can take up to three minutes or more until Kicksecure starts, although on fast machines it boots much quicker. On a reasonable fast developer machine, booting either Kicksecure or Kicksecure took approximately 30 seconds.

One issue is that there is no audio feedback when the boot process finishes. This is an optimization problem because Kicksecure was originally designed with privacy in mind. Most Kicksecure users would not want to reveal they are using the platform or otherwise signal they are using an operating system via an audio notification which might be noisy depending on host audio settings.

3. Wait for the boot process to finish.

4. Start the Xfce application finder.

Press the following keys in combination.

Alt + F2

5. Use the easo utility.

easo is spelled e, a, s, o. This is an easy to type abbreviation for easyorca. ^[3]

Make sure you read, understood and agreed to Kicksecure binary license agreement and Kicksecure disclaimer before continuing.

Running the easo utility ^[4] has several effects.

Sets volume inside the virtual machine to 50%. ^[5]
Starts the Orca screen reader.
Legally accepts Kicksecure binary license agreement.
Legally accepts Kicksecure disclaimer.
Disables autostart of setup-wizard-dist GUI.
Enables Orca autostart. ^[6]
Enables the orca-kill-at-shutdown.service systemd service. ^[7]
Starts Tor connections which results in Tor connecting to the Tor public network. ^[8]

Type on the keyboard.

easo

And press the Enter key.

6. Wait 10 seconds.

This allows Orca startup and the initial Orca setup to finish.

7. Wait for notification.

There should be an audio notification from Orca stating "screenreader on" -- the initial setup of Orca is complete.

At this time there is no need to re-run the easo utility after next boot. Orca will automatically start after next reboot, followed by an audio notification: "screenreader on".

8. Optional: run systemcheck.

Running systemcheck is recommended, see: systemcheck.

Functionality[edit]

The Orca screen reader is tested as functional in the following applications (non-exhaustive list):

Xfce start menu
xfce4-terminal
Xfce application finder
Most common browsers like Firefox, TorBrowser..etc

There are several limitations at present:

setup-wizard-dist (GUI) does not work. Use setup-dist CLI on the command line instead. ^[9]
Anon Connection Wizard does not work. This is normally not an issue for public Tor network users, but those requiring bridges could configure these on the command line as documented on the Bridges page.
systemcheck GUI (previously called systemcheck) does not work. Use systemcheck CLI on the command line instead. ^[10] See also: systemcheck.
Repository Dist Wizard (GUI) does not work. If needed, use repository-dist (CLI) instead as documented here.

Advanced[edit]

Autostart Orca[edit]

This chapter is usually not required because these steps are already automated by easo.

1. Start Xfce application finder.

Press these keys in combination.

Alt + F2

2. Launch a terminal.

Type.

xfce4-terminal

And press Enter.

3. Enable Orca autostart.

Type.

dsudo orca-enable-autostart

And press Enter. ^[11] ^[12]

4. Done.

After reboot, Orca should now automatically start. Once the boot process finishes and Orca has started there will be an audio notification.

Complete setup-dist[edit]

This chapter is usually not required because these steps are already automated by easo.

setup-dist-noninteractive is a tool to non-interactively use setup-dist. Menu option 1 enables Tor which results in accessing the public Tor network unless the user previously manually configured Bridges.

If required, run this command on both Kicksecure and Kicksecure only.

dsudo setup-dist-noninteractive 1

Packages[edit]

The following package dependencies are installed:

libatk-adaptor libgail-common - required for Xfce settings menu screen reader support
non-qubes-audio - required for adding audio support to Kicksecure
gstreamer1.0-plugins-good - missing dependency in Debian buster
xbrlapi - Recommends: by orca
python3-gst-1.0 - Recommends: by orca
speech-dispatcher-espeak-ng - required for spd-say test
sound-icons - this package might be optional

Issues[edit]

As at April 2021 the following issues are unresolved:

run orca as systemd user service / shutdown takes a long time with orca enabled. ^[13] Worked around using orca-kill-at-shutdown.service systemd service. ^[7]
--debug (or new option) write to console (stdout (and/or stderr))

The following issues have been resolved:

Footnotes[edit]

↑ dsudo allows commands to be run as root without entering a password, so long as the default password has not been changed.
↑ First disable the host internet connection and follow these steps: Setup bridges → Reconnect host internet connection → Make sure host internet connection is functional → Restart Tor or reboot Kicksecure if not connected yet.
↑ It could not be named easyorca for technical reasons; avoiding the letter y inside easo circumvents issues relating to English versus German keyboard layouts. See: orca --replace should not kill script which is starting it.
↑
- https://github.com/Kicksecure/setup-dist/blob/master/usr/bin/easo
- https://github.com/Kicksecure/setup-dist/blob/master/usr/sbin/easyorca-root
↑ By running command amixer set Master 50%. 50% was arbitrarily chosen and is hopefully not too quiet / noisy. It can be regulated using the host operating system or physical speaker volume control.
↑ https://github.com/Kicksecure/usability-misc/blob/master/usr/sbin/orca-enable-autostart
↑ ^7.0 ^7.1 https://github.com/Kicksecure/usability-misc/blob/master/usr/lib/systemd/system/orca-kill-at-shutdown.service
↑ Using setup-dist(-noninteractive) 1. https://github.com/Kicksecure/setup-dist/blob/master/usr/sbin/setup-dist-noninteractive
↑ Run sudo setup-dist in a terminal.
↑ Run systemcheck in a terminal.
↑ This command uses dsudo instead of sudo because commands can be run as root without entering a password, so long as the default password has not been changed. For blind users this is likely far simpler than using sudo and typing the password, especially during the initial setup. See: dsudo for further information.
↑ orca-enable-autostart
↑ https://gitlab.gnome.org/GNOME/orca/-/issues/188#note_1027211

Kicksecure

A secure by default operating system with the latest security research in place.

Dark mode

Supported by Power Up Privacy

Kicksecure is proudly supported until 2025 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Kicksecure we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint

2012- 2024 ENCRYPTED SUPPORT LP

Your support makes
all the difference!

We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!

[1] dsudo allows commands to be run as root without entering a password, so long as the default password has not been changed.

[2] First disable the host internet connection and follow these steps: Setup bridges → Reconnect host internet connection → Make sure host internet connection is functional → Restart Tor or reboot Kicksecure if not connected yet.

[3] It could not be named easyorca for technical reasons; avoiding the letter y inside easo circumvents issues relating to English versus German keyboard layouts. See: orca --replace should not kill script which is starting it.

[4] 
https://github.com/Kicksecure/setup-dist/blob/master/usr/bin/easo

https://github.com/Kicksecure/setup-dist/blob/master/usr/sbin/easyorca-root

[5] ttps://github.com/Kicksecure/setup-dist/blob/master/usr/bin/easo

[6] ttps://github.com/Kicksecure/setup-dist/blob/master/usr/sbin/easyorca-root

[5] By running command amixer set Master 50%. 50% was arbitrarily chosen and is hopefully not too quiet / noisy. It can be regulated using the host operating system or physical speaker volume control.

[6] ttps://github.com/Kicksecure/usability-misc/blob/master/usr/sbin/orca-enable-autostart

[orca-kill-at-shutdown.service-7] 7.0 ^7.1 https://github.com/Kicksecure/usability-misc/blob/master/usr/lib/systemd/system/orca-kill-at-shutdown.service

[8] Using setup-dist(-noninteractive) 1. https://github.com/Kicksecure/setup-dist/blob/master/usr/sbin/setup-dist-noninteractive

[9] Run sudo setup-dist in a terminal.

[10] Run systemcheck in a terminal.

[11] This command uses dsudo instead of sudo because commands can be run as root without entering a password, so long as the default password has not been changed. For blind users this is likely far simpler than using sudo and typing the password, especially during the initial setup. See: dsudo for further information.

[12] orca-enable-autostart

[13] ttps://gitlab.gnome.org/GNOME/orca/-/issues/188#note_1027211

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

Orca Screen Reader

Contents

Introduction[edit]

Installation[edit]

Orca Configuration[edit]

Prerequisites[edit]

Bridges Functionality[edit]

Initial Setup[edit]

Functionality[edit]

Advanced[edit]

Autostart Orca[edit]

Complete setup-dist[edit]

Packages[edit]

Issues[edit]

Footnotes[edit]

Navigation menu

Orca Screen Reader

Introduction[edit]

Installation[edit]

Orca Configuration[edit]

Prerequisites[edit]

Bridges Functionality[edit]

Initial Setup[edit]

Functionality[edit]

Advanced[edit]

Autostart Orca[edit]

Complete setup-dist[edit]

Packages[edit]

Issues[edit]

Footnotes[edit]

Navigation menu

Search