Do you use an AI agent? Give it this page as Markdown.

Recadio automation reference

This document tells an AI agent how to control Recadio with AppleScript. It is also correct for humans who write scripts.

Recadio is a macOS menu bar app. It selects the audio input device (microphone) and the audio output device (speakers, headphones) automatically, from a priority list that the user sets. Scripts can select a device, remove a lock, and make Recadio skip a device.

Status: beta. The commands can change before the final 2.2 release.
Minimum version: Recadio 2.2-beta.1. Download it from https://www.recadio.com/download-latest-beta
Human docs: https://www.recadio.com/docs
This document as Markdown: https://www.recadio.com/docs/automation.md

#Rules for agents

Run every command on the user's Mac with osascript. If you cannot run shell commands, write the script and give it to the user.
Read the device names before you select, ignore, or unignore a device. Do not guess names.
Use the device name exactly as Recadio returns it. The match ignores case, but it does not accept a part of a name.
Act on one device type at a time. Input commands do not change the output device, and output commands do not change the input device.
After a command that changes a device, read current input device or current output device to confirm the result.
If a command fails, read the error number and use the "Errors" section. Do not retry the same command without a change.
Do not try to change the priority order, rename devices, or change the selection method with a script. Recadio does not support this. Tell the user to use Settings.

#Before you start

Check these conditions in this order.

#1. Recadio is installed

osascript -e 'id of application "Recadio"'

The expected result is com.dgrcode.recadio. An error means that Recadio is not installed.

#2. The version supports scripting

osascript -e 'version of application "Recadio"'

The result must be 2.2-beta.1 or later. Version 2.1 and earlier have no scripting commands. If the version is too old, tell the user to install the latest beta.

#3. Recadio is running

osascript -e 'application "Recadio" is running'

If the result is false, start Recadio and wait a few seconds before you send commands:

open -a Recadio

A tell application "Recadio" block also starts Recadio, but the device lists can be empty while Recadio starts.

#4. macOS allows the automation

The first time that an app controls Recadio, macOS shows a permission dialog. The app is the one that runs osascript, for example Terminal, iTerm, or your agent's host app. The user must click "Allow". If the user does not allow it, every command fails with error -1743. The user can change this in System Settings > Privacy & Security > Automation.

If you run without a visible terminal, the dialog can block your command. Tell the user to look for the dialog.

#5. A license or a trial is active

All commands and all properties need a license or an active trial. Without one, they fail with error -10004. The user can start a free trial in Recadio Settings > License, or buy a license at https://www.recadio.com/#pricing

#Concepts

#Device types

Each command acts on input devices or on output devices. A device that is both an input and an output, such as a USB headset, has a separate state for each type. For example, the user can ignore a headset as an input and still use it as an output.

#Device names

Each device has a system name from macOS, for example MacBook Pro Microphone. The user can also give a device a custom name in Recadio Settings > Devices.

Properties return the custom name if one exists. Otherwise they return the system name.
Commands accept the custom name or the system name.
The match ignores upper and lower case, and spaces at the start or at the end.
The match must be the full name. AirPods does not match AirPods Pro.
A custom name match comes before a system name match. In each group, a connected device comes before a disconnected device.
If the user has two devices with the same name, ask the user to rename one of them in Settings > Devices.

#Selection methods

The user chooses one selection method in Recadio Settings. A script cannot read or change the method.

Priority (the default): Recadio selects the connected device that is highest in the priority list. A selected device becomes locked. A locked device stays selected until the lock is removed.
Connected devices: Recadio remembers a preferred device for each set of connected devices. A selected device becomes the preferred device for the current set. There is no lock.

#Locks

In the Priority method, select input device and select output device lock the device. A lock wins over the priority list and over an ignore. unlock input and unlock output remove the lock, and Recadio selects automatically again.

A script cannot read which device is locked.

#Ignored devices

An ignored device is skipped when Recadio selects a device automatically. If the ignored device is in use, Recadio changes to the next device in the priority list.

An ignore is temporary. Recadio forgets all ignored devices when it quits.
In the Priority method, a lock wins over an ignore. If you select an ignored device, it stays selected until you unlock it. Then Recadio skips it again.
In the Connected devices method, an ignore wins over the preferred device. To use an ignored device, unignore it first.
You can ignore and unignore a disconnected device.

#Properties

Read a property with get, or use it in an expression. All properties are read-only.

#current input device

Text. The name of the input device in use. It is an empty text if Recadio does not know the device.

tell application "Recadio" to get current input device

#current output device

Text. The name of the output device in use. It is an empty text if Recadio does not know the device.

tell application "Recadio" to get current output device

#input devices

List of text. The names of the connected input devices, in priority order. The first item has the highest priority.

tell application "Recadio" to get input devices

Example result from osascript: MacBook Pro Microphone, Shure MV7, AirPods Pro

#output devices

List of text. The names of the connected output devices, in priority order.

tell application "Recadio" to get output devices

#ignored input devices

List of text. The names of the ignored input devices, in priority order. The list can include disconnected devices.

tell application "Recadio" to get ignored input devices

#ignored output devices

List of text. The names of the ignored output devices, in priority order. The list can include disconnected devices.

tell application "Recadio" to get ignored output devices

#Commands

No command returns a value. A command that succeeds returns nothing. A command that fails stops the script with an error.

#select input device

Selects an input device. The device must be connected.

Priority method: the device becomes locked.
Connected devices method: the device becomes the preferred input device for the current set of connected devices.

tell application "Recadio" to select input device "Shure MV7"

Errors: -1728 if no input device has this name. -10000 if the device is not connected, or if macOS does not accept the change.

#select output device

Selects an output device. The rules are the same as for select input device.

tell application "Recadio" to select output device "AirPods Pro"

#unlock input

Removes the lock from the input device. Recadio then selects the input device automatically again. If no input device is locked, the command has no effect. It takes no parameter.

tell application "Recadio" to unlock input

#unlock output

Removes the lock from the output device. The rules are the same as for unlock input.

tell application "Recadio" to unlock output

#ignore input device

Makes Recadio skip an input device in automatic selection. The device can be disconnected. If the device is already ignored, the command has no effect.

tell application "Recadio" to ignore input device "Wireless Microphone"

Errors: -1728 if no input device has this name.

#ignore output device

Makes Recadio skip an output device in automatic selection. The rules are the same as for ignore input device.

tell application "Recadio" to ignore output device "LG Monitor"

#unignore input device

Makes Recadio use an ignored input device in automatic selection again. If the device is not ignored, the command has no effect.

tell application "Recadio" to unignore input device "Wireless Microphone"

Errors: -1728 if no input device has this name.

#unignore output device

Makes Recadio use an ignored output device in automatic selection again. The rules are the same as for unignore input device.

tell application "Recadio" to unignore output device "LG Monitor"

The command is unignore and not stop ignoring, because ignoring is a reserved word in AppleScript.

#Errors

A failed command stops the script. osascript writes the message and the number to standard error, and exits with a status that is not zero. For example:

execution error: Recadio got an error: Recadio can't find an input device named "Shure". (-1728)

#-1728: device not found

Messages:

Recadio can't find an input device named "NAME". or the same message for an output device.
Write the name of the input device. The command has no device name.

What to do: read input devices or output devices, and use a name from the result. Make sure that you use the correct device type.

#-10000: selection failed

Messages:

The input device "NAME" is not connected. You can only select a connected device.
Recadio couldn't select the input device "NAME". macOS did not accept the change.

What to do: read the list of connected devices. If the device is not in the list, tell the user to connect it. If the device is in the list, wait a few seconds and try one more time.

#-10004: license required

Message: Recadio automation needs a license or an active trial.

What to do: tell the user to start a trial or to buy a license. Do not retry.

#-1743: not authorized

Message from macOS: Not authorized to send Apple events to Recadio.

What to do: tell the user to allow the automation in System Settings > Privacy & Security > Automation. Do not retry before the user confirms.

#-600: application isn't running

Recadio quit or did not start. Start it with open -a Recadio, wait a few seconds, and try again.

#Recipes

#Read the full state

tell application "Recadio"
    set report to "Input: " & current input device & linefeed
    set report to report & "Output: " & current output device & linefeed
    set AppleScript's text item delimiters to ", "
    set report to report & "Connected inputs: " & (input devices as text) & linefeed
    set report to report & "Connected outputs: " & (output devices as text) & linefeed
    set report to report & "Ignored inputs: " & (ignored input devices as text) & linefeed
    set report to report & "Ignored outputs: " & (ignored output devices as text)
    set AppleScript's text item delimiters to ""
    return report
end tell

#Select a device only if it is connected

tell application "Recadio"
    if "AirPods Pro" is in output devices then
        select output device "AirPods Pro"
    end if
end tell

#Go back to automatic selection for both types

tell application "Recadio"
    unlock input
    unlock output
end tell

#Toggle the ignore for a device

tell application "Recadio"
    if "Wireless Microphone" is in ignored input devices then
        unignore input device "Wireless Microphone"
    else
        ignore input device "Wireless Microphone"
    end if
end tell

#Continue after a failure

tell application "Recadio"
    try
        select input device "Shure MV7"
    on error errorMessage number errorNumber
        return "Failed (" & errorNumber & "): " & errorMessage
    end try
end tell

#Run from the shell

Use single quotes around the script and double quotes around device names:

osascript -e 'tell application "Recadio" to select output device "MacBook Pro Speakers"'

For a script with more than one line, use one -e for each line, or a heredoc:

osascript <<'EOF'
tell application "Recadio"
    select input device "Shure MV7"
    return current input device
end tell
EOF

#Use from other tools

The same scripts run in Script Editor, in the Shortcuts app with the "Run AppleScript" action, in Keyboard Maestro, and in any other tool that runs AppleScript.

#What a script cannot do

Read or change the selection method.
Read which device is locked.
Change the priority order.
Rename a device.
Change the volume, or make a device that Recadio does not know.
Keep an ignore after Recadio quits.

For these tasks, tell the user to open Recadio Settings.

#Check the dictionary yourself

The app includes its scripting dictionary. To print it:

sdef /Applications/Recadio.app

The Recadio commands are in the "Recadio Suite". The "Standard Suite" is a part of every scriptable macOS app, and Recadio does not add to it.