Advanced Renamer .aren technical reference for LLMs

Markdown source · Complete reference (text) · JSON Schema

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.