Permute · Help
Jump to
Shortcuts Drop Zones Custom URLs

Automation

Permute can be automated in several ways.

Shortcuts

You can create automations via UI in the Shortcuts app. Permute supports several actions that can be performed. This is the recommended way.

Drop Zones

You can create drop zones which are simple drag and drop actions. See the Drop Zones help article for more information.

See alsoDrop Zones

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 Settings > Destination, conversions added via such links will be started automatically.

You can open such a 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 4 for non-Setapp builds, or just Permute for Setapp builds. Full command would then look like open -a 'Permute 4’ '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:

  • success - with the value being either true or false
  • file - path to the output file in case the conversion was successful

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:

  • action - either convert or stitch
  • preset - name of the preset to use
  • source - optional - is used for grouping conversions
  • callback - optional - callback to be called when the conversion finishes (see above for details)
  • destination - optional - path to a folder that should be used as destination
  • remove_original - optional - pass true in case you want Permute to remove the input file when done. Note that Permute only moves the file to Trash, it does not delete it.
  • name - in case action is stitch, a name of the output file is required
  • file[N] - in case action is stitch, a list of files to stitch. [N] is the index of the file, starting with 1 (i.e. file1, file2, …)
  • custom_group - optional - if set, then the file will be added into a custom group.
  • trim - optional - if set, then the file will be trimmed in length (audio and video only). The format is start:stop where both start and stop are in seconds (floating point is allowed - i.e. 1.5 will be 1.5 seconds). If you omit one value, then it will be taken as the beginning or end of the file. Examples:
  • :10 - keep only first 10 seconds (0 - 10)
  • 10: - drop first 10 seconds (start at 10 seconds)
  • 10:90 - between 00:10 and 01:30
  • crop - optional - if set, then the file will be cropped (video and images only). The format is x;y;width;height. All values are required and the crop will start at x;y and will be width;height in size. x = 0 is the leftmost pixel, y = 0 is the bottom pixel (i.e. 0;0 coordinate is the bottom-left corner).