Manual VoiceOver Setup
If @guidepup/setup
cannot be used for your MacOS workflow, these guides instruct how to setup your MacOS environment manually for VoiceOver automation.
Local Setup
Allow VoiceOver To Be Controlled
This setup is required to allow VoiceOver to be controlled by Guidepup.
Open the "VoiceOver Utility" application.
On the "General" tab, tick the checkbox "Allow VoiceOver to be controlled with AppleScript".
Allow App Automation
This setup is required to allow applications, e.g. your terminal or IDE, to control other applications, i.e. VoiceOver:
- MacOS 12 - Monterey
- MacOS 13 - Ventura
Open the "Security & Privacy" application within "System Preferences". Choose the "Privacy" tab.
Select the "Accessibility" option and click on the padlock to unlock configuration. This will require you to enter an admin username and password.
In the "Allow the apps below to control your computer." section, use the plus "+" button to add any application that you will run a Guidepup script from - this will likely be your preferred terminal or IDE. Ensure you have also ticked the checkbox next to each application that you will run a Guidepup script from.
Open the "Privacy & Security" pane within "System Settings".
Select the "Accessibility" option.
In the "Allow the applications below to control your computer." section, use the plus "+" button to add any application that you will run a Guidepup script from - this will likely be your preferred terminal or IDE. This will prompt you for an administrator password. Ensure you have also ticked the checkbox next to each application that you will run a Guidepup script from.
Additional System Permissions
Depending on how you use Guidepup you may require additional "Security & Privacy" updates with "System Preferences":
- "Location Services"
- "Microphone"
- "Screen Recording"
- "Bluetooth"
- "Automation"
While using Guidepup if a system permission is required a dialog box will pop up automatically asking for the permission. Alternatively you can proactively set these permissions in the same way as the "Accessibility" settings were updated in the previous step.
CI Setup
Allow VoiceOver To Be Controlled
For VoiceOver to be controlled by AppleScript the following needs to be run:
# Create VoiceOver database file specifying automation is enabled
sudo bash -c 'echo -n "a" > /private/var/db/Accessibility/.VoiceOverAppleScriptEnabled'
# Update system preference defaults specifying automation is enabled
defaults write com.apple.VoiceOver4/default SCREnableAppleScript -bool true
Note: for the
.VoiceOverAppleScriptEnabled
file to be created you must first disable "SIP". This can only be performed whilst in Recovery Mode. Please refer to the Apple documentation for more details.
Allow App Automation
In order for applications (e.g. a CI terminal) to control other applications (e.g. VoiceOver) using AppleScript, updates need to be made to the TCC.db
.
Please refer to the following examples of how to update the TCC.db
for your desired application(s):
- @guidepup/setup - Guidepup
TCC.db
setup - actions/virtual-environments - GitHub Actions
TCC.db
setup - CircleCI-Public/macos-orb - CircleCI MacOS Orb
TCC.db
setup
Note: for system TCC.db updates you must first disable SIP. This can only be performed whilst in Recovery Mode. Please refer to the Apple documentation for more details.