:tocdepth: 2 Functions ========= .. _autonumbering: Autonumbering ------------- Arguments ^^^^^^^^^ 1. Start 2. Max Length After Padding 3. 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: Case Conversion --------------- Arguments ^^^^^^^^^ 1. Type 2. 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: Convert from non-standard encoding ---------------------------------- Arguments ^^^^^^^^^ 1. 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: Export artwork to file ---------------------- Arguments ^^^^^^^^^ 1. 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: .. describe:: img_desc The description of the current image. .. describe:: img_count The number of images contained in the file. .. describe:: img_counter The number current image being processed. .. describe:: img_mime The mimetype of the current image. .. describe:: 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**. .. _filename_to_tag: Filename to Tag --------------- Arguments ^^^^^^^^^ 1. Pattern Description ^^^^^^^^^^^ See :ref:`menus_file_to_tag`. .. _format_value: Format value ------------ Arguments ^^^^^^^^^ 1. 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 :doc:`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: Import text file ---------------- Arguments ^^^^^^^^^ 1. 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: Load artwork ------------ Arguments ^^^^^^^^^ 1. Filenames 2. Default description 3. 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: Merge Field ----------- Arguments ^^^^^^^^^ 1. 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_fields: Remove Fields ------------- Description ^^^^^^^^^^^ Removes the fields you specify [separated by a comma "**,**"]. .. _remove_all_fields_except: Remove all fields except ------------------------ Arguments ^^^^^^^^^ 1. 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: Remove duplicate values ----------------------- Arguments ^^^^^^^^^ 1. 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: Replace ------- Arguments ^^^^^^^^^ 1. Text to replace 2. Text to replace with 3. Match Case 4. 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: Replace with RegExp ------------------- Arguments ^^^^^^^^^ 1. The regular expression 2. 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: Sort values ----------- Arguments ^^^^^^^^^ 1. Sort Order 2. 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: Split field using separator --------------------------- Arguments ^^^^^^^^^ 1. 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: Tag to Dir ---------- Arguments ^^^^^^^^^ 1. 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: Tag to filename --------------- Arguments ^^^^^^^^^ 1. 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: Text To Tag ----------- Arguments ^^^^^^^^^ 1. The text. Can be any pattern. 2. 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**. 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 ` 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: 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: Update From Tag --------------- Arguments ^^^^^^^^^ 1. Field list (;-separated). Start the list with the tilde (~) character to update all the fields except the ones in the list. 2. 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.