# Scripting Functions

**URL:** https://community.mp3tag.de/t/scripting-functions/51689
**Category:** Documentation
**Tags:** mac
**Created:** [January 22, 2021, 5:25pm UTC](https://community.mp3tag.de/t/scripting-functions/51689 "2021-01-22T17:25:21Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![Florian](https://community.mp3tag.de/user_avatar/community.mp3tag.de/florian/32/5759_2.png) [@Florian](https://community.mp3tag.de/u/Florian)
#### Post date: [January 22, 2021, 5:25pm UTC](https://community.mp3tag.de/t/scripting-functions/51689/1 "2021-01-22T17:25:21Z")

</div>

Mp3tag offers various built-in scripting functions, which can be used at various places in the program. 

These functions offer advanced display and converting options and are to be used in combination with [Format Strings and Available Placeholders](https://community.mp3tag.de/t/format-strings-and-available-placeholders/51688).

# General Functions

### Replace

> **$replace(string,from,to)** or **$replace(string,from1,to1,from2,to2,...)**
> 
> Example: `$replace(%title%,_,-)`
> 
> This example replaces all underscores with dashes. You can provide additional pairs of from/to as parameters.

### Case Conversion _Normal_

> **$caps(string,...)**
> 
> Example: `$caps(%artist%)`  
> This example converts the given string to normal case. The second parameter is optional and specifies additional characters that trigger upper case.

### Case conversion _Normal_ (without changing uppercase characters)

> **$caps2(string)**
> 
> Example: `$caps2(%artist%)`  
> This example converts the given string to normal case without changing uppercase characters. The second parameter is optional and specifies the characters that trigger upper case.

### Case conversion _Sentence_

> **$caps3(string)**
> 
> Example: `$caps3(%artist%)`  
> This example converts the given string to first-letter upper case. The second parameter is optional and specifies additional characters that trigger upper case.

### Case conversion _UPPER_

> **$upper(string)**
> 
> Example: `$upper(%artist%)`  
> This example converts the given string to upper case.

### Case conversion _lower_

> **$lower(string)**
> 
> Example: `$lower(%artist%)`  
> This example converts the given string to lower case.

### Pad integer number with leading zeros

> **$num(x,y)**
> 
> Example: `$num(%track%,3)`  
> This example returns the track number with three digits.

# String Functions

| Function | Description |
| --- | --- |
| `$char(x)` | returns the Unicode character for decimal code point x. |
| `$cutLeft(x,n)` | removes n characters from the left side of string x and returns the remaining string. |
| `$cutRight(x,n)` | removes n characters from the right side of string x and returns the remaining string. |
| `$dedup(x,y,c)` | removes duplicated strings from x, separated by y, optionally using case-insensitive comparison if c is set to 1. |
| `$fmtDate(fmt,x)` | formats the raw timestamp x as a human-readable date using the format string fmt. See [Date and Time Formatting](#p-153045-date-and-time-formatting-13) for details and supported placeholders. |
| `$fmtDuration(x,y,h,ms)` | formats number x as a duration string. The optional parameter y decides how the number is intepreted, where `m` is minutes, `s` is seconds (default), and `ms` is milliseconds. Optional parameters h and ms set to `1` enable the display of hours and milliseconds respectively in the formatted duration string. |
| `$fmtNum(x)` | formats number x with separator for thousands according to current locale settings. |
| `$left(x,n)` | returns the leftmost n characters of string x. |
| `$len(x)` | returns the length of string x. |
| `$mid(x,i,n)` | returns the first n characters of text x, starting at character i. If n is ommited, the character at position i is returned. |
| `$ord(x)` | returns the decimal Unicode code point of the first character of string x. Currently supports characters up to U+FFFF. |
| `$repeat(x,n)` | returns the string x n times. |
| `$regexp(x,expr,repl)` | replaces the pattern specified by the regular expression expr in the string x by repl. The fourth optional parameter enables ignore case (1) or disables the ignore case setting (0). Please note that you have to escape comma and other special characters in expr. |
| `$reverse(x)` | reverses the order of the characters in string x. |
| `$right(x,n)` | returns the rightmost n characters of text x. |
| `$sort(x,y)` | sorts segments of a string x based on a specified delimiter y. |
| `$strcmp(x,y)` | compares strings x and y case-sensitively. |
| `$stricmp(x,y)` | compares strings x and y case-insensitively. |
| `$strchr(x,y)` | finds the first occurrence of character y in string x. |
| `$strrchr(x,y)` | finds the last occurrence of character y in string x. |
| `$strstr(x,y)` | finds the first occurrence of string y in string x. |
| `$strrstr(x,y)` | finds the last occurrence of string y in string x. |
| `$trim(x)` | trims all leading and trailing whitespace from the string x. The optional second parameter specifies the character to trim. |
| `$trimLeft(x)` | trims all leading whitespace from the string x. The optional second parameter specifies the character to trim. |
| `$trimRight(x)` | trims all trailing whitespace from the string x. The optional second parameter specifies the character to trim. |

# Boolean Functions

| Function | Description |
| --- | --- |
| `$and(x,y)` | returns true if x and y are true. |
| `$eql(x,y)` | returns true if x equals y. If x and y are strings, they're compare case-insensitively. |
| `$geql(x,y)` | returns true if x is greater than or equal to y. |
| `$gt(x,y)` | returns true if x is greater than y. |
| `$if(x,y,z)` | if x is true, y is returned, otherwise z. |
| `$if2(x,y)` | if x is true, x is returned, otherwise y. |
| `$ifgreater(a,b,x,y)` | if number a is greater than number b, x is returned, otherwise y. |
| `$iflonger(a,b,x,y)` | if string a is longer than number b, x is returned, otherwise y. |
| `$isdigit(x)` | returns true if the first character in x is a decimal digit (0-9). |
| `$leql(x,y)` | returns true if x is less than or equal to y. |
| `$lt(x,y)` | returns true if x is less than y. |
| `$neql(x,y)` | returns true if x not equal to y. |
| `$not(x)` | returns true if x is false. |
| `$odd(x)` | returns true if x is odd. |
| `$or(x,y)` | returns true if x or y (or any additional argument given) is true. |

# Arithmetic functions

| Function | Description |
| --- | --- |
| `$add(x,y)` | adds y to x. |
| `$div(x,y)` | divides x by y. |
| `$mod(x,y)` | returns the remainder of x divided by y. |
| `$mul(x,y)` | multiplies x by y. |
| `$rand()` | returns a pseudorandom number. |
| `$sub(x,y)` | subtracts y from x. |
| `$uuid()` | creates a 128-bit universally unique identifier (UUID) |

# Metadata (including multiple tag fields)

| Function | Description |
| --- | --- |
| `$columnNames(x,y)` | returns all names from File List columns. The names are prefixed by x, where y is used as a suffix. |
| `$columnValues(x,y)` | returns all values from File List columns. The values are prefixed by x, where y is used as a suffix. |
| `$list(x,y,z,v)` | returns a list of all read tag fields and their values that are stored in the file. The fields are prefixed by x, y is used as separator between field and value, and z is used as suffix after the tag field's value. Multiple values of a field are separated by the optional parameter v or `, ` if omitted. |
| `$meta(x)` | returns all values of field `x` (e.g. `$meta(artist)`). Multiple values of a field are separated by ", ". |
| `$meta(x,n)` | returns the nth value of field `x` (where `n` starts at 0, e.g. `$meta(artist,1)`). |
| `$metasep(x,sep)` | returns all values of field `x` (e.g. `$metasep(artist,; )`). Multiple values of a field are separated by `sep`. |

# Date and Time Formatting

The scripting function `$fmtDate(fmt,x)` formats the raw timestamp `x` (e.g., `%_file_mod_datetime_raw%`) as a human-readable date using the format string fmt. If `x` is omitted, the current timestamp is used.

For example, the date `2001-02-03 04:05:06` can be created using `yyyy-MM-dd HH:mm:ss`.

This table describes supported placeholders for `fmt`:

| Format | Output | Field |
| --- | --- | --- |
| `yyyy` | `2001` | year |
| `yy` | `01` | year, short |
| `MMMM` | `February` | month name, long |
| `MMM` | `Feb` | month name, short |
| `MM` | `02` | month, zero-padded |
| `M` | `2` | month |
| `dddd` | `Saturday` | weekday, long |
| `EEEE` | `Saturday` | weekday, long |
| `ddd` | `Sat` | weekday, short |
| `EE` | `Sat` | weekday, short |
| `dd` | `03` | day, zero-padded |
| `d` | `3` | day |
| `HH` | `04` | 24-hour, zero-padded |
| `H` | `4` | 24-hour |
| `hh` | `04` | 12-hour, zero-padded |
| `h` | `4` | 12-hour |
| `mm` | `05` | minute, zero-padded |
| `m` | `5` | minute |
| `ss` | `06` | second, zero-padded |
| `s` | `6` | second |

---

_[View the full topic](https://community.mp3tag.de/t/scripting-functions/51689)._