TROUBLESHOOTING

Issues with Voice Commands

If you encounter issues with voice commands not appearing or working, here’s how those issues can be resolved.

Problem #1: Missing Target Application

On macOS systems, installed voice commands may sometimes not work as expected. Such commands will appear in the Voice Control system preference pane to be installed, but they will be missing a key connection to the targeted Omni application.

If you navigate to the Voice Control tab of the Accessibility system preference pane, and click the “Commands…” button at the bottom right of the window:

The commands editing sheet will appear. Select one of the “problem” custom commands and notice that the popup menu (right side) for indicating the target application is blank!

The missing application name indicates that the local Omni application’s identifier (ID) does not match the one used in the commands file. This issue can be resolved!

Identifying the Target Application

Every application used on Apple devices has a unique identifier, which is used by Voice Control to determine when to make the specified command available to the user — like when OmniFocus is the frontmost application.

Like many other developers, Omni uses multiple versions of its application identifiers, depending on how the application is acquired.

For example, here are the possible application IDs for the macOS version of OmniOutliner:

• com.omnigroup.OmniOutliner5 <— direct download from Omni website
• com.omnigroup.OmniOutliner5.MacAppStore <— The Mac App Store free download
• com.omnigroup.OmniOutliner5.enterprise <— The Mac App Store prepaid download

In a voice commands file, each command has a property named CustomScope that has a value that is an identifier indicating which application is targeted by the command.

In the example command show below, the application identifier for the command is for the Mac App Store version of OmniFocus. However, if the version of OmniFocus on your computer is the direct download version, a mismatch occurs and the voice command fails to be linked to the copy of OmniFocus on your computer!

Voice Command Data
Copy

<key>Custom.669250609.533330</key>
<dict>
	<key>CustomAppName</key>
	<string>OmniFocus</string>
	<key>CustomCommands</key>
	<dict>
		<key>en_US</key>
		<array>
			<string>About OmniFocus</string>
		</array>
	</dict>
	<key>CustomMenuTextList</key>
	<array>
		<string>About OmniFocus</string>
	</array>
	<key>CustomModifyDate</key>
	<string>2022-03-21T18:41:00Z</string>
	<key>CustomScope</key>
	<string>com.omnigroup.OmniFocus3.MacAppStore</string>
	<key>CustomType</key>
	<string>Menu</string>
</dict>

TIP: To look up the application ID for any Omni app, run this script in the app’s Automation Console:

Get Omni Application ID
Copy

URL.currentAppScheme

The VC Commands Adjuster Applet

Automation to the rescue! The VC Commands Adjuster applet (DOWNLOAD) is a small application that “adjusts” a voice commands file to target the version of the Omni application installed on your computer.

To adjust and install an Omni voice commands file:

• Remove the previously installed non-functioning voice commands installed by importing the voice commands file. NOTE: You can use the “Delete All Custom Commands…” option from the Advanced Actions menu in the Voice Control preference pane to clear out all previously installed custom commands. Or you can select the commands to remove in the custom commands list and click the minus button (-) below the list to remove them. (see previous illustration)
• 
• Next, DOWNLOAD and unpack the applet archive file. Launch the applet and follow the spoken instructions to first select the voice commands file to adjust, and then select the copy of the target Omni application on your computer. The applet will announce when it has updated the commands file.
• Lastly, install the adjusted voice commands file using the “Import Custom Commands…” option from the Advanced Actions menu in the Voice Control preference pane. The new commands should show the target Omni application when selected in the commands editing sheet.

Problem #2: Missing Command Phrases

If you install a set of commands and their command phrases are not appearing in the commands sheet (see below) it is an indication that the language used for the commands does not match the language currently in use by the computer.

Each voice command in the commands file has a country locale code like the one shown below for en_CA for Canadian English. If the language used on your computer is not the same as the language represented by this code, the voice command will not be available for use.

Voice Command Data
Copy

<key>Custom.669250609.533330</key>
<dict>
	<key>CustomAppName</key>
	<string>OmniFocus</string>
	<key>CustomCommands</key>
	<dict>
		<key>en_CA</key>
		<array>
			<string>About OmniFocus</string>
		</array>
	</dict>
	<key>CustomMenuTextList</key>
	<array>
		<string>About OmniFocus</string>
	</array>
	<key>CustomModifyDate</key>
	<string>2022-03-21T18:41:00Z</string>
	<key>CustomScope</key>
	<string>com.omnigroup.OmniFocus3.MacAppStore</string>
	<key>CustomType</key>
	<string>Menu</string>
</dict>

A possible solution is to use specialized software, like PlistEdit Pro from Fat Cat Software to open and edit the voice commands file, performing a search and replace with the country code used by your system.

Once the codes have been replaced, save the edited commands file, then delete the existing installed custom commands, and re-import the edited commands file. The commands should now appear properly in the commands list.