Orca Frequently Asked Questions

Overall Information

How do I contribute to this WIKI?

We love you! Thanks for contributing. Create a new account by visiting http://live.gnome.org/action/login/Orca?action=login. Login and you will find an "Edit" link near the top of the page. Follow this link and edit the content. Further instructions for WIKI syntax and editing can be found at the bottom of the page once you start editing it.

What is Orca?

Orca is a flexible, extensible, and powerful assistive technology for people with visual impairments. Using various combinations of speech synthesis, braille, and magnification, Orca helps provide access to applications and toolkits that support the AT-SPI (e.g., the GNOME desktop). Orca is also free open source software.

Any idea of the system prerequisites?

A modern system will typically suffice. If you try to use a machine from the 1990's with very little RAM, well, expect it to work like a machine from the 1990's with very little RAM.

Why the name Orca?

One of the first DOS screen readers was Flipper by Omnichron corporation in Berkeley, CA. It was named Flipper in part because the blind wife of the programmer envisioned computers as being programmed by flipping switches (an accurate image of a bygone era). Then came another DOS screen reader from Henter-Joyce in Florida - "Jobs access With Speech" (or JAWS). Meanwhile in the UK we had the company Dolphin systems making their own DOS screen reader.

While there isn't otherwise an obvious connection between blindness and creatures from the sea, there is certainly a long tradition around it.

Hence the lore is that it is just keeping with the sea animal naming theme of screen readers. Plus, Orca is a lot tougher sounding than Nemo, Ariel, Willy, or Mr. Limpet.

What's the schedule?

Orca is part of the GNOME platform and Orca's releases are coupled with the releases of the GNOME platform. The GNOME platform releases on a 6 month cycle, with stable releases typically around the March and October timeframes. During the 6 month cycle, there are a number of "odd" releases, such as GOME 2.21.1, GNOME 2.21.2, etc. The stable releases that follow are "even" releases, such as GNOME 2.22.0, GNOME 2.22.1, etc.

How do I request a new feature?

Bugs and feature/enhancement requests (RFEs) should be reported to the GNOME Bug Tracking System. Patches are always welcome, and instructions for creating patches can be found in the GNOME introduction to Subversion (svn). You can also read more about Orca bugs and enhancements on the Orca Bugs page.

Where's the discussion list?

You can get in touch with developers and other users by sending an e-mail to the Orca mailing list (Archives).

NOTE: there is a #orca IRC channel on irc.gnome.org. If you drop in the #orca room and nobody answers your questions, you're probably just talking to the software robots in the room, such as A11yLogger. Don't be dismayed. We are not ignoring you. The best way to reach the Orca community is via the Orca mailing list.

Is braille supported?

Yes! Braille is supported via BrlTTY and it is integrated well with Orca. BrlTTY offers support for nearly every refreshable braille display known to man. Please refer to the Braille page for more information.

Is contracted braille supported?

As of GNOME 2.22.0, Orca supports uncontracted braille.

/etc/brltty.conf is overwritten, what to do?

Please see solution, posted on the Braille page.

What voices are available?

Orca provides inerfaces to both gnome-speech and emacspeak speech services. There is also experimental support for Speech Dispatcher. As such, the available voices for Orca are only restricted by the speech engines supported by the available speech services. For free speech engines, you typically have a choice of the eSpeak, Festival, and FreeTTS speech engines. For commercial engines, you have a choice of additional engines such as Fonix DECtalk, Loquendo, Eloquence, Cepstral, IBMTTS, and others may be on the way soon. Keep an eye on the gnome-speech package for more progress in this area.

See also the Speech page for more information.

What languages are supported?

The GNOME Translation teams are composed of many passionate volunteers from around the world. These teams do a great job and keep an up-to-date status report. Please see the Orca translation status page for the large number of languages into which Orca has been translated. NOTE that the support for a language also depends upon a speech synthesis engine that supports the language whether BrlTTY has braille tables for the language or not.

How well does magnification work?

Orca currently uses the gnome-mag magnification service. As of this writing (GNOME 2.18), gnome-mag has incorporated some support for smoother full screen magnification, which relies upon newer extensions in the X Window System server. These extensions do not always function well on all platforms, so smooth full screen magnification may not always work.

How's web access coming along?

It's going well! See the Orca Firefox page for more information.

Where can I find more information about Python?

More information on Python can be found here:

• Dive Into Python, Mark Pilgrim

• Python in a Nutshell, Alex Martelli

• Python Pocket Reference, Mark Lutz

I would like to help with Orca code, what do I need to know before starting?

Please see Orca/CodingGuidance

Any good OCR packages available?

Here's what a few of our users have to say:

two OCR packages are gocr and ocrad, and both of these work reasonably
well for me. The most important thing is to make sure the images are in
the correct resolution (my scanners default is 600 but it needs to be
300, until I realised this I was lucky if it got one character correct
on a page, where as now it is good enough to know what is meant to be
there if there is any errors). You can pipe the output from the sane
tools to these (eg. scanimage --resolution=300 | ocrad - ). There is
also tesseract ocr, but I haven't got that working although it came from
a commercial OCR package from the 1990s as I understand.

Also if you want a GUI, then I think xsane provides a full system to
scan and get OCR, although not as quick as typing in the piped command
above (particularly if you create a script to shorten it).

tesseract-ocr is available under debian and is the greatest free ocr
solution under linux.

Installation and Configuration

Where can I find binary packages?

Orca is now included with most modern Solaris and Linux operating system releases. The Download and Install page contains more information on obtaining and installing several operating systems, and also includes information on building Orca from source code.

Where do I get the Orca sources?

The latest stable sources can always be found at the GNOME ftp site.

The brave can always obtain the latest sources from the orca trunk in the GNOME Subversion (svn) source code repository. The Download and Install page contains more information on building Orca from source code.

How do I build Orca from source?

The Download and Install page contains more information on building Orca from source code.

Do I have to be root and/or install into /usr?

No. You can install to and run orca from nearly anywhere you want, including directories owned by you. When you run ./configure, you can pass it a prefix that points to some other location (e.g., --prefix=$HOME/orca). If you do this, you need to define PYTHONPATH to point to the new lib/python2.4/site-packages directory (e.g., PYTHONPATH=$HOME/orca/lib/python2.4/site-packages). You can then run orca from this new location (e.g., $HOME/orca/bin/orca). NOTE: if you are using Python 2.5, you may need to adjust the PYTHONPATH accordingly.

How do I set up Orca?

The short answer is that when you run orca for the first time, orca will automatically enter setup mode. If you want to run setup at some later point, you can pass the --setup option to orca the next time you run it. Furthermore, while orca is running, you can press Insert+Space to bring up the orca setup window. Finally, orca provides a text setup utility that you can start by passing the --text-setup option to orca. All of these options will create a ~/.orca/user-settings.py file that holds your preferences and will also enable the accessibility infrastructure. You need to log out and log back in for the accessibility infrastructure settings to take effect.

See also the Configuration and Use page for more information.

How do I get Orca to launch automatically when I log in?

See the Configuration and Use page for more information.

How do I set up accessible login?

See the Accessible Login page for more information.

How do I get Orca working with Java applications?

In order to access Java applications, you need to install and set up the Java access bridge. The Java access bridge for GNOME page provides information on installing and setting up the Java access bridge.

Does Orca work on GNOME 2.12 (Solaris 10, Ubuntu 5.10, Fedora Core 4, etc.)?

Orca works best with GNOME 2.22 or later. See the Download and Install page for information on obtaining and installing more modern operating systems that support Orca out of the box.

Using Orca

How do I run Orca?

Merely run orca. You can do so from a virtual console window if you do not yet have access to the GUI -- orca will automatically enter text setup mode if you run it from a virtual console window or your GUI environment is not yet set up for accessibility.

See also the Configuration and Use page for more information.

What keyboard commands do I use to access the desktop and applications?

Orca is designed to allow you to navigate the desktop and its applications using the standard keyboard navigation mechanisms built into the GNOME platform (see http://developer.gnome.org/projects/gup/hig/2.0/input-keyboard.html).

See also the Configuration and Use page for more information.

What keyboard commands do I use to control Orca?

Orca is designed to allow you to navigate the desktop and its applications using the keyboard navigation mechanisms built into the GNOME platform (see http://developer.gnome.org/projects/gup/hig/2.0/input-keyboard.html). As such, we try to limit the Orca-specific keyboard commands as much as possible. There are occasions, however, where you may want to interact with Orca itself, such as invoking the configuration GUI or escaping to flat review mode to get a better idea of what is on the screen.

Refer to the Configuration and Use page and the Orca Keyboard Commands page for more information on the keyboard commands for Orca.

How do I get Orca to speak alongside other ALSA applications?

NOTE to Ubuntu Hardy users: Ubuntu Hardy is investigating the use of PulseAudio to take care of a lot of device contention. As a result, audio mixing should "just work" on Ubuntu Hardy and you shouldn't have to monkey around with this stuff.

Hotly debated issue, It is not Orca's fault that it is set up like this, so the fix should be done elsewhere, but if you don't care about the politics and simply want it to work then:

sudo apt-get install alsa-oss

now change directory:

cd /usr/lib/bonobo/servers/

now edit using your favorite editor: If you are using Espeak then modify:

GNOME_Speech_SynthesisDriver_Espeak.server

and if you are using Festival:

GNOME_Speech_SynthesisDriver_Festival.server

replace "festival" for "espeak" if you wish to modify the festival synthesizer. On the third line of the file you will see (remember to use dashes instead of underscores):

                type="exe" location="/usr/bin/espeak-synthesis-driver"

replace this with:

                type="exe" location="/usr/bin/aoss /usr/bin/espeak-synthesis-driver"

Note that if the alsa-oss package is not installed then you will have a broken system and wont have any speech output, so make sure it is installed.

save the file, and restart Orca, now you can use mplayer and suchlike to output sound alongside Orca.

What applications does Orca work with?

See the Accessible Applications page.

Does Orca work with Skype?

No. You'll need to ask the Skype team to make their user interface work with the AT-SPI. See also a hack for Pidgin that's still not very accessible.

Does Orca work with KDE?

No. KDE currently does not support the AT-SPI. There's some work being done to make the AT-SPI more amenable to the KDE folks.

How do I do system administration tasks?

See the GNOME System Administration Using Orca page for more information.

Customizing Orca

How do I define my own punctuation or character pronunciations?

Here's an example you can add to your ~/.orca/orca-customizations.py file. Be careful about the syntax -- if you screw it up, you might screw up Orca.

import orca.chnames
orca.chnames.chnames["'"] = "tick"
orca.chnames.chnames['"'] = "quote"
orca.chnames.chnames["!"] = "bang"

The basic idea is that orca.chnames.chnames is a dictionary where the keys are the characters you want to create a pronunciation for and the values are the pronunciation. Note that the above example provides two alternative mechanisms for the keys -- one uses double quote characters to allow you to embed single quotes inside the string, and the other uses single quote characters to allow you to embed double quotes in the string.

How do I define my own keybindings?

You can currently redefine your key bindings for Orca in two main ways. The first way is to be able to choose between the destkop and laptop layouts, which can be selected on the "General" page of the Orca Configuration GUI (press Insert+space to bring up the Orca preferences GUI). For finer-grained control, you can also redefine indivual key bindings on the "Key Bindings" page of the Orca Configuration GUI.

NOTE: the remainder of this answer might be out of date.

Here's an example you can add to your ~/.orca/user-settings.py file. It sets up a global keybinding for Insert+t (Insert is the Orca modifier) to speak and braille "Hello World."

# Set up custom keybindings.
#
import orca.braille
import orca.input_event
import orca.keybindings
import orca.orca
import orca.speech
from orca.orca_i18n import _
def sayHello(script, inputEvent=None):
    message = _("Hello World")
    # Say/braille something.
    #
    orca.speech.speak(message)
    orca.braille.displayMessage(message)
    # Consume the event so it will not go to an application.
    #
    return True
sayHelloHandler = orca.input_event.InputEventHandler(
    sayHello,
    _("Says hello to this fine world."))
myKeyBindings = orca.keybindings.KeyBindings()
myKeyBindings.add(orca.keybindings.KeyBinding(
    "t",
    1 << orca.settings.MODIFIER_ORCA,
    1 << orca.settings.MODIFIER_ORCA,
    sayHelloHandler))
orca.settings.keyBindingsMap["default"] = myKeyBindings

How I can customize Orca so it can speak / braille current date and time information with a keyboard command??

Placing the following lines in ~/.orca/orca-customizations.py (creating it if necessary) should work:

import orca.input_event
import orca.keybindings
import orca.orca
import orca.speech
import orca.braille
import re

myKeyBindings = orca.keybindings.KeyBindings()

def sayTime(script, inputEvent=None):
    import time
    message = time.strftime("%a, %d %b %Y %H:%M:%S", time.localtime())
    orca.speech.speak(message)
    orca.braille.displayMessage(message)
    return True

sayTimeHandler = orca.input_event.InputEventHandler(
    sayTime,
    "Presents the time.")

myKeyBindings.add(orca.keybindings.KeyBinding(
    "d",
    1 << orca.settings.MODIFIER_ORCA,
    1 << orca.settings.MODIFIER_ORCA,
    sayTimeHandler))

orca.settings.keyBindingsMap["default"] = myKeyBindings

NOTE that in this case insert + d will be used to report current information about the time and date.

See also an attached orca-customizations.py that uses Insert+w to speak the weather and Insert+l to switch the translations between your preferred language and German.

How do I set up my own custom script area?

The short answer is that if you create an empty ~/.orca/orca-scripts/__init__.py and place your custom scripts in ~/.orca/orca-scripts, Orca will pick up any scripts from there before looking in the installed area.

Troubleshooting

Orca is not speaking. What's going wrong?

See Troubleshooting Speech.

My desktop has stopped responding. What do I do?

If you can get to a terminal, try restarting Orca by issuing another orca command in a terminal window. This will force any existing Orca process to exit and will then restart Orca. This sometimes has the effect of unhanging the desktop (which is usually due to an ill-behaved application).

Also, if you've just started a program which you believe to be the cause of the problem, press control+alt+d to show the desktop (I do this because if you use system sounds there is a little audio feedback, and if you have useful vision, you can see the difference in brightness). Next, press alt+f2 to get the run box up, and type:

killall appname

where appname is the name of the program (for example pidgin).

If orca hasn't started talking again, use the method outlined above, but enter orca into the run box instead.

Note that when you show the desktop with control+alt+d, and when you press alt+f2 from there to show the run box, if you are using system sounds (configured in your sound preferences), there is some audible feedback which will assist you. Another good audio queue is to take advantage of the new beep at the begining of a line which gnome has started doing. When you think you are in the run box, press backspace, and you should here a beep from your system speaker (if it is enabled), this is another useful trick, and will work at the begining and end of almost any input.

If none of the above methods are successful, try pressing ctrl+alt+backspace to kill the X Window System server. This should have the effect of returning you to the login screen.

I did something that required me to enter a password and my system hung. What's up with that?

The gnome-keyring implementation can be run in synchronous mode or asynchronous mode, and it's unfortunately up to the application developer to decide which mode to use. The synchronous mode is what causes the hang, and you need to log a bug with the application (not Orca and not gnome-keyring) to get them to fix it. See also bug #540146 and comment #9 of bug #447435.

I am using the ubuntu 7.04 live cd, I get the desktop and Orca starts, but it only says "switching to focus tracking mode" Whats wrong with it?

For some reason the version on the cd seem to be broken. If you simply wish to try Orca out, then the ubuntu 6.10 does contain a working Orca. Alternatively, you could use a later version of the live CD (up to 8.04 at the time of this writing). Keep in mind that Orca has a good and fast development, so you will not be able to benefit from the latest accessibility changes and Orca features.

If you are installing to hard drive, then worry not, you will be able to update to the latest version as soon as the install is finished, and (preferably) you have brought your system up-to-date). If you have done so, and would want instructions on how to proceed, visit Orca/DownloadInstall