: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 <scripting>` 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 <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.