# Advanced Renamer .aren JSON project format reference

This reference describes reusable JSON `.aren` projects accepted by the Advanced Renamer **4.29**. For an introduction and a complete file, see [Generate Advanced Renamer .aren files](index.md). For complete task examples, see [worked examples](examples.md).

## File representation

Use UTF-8 JSON with one root object. JSON property names are case-sensitive. Use the lowercase identifiers shown here. No comments, trailing commas, Markdown fences, or executable wrapper belong in an `.aren` file.

The recommended authoring profile requires `type`, `batchmode`, `pairrename`, `foldermode`, `namecollision.rule`, and a `methods` array, even though the application can load files with fewer fields. For `batchmode: "rename"`, include at least one active method. For `move` or `copy`, `methods: []` is valid when filenames should stay unchanged; supply the destination in `outputfolder`. This makes generated intent explicit. Each method includes `methodname` and `active`; text methods also include `applyto`.

The [companion JSON Schema](aren-project.schema.json) checks this authoring profile. It intentionally rejects unknown fields rather than covering every historical or full-project file the application can load. It does not prove regex validity, tag validity, filename validity, or the intended transformation. Optional application-saved fields `program`, `version`, and `tagpage`, described below, are outside that schema; omit them in schema-validated generated files.

## Root properties

| Property | JSON type | Meaning / loading behavior |
| --- | --- | --- |
| `type` | string | Required. Always use `"project"`. |
| `batchmode` | string | Required. `"rename"`, `"move"`, or `"copy"`. Specify explicitly. |
| `pairrename` | boolean | Pair renaming. Prefer `false` enable only when the user intends paired-file behavior. |
| `namecollision.rule` | string | Collision rule identifier; use `"fail"` for a routine project. |
| `namecollision.separator` | string | Separator for collision rules that append text; defaults to `"_"`. |
| `namecollision.pattern` | string | Pattern for `append_pattern` or `newname` collision rules; defaults to `""`. |
| `namecollision.startvalue` | string | Start value for collision rule `append_number` or `append_character`; defaults to `""`. Use an explicit suitable value when choosing those rules. |
| `outputfolder` | string | Destination folder mask for move/copy mode. Use a real destination appropriate to the user's OS; supports tags. Omit when batchmode is `"rename"`. |
| `foldermode` | boolean | Required. `false` processes files; `true` processes folders. Copying folders is unsupported. |
| `program` | string | Optional application identity, written by the application. Generated projects can omit it. |
| `version` | integer | Optional application build identifier, not a schema version. Generated projects can omit it. The writer encodes major × 1,000,000 + minor × 10,000 + release × 100 + build; 4.29.0.0 is `4290000`. |
| `methods` | array of objects | Methods to execute in order. For rename, include at least one active method. For move/copy without renaming, use `[]`. |

The collision property names contain literal dots. For example, `"namecollision.rule": "fail"` is correct. A nested `"namecollision": {"rule": "fail"}` object is not the same setting.

### Collision rules

| Identifier | Purpose | Relevant additional properties |
| --- | --- | --- |
| `fail` | Report collisions rather than resolving them by altering the names. | None. |
| `ignore` | Ignore later items that collide with an earlier batch destination. | None. |
| `append_number` | Append a number to resolve duplicate destinations. | `namecollision.separator`, `namecollision.startvalue`, e.g. `"1"`. |
| `append_character` | Append an alphabetic sequence. | `namecollision.separator`, `namecollision.startvalue`, e.g. `"A"`. |
| `append_imgsubsec` | Append image subseconds. | `namecollision.separator`; needs metadata. |
| `append_pattern` | Append a tag/text pattern before the extension. | `namecollision.separator`, `namecollision.pattern`. |
| `newname` | Use a replacement basename mask for collision resolution, retaining the extension. | `namecollision.pattern`. |

## Common method properties

| Property | JSON type | Default when omitted | Meaning |
| --- | --- | --- | --- |
| `methodname` | string | No usable default | Exact method identifier from the sections below. |
| `active` | boolean | `true` | Required. Execute this method. |
| `description` | string | `""` | Optional method description. |
| `condition` | object | No active condition | Optional per-item condition. |
| `applyto` | string | Usually `"name"` | For text methods: `"name"`, `"extension"`, or `"nameandextension"`. Timestamp uses a different vocabulary. |

`name` means the basename without the final extension and preserves the **current** extension. `extension` selects the extension without its leading dot. `nameandextension` selects the full filename.

In method tables below, “default” means the JSON loading default, including fallback applied after reading an empty string.

## New Name — `newname`

Replaces the whole name with a mask containing text and tags.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `mask` | string | `""` | New-name mask, e.g. `"Photo_<Inc Nr:001>"`. Empty mask leaves the name unchanged. |

Use `applyto: "name"` to keep the current extension. Do not add `.<Ext>` to such a mask unless a duplicate extension is intended.

## Replace — `replace`

Replaces matches in the selected portion of the current name.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `replace` | string | `""` | Search text, wildcard/pattern list, or regular expression. |
| `replacewith` | string | `""` | Replacement text; supports tags and, in regex mode, capture references such as `$1`. |
| `casesensitive` | boolean | `false` | Case-sensitive matching. |
| `regularexpressions` | boolean | `false` | Interpret the search as a regular expression. |
| `occurrence` | integer | `0` | `0` replaces all matches; a positive value chooses an occurrence. |

In non-regex mode, `/` and `\` separate patterns, and `*` can enable wildcard behavior.

## Add — `add`

Inserts text in the selected portion of the current name.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `add` | string | `""` | Text or tag mask to insert.  |
| `position` | string | `"1"` | Insertion position. |
| `backwards` | boolean | `false` | Resolve positions from the end. |
| `regularexpressions` | boolean | `false` | Use regular expressions when resolving a position pattern. |

Prefix: `position: "1", backwards: false`. Suffix: `position: "0", backwards: true`. When `applyto` is `name`, the suffix goes before the extension.

## New Case — `newcase`

Changes capitalization of the selected portion of the current name.

| Property | Type | Default | Allowed values / meaning |
| --- | --- | --- | --- |
| `newcasetype` | string | `"lower"` | Required. `lower`, `upper`, `inverse`, `title`. |
| `newcaselocation` | string | `"all"` | Required. `all`, `firstletter`, `firstletter_word`, `pattern`, `position`. |
| `pattern` | string | `""` | Match pattern when location is `pattern`. |
| `regularexpressions` | boolean | `false` | Regex matching for location `pattern`. |
| `posstart` | string | `""` | Start position when location is `position`; Use number in string for numeric value, `"1"`. |
| `poscount` | string | `""` | Character count when location is `position`; Use number in string for numeric value, `"10"`. |
| `applylowercasefirst` | boolean | `false` | Lowercase the selected name portion before applying the case change. Available only for `upper` or `title`, subject to the location rules below. |
| `ignorewordsallcaps` | boolean | `false` | Preserve words already entirely in capitals. Available for `firstletter_word` with any case type, or `all` with `title`. |

| `newcaselocation` | Case types allowing `applylowercasefirst` | Case types allowing `ignorewordsallcaps` |
| --- | --- | --- |
| `all` | `title` | `title` |
| `firstletter` | `upper`, `title` | None |
| `firstletter_word` | `upper`, `title` | `lower`, `upper`, `inverse`, `title` |
| `pattern` | `upper`, `title` | None |
| `position` | `upper`, `title` | None |

For generated projects, omit an option or set it to `false` outside these combinations. Both options can be enabled together where both columns allow the chosen case type. With `applylowercasefirst`, lowercasing applies to the whole portion selected by `applyto` before the location-specific change; it is not limited to the matched pattern or position range. When both options are enabled, all-capital words are also preserved during that preliminary lowercasing.

## Remove — `remove`

Removes characters by position, pattern, or character category.

| Property | Type | Default | Allowed values / meaning |
| --- | --- | --- | --- |
| `removetype` | string | `"position"` | `position`, `pattern`, `diacritics`, `wordchars`, `nonwordchars`, `uppercase`, `lowercase`, `charlist`, `numbers`, `notnumbers`. |
| `start` | string | `"1"` | Start position for positional removal. |
| `count` | string | `"1"` | Count for positional removal. |
| `pattern` | string | `""` | Pattern when `removetype` is `pattern`. |
| `backwards` | boolean | `false` | Resolve positional removal from the end. |
| `regularexpressions` | boolean | `false` | Regex matching when using a pattern. |
| `casesensitive` | boolean | `false` | Case-sensitive matching where applicable. |
| `charlist` | string | `""` | Characters for `charlist` removal. |
| `charexceptions` | string | `""` | Character exceptions for supported category-removal modes. |
| `location` | string | `"anywhere"` | `anywhere`, `start`, `end`. Applies only to `pattern`, `wordchars`, `nonwordchars`, `numbers`, and `notnumbers`; ignored for all other removal types. |

## Remove Pattern — `removepattern`

*Deprecated*. The older separate pattern-removal method remains loadable. Use `remove` method type with `removetype: "pattern"` instead.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `pattern` | string | `""` | Pattern to remove. |
| `casesensitive` | boolean | `false` | Case-sensitive matching. |
| `regularexpressions` | boolean | `false` | Regex matching. |

## Trim — `trim`

Removes selected characters from edges, or throughout the selected name portion.

| Property | Type | Default | Allowed values / meaning |
| --- | --- | --- | --- |
| `characters` | string | `" .,_-"` | A set of characters, not a regex. |
| `location` | string | `"start_and_end"` | `start_and_end`, `start`, `end`, `all`. |
| `casesensitive` | boolean | `false` | Case-sensitive character comparison. |
| `inversematch` | boolean | `false` | Invert the character selection. |

`location: "all"` removes selected characters everywhere. Edge trimming preserves selected characters inside the untrimmed middle.

## Move — `move`

Moves a segment **within a filename**. This is unrelated to batch mode `move`, which moves files to a destination folder.

Prefer other methods when they can produce the same result. Use `move` when moving a character segment is needed and the alternatives do not express the transformation as clearly.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `movefrom` | string | `"1"` | Source position or position pattern. |
| `movecount` | string | `"1"` | Segment length or count pattern. |
| `moveto` | string | `"1"` | Destination position or position pattern. |
| `relative` | boolean | `false` | Interpret the destination relative to the source, in modes supporting this. |
| `backwards` | boolean | `false` | Resolve positions from the end. |
| `regularexpressions` | boolean | `false` | Regex matching for position/count patterns. |

## Swap — `swap`

Swaps the text before and after a separator in the selected name portion.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `separator` | string | `""` | Required. Exact separator. |
| `occurrence` | integer | `1` | Required. Which separator occurrence to use, 1–10. |

For example, separator `" - "` changes `Artist - Title.mp3` to `Title - Artist.mp3` with `applyto: "name"`.

## Renumber — `renumber`

Changes an existing numeric sequence. To introduce a new counter into a name, use `newname` or `add` with an increment tag instead.

| Property | Type | Default | Allowed values / meaning |
| --- | --- | --- | --- |
| `numberposition` | integer | `1` | Which numeric sequence in the selected portion to change, counting from 1. |
| `change` | string | `"absolute"` | `absolute` assigns a sequence by list position; `relative` adds to the existing number. |
| `newnumber` | integer | `1` | Starting value for absolute renumbering. |
| `numberdifference` | integer | `1` | Amount added for relative renumbering; can be negative. |
| `skip` | integer | `1` | Step for absolute renumbering. |
| `zeropad` | string | `"auto"` | `auto`, `manual`, `no`. |
| `numberlength` | integer | `3` | Minimum number length with manual padding. |
| `negativenumbers` | boolean | `false` | Recognize a preceding minus sign as part of a number. |

Names without the chosen numeric sequence are unchanged. List order affects absolute renumbering. Renumber uses JSON **integers**, unlike Add/Remove position fields.

Renumber can also change the zero padding of existing numbers without changing their numeric values. Set `change: "relative"`, `numberdifference: 0`, `zeropad: "manual"`, and `numberlength` to the desired minimum number length (`NEW_LENGTH`). For example, `numberlength: 4` changes `image_7.jpg` to `image_0007.jpg`.

## List — `list`

Assigns one replacement name per item in list order.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `newnames` | string | `""` | Newline-separated names, e.g. `"First\nSecond\nThird"`. It is a string, not a JSON array. |

## List Replace — `listreplace`

Applies multiple replacement rows to each selected item, in row order.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `replace` | array of strings | `[]` | Search patterns. Unlike `replace` in the single Replace method, this is an array. |
| `replacewith` | array of strings | `[]` | Corresponding replacements. Use the same number of rows as `replace`. |
| `casesensitive` | boolean | `false` | Case-sensitive matching. |
| `regularexpressions` | boolean | `false` | Regex matching. |

Rows run sequentially, so later rows see earlier replacements.

## Script — `script`

Executes an Advanced Renamer JavaScript method. Use ordinary methods when they express the task clearly.

| Property | Type | Default | Meaning |
| --- | --- | --- | --- |
| `script` | string | `"return item.newBasename;"` | Per-item JavaScript method body returning the new selected name portion. Empty input falls back to the default. |
| `prescript` | string | `""` | Pre-batch JavaScript. |

Keep the script inside a JSON string with quotes and newlines escaped.

## Timestamp — `timestamp`

Changes **file timestamps**, not the text of the filename. Renaming a file from a date tag is usually a `newname` task instead.

| Property | Type | Default | Allowed values / meaning |
| --- | --- | --- | --- |
| `applyto` | string | `""` (no targets) | One or more comma-separated targets: `created`, `accessed`, `modified`; e.g. `"created,modified"`. This is not a JSON array. |
| `change` | string | `"absolute"` | `created`, `accessed`, `modified`, `image`, `absolute`, `relative`, `filenamepattern`, `dirnamepattern`, `now`, `metadata`. |
| `year` | integer | `0` | Absolute year or relative year adjustment. |
| `month` | integer | `0` | Absolute month or relative month adjustment. |
| `day` | integer | `0` | Absolute day or relative day adjustment. |
| `hour` | integer | `0` | Absolute hour or relative hour adjustment. |
| `minute` | integer | `0` | Absolute minute or relative minute adjustment. |
| `second` | integer | `0` | Absolute second or relative second adjustment. |
| `pattern` | string | `"<Year>-<Month>-<Day>"` | Date/time extraction pattern for pattern modes. Empty input also gets this default. |
| `metadatafield` | string | `""` | Metadata field identifier for `change: "metadata"`. |

For `absolute`, provide a valid complete date and time. For `relative`, supply integer offsets, can be negative and zero for unaffected units. `filenamepattern`/`dirnamepattern` extract date components from the source basename/folder name. Available `metadatafield` depends on items in the batch and their metadata.

## Per-item conditions

A condition selects which items a method changes. Put it inside that method, not at the root. The List, Script, and Timestamp do not support this common condition object; omit it on those methods.

```json
{
  "active": true,
  "field": "ext",
  "match": "equals",
  "pattern": "jpg/jpeg",
  "notmatching": false
}
```

This condition selects original extensions `jpg` or `jpeg`, ignoring case. Extension condition values omit the leading dot.

| Property | Type | Default | Allowed values / meaning |
| --- | --- | --- | --- |
| `active` | boolean | `false` | Must be `true` to enable the condition. This default differs from method `active`. |
| `field` | string | `"name"` | `name`, `newname`, `ext`, `newext`, `path`, `pathandname`, `newpathandname`, `metadata`. |
| `match` | string | `"contains"` | `contains`, `startswith`, `endswith`, `equals`, `regex`, `lengthshorter`, `lengthlonger`. |
| `pattern` | string | `""` | Search expression, alternatives, regex, or decimal length threshold. Empty pattern does not filter items. |
| `notmatching` | boolean | `false` | Invert a nonempty active condition. |
| `metadatafield` | string | `""` | Required for field `metadata`. |

Conditions use case-insensitive matching. For `contains`, `startswith`, `endswith`, and `equals`, `/` or `\` separates alternatives, with any matching alternative sufficient.
