AppleScript Automation

Frame-A-Face supports automation on macOS systems using AppleScript. AppleScript allows users to automate image processing tasks such as cropping and exporting images efficiently. With AppleScript, users can integrate Frame-A-Face into their existing workflows and automate tasks with minimal manual intervention.

Enabling AppleScript Automation

AppleScript functionality is always enabled in Frame-A-Face. Users can interact with the program even when the CSV menu options are hidden.

Important: If Frame-A-Face is not running, executing a script will automatically open the application. If you have multiple copies of Frame-A-Face installed, it is recommended to use the full path to the application in the tell command to avoid unexpected behavior.

Running AppleScript Commands

To automate tasks with AppleScript, users can send commands to Frame-A-Face using the tell command. Below is an example AppleScript to run a CSV workflow:

tell application "/Applications/Frame-A-Face.app"
    run CSV workflow "/Users/User/FAFFolder/csvFile.txt"
    repeat
        if process completed then exit repeat
        delay 0.5 -- Wait for 0.5 seconds before checking again
    end repeat
end tell

Using Variables in AppleScript

AppleScript allows the use of variables to dynamically assign file paths and parameters. Here’s an example:

set CSVfile1 to "/Users/User/FAFFolder/csvFile.txt"
tell application "/Applications/Frame-A-Face.app"
    run CSV workflow CSVfile1
    repeat
        if process completed then exit repeat
        delay 0.5 -- Wait for 0.5 seconds before checking again
    end repeat
end tell

Chaining Commands and Checking Completion

Frame-A-Face processes images in multiple background threads and does not block the interface. To avoid simultaneous execution of different scripts, which may lead to unexpected results, it is recommended to always include the following waiting loop in every script:

repeat
    if process completed then exit repeat
    delay 0.5 -- Wait for 0.5 seconds before checking again
end repeat

Processing Individual Files

To process a single image file with a specific preset and export settings:

tell application "/Applications/Frame-A-Face.app"
    process path "/Users/User/Pictures/image1.jpg" output path "/Users/User/Pictures/Output/" preset "Square" suffix "_S" width 800 format "jpg"
    repeat
        if process completed then exit repeat
        delay 0.5 -- Wait for 0.5 seconds before checking again
    end repeat
end tell

Explanation of Commands

run CSV workflow\ Runs an automated workflow based on the provided CSV file. The file must be a valid CSV or TXT containing image processing tasks.

process path\ Processes a single image or all images in a folder with the specified parameters:

path\ Specifies the location of the input image or folder containing images. Supported formats include JPG, PNG, and TIFF.

preset\ The name of an existing Frame-A-Face preset as displayed in the Presets menu.

output path\ Defines the export destination. If the path doesn’t exist, it will be created automatically.

Optional fields:

suffix: A custom suffix added to exported file names. If left empty or omitted, the program uses the preset name as the suffix. To keep the original file name without any suffix, use the * asterisk symbol.

width: Defines the width of the exported image. If not specified, the image is saved in its original cropped dimensions. However, for images using “Masked presets”—where overlays with transparent areas are applied—the export size is always determined by the preset itself.

format: Specifies the output format (“jpg” or “png”). If omitted, the original image format is retained.

Command parameters are the same as those used in CSV Lists.

Example: Chain of Commands

set CSVfile1 to "/Users/User/FAFFolder/csvFile.txt"
set imagePath to "/Users/User/Pictures/image1.jpg"
set outputPath to "/Users/User/Pictures/Output/"

tell application "/Applications/Frame-A-Face.app"
    run CSV workflow CSVfile1
    repeat
        if process completed then exit repeat
        delay 0.5
    end repeat
    
    process path imagePath output path outputPath preset "Square" suffix "_S" width 800 format "jpg"
    repeat
        if process completed then exit repeat
        delay 0.5
    end repeat
end tell

Common Errors and Troubleshooting

If AppleScript does not communicate with Frame-A-Face correctly:

By utilizing AppleScript automation, users can optimize their image processing workflows and achieve consistent, high-quality results.