Automation

Permute can be automated in several ways.

Shortcuts

On supported macOS versions (macOS 11 or later), you can create automations via UI in the Shortcuts app. Permute supports several actions that can be performed.

Starting with Permute 3.14.1 the conversion shortcut includes a crop parameter so that you can automate your cropping as well.

Apple Script

Firstly, there is the option to use Apple Script - for more details, please see the Apple Script documentation which is viewable via the Script Editor (select Window > Library and double-click Permute on the list - if it’s not listed, use the + toolbar button to add it).

Custom URLs

Additionally, more advanced workflows can be achieved using URLs with permute:// scheme. Downie uses this, for example, to send downloads to Permute. Here is an example of such link:

permute:///Users/charliemonroe/Downloads/file.mp4?action=convert&preset=MP4&source=MyScript

This will create a new group called From MyScript -> MP4 (if necessary), sets the preset to MP4 and adds a file with path /Users/charliemonroe/Downloads/file.mp4 (please note the 3 slashes in the URL - first two are part of the scheme deliminator and the third is the root of the file system, just like with file:///Users/...). Also note that any spaces need to be URL encoded (%20) and so do any special URL characters.

If you have the option to automatically start conversions from external sources enabled in Preferences > Advanced, the conversion will be started automatically.

You can open such link using command line open 'permute://...' (note that & is a special shell character so make sure that the URL is quoted in the command) or any other way you would instruct the system to open a link. If Permute is not being opened by default, you can specify it using the -a argument - either Permute 3 for non-Setapp builds, or just Permute for Setapp builds. Full command would then look like open -a 'Permute 3' 'permute://...'.

If you want to add a stitching conversion, use the path to the folder where are the files (all files need to be in the same folder), set the action argument to stitch and list the file names as file1, file2, … You also need to specify a stitched file name. Here is an example:

permute:///Users/charliemonroe/Downloads/?action=stitch&preset=MP4&source=MyScript&name=foo.mp4&file1=File1.mp4&file2=File2.mp4

In all cases, you can optionally pass a callback URL to get a callback about successful conversion and location of the resulting file. The callback works on basis of URLs, asynchronously and can be used by an app via custom URL schemes, or e.g. with a local server. To do so, pass in the callback parameter. For example:

permute:///Users/charliemonroe/Downloads/file.mp4?action=convert&preset=MP4&source=MyScript&callback=myapp://7452d66e-9260-43f0-97cb-d0467a1143a7

The UUID in this example is not necessary, but it allows you identify the file in the callback easily. What Permute does is that it opens this callback URL with a query that contains:

So in the end, Permute will call myapp://7452d66e-9260-43f0-97cb-d0467a1143a7?success=true&file=/Volumes/Destination/file.mp4 for a successful conversion and myapp://7452d66e-9260-43f0-97cb-d0467a1143a7?success=false for unsuccessful conversions.

Here is an overview of supported query parameters:

Alternatively, if this seems to be too complicated, you can pass files to Permute normally (just open them with Permute, like open -a Permute\ 3 file.mp4), then add a one-second delay for the file to get processed by Permute and use this Apple Script:

tell application "Permute 3"
	 repeat with aGroup in groups
		start aGroup
	end repeat
end tell

Which will start any pending conversions.

Note: Setapp users need to use tell application "Permute" instead.

Workshop Automation [BETA]

⚠️ This feature is currently in beta.
This mainly means that the feature can change in future releases slightly. 
If your workflow gets broken by an update, please check this help article.

Permute’s Workshop is a set of additional features in Permute that don’t really follow the traditional workflow - they e.g. combine multiple different files, or require some setting up. This section describes how to use these features from an external workflow.

Similar to the above, these features can be invoked via a URL. All URLs that use the Workshop modules use the scheme permute-workshop followed by the module name:

permute-workshop://module?parameter1=...&parameter2=...

Concrete example using the Apply PDF Filter:

open 'permute-workshop://pdf-filter?file=/Users/charliemonroe/Downloads/file.pdf&filter=Blue%20Tone'

This applies the Blue Tone filter on file.pdf.

You can pass the following parameters to all the modules as well: destination, name, remove_original, callback - see above for information about the individual parameters.

⚠️ Given the beta status, not all modules are supported at the moment. Please contact us in case the module you are interested in using is not currently supported.

Apply PDF Filter

Name: pdf-filter

Parameters:

Audio to Video

Name: audio-to-video

Parameters:

File Cutter

Name: file-cutter

Parameters:

HLS Generator

Name: hls-generator

Parameters:

Multi-Preset

Name: multi-preset

Parameters:

PDF Merge

Name: pdf-merge

Parameters:

PDF to Images

Name: pdf-to-images

Parameters:

Text to Speech

Name: text-to-speech

Parameters:

Video to Images

Name: video-to-images

Parameters:

Apps that integrate with Permute