Functions¶
Autonumbering¶
Arguments¶
Start
Max Length After Padding
Restart Numbering
Description¶
Numbers tracks sequentially beginning with Start.
The number you enter in Max Length After Padding will pad the track with extra zeroes until it’s of the same length. Eg. if a file has track number ‘12’, having a padding of 3 will return the number ‘012’, while a padding of 1 will leave the number unchanged since it’s length is already greater than the Max Length.
Restart Numbering at each directory will restart the numbering from Start for each directory encountered. A separate count will be kept for each directory.
Case Conversion¶
Arguments¶
Type
Word Delimiter
Description¶
There are three types of case conversion: UPPER CASE,** lower case** and** Mixed Case**. Upper and lower are self-explanatory. Mixed case capitalises each word starting after the characters you specify and converts the rest to lower case.
For instance, using Mixed Case with “.” as a delineator on “this is my name. and my surname. with a dot.here and there.” will return ‘This Is My Name. And My Surname. With A Dot.Here And There.’
Convert from non-standard encoding¶
Arguments¶
Encoding
Description¶
If your files were written using non-standard encoding (eg cp1251 on Windows) you can use this Function to fix ‘em.
Export artwork to file¶
Arguments¶
Pattern
Description¶
Saves all artwork found in an audio file using the desired Pattern. Extensions are added automatically.
If a picture file already exists ‘_1’ will be appended to the filename (before the extension). If that file already exists ‘_2’ will be appended and so on. This will not be done for cases where two or more files contain exactly the same picture data and are to be written to the same filename.
Usage of the following fields are allowed:
-
img_desc The description of the current image.
-
img_count The number of images contained in the file.
-
img_counter The number current image being processed.
-
img_mime The mimetype of the current image.
-
img_type The image type, eg. Cover (Front).
Examples¶
Consider a file /mnt/music/Thebe/Ungawa Kum.mp3 containing four images. The first two PNG images and the last two JPEG. Descriptions are ‘one’, ‘two’, etc. for each image.
The pattern folder_%img_counter% will create four images in /mnt/music/Thebe: folder_1.png, folder_2.png, folder_3.jpg and folder_4.jpg.
%img_desc% will create four images in /mnt/music/Thebe: one.png, two.png, three.jpg and four.jpg.
/home/user/Desktop/%artist% will create four images in /home/user/Desktop: Thebe_1.png, Thebe_2.png, Thebe_3.jpg and Thebe_4.jpg.
Format value¶
Arguments¶
Format string (also referred to as a Pattern)
Description¶
Formats whatever is passed to it using the Format string.
Note
Extensions are not added if you modify filename related fields using this Function.
Examples¶
A Format string can be (almost) any string. Eg. for a file with the tag, artist=A Guy, album=Screeching, title=Excessively Emo, track=2
Using ‘I wanna write my own.’ as a Format string will return ‘I wanna write my own.’ and write it to the fields you choose.
Individual fields can be referenced by placing them inbetween percent characters (%). So %artist% will return ‘A Guy’, %album%, ‘Screeching’ and so on for the others. Using %genre% would return nothing, because there ain’t no genre field in the tag.
You can combine fields with any combination of letters as in I don’t like an %title% %artist%…%album%. Returning, ‘I don’t like an Excessively Emo A Guy…Screeching’
More editing power is available via the scripting functions. They have the format $name(arguments). See the scripting functions page for a listing. They can be simple eg. $upper(value) will return ‘VALUE’, $lower(%artist%) will return ‘a guy’. You can even combine/nest them to get what you want as in I don’t like an $lower(%title% $mid(%artist%,2,10)) $lower(%album%). giving “I don’t like an excessively emo guy screeching.”
Import text file¶
Arguments¶
Pattern
Description¶
Loads the filename described by the Pattern into the field specified. Note that the files complete text is loaded into that field.
Examples¶
For the file with path /mnt/Music/artist/album/filename.mp3 and with the tag, artist=Black Eyed Peas, album=END
lyrics.txt will load the text file from /mnt/Music/artist/album/lyrics.txt
../lyrics.txt will load the file at /mnt/Music/artist/lyrics.txt
%album% will load the file at /mnt/Music/artist/album/END. No extensions will be added.
/mnt/textfiles/lyrics.txt will load from the file at /mnt/textfiles/lyrics.txt
Load artwork¶
Arguments¶
Filenames
Default description
Match Case
Description¶
Loads the artwork in filenames to the specified file.
Filenames are a colon-separated list of shell-style wildcards, eg. *.jpg;*.png. Or just something like folder.jpg. The files will be loaded in order and the images.
Default description can be any pattern, eg. %artist%.
Match Case is pretty self-explanatory.
Be aware that for now that the directory that’ll be searched will be polled every single time this Function is called, so don’t use it on large directories.
Merge Field¶
Arguments¶
Separator
Description¶
Merges the values of a multiple-valued field into a single string, separated by Separator.
eg. Say the genre field contained Rock, Rap and Reggae as distinct values. Merging them using the separator ; (semi-colon) will replace whichever field you specify with the single value Rock;Rap;Reggae.
Remove all fields except¶
Arguments¶
Field list
Description¶
Removes all the fields in the file (including cover art) except the ones you specify. The list of fields you specify are separated by a semi-colon (;). Any spaces around the field names are trimmed, so artist;title and ** artist; title ** are equivalent.
Remove duplicate values¶
Arguments¶
Match case
Description¶
Removes all duplicate values in a multiple-valued field. Case sensitively or not.
Eg. if a field has the following values Rap, Rock and rap. Using this function on it (without case-sensitivity) will leave Rap and Rock as the only values.
Replace¶
Arguments¶
Text to replace
Text to replace with
Match Case
Only as whole word
Description¶
It works just as you’d expect from any text editor. The only caveat is that words are designated by these ,.() ! characters.
Replace with RegExp¶
Arguments¶
The regular expression
Replacement string
Description¶
Matches a regular expression. Groups can then be retrieved using $group_number (counting starts from one) eg $2.
Examples¶
Some examples for the text, ‘concentricpuddle writes this’.
regexp=(concentricpuddle) and repl=$upper($1) => ‘CONCENTRICPUDDLE’
regexp=’(concentricpuddle) writes (this)’, repl=’$upper($1) wrote $2’ => ‘CONCENTRICPUDDLE wrote this’
regexp=’(concentricpuddle) writes (this)’, repl=’$upper($1) wrote $3’ => ‘CONCENTRICPUDDLE wrote $3’, because $3 wasn’t found.
regexp=’(c.*puddle)’, repl=’name=$1’ => ‘name=concentricpuddle’
Sort values¶
Arguments¶
Sort Order
Match Case
Description¶
Sorts the values in a multiple-valued field using either Ascending or Descending order. Arguments are pretty self-explanatory.
Split field using separator¶
Arguments¶
Separator
Description¶
Splits the strings found into multiple values using Separator.
Examples¶
If genre=”Rap;Rock;Dubstep” splitting it with “;” as the separator will result in genre (provided you’re writing to the genre field) having multiple values: Rap, Rock and Dubstep
If genre were a multiple-valued field with ‘Rock;Rap’ and ‘Classical;Guitar Solo’ it’s distinct values. Splitting them with ; as the separator will split each value and combine them into the multiple-valued field. In this case we get Rock, Rap, Classical and Guitar Solo as the distinct values.
Tag to Dir¶
Arguments¶
Pattern
Description¶
Works as Tag To Filename (below), but renames/moves directories instead. Directories will only be moved if the destination dir resides on the same filesystem as the source.
Tag to filename¶
Arguments¶
The text. Can be any pattern.
Description¶
Converts a tag to filename using the pattern (see above description for Format value).
If the filename contains any of the characters, \*?;”|:/, then they will be removed.
Files can also be moved, by specifying ‘/’ as a directory delimeter. Any forward slashes found in the fields used in constructing the pattern are ommitted (if the artist is AC/DC, it will not create an AC directory, rather the slash will be removed and ACDC will be used).
Intermediate directories will be created if they don’t exist.
Examples¶
Say you had a file named ‘track.mp3’ with the following tag, artist=Before The Fame, album=The Vinyl LP, title=Sounds Better Than Anything After, track=10 and invoked this function.
%artist% - %album% - %track% in the pattern combo will rename it to ‘Before The Fame - The Vinyl LP - Sounds Better Than Anything After.mp3’
%artist% - $num(%track%, 3) - %title% will rename it to ‘Before The Fame - 010 - Sounds Better Than Anything After.mp3’
%title%_$upper(%album%)-%track%-%artist% will give the filename ‘Sounds Better Than Anything After_THE VINYL LP-10-Before The Fame.mp3’
For a file with the tag, artist=Relatively Unknown, title=Horrible for everyone else, album=Fans like it, track=5 with path, /home/concentricpuddle/multimedia/music/Indie/unsorted/unknown.mp3
%album%/%artist% - %title% will move the file to /home/concentricpuddle/multimedia/music/Indie/Fans like it/Relatively Unknown - Horrible for everyone else.mp3.
For every slash, the file is moved up one directory. %artist%/%album%/%title% will move the file to /home/concentricpuddle/multimedia/music/Relatively Unknown/Fans like it/Horrible for everyone else.mp3
If you want you can also have an absolute path, by starting the pattern with a slash, eg. the pattern /mnt/library/%album%/%track% will move the file to /mnt/library/Fans like it/5.mp3
Text To Tag¶
Arguments¶
The text. Can be any pattern.
The pattern to match the text against. Works like Tag->Filename except that instead of using fields like %artist% you use tokens denoted by %number like %1, %3.
What to output the text as, can be any pattern can be used including tokens delimited by %number.
Description¶
Converts any text from any text to any other text. It’s better explained by using:
Examples¶
Say you had the text, ‘First Second’. Using the pattern %1 %2 you can reverse the text by using ‘%2 %1’ as the output, returning ‘Second First’.
You can use any valid pattern as the text. Say artist=’Eminem/Recovery’. Using the pattern %1/%2 and having %2 in the output means that you can retrieve the album name (Recovery). %1 would return Just ‘Eminem’.
:doc:’Scripting <scripting>` functions are allowed in the output. Eg. for text=’Jimmy-01/Rebellious Angel’ and a pattern=’%1-%2/%3’, the $num(%2, 1) as the output will be evaluated as normal returning just ‘1’.
Trim Whitespace¶
Description¶
Removes any whitespace before and after text. Using it on ” there’s a space before and one after “ will return “there’s a space before and one after”
Update From Tag¶
Arguments¶
Field list (;-separated). Start the list with the tilde (~) character to update all the fields except the ones in the list.
Tag type
Description¶
Updates the fields specified with the values found in Tag type.
If your FLAC file has an ID3 tag, puddletag will read/write only the VorbisComment tag. However sometimes you want to update the FLAC tag with the ID3 tag’s contents. Specify the Field List, select the Tag Type (ID3 or APEv2).
After invocation, the current file’s tag will then be updated using the ID3/APEv2 tag’s fields.
Note
The tag will be not be changed in any manner.