MusicBrainz Picard/Documentation/Scripting

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(...)).

Metadata Variables

• {i} Not all of these variables are available for all files. Plugins or scripts can also create a new ones.

%title%

• TrackTitle

%artist%

• ArtistName

%artistsort%

• Artist SortName

%album%

• ReleaseTitle

%albumartist%

• ReleaseArtist

%albumartistsort%

• ReleaseArtist SortName

%tracknumber%

• Track number

%totaltracks%

• Total tracks on the album

%discnumber%

• Disc number

%totaldiscs%

• Total number of discs

%date%

• Release date

%musicbrainz_trackid%

• TrackID

%musicbrainz_albumid%

• ReleaseID

%musicbrainz_artistid%

• ArtistID

%musicbrainz_albumartistid%

• ReleaseArtistID

%compilation%

• 0 for single artist albums, 1 for multiple artist albums

%asin%

• Amazon ASIN

%composer%

• ComposerRelationshipType

%conductor%

• ConductorRelationshipType

%arranger%

• ArrangerRelationshipType, InstrumentatorRelationshipType, OrchestratorRelationshipType

%lyricist%

• LyricistRelationshipType

%remixer%

• RemixerRelationshipType

%producer%

• ProducerRelationshipType

%engineer%

• EngineerRelationshipType

%releasetype%

• ReleaseType

%releasestatus%

• ReleaseStatus

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)

• Regular expression search. This function will return the first matching group.

$rreplace(text,pattern,replace)

• Regular expression replace.

$in(x,y)

• Returns true, if x contains y.

$unset(context, name)

• Unsets the variable name.

$set(context, name, value)

• Sets the variable name to value.

$get(name)

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

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

Examples

Use case 1: Disc numbers

$set(discnumber,$rsearch(%album%,\\\(disc \(\\d+\)\\\)))
$set(album,$rreplace(%album%,\\s\\\(disc \\d+\\\),))

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. [^\)]+\\\),))