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. For complete task examples, see worked examples.
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 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.
{
"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.