Photoshop Actions File Format

Contents

This document is intended to provide missing information about the format of Photoshop actions files. It complements and slightly corrects the original "official" information found in the Actions section (Additional File Formats) of the page Adobe Photoshop File Formats Specification.

Note: unless indicated otherwise, all multi-byte values, i.e., integer numbers (including C-style 4-character constants), floating-point (double) numbers, and Unicode characters are coded in big-endian format.

File format

Actions palette file

Actions palette file header

Actions file

Actions file header

Action set

Action

Command

Action Manager format

Boolean

Byte string

Class

Double

Enumerated

File alias

File path

ID

Identifier

Index

Integer

Item

Key-item pair

Large integer

List

Name

Object

Offset

Property

Raw data

Reference

Reference item

Unicode string

Unit double

Object array format

Object array

Object array key-item pair

Unit doubles

Specific handling

The 'ObAr' item type (assumed to be an "Object Array") can be found in some actions files, for instance in the file "Frames.atn" located in the "Presets/Actions" folder alongside the Photoshop application. This specific item type is not only undocumented, but also cannot appear directly in an ActionDescriptor since there are no associated methods putObjectArray or getObjectArray to handle it with.

In addition, it should be noted that the 'UnFl' item type (assumed to be a "Unit Floats") is not defined either (not to be confused with the standard 'UntF' item type). Consequently, the object array is altogether a very special case which requires further conversion/translation.

In practice, the object array seems to be only used to describe a polygon made of a list of points (recorded while setting a selection using the Lasso tool, Polygonal Lasso tool, or Magnetic Lasso tool). It is clearly a "packed" format, used only in serialized form inside an actions file, in order to save space by factorizing unnecessarily repeated data, such as the class (point) and keys (horizontal and vertical) of each object, as well as the common unit (distance/percent/pixels) for all double coordinates, seeing that the number of points can be quite important, especially when doing a freehand selection with the Lasso tool.

Here is a quick-and-dirty JavaScript code snippet defining a function which computes how an object array would actually appear in a byte stream in "unpacked" format; it assumes that the current position in the parsed actions file is set just after a recognized 'ObAr' item type; it returns a byte stream beginning with a 'VlLs' item type, indicating that it represents a standard ActionList:

function toListStream (file)
{
    function toBEIntValue (bytes)
    {
        var intValue = 0;
        for (var index = 0; index < bytes.length; index++)
        {
            intValue = (intValue << 8) + bytes.charCodeAt (index);
        }
        return intValue;
    }
    function readUnicodeString (file)
    {
        var unicodeLength = file.read (4);
        var unicodeLengthValue = toBEIntValue (unicodeLength);
        var unicodeString = file.read (unicodeLengthValue * 2);
        return unicodeLength + unicodeString;
    }
    function readId (file)
    {
        var idLength = file.read (4);
        var idLengthValue = toBEIntValue (idLength);
        var id = file.read ((idLengthValue) ? idLengthValue : 4);
        return idLength + id;
    }
    function readClass (file)
    {
        var classUnicodeString = readUnicodeString (file);
        var classId = readId (file);
        return classUnicodeString + classId;
    }
    //
    var objCount = file.read (4);
    var objCountValue = toBEIntValue (objCount);
    var objClass = readClass (file);
    var itemCount = file.read (4);
    var itemCountValue = toBEIntValue (itemCount);
    var itemKeyId = [ ];
    var itemUnitId = [ ];
    var itemDoubles = [ ];
    for (var itemIndex = 0; itemIndex < itemCountValue; itemIndex++)
    {
        itemKeyId.push (readId (file));
        var itemType = file.read (4);
        if (itemType !== 'UnFl')
        {
            throw new Error ("Unrecognized item type!");
        }
        itemUnitId.push (file.read (4));
        var doublesCountValue = toBEIntValue (file.read (4));
        if (doublesCountValue !== objCountValue)
        {
            throw new Error ("Inconsistent object count!");
        }
        itemDoubles.push (file.read (doublesCountValue * 8));
    }
    //
    var listStream = 'VlLs' + objCount;
    for (var objIndex = 0; objIndex < objCountValue; objIndex++)
    {
        listStream += 'Objc' + objClass + itemCount;
        for (var itemIndex = 0; itemIndex < itemCountValue; itemIndex++)
        {
            listStream += itemKeyId[itemIndex] + 'UntF' + itemUnitId[itemIndex];
            listStream += itemDoubles[itemIndex].substr (objIndex * 8, 8);
        }
    }
    return listStream;
}

Descriptor parsing

An interesting parsing strategy relies on the fact that each command's descriptor data found in the actions file matches the serialized format expected by the ActionDescriptor.fromStream method (in JavaScript), or by the corresponding HandleToDescriptor routine of the ActionDescriptor suite (in C/C++), except that it lacks the 4-byte header whose value in big-endian format is identical to the version number of the actions file itself (= 16).

Once the missing header is inserted at the beginning, each command's descriptor data can be easily decoded into an ActionDescriptor. It should be noted that object array ('ObAr') item types are correctly handled, i.e. automatically unpacked and converted to appropriate ActionList items.

The main drawback of that parsing method lies in the fact that each command's descriptor data is just a byte stream whose length is not known beforehand; as a result, it is still necessary to pre-decode each descriptor data by skipping all its fields, in order to compute its entire length and keep synchronized with the rest of the actions file. Surprisingly enough, the 32-bit field preceding the descriptor data is used as a boolean (0: no descriptor, or -1: descriptor) while it would have just been the right place to hold that useful length information...

Dialog mode

Decision table

Parsing an actions file can be used in different ways, for instance to play an action without the need to load the file in the Actions Palette.

For each command in the action, the app.executeAction method can be called with the "event ID" and the "action descriptor" directly available from the resulting data, whereas the dialog mode requires both "dialog options" and "with dialog" to be taken into account.

The "dialog options" value is set once and for all at the time of recording the action, while the "with dialog" flag can be interactively modified by the user in the Actions palette, by clicking in the toggle dialog visual mark located on the left of each command of the action, provided the mark is both visible and enabled.

Dialog options	With dialog	Toggle dialog visual mark (Actions palette)		Dialog mode for app.executeAction
0	false	OFF		DialogModes.NO
	true	ON		DialogModes.ALL
1	false	Always ON		DialogModes.ALL
	true
2	false	Always OFF		DialogModes.NO
	true
3	false	Always OFF		DialogModes.ALL
	true

Dialog recording options

While recording an action from the Actions palette, running a dedicated automation plug-in such as the JSON Event Listener, part of the JSON Action Toolbox, is very useful to monitor the event, descriptor, and dialog options associated with each recorded command.

Here are the different values of dialog opions that can be encountered in practice:

Notes:

• Values 3 and 4 are undocumented; what they stand for is a guess based on extensive tests.
• Examples of user actions resulting in specific conditions (value 3):
  • [Actions palette] > Insert Menu Item... (only for some menu items: Blur, Free Transform, Zoom In, etc.)
  • Image > Adjustments > Equalize (or Equalize... when active selection)
  • File > Import > Scanner XYZ...
  • Filter > Liquify...
  • Filter > Vanishing Point...
• User action bringing on a stop/continue dialog (value 4):
  • [Actions palette] > Insert Stop...
• The value 4 is never recorded as such in the actions file, it is always changed to 0.

Dialog playback options

For the sake of completeness:

Parsing actions files

A practical set of JavaScript functions for parsing actions files is contained in the module jamActions, which is part of the JSON Action Manager scripting library. It is used by three utility scripts:

• Convert Actions File: [Photoshop CS3 or later] convert an actions file (.atn) into a folder of directly executable scripts (.js) which can be further edited.
• Parse Actions File: [Photoshop CS2 or later] parse an actions file (.atn) or an actions palette file (Actions Palette.psp) into a JSON text file.
• Play Actions File Action: [Photoshop CS3 or later] play a specific action contained in an actions file (.atn), without the need to load the file in the Actions Palette.

All files are open-source and licensed under GPLv3; the utility scripts have been successfully tested in Photoshop CS4 on Mac OS X, but should be platform agnostic.

Doc version: 2.6
Date: 2018-04-16
Copyright: © 2012-2018 Michel MARIANI
Disclaimer: this information is provided 'as is' without warranty of any kind, express or implied; use it at your own risk.