Skip to main content

VoiceOver

Implements: ScreenReader

A VoiceOver instance can be used to launch and control VoiceOver.

Here's a typical example using a VoiceOver instance:

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Contents:

voiceOver.commanderCommands​

Getter for all VoiceOver commander commands.

Use with the VoiceOver perform command to invoke a Commander action:

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move down.
  await voiceOver.perform(voiceOver.commanderCommands.MOVE_DOWN);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: <VoiceOverCommanderCommands>

voiceOver.keyboardCommands​

Getter for all VoiceOver keyboard commands.

Use with the VoiceOver perform command to invoke a keyboard action:

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the next item.
  await voiceOver.perform(voiceOver.keyboardCommands.moveToNext);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: <voiceOverKeyCodeCommands>

voiceOver.act([options])​

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

Equivalent of executing VO-Space bar.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Perform the default action for the item.
  await voiceOver.act();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.click([options])​

Click the mouse.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Left-click the mouse.
  await voiceOver.click();

  // Left-click the mouse using specific options.
  await voiceOver.click({ button: "left", clickCount: 1 });

  // Double-right-click the mouse.
  await voiceOver.click({ button: "right", clickCount: 2 });

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.copyLastSpokenPhrase([options])​

Copy the last spoken phrase to the Clipboard (also called the "Pasteboard").

This command is specific to the VoiceOver screen reader.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Copy the phrase spoken by VoiceOver from moving to the next item above to
  // the Clipboard.
  await voiceOver.copyLastSpokenPhrase();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.default()​

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

  • false for Windows
  • true for MacOS
  • false for Linux
import { voiceOver } from "@guidepup/guidepup";

(async () => {
  const isVoiceOverDefaultScreenReader = await voiceOver.default();

  console.log(isVoiceOverDefaultScreenReader);
})();

Returns: <Promise<boolean>>

voiceOver.detect()​

Detect whether VoiceOver is supported for the current OS.

  • false for Windows
  • true for MacOS
  • false for Linux
import { voiceOver } from "@guidepup/guidepup";

(async () => {
  const isVoiceOverSupportedScreenReader = await voiceOver.detect();

  console.log(isVoiceOverSupportedScreenReader);
})();

Returns: <Promise<boolean>>

voiceOver.interact([options])​

Interact with the item under the VoiceOver cursor.

Equivalent of executing VO-Shift-Down Arrow.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Interact with the item.
  await voiceOver.interact();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.itemText()​

Get the text of the item in the VoiceOver cursor.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Get the text (if any) for the item currently in focus by the VoiceOver
  // cursor.
  const itemText = await voiceOver.itemText();
  console.log(itemText);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

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

voiceOver.itemTextLog()​

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

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move through several items.
  for (let i = 0; i < 10; i++) {
    await voiceOver.next();
  }

  // Get the text (if any) for all the items visited by the VoiceOver cursor.
  const itemTextLog = await voiceOver.itemTextLog();
  console.log(itemTextLog);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

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

voiceOver.lastSpokenPhrase()​

Get the last spoken phrase.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Get the phrase spoken by VoiceOver from moving to the next item above.
  const lastSpokenPhrase = await voiceOver.lastSpokenPhrase();
  console.log(lastSpokenPhrase);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Returns: <Promise<string>> The last spoken phrase.

voiceOver.next([options])​

Move the VoiceOver cursor to the next location.

Equivalent of executing VO-Right Arrow.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.perform(command[, options])​

Perform a VoiceOver command.

The command can be a MacOSKeyCodeCommand, MacOSKeystrokeCommand, or VoiceOverCommanderCommands.

import {
  voiceOver,
  VoiceOverCommanderCommands,
} from "@guidepup/guidepup";

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Type using a custom keystroke command.
  await voiceOver.perform({ characters: "my-username" });

  // Keyboard commands available on the VoiceOver instance.
  await voiceOver.perform(
    voiceOver.keyboardCommands.performDefaultActionForItem
  );

  // Commander commands available on the VoiceOver instance.
  await voiceOver.perform(voiceOver.commanderCommands.MOVE_DOWN);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.press(key[, options])​

Press a key on the focused item.

key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found on the MDN key values page. Examples of the keys are:

F1 - F20, Digit0 - Digit9, KeyA - KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

See MacOSKeyCodes for the full range of available keys.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta, Command.

See MacOSModifiers for the full range of available modifiers.

Holding down Shift will type the text that corresponds to the key in the upper case.

If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

Shortcuts such as key: "Command+f" or key: "Command+Shift+f" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Open a find text modal.
  await voiceOver.press("Command+f");

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

  • key <string> Name of the key to press or a character to generate, such as ArrowLeft or a.
  • Optional: options <KeyboardOptions> Additional options.

Returns: <Promise<void>>

voiceOver.previous([options])​

Move the VoiceOver cursor to the previous location.

Equivalent of executing VO-Left Arrow.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move to the previous item.
  await voiceOver.previous();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.saveLastSpokenPhrase([options])​

Save the last spoken phrase and the crash log to a file on the desktop for troubleshooting.

This command is specific to the VoiceOver screen reader.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Save the phrase spoken by VoiceOver from moving to the next item above to
  // a file on the desktop.
  await voiceOver.saveLastSpokenPhrase();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.spokenPhraseLog()​

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

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Move through several items.
  for (let i = 0; i < 10; i++) {
    await voiceOver.next();
  }

  // Get the phrase spoken by VoiceOver from moving through the items above.
  const spokenPhraseLog = await voiceOver.spokenPhraseLog();
  console.log(spokenPhraseLog);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

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

voiceOver.start([options])​

Turn VoiceOver on.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.stop([options])​

Turn VoiceOver off.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // ... perform some commands.

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.stopInteracting([options])​

Stop interacting with the current item.

Equivalent of executing VO-Shift-Up Arrow.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Interact with the item.
  await voiceOver.interact();

  // ... perform some commands.

  // Stop interacting with the item.
  await voiceOver.stopInteracting();

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<void>>

voiceOver.takeScreenshot([options])​

Takes a screenshot of the item focussed in the VoiceOver cursor and returns the path to screenshot file.

This command is specific to the VoiceOver screen reader.

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

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

  // Take a screenshot of the item focussed in the VoiceOver cursor.
  const screenshotFile = await voiceOver.takeScreenshot();
  console.log(screenshotFile);

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

Returns: <Promise<string>> The path to the screenshot file.

voiceOver.type(text[, options])​

Type text into the focused item.

To press a special key, like Control or ArrowDown, use voiceOver.press(key[, options]).

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

(async () => {
  // Start VoiceOver.
  await voiceOver.start();

  // Type a username and key Enter.
  await voiceOver.type("my-username");
  await voiceOver.press("Enter");

  // Stop VoiceOver.
  await voiceOver.stop();
})();

Parameters:

  • text <string> Text to type into the focused item.
  • Optional: options <CommandOptions> Additional options.

Returns: <Promise<void>>