Difference between revisions of "MusicBrainz Picard/Documentation/Scripting"

From MusicBrainz Wiki
(Put subdiscs (disc 1, bonus disc, ...) in subdirectory)
(Functions: Added functions firstalphachar, initials and truncate)
Line 149: Line 149:
 
===$performer(pattern="", join=", ")===
 
===$performer(pattern="", join=", ")===
  
* Returns the performers where the performance type (e.g. "vocal") matches <code><nowiki></nowiki></code>pattern<code><nowiki></nowiki></code>, joined by <code><nowiki></nowiki></code>join<code><nowiki></nowiki></code>.  
+
* Returns the performers where the performance type (e.g. "vocal") matches <code>pattern</code>, joined by <code>join</code>.
 +
 
 +
===$firstalphachar(text, nonalpha="#")===
 +
 
 +
* Returns the first character of <code>text</code>. If <code>text</code> is not an alphabetic character <code>nonalpha</code> is returned instead.
 +
 
 +
===$initials(text)===
 +
 
 +
* Returns the first character of each word in <code>text</code>, if it is an alphabetic character.
 +
 
 +
===$truncate(text, length)===
 +
 
 +
* Truncate <code>text</code> to <code>length</code>.
  
 
==Examples==
 
==Examples==

Revision as of 15:34, 26 October 2009

This page describes a simple scripting language implemented in PicardQt.

Syntax

The syntax is derived from Foobar2000's titleformat. There are three base elements: text, variable and function. Variables consist of alpha-numeric characters enclosed in percent signs (e.g. %artist%). Functions start with a dollar sign and end with an argument list enclosed in parentheses (e.g. $lower(...)).

To use parenthesis or commas as-is inside a function call you must escape them with a backslash.

Metadata Variables

See PicardTags for list of variables available in TaggerScript.

Technical Variables

%_extension%

  • Extension of the file name. For example mp3 for file 01 Track.mp3.

Functions

$if(if,then,else)

  • If if is not empty, it returns then, otherwise it returns else.

$if2(a1,a2,a3,...)

  • Returns first non empty argument.

$lower(text)

  • Returns text in lower case.

$upper(text)

  • Returns text in upper case.

$left(text,num)

  • Returns first num characters from text.

$right(text,num)

  • Returns last num characters from text.

$num(num,len)

  • Returns num formatted to len digits.

$replace(text,search,replace)

  • Replaces occurrences of search in text with value of replace and returns the resulting string.

$rsearch(text,pattern)

$rreplace(text,pattern,replace)

$in(x,y)

  • Returns true, if x contains y.

$unset(name)

  • Unsets the variable name.

$set(name, value)

  • Sets the variable name to value.

$get(name)

  • Returns the variable name (equivalent to %name%).

$copy(new,old)

  • Copies metadata from variable old to new. The difference between $set(new,%old%) is that $copy(new,old) copies multi-value variables without flattening them.

$trim(text[,char])

  • Trims all leading and trailing whitespaces from text. The optional second parameter specifies the character to trim.

$add(x,y)

  • Add y to x.

$sub(x,y)

  • Substracts y from 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.

$or(x,y)

  • Returns true, if either x or y not empty.

$and(x,y)

  • Returns true, if both x and y are not empty.

$not(x)

  • Returns true, if x is empty.

$eq(x,y)

  • Returns true, if x equals y.

$ne(x,y)

  • Returns true, if x not equals y.

$lt(x,y)

  • Returns true, if x is lower than y.

$lte(x,y)

  • Returns true, if x is lower than or equals y.

$gt(x,y)

  • Returns true, if x is greater than y.

$gte(x,y)

  • Returns true, if x is greater than or equals y.

$noop(...)

  • Does nothing (useful for comments or disabling a block of code).

$len(text)

  • Returns the number of characters in text.

$performer(pattern="", join=", ")

  • Returns the performers where the performance type (e.g. "vocal") matches pattern, joined by join.

$firstalphachar(text, nonalpha="#")

  • Returns the first character of text. If text is not an alphabetic character nonalpha is returned instead.

$initials(text)

  • Returns the first character of each word in text, if it is an alphabetic character.

$truncate(text, length)

  • Truncate text to length.

Examples

Use case 1: Disc numbers

$set(discnumber,$rsearch(%album%,\\\(disc \(\\d+\)\\\)))
$set(album,$rreplace(%album%,\\s\\\(disc \\d+\\\),))
  • Would it be possible to trim all of (disc 1: Subtitle Here) and also set the disc number? --AaronCooper (2007-03-07)

Use case 2: Artist names

$if($search(%album%,(feat. conductor)),
  $set(artist,%orchestra%))
  • Stupid assumption that all classical albums have "feat. conductor" in the title, but it shows the idea. :)

Use case 3: Live tracks on live albums

$if($and($eq(%releasetype%,live),$not($in(%title%,\(live\)))),$set(title,%title% \(live\)))

Lower case filenames with underscores

$lower($replace(%albumartist%/%album%/$num(%tracknumber%,2) %title%, ,_))

(Year) only if available

$if(%date%,\($left(%date%,4)\))

Remove "feat." from track titles

$set(title,$rreplace(%title%,\\s\\\(feat. [^\)]+\\\),))

Convert triple-dot to ellipsis

$set(title,$replace(%title%,...,…))
$set(album,$replace(%album%,...,…))

This one is useful for people concerned about correct typography and also fixes one problem on Linux: if an album (assuming it's also a directory) is called something like "...for you!", it is considered hidden and therefore might be not accessible from some applications.

Use a different naming pattern for NATs

$if($eq([non-album tracks],%album%),[non-album tracks]/%tracknumber%. %artist% - ,%artist% - $if(%date%, $left(%date%,4) )- %album%/%tracknumber%.)%title%

Result:

  • Non-Album Tracks: [non-album tracks]/Band Name - Track Name.ext
  • Tracks in releases: Band Name - year - Release Name/##. Track Name.ext

Put subdiscs (disc 1, bonus disc, ...) in subdirectory

This one puts all sorts of subdiscs in one directory. For the subalbum it uses the full name.

$if2(%albumartist%,%artist%)/$if(%date%,\($left(%date%,4)\) )$if($rsearch(%album%,\(\\\([^\\\)]*disc[^\\\)]*\\\)\)),$rreplace(%album%,\\\([^\\\)]*disc[^\\\)]*\\\),)/)%album%/$num(%tracknumber%,2) %artist% - %title%

Result:

  • Band Name/(year) Release Name/Release Name (disc #: Subname)/## Band Name - Track Name.ext
  • Band Name/(year) Release Name/Release Name (bonus disc: Subname)/## Band Name - Track Name.ext

So a tree could look something like:

Ayreon/
  (2000) Universal Migrator/
    Universal Migrator (disc 1_ The Dream Sequencer)/
      01 ...
    Universal Migrator (disc 2_ Flight of the Migrator)/
      01 ...

Or:

Belle and Sebastian/
  (2008) The BBC Sessions/
    The BBC Sessions (bonus disc_ Live in Belfast, 2001)/
      01 Belle and Sebastian - Here Comes the Sun.mp3
      02 ...
    01 Belle and Sebastian - The State I Am In.mp3
    02 ...

It only doensn't handle colons nicely. Also it catches every 'disc' between parentheses, so there could be albums where it goes wrong, for example if an album is named "Groovy Beats (disco mix)" it will end up in a double directory.