{{Header}}
{{Title|title=
Orca Screen Reader
}}
{{#seo:
|description=Using the Orca Screen Reader in {{project_name_long}} Virtual Machines
|image=Orcascreenreader131233.png
}}
[[File:Orcascreenreader131233.png|thumb]]
{{intro|
Using the Orca Screen Reader in {{project_name_short}} Virtual Machines
}}

<u>'''Note:'''</u> These instructions have not been tested in a long time and are likely at least partially broken.

= Introduction =
[https://github.com/GNOME/orca Orca] is:

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

This documentation has been written by a sighted developer without input from a blind person for testing purposes. Therefore, some written advice might be incorrect, such as instructions concerning the use of <code>sudo</code> vs <code>dsudo</code>. <ref><code>dsudo</code> allows commands to be run as root without entering a password, so long as the default password has not been changed.</ref>

= Installation =

{{Install Package|package=
orca
}}

= Orca Configuration =

== Prerequisites ==

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

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

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

== Bridges Functionality ==

Orca was only recently integrated into {{project_name_short}}, so 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. <ref>First disable the host internet connection and follow these steps:
<code>Setup bridges</code> &rarr; <code>Reconnect host internet connection</code> &rarr; <code>Ensure host internet connection is functional</code> &rarr; <code>Restart Tor or reboot {{project_name_short}} if not connected yet</code>.</ref>

== Initial Setup ==
{{Box|text=
'''1.''' Agree to {{project_name_short}} legal terms.

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = <u>'''Acknowledge that you have read, understood and agreed to our [[Terms of Service|<span style="color:#FF1493;">Terms of Service</span>]] and [[License Agreement|<span style="color:#FF1493;">License Agreement</span>]].'''</u>
}}

'''2.''' Start {{project_name_short}} using the VirtualBox host user interface normally.

Depending on system performance, it can take up to three minutes or more until {{project_name_short}} starts. On fast machines, it boots much quicker. On a reasonably fast developer machine, booting either {{project_name_gateway_long}} or {{project_name_workstation_long}} took approximately 30 seconds.

One issue is that there is no audio feedback when the boot process finishes. This is an optimization because {{project_name_short}} was originally designed with privacy in mind. Most {{project_name_short}} users would not want to reveal they are using the platform 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 key combination:

<code>Alt</code> + <code>F2</code>

'''5.''' Use the <code>easo</code> utility.

<u>Note:</u> TODO: <code>easo</code> is broken.

<code>easo</code> is spelled <code>e</code>, <code>a</code>, <code>s</code>, <code>o</code>. This is an easy-to-type abbreviation for easyorca. <ref>
It could not be named easyorca for technical reasons; avoiding the letter y inside <code>easo</code> circumvents issues relating to English versus German keyboard layouts. See: [https://gitlab.gnome.org/GNOME/orca/-/issues/189 orca --replace should not kill script which is starting it].
</ref>

Make sure you have read, understood and agreed to [https://github.com/{{Project_name_short_lowercase}}/{{Project_name_short_lowercase}}-base-files/blob/master/usr/share/{{Project_name_short_lowercase}}/KICKSECURE_BINARY_LICENSE_AGREEMENT {{project_name_short}} binary license agreement] and [https://raw.githubusercontent.com/{{Project_name_short_lowercase}}/{{Project_name_short_lowercase}}-base-files/master/usr/share/{{Project_name_short_lowercase}}/KICKSECURE_DISCLAIMER {{project_name_short}} disclaimer] before continuing.

Running the <code>easo</code> utility <ref>
* https://github.com/{{project_name_short}}/setup-dist/blob/master/usr/bin/easo
* https://github.com/{{project_name_short}}/setup-dist/blob/master/usr/sbin/easyorca-root
</ref> has several effects.
{{Box|text=
# Sets volume inside the virtual machine to 50%. <ref>
By running command <code>amixer set Master 50%</code>. <code>50%</code> was arbitrarily chosen and is hopefully not too quiet or noisy. It can be adjusted using the host operating system or physical speaker volume control.
</ref>
# Starts the Orca screen reader.
# Legally accepts [https://github.com/{{Project_name_short_lowercase}}/{{Project_name_short_lowercase}}-base-files/blob/master/usr/share/{{Project_name_short_lowercase}}/KICKSECURE_BINARY_LICENSE_AGREEMENT {{project_name_short}} binary license agreement].
# Legally accepts [https://raw.githubusercontent.com/{{Project_name_short_lowercase}}/{{Project_name_short_lowercase}}-base-files/master/usr/share/{{Project_name_short_lowercase}}/KICKSECURE_DISCLAIMER {{project_name_short}} disclaimer].
# Disables autostart of <code>setup-wizard-dist</code> GUI.
# Enables Orca autostart. <ref>
https://github.com/{{project_name_short}}/usability-misc/blob/master/usr/sbin/orca-enable-autostart
</ref>
# Enables the <code>orca-kill-at-shutdown.service</code> systemd service. <ref name=orca-kill-at-shutdown.service>
https://github.com/{{project_name_short}}/usability-misc/blob/master/usr/lib/systemd/system/orca-kill-at-shutdown.service
</ref>
# Starts Tor connections which result in Tor connecting to the Tor public network. <ref>
Using <code>setup-dist</code> (<code>-noninteractive</code>) <code>1</code>.

https://github.com/{{project_name_short}}/setup-dist/blob/master/usr/sbin/setup-dist-noninteractive
</ref>
}}
Type on the keyboard:

{{CodeSelect|code=
easo
}}

And press the <code>Enter</code> key.

'''6.''' Wait 10 seconds.

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

'''7.''' Wait for the 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 <code>easo</code> utility after reboot. Orca will automatically start after the next reboot, followed by an audio notification: "screenreader on".

'''8.''' ''Optional:'' run systemcheck.

Running <code>systemcheck</code> is recommended. See: [[systemcheck]].
}}

= Functionality =

The Orca screen reader has been tested as functional in the following applications (non-exhaustive list):
* Xfce start menu
* xfce4-terminal
* Xfce application finder
* Most common browsers like Firefox, Tor Browser, etc.

There are several limitations at present:
* <code>setup-wizard-dist</code> (GUI) does not work. Use <code>setup-dist</code> CLI on the command line instead. <ref>
Run <code>sudo setup-dist</code> in a terminal.
</ref>
* [[Anon Connection Wizard]] does not work. This is generally not an issue for public Tor network users, but those requiring bridges can configure them on the command line as documented on the [[Bridges]] page.
* <code>systemcheck</code> GUI (previously called <code>systemcheck</code>) does not work. Use <code>systemcheck</code> CLI on the command line instead. <ref>Run <code>systemcheck</code> in a terminal.</ref> See also: [[systemcheck]].
* Repository Dist Wizard (GUI) does not work. If needed, use <code>repository-dist</code> (CLI) instead as documented [[Project-APT-Repository#Command_Line_Interface|here]].

= Advanced =

== Autostart Orca ==

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = This chapter is usually not required because these steps are already automated by <code>easo</code>.
}}

{{Box|text=
'''1.''' Start Xfce application finder.

Press this key combination:

<code>Alt</code> + <code>F2</code>

'''2.''' Launch a terminal.

Type:

{{CodeSelect|code=
xfce4-terminal
}}

And press <code>Enter</code>.

'''3.''' Enable Orca autostart.

Type:

{{CodeSelect|code=
dsudo orca-enable-autostart
}}

And press <code>Enter</code>. <ref>This command uses <code>dsudo</code> instead of <code>sudo</code> 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 <code>sudo</code> and typing the password, especially during initial setup. See: [[Root#dsudo_-_default_password_sudo|dsudo]] for further information. </ref> <ref>[https://github.com/{{project_name_short}}/usability-misc/blob/master/usr/sbin/orca-enable-autostart <code>orca-enable-autostart</code>]</ref>

'''4.''' Done.

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

== Complete setup-dist ==

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = This chapter is usually not required because these steps are already automated by <code>easo</code>.
}}

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

If required, run this command on both {{project_name_gateway_short}} and {{project_name_workstation_short}} only.

{{CodeSelect|code=
dsudo setup-dist-noninteractive 1
}}

== Packages ==

The following package dependencies are installed:
* <code>libatk-adaptor libgail-common</code> - required for Xfce settings menu screen reader support
* <code>non-qubes-audio</code> - required for adding audio support to {{project_name_gateway_short}}
* <code>gstreamer1.0-plugins-good</code> - [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=931687 missing dependency in Debian buster]
* <code>xbrlapi</code> - <code>Recommends:</code> by <code>orca</code>
* <code>python3-gst-1.0</code> - <code>Recommends:</code> by <code>orca</code>
* <code>speech-dispatcher-espeak-ng</code> - required for <code>spd-say test</code>
* <code>sound-icons</code> - this package might be optional

== Issues ==

As of April 2021, the following issues remain unresolved:

* [https://gitlab.gnome.org/GNOME/orca/-/issues/188 run orca as systemd user service / shutdown takes a long time with orca enabled]. <ref>https://gitlab.gnome.org/GNOME/orca/-/issues/188#note_1027211</ref> Worked around using <code>orca-kill-at-shutdown.service</code> systemd service. <ref name=orca-kill-at-shutdown.service/>
* [https://gitlab.gnome.org/GNOME/orca/-/issues/191 --debug (or new option) write to console (stdout (and/or stderr))]

The following issues have been resolved:
* Issues on {{project_name_short}} host: [https://gitlab.gnome.org/GNOME/orca/-/issues/176 orca not starting - TIMEOUT: something has hung. Aborting.]
* [https://gitlab.gnome.org/GNOME/orca/-/issues/189 orca --replace should not kill script which is starting it]
* [https://gitlab.gnome.org/GNOME/orca/-/issues/190 ctrl + c does not terminate orca - AttributeError: module 'signal' has no attribute 'strsignal']

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]