File Naming Script Editor

The file naming script editor is used to manage the file naming scripts available for use by Picard. Each script has a title that will show up in the script selection box, and all listed scripts can be edited by the user.

../_images/options-filenaming-editor-1.png

The editor screen has the following sections:

Select the file naming script to use

This option allows the user to select the file naming script to use from the list of scripts available. The selected script will show up in the editing section, where it can be modified if required.

Title

The title assigned to the currently selected script. This can be modified if required.

Script

Below the title is an edit box section containing the formatting string of the selected script. This tells Picard what the new name of the file and its containing directories should be in terms of various metadata values. The formatting string is generally referred to as a “file naming script”, and is in Picard’s scripting language.

The script editor automatically highlights the elements of the script, including function names and tag and variable names. Hovering your mouse pointer over one of the highlighted entries will display help information about the entry if available.

Unicode characters can be entered into the script using the format \uXXXX where “XXXX” is the hexadecimal value of the unicode character. It is not recommended to include unicode characters in the directory or filename.

The use of a ‘/’ in the formatting string separates the output directory from the file name. The formatting string is allowed to contain any number of ‘/’ characters. Everything before the last ‘/’ is the directory location, and everything after the last ‘/’ becomes the file’s name.

Each file naming script can vary from a simple one-line script such as %album%/%title% to a very complex script using different file naming formats based on different criteria. In all cases, the files will be saved using the text output by the script.

Scripts are often discussed in the MetaBrainz Community Forum, and there is a thread specific to file naming and script snippets. There is also a tutorial on Writing a File Naming Script available.

Note

Any new tags set or tags modified by the file naming script will not be written to the output files’ metadata.

Files will be named like this

Below the file naming script is a section showing examples of the output of the script in two columns: Before and After. If you select files from the Cluster pane or Album pane prior to opening the Options screen, up to 10 files will be randomly chosen from your selection as file naming examples. If you have not selected any files, then some default examples will be provided.

Menu bar

At the top of the screen is a menu bar that provides script management functions as well as display settings options. The display settings include:

  • Word wrap script - This will toggle word wrap on and off in the script edit box.

  • Show help tooltips - This will determine whether or not the information is displayed when hovering over a highlighted item.

  • Show documentation - This will toggle displaying the scripting documentation in a sidebar on the screen.

There is also an option to update the randomly selected example files from your selected files list.

The script management functionality includes:

  • Import a new script from a file, either as a plain-text script or a Picard Naming Script Package.

  • Export the current script to a file, either as a plain-text script or a Picard Naming Script Package.

  • Add a new (default) script. This can be a blank script or one of the basic system preset scripts provided by Picard.

  • Copy the current script as a new script.

  • Delete the current script.

  • Reset all scripts, also available via the Reset button.

  • Save all changes, also available via the Make It So! button.

  • Exit without saving changes, also available via the Cancel button.

Script Metadata

../_images/options-filenaming-editor-metadata.png

There is also an option to view/edit the metadata details for the current script. These details include such things as title, author, version, license, description, and date and time of the last update. It is recommended that the description include things such as any required plugins, settings, or tagging scripts. This can also be triggered by double clicking the script title text box.

This information is saved in the Picard Naming Script Package file, and is included when a script package file is imported.