The Settings-Rename template editor is used to create and modify rename templates.
The Template name field is the unique name associated with the template.
Tabs and newline characters may be used to provide formatting to make it easier to read the template. They are ignored when processing the template. Space characters are meaningful and are displayed as a centered-dot character to make it easier to see them. The Format button can be used to apply formatting to the current template. If for any reason you want to remove the formatting and display the template as a single line of text, hold down the Shift key and click on the Format button.
Characters in text strings can be escaped. Currently the only meaningful escape sequence is the ability to specify a centered-dot character which is used to represent spaces for visibility reasons. The escape sequence is \. (backslash-period). All other escape sequences insert the escaped character. eg. \\ will insert \
Tokens are inserted via the Add Token button or via the context menu. Holding down the Control key while entering an alphabetic character will display an abbreviated menu displaying only those menu items beginning with the specified character.
The font size can be changed by Font>Bigger (⌘+) and Font>Smaller(⌘-)
You can preview and optionally apply the template by the Preview button.
A template can optionally specify any of the case transformation operations described in Alphabetic Case Transformations.
You can optionally choose to apply Name Exceptions, General Exceptions, Replacements and Roman Numeral capitalization. More information on these settings can be found in Alphabetic Case Transformations.
Spaces to underscores will cause all space characters to be replaced by underscore characters.
You can apply the following encoding changes:
- Remove Accents
- This setting will attempt to remove all accents from characters.
- Force Latin-1
- This setting attempts to ensure that every character in the result can be represented as an ISO Latin-1 character. It does so by changing various characters to their similar ISO Latin-1 equivalents, removing accents if necessary and as a last resort by changing characters which cannot be represented as ISO Latin-1 to underscore characters. Unicode UNFC, and Fold Characters are applied. See the Re-Encoding Text for more information.
- Force ASCII
- This setting attempts to ensure that every character in the result can be represented as an ASCII character. It does so by changing various characters to their similar ASCII equivalents, removing accents if necessary and as a last resort by changing characters which cannot be represented as ASCII to underscore characters. Unicode UNFC, and Fold Characters are applied. See the Re-Encoding Text for more information.
The Finder has the ability to show or hide filename extensions. When renaming files you can elect to leave the current setting unmodified or to force the state to Hide or Show. Note that any change to the show/hide state is only made if a file is actually renamed.
Some additional advanced setting can be applied via the gear button at the upper right of the panel. If the gear button is preceded by a grey circle, there are no advanced settings currently enabled. If the gear button is preceded by a green circle, there are current advanced settings enabled. Information on the advanced rename settings can be found here.
The Template field describes how the new filename is composed. You may place text or tokens into the definition. Note that the tokens are entered by clicking on the Add Token button or via the context menu. For ease of access, some tokens are placed in submenus. Control alphabetic character will display an abbreviated list of tokens which start with the typed character.
The Renaming and Restructuring Files and Folders online document contains additional information on the use of the rename tokens.
The following table describes those tokens which do not simply map to a field.
| Token | Description |
|---|---|
| Flow Control | |
| IfCompilation | This token is used to test if the file is part of a compilation. The determination is based on the Part of a Compilation field. If the condition is true, all tokens and text until the next associated Else or endIf token will be processed. |
| IfDup | Everything between IfDup and endIf tokens is treated as a repair section to handle the case where files cannot be renamed because the name already exists. It is not uncommon for albums to have more than one track named intro or introduction. If you are renaming all tracks in an album to the title of the track, the rename will fail because more than one track has the same name. IfDup-endIf sections are only used in this case. |
| IfExists item | The IFExists tokens are used to test if an item (field or property) exists (is non empty). If the specified item exists all tokens and text until the next associated Else or endIf token will be processed. Tokens which begin with the following names treat a numeric value of 0 as being equivalent to empty: Disc, Episode, Movement Number, Season and Track. Any custom field defined as being a Yes/No value will also treat a numeric value of 0 as equivalent to being empty. Note that a Yes/No custom field with a case insensitive value of true, is not considered empty. Properties which might not exist are available on a Properties submenu. |
| IfExists+ item | The IFExists+ tokens are a typing convenience. ❨IfExists+ Album❩ ... is equivalent to ❨IfExists Album❩ ❨Album❩ .... It is used when you want to insert the field being tested if it exists. |
| IfFalse item | The IfFalse tokens are used to determine if a particular condition is false. The condition can be one of the following: a property test such as hasVideo, a test if a file is a particular audio type, a test if a track variable is false. A track variable containing true (case insensitive) is not false. Any other text which has an integer value of 0 is treated as false. Remember that Yate determines an integer value by accumulating leading decimal digits. |
| IfLength | This token is used to test if the current length of the name being constructed (in characters) is greater than the value specified in the following integer. If it is, all tokens and text until the next associated Else or endIf token will be processed. eg. Truncate the name if it is greater than 100 characters. ❨IfLength❩100❨Truncate❩100❨Break❩; For historic reasons, negative numbers will be negated. See Filename Lengths for additional information. In many cases it may be easier to control the length of path components by selecting the Settings - Rename - Settings - Automatically truncate path components setting. |
| IfMultiDisc | This token is used to test if the file is part of a multi disc album. A file is considered part of a multi disc album if at least one of the Disc or Disc Count fields is greater than 1. If the condition is true, all tokens and text until the next associated Else or endIf token will be processed. |
| IfMultiple field | The IfMultiple tokens are used to test if a field contains more than one value by testing for the presense of a multi value delimiter in the field. If a multi value delimiter is found all tokens and text until the next associated Else or endIf token will be processed. |
| IfTrue item | The IfTrue tokens are used to determine if a particular condition is true. The condition can be one of the following: a property test such as hasVideo, a test if a file is a particular audio type, a test if a track variable is true. A track variable containing true (case insensitive) is true. Any other text which has an integer value of 0 is treated as false. Remember that Yate determines an integer value by accumulating leading decimal digits. |
| IfVariousArtists | This token is used to test if the file's Album Artist field contains Various Artists (case insensitive). If the Album Artist field contains multiple items separated by the multi value delimiter, true will be returned as long as one of the items is Various Artists. |
| Else | Marks the end of the true processing for an If construct. Everything after the optional Else token is processed up to the next EndIf or Folder Start or end of the template if the condition was false. |
| endIf | Marks the end of processing for an If construct. endIF tokens may be omitted at the end of a template and before a Folder Start token. |
| Folder Start | This token marks the start of the template used to rename a folder path component. The folder portion extends until the end of the template or another Folder Start token is encountered. When the Folder Start token is encountered all previous If sequences are terminated. IfDup sequences are not permitted after this token. Successive Folder Start tokens may be used to process folders higher up the path. Successive Folder Start tokens select path components from the right to the left. eg. /users/me/music/artist/album/filename The first Folder Start token will be renaming the album path component. A second Folder Start token will be renaming the artist path component. If there is no Folder Start token present no folders will not be renamed. If Folder Start is the first token, only folders will be renamed. ie. filenames will not be modified. Note that the rename function operates on the current file selection. However, if folders are renamed, all open files in the renamed folder will have their paths adjusted. Further, if such a file has its path automatically modified and it is linked to an Apple application, the application will be notified of the path change. These automatic changes occur each time an individual path component is changed. The changes cannot be made after all renaming has finished as it becomes impossible to guarantee the correct updating of paths and the notification to Apple applications in the case of an intermediate error. If you do not want to change a folder path component which must be included, specify a Current Folder token for the new name. If there are too many Folder Start tokens to accomodate a track's full path, they are ignored. If the constructed text following the Folder Start token is visually empty an error will be issued. You cannot have empty path components. See the Ignore if Empty token for additional information. |
| Leading Articles | |
| Remove Leading Articles | This token will enable the attempt to remove a single leading article from all fields that are subsequently inserted. The articles are specified in the Settings - Exception Natural Sort Set. |
| Preserve Leading Articles | This token disables any Remove Leading Articles token which might have been specified. |
| Names | |
| Current Filename | Inserts the current value of the filename. |
| Current Folder | Inserts a path component extracted from the file's current path. If there is no Folder Start token active, the name of the file's containing folder will be inserted. If a Folder Start token is active, the folder component associated with the path component being renamed will be inserted. |
| Initial Filename | Inserts the value of the filename when the file was first loaded. | Initial Folder | Inserts a path component extracted from the file's path when the file was first loaded. If there is no Folder Start token active, the name of the file's containing folder will be inserted. If a Folder Start token is active, the folder component associated with the path component being renamed will be inserted. |
| Properties | |
| Bit Depth | Inserts the bit depth of the audio stream if meaningful. |
| Bit Rate | Inserts the bit rate of the audio stream. |
| File Type | Inserts the uppercase file extension. |
| Linked PID | Inserts the value of the Linked PID property (not a potentially saved Apple App PID UDTI). |
| Sample Rate | Inserts the sample rate of the audio stream in Hz. |
| Sample Rate kHz | Inserts the sample rate of the audio stream in kHz. |
| Stream | Inserts the audio stream format. |
| Miscellaneous Special Tokens | |
| Break | The template field holds tokens and strings of text. The IfLength and Truncate tokens must be followed by an integer value. If you want to follow the integer value by a text sequence you will have to separate the two sequences with a Break token. eg. truncate the result to twenty characters and insert ... ❨Truncate❩20❨Break❩;... |
| Dup # | This token is only valid when inside an IfDup sequence. When the token is present and a filename is a duplicate, it will be replaced by the first number 2, 3, 4, etc. which causes the filename to be unique. |
| Ignore if Empty | If a folder path following a Folder Start token is empty, it is by default considered an error. If an Ignore if Empty token is executed in a Folder Start section and the path resolves to be empty, the entire Folder Start section is ignored. ie. a path component will not be processed. This token is only valid in Folder Start sections. |
| Truncate | Truncates the current representation to the number of characters specified in the following integer. For historic reasons, negative numbers will be negated. eg. truncate the result to twenty characters. ❨Truncate❩20❨Break❩ See Filename Lengths for additional information. In many cases it may be easier to control the length of path components by selecting the Settings - Rename - Settings - Automatically truncate path components setting. |
| Multi Value Delimiter | By default, when a field contains multiple values, the handling of the values is controlled by the Settings-Rename-Multi Value Delimiter substitution setting. When the rename substitution setting is empty, all content following the first occurrence of a multi value delimiter is removed. When non empty, the specified text will replace each occurrence of a multi value delimiter. You can use this token to override your rename substitution setting. If the token is followed by text, the text overrides the rename substitution setting. If the token is immediately followed by another token, it is treated as an empty rename substitution setting. The override is retained until the end of the template or another occurrence of a Multi Value Delimiter token. eg. use " and " in Album Artist and ignore multiple values in subsequent tokens. ❨Multi Value Delimiter❩ and ❨Album Artist❩ - ❨Multi Value Delimiter❩❨Genre❩ or ❨Multi Value Delimiter❩ and ❨Album Artist❩❨Multi Value Delimiter❩❨Break❩ - ❨Genre❩ |
| Variable # | These tokens insert the contents of the specified track variable. |
| Non Standard Fields | |
| Album Artist | Inserts the contents of the Album Artist field. If the field is empty the contents of the Artist field will be inserted. |
| Disc Pad2 | Inserts the contents of the Disc field, padded if necessary, with a leading zero so that the field occupies two characters. |
| Disc Pad3 | Inserts the contents of the Disc field, padded if necessary, with up to two leading zeros so that the field occupies three characters. |
| Disc Smart Pad | Inserts the contents of the Disc field, padded if necessary, with leading zeros so that the width is consistent across an album for the maximum number of discs. The padding will only occur if there are ten or more discs in the album. The Disc Count field determines the maximum number of discs. |
| Episode Pad2 | Inserts the contents of the Episode field, padded if necessary, with a leading zero so that the field occupies two characters. |
| Episode Pad3 | Inserts the contents of the Episode field, padded if necessary, with a leading zero so that the field occupies three characters. |
| Movement Number - Roman | Inserts the Movement Number as a Roman numeral. |
| Season Pad2 | Inserts the contents of the Season field, padded if necessary, with a leading zero so that the field occupies two characters. |
| Track Pad2 | Inserts the contents of the Track field, padded if necessary, with a leading zero so that the field occupies two characters. |
| Track Pad3 | Inserts the contents of the Track field, padded if necessary, with up to two leading zeros so that the field occupies three characters. |
| Track Pad4 | Inserts the contents of the Track field, padded if necessary, with up to three leading zeros so that the field occupies four characters. |
| Track Smart Pad | Inserts the contents of the Track field, padded if necessary, with leading zeros so that the width is consistent for the maximum number of tracks. The Track Count determines the maximum number of tracks. |
| Track Symbolic | Inserts the contents of the Track Position UDTI or Custom Field. If the item does not exist, nothing is inserted. If you have a custom field correctly mapped to Track Position it will insert the same value, however this token will work if the custom field is not defined and the UDTI contains a value. |
| Year | The Year token formats the inserted year based on the Settings - File List - Format the Year field setting. The entire Year field can be inserted or it may be cropped to YYYY. |
| Year4 | he Year4 token always displays as YYYY (assuming the Year field exists). |
Tip: Actions can be used to perform complicated rename operations when a template's functionality does not suffice. An action can be placed on the File>Rename>Actions menu by selecting the action in the Action Manager and changing the setting in the Association column to R.
Tip: rename templates are extendable through the use of track variables which can be configured in an action. The contents of Variables 0 through 15 can be inserted as can any other field. You can also use track variables to set up conditions which can be tested with the IfExists constructs. When testing a track variable for existence it must be non empty to pass. If in an action you're setting a track variable to a boolean value make sure that you adjust the value with Format Numeric statement's As 1 or Empty from Boolean function to ensure that false is represented as empty.
Tip: if you want a rename template to use a non default exception or replacement set you can easily do so in an action. The Modify Application Settings statement can be used to change which set is currently the default. Example:
Set Rename Exception Set to (any exception set) Set Names Exception set to (any exception set) Set Rename Replacement set to (any replacement set) Rename Files (rename template name)
The first three statements are Modify Application Settings statements. The last is a Rename Files statement. Note that you do not have to change all three sets, only those where you do not wish to use the default associations. After you save the action you can place the action on the File>Rename>Actions menu by selecting the action in the Action Manager and changing the setting in the Menu column to R.