Skip to main content

Orca

Implements: IScreenReader

An Orca instance can be used to launch and control Orca on Linux. The API is currently available through the unstable unstable_orca export.

Here's a typical example using an Orca instance:

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  // Start Orca.
  await unstable_orca.start();

  // Move to the next item.
  await unstable_orca.next();

  // Stop Orca.
  await unstable_orca.stop();
})();

Contents:

unstable_orca.keyboardCommands​

Getter for the Orca keyboard commands supported by Guidepup.

Use a command with perform to invoke it:

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  // Start Orca.
  await unstable_orca.start();

  // Move to the next item.
  await unstable_orca.perform(unstable_orca.keyboardCommands.MoveToNextSibling);

  // Stop Orca.
  await unstable_orca.stop();
})();

Each command includes its command name, description, keyboard representation, and Orca service.

See OrcaKeyCodeCommands for the available commands.

Returns: OrcaKeyCodeCommands

unstable_orca.name​

Getter for the screen reader name "Orca".

import { unstable_orca } from "@guidepup/guidepup";

console.log(unstable_orca.name); // "Orca"

Returns: string

unstable_orca.version​

Getter for the Orca version.

import { unstable_orca } from "@guidepup/guidepup";

console.log(unstable_orca.version);

Returns: string

unstable_orca.act([options])​

Perform the default action for the item in the Orca cursor.

Equivalent of executing Orca+Control+Enter.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.next();
  await unstable_orca.act();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.capture(action[, options])​

Capture Orca output produced while an action runs. The action can be performed using an external automation tool such as Playwright. The returned capture contains the action's result and the Orca output associated with the action.

import { test } from "@playwright/test";
import { unstable_orca } from "@guidepup/guidepup";

test("capture Orca output while clicking a button", async ({ page }) => {
  await unstable_orca.start();

  const capture = await unstable_orca.capture(() =>
    page
      .getByRole("button", {
        name: "Submit",
      })
      .click(),
  );
  console.log(capture);

  await unstable_orca.stop();
});

Parameters:

  • action () => Promise<T> | T The action to perform while capturing Orca output.
  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<Capture<T>> The action's result and captured Orca output.

unstable_orca.clearItemTextLog()​

Clear the log of all spoken phrases for this Orca instance.

For Orca this is the same as clearSpokenPhraseLog.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.clearItemTextLog();
  await unstable_orca.stop();
})();

Returns: Promise<void>

unstable_orca.clearSpokenPhraseLog()​

Clear the log of all spoken phrases for this Orca instance.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.clearSpokenPhraseLog();
  await unstable_orca.stop();
})();

Returns: Promise<void>

unstable_orca.click([options])​

Click the mouse.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.click({ button: "left", clickCount: 1 });
  await unstable_orca.click({ button: "right", clickCount: 2 });
  await unstable_orca.stop();
})();

Parameters:

Returns: Promise<void>

unstable_orca.default()​

Detect whether Orca is the default screen reader for the current OS:

  • false for Windows
  • false for macOS
  • true for Linux

This detects the operating system; it does not check whether Orca is installed.

import { unstable_orca } from "@guidepup/guidepup";

console.log(unstable_orca.default());

Returns: boolean

unstable_orca.detect()​

Detect whether Orca is supported on the current operating system:

  • false for Windows
  • false for macOS
  • true for Linux

This detects the operating system; it does not check whether Orca is installed. start() will fail if Orca is not installed.

import { unstable_orca } from "@guidepup/guidepup";

console.log(unstable_orca.detect());

Returns: boolean

unstable_orca.getSetting(key)​

Returns the value of a setting for this Orca instance.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  console.log(
    unstable_orca.getSetting("/org/gnome/orca/default/speech/enable"),
  );
  await unstable_orca.stop();
})();

Parameters:

  • key string The setting name.

Returns: unknown The setting value.

unstable_orca.getSettings()​

Returns all the current settings for this Orca instance.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  console.log(unstable_orca.getSettings());
  await unstable_orca.stop();
})();

Returns: Record<string, unknown> Current settings values.

unstable_orca.interact([options])​

Interact with the item under the Orca cursor.

Equivalent of executing Orca+Control+Down Arrow.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.next();
  await unstable_orca.interact();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.itemText()​

Get the text of the item in the Orca cursor.

For Orca this is the same as lastSpokenPhrase.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.next();
  console.log(await unstable_orca.itemText());
  await unstable_orca.stop();
})();

Returns: Promise<string> The item's text.

unstable_orca.itemTextLog()​

Get the log of all visited item text for this Orca instance.

For Orca this is the same as spokenPhraseLog.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  for (let i = 0; i < 10; i++) {
    await unstable_orca.next();
  }
  console.log(await unstable_orca.itemTextLog());
  await unstable_orca.stop();
})();

Returns: Promise<Array<string>> The item text log.

unstable_orca.lastSpokenPhrase()​

Get the last spoken phrase.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.next();
  console.log(await unstable_orca.lastSpokenPhrase());
  await unstable_orca.stop();
})();

Returns: Promise<string> The last spoken phrase.

unstable_orca.next([options])​

Move the Orca cursor to the next location.

Equivalent of executing Orca+Control+Right Arrow.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.next();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.nextHeading([options])​

Move the Orca cursor to the next heading.

Equivalent of executing H.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.nextHeading();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.nextLandmark([options])​

Move the Orca cursor to the next landmark.

Equivalent of executing D.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.nextLandmark();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

Move the Orca cursor to the next link.

Equivalent of executing K.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.nextLink();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.perform(command[, options])​

Perform an Orca keyboard command.

The command can be any OrcaKeyCodeCommand exposed through OrcaKeyCodeCommands, available as unstable_orca.keyboardCommands or the orcaKeyCodeCommands export.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.perform(unstable_orca.keyboardCommands.MoveToNextSibling);
  await unstable_orca.stop();
})();

Parameters:

  • command OrcaKeyCodeCommand Orca keyboard command.
  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.previous([options])​

Move the Orca cursor to the previous location.

Equivalent of executing Orca+Control+Left Arrow.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.previous();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.previousHeading([options])​

Move the Orca cursor to the previous heading.

Equivalent of executing Shift+H.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.previousHeading();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.previousLandmark([options])​

Move the Orca cursor to the previous landmark.

Equivalent of executing Shift+D.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.previousLandmark();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

Move the Orca cursor to the previous link.

Equivalent of executing Shift+K.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.previousLink();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.press()​

press is part of the shared screen reader API, but it is not currently implemented for Orca. Calling it throws an error.

unstable_orca.spokenPhraseLog()​

Get the log of all spoken phrases for this Orca instance.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  for (let i = 0; i < 10; i++) {
    await unstable_orca.next();
  }
  console.log(await unstable_orca.spokenPhraseLog());
  await unstable_orca.stop();
})();

Returns: Promise<Array<string>> The spoken phrase log.

unstable_orca.start([options])​

Turn Orca on. Orca must be installed on Linux.

By default, capture is set to "initial": it captures the first page of output, but not subsequent content. Set capture to true for full capture or false to disable capture.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  // ... perform some commands.
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<StartOptions, "capture" | "settings"> Capture and screen reader settings options.

Returns: Promise<void>

unstable_orca.stop()​

Turn Orca off.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  // ... perform some commands.
  await unstable_orca.stop();
})();

Returns: Promise<void>

unstable_orca.stopInteracting([options])​

Stop interacting with the current item under the Orca cursor.

Equivalent of executing Orca+Control+Up Arrow.

import { unstable_orca } from "@guidepup/guidepup";

(async () => {
  await unstable_orca.start();
  await unstable_orca.next();
  await unstable_orca.stopInteracting();
  await unstable_orca.stop();
})();

Parameters:

  • Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

unstable_orca.type()​

type is part of the shared screen reader API, but it is not currently implemented for Orca. Calling it throws an error.