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

From MusicBrainz Wiki
Jump to navigationJump to search
((Imported from MoinMoin))
(from looking at the source code, this seems to be how the function works (Imported from MoinMoin))
Line 182: Line 182:
   
 
<ul><li style="list-style-type:none">Returns the number of characters in text.
 
<ul><li style="list-style-type:none">Returns the number of characters in text.
  +
</ul>
  +
  +
===$performer(pattern="", join=", ")===
  +
  +
<ul><li style="list-style-type:none">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>.
 
</ul>
 
</ul>
   

Revision as of 14:00, 4 September 2008

Scripting in Picard

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)

  • Returns replace in place of text, if search was found in text.

$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.

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