I just noticed that my saved filenames were being cut off, so I read up a bit and here is what I learned.
Picard 1.3 controls excessive directory path and filename length differently than Picard 1.2. With Picard 1.3, there is a big division between length control if you a) either are running Picard on Windows or have the Picard 1.3 option “Windows compatibility” checked; versus b) are running Picard on Mac OS or on Linux, and have “Windows compatibility” unchecked.
As part of renaming tagged audio files and moving them to their final destination, Picard constructs a file path for the file. The path is the complete sequence of directory names, ending in the file name. Picard constructs the file path starting with the directory path in the options box “Move files to this directory when saving”. It then fills in the tagger script in the options box “Name files like this”, using tags from the audio file, constructing a sequence of directories and a file name, and appends this to the starting path.
Then, Picard forms two kinds of corrections to the file path. It changes any undesirable or forbidden characters in the path to safer alternative characters. It also shortens directory names and/or the file name from the file path if they are too long. The details of these two kinds of corrections can play out according to two cases, the Windows compatibility case and the non-Windows case.
Windows compatibility case
When Picard runs on Windows, or when the “Windows compatibility” option is checked on any system, Picard changes the file path characters in the file path which are forbidden on windows, and shortens directory and file names if needed to comply with Windows limitations.
Picard changes any characters "*:<>?|
to _
. It also changes any .
at the end of a directory or file name to a _
.
Picard enforces three limits on the overall file path, and on each directory name or file name in the path.
- The entire path must be 260 characters or less. A few positions are reserved, so only 255 characters are available.
- The length of the directory part of the path must be 247 characters or less. There are several tricky details to this limit.
a. The same few positions are reserved, so only about 244 characters are available.
b. The limit includes the path separators ( \
or /
, for Windows or non-Windows) as well as directory names.
c. The file name part, after the final path separator, is not counted.
d. If you are on a Windows system, the entire path in the “Move files to this directory” option is counted.
e. If you are on a non-Windows system, and the “Move files to this directory” option is for a directory on the file server, then the volume name is not counted against the limit. e.g. if the server has a volume “Qmultimedia”, and the option starts with /Volumes/Qmultimedia/
, then none of those characters are counted against the limit.
- Each directory name and file name in the file path must be 226 characters or limit.
As of version 1.3, Picard enforces the limits as follows. First, any directory name or file name which is over 226 characters is cut down to 226 characters. Then Picard gives the directory names as much of the overall limit as they need, subject to their own 244 character limit. Picard adds up the length of directory names, after allowing for the tricky details. If they are longer than the effective 244 character limit, then Picard truncates the longer directory names proportionately to their length, until the limit is met. Finally, Picard compares the length of the directory names part of the path to the overall limit of about 255 characters for the entire path. Whatever is left over is what the file name must fit into. Picard truncates the file name by preserving the extension (e.g. .flac
or .mp3
), truncating the right-hand end of the rest of the filename, and restoring the extension.
All this adds up to Picard quite possibly cutting off file names in order to maintain Windows compatibility. If you have a file naming script like:
%artist%/%album%/$num(%tracknumber%,2) %title%
And if your %artist% is a 292-character behemoth like in this classical Release, then the %artist% will soak up the entire 244-character limit for the directories, and the file will likely end up truncated to the 12 or so characters left in the overall 255-character limit after 244-or-so characters for the directory part of the path is consumed. The track number and leading space take 3 characters, the extension and separator take 4 or 5 characters, so the rest of the file name will will be 3 characters!
To limit %artist% strings a reasonable part of the overall path, start with about 255 characters for the overall path. Reserve a reasonable number for the file name characters (e.g. 80), and enough for the path in the “Move files to this directory” option, and then limit each of the directories in your “Name files like this” option script to a reasonable proportion of the remaining characters. Use the tagger script function $truncate(
string,
length)
for this.
Here is an example file naming script, allowing 30 characters for the “Move file to this directory” option and 80 characters for the filename, leaving about 140 characters for the two directories:
$truncate(%artist%,90)/$truncate(%album%,50)/$num(%tracknumber%,2) %title%
non-Windows case
When Picard runs on a non-Windows system, and the “Windows compatibility” option is unchecked, Picard shortens directory and file names if needed to comply with that system’s limitations. For Mac OS, each directory name, and the file name, must be 255 or fewer characters long. For Linux, the limit on the length of each directory name, and the file name, depends on the specific system, but is likely 255 or more characters.
Further reading
There are many technical details, especially for the Windows compatibility case. Consult the following references:
- Picard source code picard/picard/util/filenaming.py. The function make_short_filename(basedir, relpath, win_compat=False, relative_to="") shortens a filename’s path to proper limits. It calls the function _make_win_short_filename(relpath, reserved=0) to shorten a relative file path according to WinAPI quirks.
- Picard source code picard/picard/util/init.py. The function replace_win32_incompat(string, repl=u"_") replaces win32 filename incompatible characters.
- Microsoft Windows developer documentation, Naming Files, Paths, and Namespaces is the reference for the Windows path length limit.
- Picard source code pull request #125 “New approach to file renaming”, where the Picard 1.3 length limitations were discussed and accepted into Picard.
- ticket PICARD-110, which led to the name limits being implemented.