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 { voiceOver } 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>>