Expression Language

Using this page

The 'Contents' box above contains a list of available functions roughly grouped by usage scenario, and each function name gives a fair indication of what it might do. Each of the group headers contain some basic information pertinent to the functions inside the group. Click on a function or function group header in the Contents box to be taken directly to more information about it on the page. At the bottom right of each section there is a "Back to top" link which will take you back up to the Contents box allowing you to quickly get to where on the page you would like to go next.
Some of the function descriptions reference other functions to help illustrate their usage. Where this happens, a link to the referenced function is provided if needed. The browser's "Back" button will then return you to the previous place you were at on the page.
The page contains some references that link to external pages. Such links can be identified by the little square icon that follows them, like this--->. These links will not load in new tabs or windows, so, if you would like to keep this page open in your browser, right click on these links and choose to open them in a new tab or window.

(Back to top)

Overview

The J. River Media Core database engine supports Excel-style functions for use in view schemes, searches, displayed columns, and tag editing.

An expression is a mixture of text, fields, and functions. A function allows special operations to be performed. Functions are all listed with a name followed by an opening and closing parenthesis. When building expressions, the instructions you wish to pass to the function are placed inside these parenthesis, with multiple instructions separated by commas. When your expression is evaluated, any spaces entered after a comma are ignored. This allows you to compose complex expressions on multiple lines, making it easier to keep track of where you are in your expression. Occasionally, you will find that you want a space, or parenthesis character to be treated literally as part of your instructions, rather than expression syntax, and in these cases, the character is "escaped" by using a preceding forward slash. Examples using this escaping can be seen here and here. As you progress with your expression building, you will begin nesting multiple functions into a single expression; always remember that a completed expression must contain a matching number of opening and closing parenthesis in order to work reliably.

The functions available to us range from highly functional, with a broad range of applicable uses, through specialised, limited use functions that only appeal to a select group of users, to seemingly redundant functions and obscure functions that Media Center uses internally. The functions below are listed with those with the broadest appeal at the top, and the more obscure at the bottom.

Any given expression can only work on any given single file. It is not possible to compare a field in one file with a field in another file.
Batch file operations are possible, and when used in a list, even a grouped list, an expression will be applied to each individual file in turn, not as a group.

A slightly extended overview is also available elsewhere in this wiki, titled Database Expressions, and another page attempts to demonstrate Media Center mimicking the "AND", "OR" and "XOR" database searches.

(Back to top)

Using expressions

Expressions are ubiquitous in Media Center, and are useful in a variety of locations such as the following:

• Player Display (right-click the Player Display , choose "Customize")
• Captions & Thumbnail text
• Panes (aka Categories)
• Expression columns (right-click a column header and choose "Add expression column")
• The library field manager (Create expression-based library fields)
• Theater View
• Link manager (Use expressions to format link URLs)
• Rename, Move, & Copy Files tool

The syntax of the expression language is generally consistent throughout Media Center. An expression is evaluated, formatting output that is used in the context where the expression was evaluated. To perform Tag assignment or Search rule filtering, an expression is modified slightly to work in these contexts.

(Back to top)

Formatting output

To give usage examples for all of these locations is beyond the scope of this page, so a few tips should suffice to get those interested up and running.

• Using expressions to produce custom Thumbnail text makes it possible to display only relevant or useful data.
• Expressions can be used to reduce link bar clutter by conditionally displaying links based on, for example, Media Type.
• File and directory paths may be based on expressions; this is especially useful in Options > File Locations, and in the "Rename, Move, & Copy Files" tool.
• User-specified library fields may be calculated, based on the output of expressions.

(Back to top)

Tag assignment

The output of an expression can be used to assign a value to a tag. This is accomplished by preceding the expression with an "=" character. The "=" character causes the tagging engine to invoke the expression evaluator first, and then to use its output as the value to assign to the tag. Without the prepended "=" character, the expression itself (and not its evaluated value) would be stored in the tag.

An assignment expression can be entered into the Tag Action Window, or by using inline editing in the file list or a pane entry.

Note: Undo is supported, reverting each tag to its value prior to the assignment. Redo is also supported, reapplying the most recent Undo.

The following screenshots illustrates using an expression for tag assignment:

Pressing "Enter" copies the Date data into the caption field

Just like that!

(Back to top)

Search rule filtering

Expressions can be used as search filters, and in order to do so, the expression must be entered into the search field using the following format:
[=EXPRESSION]=1 or [=EXPRESSION]=0

All files that match the expression will return "1" and all that don't match, return "0". Decide which is required and use "1" or "0" accordingly.

Remember that the search field appears in many places throughout Media Center, places that include:

• The search field itself (in the top right corner of the program)
• A view scheme search list
• "Edit Files To Show" area of the Customize View dialogue
• Play Radio Files
• The last.fm submission filter
• The links manager

and this method of expression application can be used in all of them.

An example of an expression formatted for use in the search field would be: [=isequal(formatdate([date imported,0],MM//yyyy),formatdate(now(),MM//yyyy),1)]=1 Which will list all files that have been imported this month.

(Back to top)

Specify data types for expression based fields

It is often useful to force Media Center to operate on data of one type as if it were another type. This is useful for changing sort order, or handling list data as a simple string. For example, month names are sorted alphabetically by default, but by setting the data type, sorting can be chronological instead. Data types are forced by appending to an expression the string: &datatype=[DATA TYPE], where DATA TYPE is one of the following values:

• List: A list of strings, separated by semicolons
• String: Sorts as strings (with smart number handling)
• Number: Sorts values as numbers (decimal or integer)
• Integer: Sorts values as integers
• Path: Sorts using a smart filename compare style
• Month: Sorts string month names (i.e. January, February, etc.)

The following screen images show these data type instructions in action:

&DataType=[Month]			&DataType=[List]
Used in a pane, formatdate([date,0],MMMM) returns the months as requested, but the alphabetic order is a little confusing.	Adding the "month" data type, like so, formatdate([date,0],MMMM)&datatype=[month], takes care of the order.		No data type has been specified, so the expression results are presented literally, as individual string values.	Add the "list" data type to the expression and it is then formatted correctly in the pane. Here, the ListBuild function has been used to create a nested browsing tree.

(Back to top)

Fields

Any text between brackets [] will be replaced with the corresponding field from your library. As an example, [Artist] would be replaced by Bob Dylan for any Bob Dylan tracks. If the text between brackets doesn't match any known fields, it will be left alone, [My Fake Artist] will be treated literally, square brackets and all. After the field name, a comma can be placed followed by a 0 or 1 to indicate whether the field should be formatted. So, [Duration] and [Duration, 1] will give "4:02" while [Duration, 0] will give "242". This is particularly important when working with the "Format" functions, where most times you will want the evaluator to work with the raw field contents rather than the formatted contents you see in the file list.

Function and field values in expressions are not case-sensitive. Available functions with descriptions and examples are listed below.

(Back to top)

Functions

Accessing and Storing Functions

The functions in this section access field values, store and load global variables, access file tags, and access note fields.

Field(…): Returns a field's value

Description	field(name, mode) The Field() function returns the value stored in field name. The format of return is selected by mode. Available mode values: 0 Raw, unformatted data 1 Formatted data Argument mode is optional (defaults to 1).
Examples	field(album) Returns the formatted value of field name album. Note that this is equivalent to [album]. field(date, 0) Returns the raw, unformatted value stored in the date field. Note that this is equivalent to [date,0].

(Back to top)

Load(…): Outputs the value of a global variable

Description	load(varname) Loads and outputs the value of the specified global variable varname that has been previously stored with Save().
Examples	load(var1) Loads and outputs the previous stored value of the global variable named var1. If var1 has not been previously stored, the output will be empty. save(math(1 + 2), sum)load(sum) Saves the output of the Math() function into sum, and then loads and outputs the value of sum, which is 3.

(Back to top)

Note(…): Retrieve note fields

Description

note(field label, field type, occurrence) The Note() function retrieves information from a Media Center Note. Specifically, it returns the contents assosicated with a field label, of a given field type. The Nth occurrence may be requested. Notes data may be simple text, or associated with defined a field label. Currently the only type of field label is contact information. The first line of a Note is assosciated with the omnipresent field label Name. The field type selects the specific sub-type for a given field label, and occurrence selects which instance of several field label / field type pairs is returned. The occurrence value is zero-based. Argument field type is optional (defaults to FIRST AVAILABLE). Argument occurrence is optional (defaults to 0).

Examples

note(phone) Returns the value found in the first Phone field label. If no Phone label exists, nothing is returned. note(phone, home) Returns the value found in the first Home field type from the Phone field label. If the Phone label, Home type does not exists, nothing is returned. note(phone, home, 1) Same as the previous example, but the second instance of the field type is selected instead of the first, since occrrence is zero-based.

(Back to top)

Save(…): Saves a value to a global variable

Description

save(value, variable, mode) This Save() function saves the value into the specified global variable, and optionally will return that value if mode is set. Once a global variable has been created using Save(), that variable's value is available for use with either Load() or the pseudo-field "[variable]". 0 Suppress output 1 Output variables value Argument mode is optional (defaults to 0).

Examples

save(Much Money, local_bank) Saves the value Much Money into the global variable local_bank. save(More Money, My Bank, 1) Saves More Money into My Bank and outputs the variables value More Money. save(math([duration,0] / 60), durmins)if(compare([durmins], >, 5.0), Long Track, Short Track) Saves the calculated duration in minutes into the variable durmins. Notice that subsequent expressions fragments such as the if(compare()...) may now use the pseudo-field [durmins] as shorthand for load(durmins). Additional Examples Generating statistics Generating album track count Generating album ratings Highlighting playing album

(Back to top)

SaveAdd(…): Adds to a global variable

Description

saveadd(variable, value, mode) The SaveAdd() function adds value to a global variable either numerically or as a list item. The mode argument indicates how variable is modified. Available mode values: 0 Add numeric value (integer or decimal) to variable 1 Append string value as a list item to variable 2 Prepend string value as a list item to variable Argument mode is optional (defaults to 0).

Examples

saveadd(v, 1) Numerically increments the global variable v by 1. saveadd(v, math(2 - 6)) Numerically increments the global variable v by the outcome of the Math(), which is -4. load(foo, v)saveadd(v, bar, 1)load(v) Loads value foo into variable v, then appends the value bar as a list item, and the final load(v) expression outputs the result of foo; bar. load(That, v)saveadd(v, This, 2)load(v) Similar to the previous example, but using the prepend mode, resulting in the output This; That.

(Back to top)

Tag(…): Returns a file's physical tag

Description

tag(tag name) The Tag() function reads and returns the value of tag name directly from a file. The Media Center Library database is not used with Tag(), and instead the specified file is read for the requested tag. The spelling and letter case of the tag name must match exactly those stored in the file. Performance note: This function must open and read the actual file, so its performance is significantly slower than other functions which operate on database fields.

Examples

tag(My Personal Tag) This will return the value from the tag named My Personal Tag from file referenced by the [filename] field. tag(Gapless Header) Returns the Gapless Header tag value, often contained in an mp3 file. Examxple: tag(exif: Date) Returns the raw date data from the EXIF data saved inside a jpg file.

(Back to top)

Conditional Functions

The functions in this section test one or more arguments to produce either a true or false outcome, and execute specific actions depending upon that result.

The expression language does not directly support AND, OR, and XOR operations. However, these can be easily emulated using any of several techniques. See: Database_Expressions_AND_OR_And_XOR.

The NOT operator ! (exclamation point) may be used in a conditional to invert the sense of the conditional test. Inverting the sense of a test can make reading expressions easier, or support better IfElse() sequences.

If(…): Conditional if-else evaluator

Description

if(test expression, true expression, false expression) The If() function is used to evaluate a test expression, and will output the result of the true expression or false expression, depending upon the evaluation result. The test expression is expected to return a 0 (false value) or a non-zero (true value). Nesting is allowed. If the test expression is preceded by the NOT operator (!, an exclamation point), the sense of the test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1.

Examples

if(isequal([artist], bob dylan, 1), Genius, Mediocre) Outputs Genius when artist is (case insensitive) Bob Dylan and Mediocre otherwise. if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre)) This nested If() expression expands on the previous example, by first evaluating if the artist is Bob Dylan, and outputs Genius if true. When the artist is not Bob Dylan, the album is then tested to see if it is Joshua Tree, and if so outputs Great Album, otherwise outputs Mediocre. if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment) Output's the first three words of the comment field; otherwise, outputs *No Comment. By using the NOT operator, the sense of the conditional is inverted so that the more interesting case is moved ahead of the more mundane case.

(Back to top)

IfElse(…): Conditional if-elseif evaluator

Description

ifelse(test1, action1, test2, action2, test3, action3, …) The IfElse() conditional provides a convenient mechanism for shortening and more clearly expressing nested conditionals into an alternating sequence of tests and actions. One or more test/action pairs may be specified. For example, consider a nested sequence of If() tests such as the following pseudo-code: if (test1) action1 else if (test2) action2 else if (test3) action3 The IfElse() statement may be used to more cleanly express the flow of expression by removing the superfluous internal If() statements, converting the clumsy expression: if(test1, action1, if(test2, action2, if(test3, action3))) into the more elegant: ifelse(test1, action1, test2, action2, test3, action3) If any of the test expressions test1, etc. are preceded by the NOT operator (!, an exclamation point), the sense of that test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1.

Examples

ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video]), Flix) If media type is audio, outputs Le Tunes, else if media type is video, outputs Flix ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre) This example, implements the nested if statements from the If() section above, first testing if the artist is Bob Dylan, and if true, outputs Genius, otherwise evaluates the second test to determine if the album is Joshua Tree, and if true, outputs Great Album, otherwise, performs a final test, in this case a degenerate test of 1 (and 1 is always true), thus outputting the value Mediocre.

(Back to top)

FirstNotEmpty(…): Returns the first non-empty argument

Description

firstnotempty(value1, value2, …) The FirstNotEmpty() function acts as a conditional by returning the first argument from value1, value2, ... that is not empty. Two or more arguments may be used, and the first non-empty argument is returned. With two arguments, is is functionally equivalent to the sequence such as "if(!isempty(value1), value1, value2)". With more than two arguments, FirstNotEmpty() avoids long nested If() sequences that simply test for emptiness.

Examples

firstnotempty([media sub type], Misc Video) Returns the value in media sub type if it is not empty, otherwise returns Music Video. firstnotempty([series], [name], Tag your Videos!) Returns the first non-empty value from the fields series or name, and if both are empty, returns the reminder to Tag your Videos!.

(Back to top)

Test and Comparison Functions

The functions in this section return a Boolean value of either 1 (true) or 0 (false). They are generally used to drive an action specified in one of the Conditional Functions.

Compare(…): Compares two numbers

Description	compare(value1, operator, value2) The Compare() function compares two numeric values value1 and value2 using the specified operator. Available operator values: = Equivalence < Less than <= Less than or equal to > Greater than >= Greater than or equal to Outputs 1 if the comparison is true, and 0 otherwise.
Examples	compare([bitrate], <, 320) Returns 1 when the bitrate is less than 320 (Kbps), and 0 otherwise. if(compare(math(now() - [date modified, 0]), >, 21), Expired, formatdate([date modified, 0], elapsed)) Outputs the age of files under 21 days old, or Expired for older files.

(Back to top)

IsEqual(…): Compares two values in one of nine specified modes

Description

isequal(value1, value2, mode) The IsEqual() function compares value1 with value2 using any mode from the list of modes below. Outputs 1 when the comparison succeeds according to the mode, and 0 otherwise. Although the mode is specified as the last argument, the comparison should be mentally read as: value1 mode value2. Available mode values: 0 Case-sensitive string compare for equality 1 Case-insensitive string compare for equality 2 Numeric compare for equality 3 Numeric less than 4 Numeric less than or equal to 5 Numeric greater than 6 Numeric greater than or equal to 7 Substring search (case sensitive) 8 Substring search (case insensitive) Argument mode is optional (defaults to 0).

Examples

isequal([artist], [album], 1) If the artist and album values are the same, the output will be 1, otherwise, the output will be 0. if(isequal([artist], [album], 1), Eponymous, [album]) The If() function basis its decision on the outcome of IsEqual(), so if the artist and album values are the same, the output will be Eponymous, otherwise, the output will be the value of album. if(isequal([artist], [album], 1), Eponymous/,, [album]/)) This example demonstrates the character escaping mentioned in the overview earlier. Here, we want the output to be either Eponymous, (note the inclusion of the comma) or the album value with a closing parenthesis. In order to achieve this, the comma, and the closing parenthesis, are escaped using a forward-slash character. This informs the expression evaluator that these characters are not part of the expression syntax and are to be treated literally. if(isequal([filename (path)], classical, 8), Classical, Not Classical) Because compare mode 8 has been specified, if the word classical appears anywhere in the case-insensitive file path, the expression will return Classical, and if not it will return Not Classical.

(Back to top)

IsEmpty(…): Tests a value for emptiness

Description

isempty(value, mode) The IsEmpty() function tests the given value for emptiness. The value passed is typically an Media Center field, so that some action may be taken when the field is or is not empty. Returns 1 when the value is empty, otherwise 0. Available mode values: 0 String test (field must be empty to get a positive result) 1 Numerical test (field must be empty, or contain 0 to get a positive result) Note that Media Center does not discriminate between a 0 value and an empty value for fields of type Integer and Decimal - both 0 and empty are considered equivalent for these field types. This is useful for fields such as the integer field Disc #, where an empty or 0 value implies that Disc # contains no useful data, and should be generally ignored or absent in display output. Pay particular attention to the third example offered below, as it covers a caveat that comes with this particular function. Argument mode is optional (defaults to 0).

Examples

isempty([comment], 0) If the comment field is empty, IsEmpty() returns 1, otherwise 0. isempty([track #], 1) Performs a numerical test for data in the [track #] field. If the field is empty or 0, a 1 is returned, otherwise 0 is returned. ifelse(!isempty([disc #]), [disc #]) Outputs the value of the disc # field when it is not empty.

(Back to top)

IsRange(…): Tests a value for inclusion within a given range

Description

isrange(value, range) The IsRange() function tests if a value falls within a given range of values. If the value falls within the given range, 1 is returned, otherwise 0 is returned. A range is specified in the form of low-high, where low and high are either letters or numbers. The lowest value comes first, the highest second. Both low and high must be the same kind (letters or numbers). The low and high values are inclusive. Example Ranges: 1-100 a-z c-d 23-7542

Examples

isrange([artist], a-c) Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0. if(isrange([bitrate], 96-191), Poor Quality, High Quality) Returns Poor Quality for any file whose bitrate falls in the range of 96 to 191, and returns High Quality for all bitrates. Additional Examples Using IsRange() in a Search List.

(Back to top)

IsMissing(…): Tests to see if a file exists on the system

Description

ismissing(filepath) The IsMissing() function tests for the existence of a file in the file system. If the file is missing, the function returns 1, otherwise 0 is returned if the file exists. This function is useful for checking for missing files in a Library. IsMissing() treats special entries such as ripped Blu-ray or DVDs as single files, even though they physically exist in the file system as several files and directories. Note: Any view or list that uses IsMissing() will be slow, is Media Center must interogate each referenced file in the file system. The larger the number of files being queried, the longer it will take to produce results. Use IsMissing() with care. Argument filepath is optional (defaults to [filename]).

Examples

ismissing() If the referenced file was not found in the file system, 1 is returned; othewise 0 is returned. ismissing(C:\Music\My Lost File.mp3) Checks for My Lost File.mp3 and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist. if(ismissing(), File is missing, File exists) Outputs File is missing or File Exists depending on the result returned by IsMissing(). [=ismissing([filename])]=1 This example demonstrates how to construct an expression for use as a Media Center search query. If you place this in the search field in the top right corner of the program while viewing all of your library, it will filter the list, leaving only the missing files on view. If all files in library exist, this list will be empty. You could also create a view scheme and use this string in the Set rules for file display search to give you a view that you can visit periodically to check that your library is not missing any files.

(Back to top)

IsRemovable(…): Tests to see if a file is stored on removable media

Description	isremovable(filepath) The IsRemovable() function tests if a file resides on removable media and if so, returns 1, and if not, returns 0. The Media Center field [Removable] also provides the same value for a given file. Argument filepath is optional (defaults to [filename]).
Examples	isremovable() Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.

(Back to top)

IsInPlayingNow(…): Tests to see if a file is in the Playing Now playlist

Description	isinplayingnow(filepath) The IsInPlayingNow() function tests if a file is in any zone's Playing Now list. Used as an expression category, pane or file list column allows distinguishing files that are in the Playing Now list. Argument filepath is optional (defaults to [filename]).
Examples	isinplayingnow() If the file in the Playing Now list, returns 1, otherwise returns 0. if(isinplayingnow(), Queued, Not queued) If the file in the Playing Now list, returns Queued, otherwise Not queued. Additional Examples How to use IsPlaying() and IsInPlayingNow()

(Back to top)

IsPlaying(…): Tests to see if a file is in currently being played

Description

isplaying(filepath) The IsPlaying() function tests if a file is playing in any zone. Used as an expression category, pane or file list column allows distinguishing files that are playing now. Argument filepath is optional (defaults to [filename]).

Examples

IfElse(IsPlaying(), <font color="ff0000">♪<//font>, IsInPlayingNow(), ♪) This expression in a file list expression column shows which files are in the Playing Now list and which are currently playing by outputing a musical note in the column. The musical note will be displayed in red for any currently playing file. Additional Examples How to use IsPlaying() and IsInPlayingNow() How to play an artist's full work when a genre is shuffling?

(Back to top)

Formatting Functions

The functions in this section format their arguments in specific ways. Some functions are used for formatting values for better presentation, or according to some format, while other functions work on Media Center internal "raw" data to convert to user-friendly formats.

Certain Media Center fields are used to store values in ways that are internally convenient or effecient. But these field values are not terribly useful or meaningful when used directly.

For example, the Duration field holds values as a number seconds of length, while various Date/Time fields such as Date or Last Played store values as floating point numbers specifying a number of days and fractions of a day since a particular epoch time.

Media Center will generally format fields using the "display" format where necessary, such as in panes, file list columns, or various tools such as the Rename, Move & Copy tool. When a function requires a raw field value, or you want to access a raw field value, by sure to use the raw field format. This is done by appending a ,0 to the field's name inside the brackets, for example [Date Imported,0].

Delimit(…): Outputs a value with head/tail strings when value is non-empty

Description	delimit(expression, tail, head) The Delimit() function outputs the value of expression prepended with a head string and/or appended with a tail string, but only if the value of the expression is non-empty. Nothing is output when the expression evaluates to empty. Argument tail is optional (defaults to SPACE). Argument head is optional (defaults to EMPTY).
Examples	delimit([Track #], .) Appends a period after a track number if [Track #] is not empty, such as 12.. delimit([Date (year)], {, }) Outputs the year surrounded by curly braces, for example {2012}.

(Back to top)

FormatBoolean(…): Formats a boolean (true / false) value in a specified manner

Description

formatboolean(conditional, true string, false string) The FormatBoolean() function outputs true string and false string values to represent the 0 or 1 Boolean output resulting from the conditional expression. When the conditional evalutes to 1, the true string will be output, otherwise the false string will be output. Argument true string is optional (defaults to True). Argument false string is optional (defaults to False).

Examples

formatboolean(isempty([number plays]), Never Played, Has Been Played) Returns Never Played when the expression IsEmpty() evaluates to 0, and Has Been Played when it evaluates to 1. formatboolean(math([track #] % 2) Outputs the default True label for odd track numbers, and the default False label for even ones.

(Back to top)

FormatDuration(…): Presents a duration of seconds in a reader friendly format

Description	formatduration(duration value) The FormatDuration() function formats a duration value into a friendly format. The duration value argument is expected to be a value representing a number of seconds, typically used for media file duration. Media Center internally stores duration values in seconds.
Examples	formatduration([duration,0]) Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list. formatduration(600) This will output ten minutes in the format 10:00.

(Back to top)

FormatFileSize(…): Presents a number of bytes in a reader friendly format

Description	formatfilesize(bytes value) The FormatFileSize() function formats a bytes value into a friendly format. The bytes value argument is expected to be a value representing a number of bytes, typically used for media file size. Media Center internally stores file size values in bytes. FormatFileSize() will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB.
Examples	formatfilesize([file size,0]) Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list. formatfilesize(56123456) Outputs the bytes value 56,123,456 as 53.5 MB.

(Back to top)

FormatNumber(…): Formats and rounds a number to a specified number of decimal places

Description

formatnumber(value, decimal places, label zero, label plural, label singular) The FormatNumber() function formats a numeric value to a specified number of decimal places, rounding its value, and optionally outputs value-dependent labels, which can be used to construct more gramatically-correct output. The value can be any numeric value. The decimal places argument specifies the number of digits to be used after the decimal point. Use -1 to output as many decimal places as available. The label selected depends on the original value, not the resulting formatted value. The label zero argument is output instead of a formatted value when the original value is 0. When this label is specified as empty, label plural is used. The label plural argument is appended to the formatted value when the original value is more than 1. The label singular argument is appended to the formatted value when the original value is equal to 1. Note: FormatNumber() will not output additional zero's after the decimal point. In otherwords, FormatNumber() rounds fractional values, but does not zero fill. Argument decimal places is optional (defaults to 0). Argument label zero is optional (defaults to label plural). Argument label plural is optional (defaults to 0). Argument label singular is optional.

Examples

formatnumber([duration,0], 2) Returns a file's duration (which are in seconds) rounding to two decimal places. formatnumber([number plays,0], 0, Unplayed, Plays, Play) Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be Unplayed. When it is more than one, such as six, outputs 6 Plays. And when the number of plays is one, outputs 1 Play. formatnumber([number plays,0], 0, , Plays, Play) Same as the previous example, but uses the default value for label zero (which is label plural), so that when number of plays is zero, output is 0 Plays. formatnumber([number plays,0], , , , Time) In this example, only label singular argument is specified (as Time), so all other arguments use their defaults values. The output will be 0 when number of plays is zero, 1 Time when number of plays is one, and the actual number of plays for other values (e.g. 6).

(Back to top)

FormatRange(…): Formats a value as a range

Description

formatrange(value, range size, mode) The FormatRange() function creates numerical or alphabetic groupings of size range size, and returns the grouping where value falls. Only the first character of value is considered and used. The range size is a numerical value specifying how wide the range should be. Numeric ranges are 0-based. The mode specifies the type of range grouping. Available mode values: 0 Automatically choose between number / letter grouping 1 Letter grouping 2 Number grouping Argument range size is optional (defaults to 1). Argument mode is optional (defaults to 0).

Examples

formatrange([artist], 3, 1) Outputs the range that the artist's first letter falls within. With a range size of 3 and using mode 1 (letter grouping), ranges will be produced in the form of a-c, d-f, g-i, etc. formatrange([artist]) With range size and mode values left unspecified, default values are used, so automatic range groupings of size 1 are output. Hence, the first character of [artist] will be output. formatrange([bitrate], 100, 2) Numeric range groupings of size 100 will be output, for the value of [bitrate]. Possible outputs are: 0-99, 100-199, 200-299, etc. Additional Examples How to produce 1-based range values.

(Back to top)

Orientation(…): Outputs the orientation of an image

Description	orientation() The Orientation() function outputs one of the following words indicating the orientation of an image file: Portrait When height > width Landscape When width > height Portrait When height = width
Examples	if(isequal(orientation(), Square), Square, Rectangle) Outputs Square for square images or Rectangle for portrait and landscape images.

(Back to top)

PadNumber(…): Adds leading zeros to any given number

Description	padnumber(value, number digits) The PadNumber() function adds leading zeros to any given number value, producing a value of length number digits.
Examples	padnumber([track #], 2) This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length. padnumber(counter(), 4) Outputs 4 digits of zero-padded numbers produced by Counter(). For example, 0001, 0002, 0003, etc.

(Back to top)

RatingStars(…): Outputs the value of Rating as a number of star characters

Description	ratingstars() The RatingStars() function outputs the Rating field's value as the equivalent number of black star characters.
Examples	ratingstars() For a file that has a Rating of 4, outputs ★★★★.

(Back to top)

Watched(…): Outputs a formatted video bookmark

Description	watched(mode) Outputs a video's bookmark position in a human-readable format, using a specified mode. Available mode values: 0 Output a human-readable watched status. 1 Output a numeric watched value, 0 if not watched, 1 if partially watched, 2 if entirely watched. 2 Output a watched checkmark ✓ if watched Argument mode is optional (defaults to 0).
Examples	watched() Outputs formatted watched status, such as 57% on Sep 25, or Aug 21, or nothing when the video has not been watched.

(Back to top)

String Manipulation Functions

The functions in this section are used primarly to manipulate strings. Since the Media Center expression language is primarly string-oriented, these functions provide a means to manipulate field values or the output from other expressions.

Clean(…): Clean a string to be used for various operations

Description

clean(string, mode) The Clean() function is generally used to sanitize a string by stripping empty brackets, remove superfluous dash characters, eliminate leading or trailing articles, or replace filesystem-illegal characters. It is typically employed before some operation such as Rename to clean the product of joining various fields, some of which may be empty, or to produce filesystem-safe filenames. It may be used for a variety of purposes, however. Available mode values: 0 Removes empty () and [], superfluous dash (-) and whitespace characters and sometimes comma (be careful) 1 Removes the article 'the' from the beginning and ', the' from the end 2 Removes any article (a, an, the, etc.) from the beginning and end 3 Replaces each filesystem-illegal character \ / : * ? " < > | with an underscore _, and replaces each unprintable character with a space Argument mode is optional (defaults to 0).

Examples

clean([album] - [date]) The concatenation of [Album] - [Date] may leave a dangling - string when date is empty. Clean() in the default mode removes this dangling string. clean(The Beatles, 1) For sorting or grouping purposes, it is often desirable to remove the leading article The from a string. Clean() in mode 1 provides a convenient solution, and in this example produces Beatles. clean(AC//DC: Back In Black, 3) When an expression is to be used to produce a filename, filesystem-illegal characters must be removed or converted to legal characters. Clean() in mode 3 will convert such characters into safe underscores. This example would produce the filesystem-safe value of AC_DC_ Back In Black. clean(\//:*?"<>|, 3) This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character output _________ which consists entirely of underscores.

(Back to top)

FixCase(…): Changes the case of a given string

Description	fixcase(string, mode) The FixCase() function will convert the supplied text string according to the specified mode. Available mode values: 0 Title Case 1 All Words 2 First Word 3 All Uppercase 4 All Lowercase Argument mode is optional (defaults to 0).
Examples	fixcase(enjoy the silence) The default mode 0 is used, so the output is Enjoy the Silence. fixcase(enjoy the silence, 1) Using mode 1, all words are uppercased, so the output is Enjoy The Silence. fixcase(MY ALbUm IS cAlLeD: adam, 4) Outputs my album is called: adam.

(Back to top)

FixSpacing(…): Intelligently splits adjacent camel-cased words

Description	fixspacing(string, mode) The FixSpacing() function inserts spaces between adjacent camel-cased words in string. It is useful for helping to clean and convert metadata that favors compactness over standard sentence structure. Available mode values: 0 Disables conversion 1 Enables camel-case conversion Argument mode is optional (defaults to 1).
Examples	fixspacing(OneWorld) Outputs One World. fixspacing([name], 1) Outputs the name field with any camel-case converted into standard sentence structure. If the value of name was, MiracleOn34thStreet, the output would be Miracle On 34th Street. fixspacing(Another [name]) Assuming the same [name] as above, this would return Another Miracle On 34th Street.

(Back to top)

Hexify(…): Hexifies a string to make it suitable for web usage

Description	hexify(string) The Hexify() function URI encodes a string to make it useable by a browser or search engine. Hexify() is typically used by expressions generating or working on URLs in Media Center's Link Manager.
Examples	hexify(Oasis - /(What's The Story/) Morning Glory?) The result is Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F.

(Back to top)

Left(…): Retrieves a specified number of characters from the left of a string

Description	left(string, quantity) The Left() function retrieves no more than quantity characters from the left of the string.
Examples	left([filename], 3) Return the Windows drive letter, colon and first back-slash from the filename.

(Back to top)

Length(…): Returns the number of characters in a string

Description	length(string) The Length() function returns the number of characters contained in string.
Examples	length(A Simple Plan) Returns 13. if(compare(length([filename]), >=, 68), Long, Short) The length of the filename is calculated, and compared against 68, outputting Long when the length is greater than or equal to 68, and Short otherwise.

(Back to top)

Mid(…): Retrieves specified characters from a string

Description

mid(string, start position, quantity) The Mid() function returns a specified quantity of characters from the start postion in string. The start postion is 0-based (i.e. the first character is considered position 0). A quantify of -1 returns all characters from the start postion to the end of string. Argument start position is optional (defaults to 0). Argument quantity is optional (defaults to 1).

Examples

mid(12345) Returns 1, using is the default quantity (1) of characters from the default start position of (0 - the beginning of the string). mid(12345, 1, 2) Returns 2 characters begining at start position 1, which is 23. Additional Examples An example that uses Mid() to re-order a date field. An example that uses Mid() to output a number of stars based on an arbitrary rating value.

(Back to top)

Regex(…): Regular expression pattern matching and capture

Description

regex(string, regexp, run mode, case sensitivity) The Regex() function performs regular expression (RE) pattern matching on a string. The string is evaluated against the regular expression regexp, and run mode dictates the values output by Regex(). The three modes allow for match testing, capture output, or silent operation. All match captures are placed into special variables referenced as [R1], [R2], ... [R9], which can be used in later in the expression. The contents of the captures [R1] ... [R9] are available until the end of the expression, or Regex() is run again, whereby they are replaced. The regular expression implementation used prior to Media Cener 19 is the Microsoft 2010 TR1 engine, and in Media Cener 19 it is the Boost engine. Available run mode values: 0 Runs in Boolean test mode, returning either a 1 or 0, indicating whether the string matched (1) or did not match (0) the regexp. This run mode is useful within an If() test, so that different true or false actions may be taken. 1 to 9 Outputs the specified Nth capture group's contents, where N ranges from 1 to 9. Only a single capture is output in this mode, but all captures are available in the [R1] ... [R9] capture variables. This run mode is used to easily output a single matching sub-string. -1 Runs in silent mode, with no output being produced. This run mode is useful as a means to capture portions of the string to be later used in subsequent portions of an expression. The case sensitivity argument toggles the case-sensitivity of regular expression matching. Note that case insensitivity does not apply to characters inside a character class [ ]. Use both uppercase and lowercase characters when necessary to match either case (e.g. [aAbB] to match either uppercase or lowercase A or B). Available case sensitivity values: 0 Ignore case when matching (e.g. the letters E and e are identical) 1 Consider case when matching (e.g. the letters E and e are considered different) The regular expression language assigns special meaning to many characters. A few of these meta-characters, such as forward slash /, comma , and both ( and ) are also reserved and used by the Media Center expression language. To force the Media Center expression engine to ignore the meta-characters in regexp, surround the entire regular expression with /# #/. This is one of Media Center's escapements, which tells the expression engine to ignore everything inside, so that the entire, uninterpreted regexp can be provided to the Regex() regular expression evaluator. Although surrounding regexp by /# #/ is not necessary or required when no conflicting characters are in use, and you may manually escape the expression languages meta-characters with a forward slash /, it is probably a safe practice to always encase every regexp within /# #/. Argument run mode is optional (defaults to 0). Argument case sensitivity is optional (defaults to 0).

Examples

ifelse(regex([name], /#^(the|an|a)\b#/, 0, 1), Fix your case!) Searches the name field for any of the lowercase articles the, and and a at the beginning of name, and outputs Fix your case! when the match succeeds. The run mode is 0 which is a test and capture mode, and case sensitivity is enabled. if(regex([artist], /#([[:punct:]])#/, 0), [R1] --> [Artist], No Punctuation) Using the default mode 0, Regex() will output a Boolean for use inside a condtional to cause some action to occur based on the match success or failure. This example matches against the artist field looking for any punctuation character. If the match succeeds (a punctuation character was found), that character is output followed by the string --> and the artist. In there was no match, the string No Punctuation is output. regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2] The string is matched against the regexp that is looking for a D followed by any number of digits, followed by a T and then more digits. Those digits were captured, and later used to output the value Disc: 03, Track: 02. regex([filename (name)], /#^(\d+)-#/, -1)Track number is [R1] Using run mode -1, the file's name is pattern tested against the regexp which is looking for leading digits followed by a dash. Those digits are captured in buffer [R1] which is used later in the expression. If the file name was 2-foo.mp3, the output would be Track number is 2. regex([filename], /#(\d{1,2})\.(\d{1,2}).(\d{4})#/, -1)[R3]//[R1]//[R2] Matches and captures a date formatted as dd.mm.yyyy anywhere within the filename, and rearranges it in a standard format of yyyy/mm/dd. Since run mode is -1, no output occurs. However, captured match segments are made available for subsequent use. The three captures, [R1], [R2] and [R3] are arranged in the textual output so that we get the desired year/month/day ordering, such as 2011/08/19.

(Back to top)

RemoveCharacters(…): Removes a list of characters from a string

Description

removecharacters(string, character list, mode) The RemoveCharacters() function will remove from string any characters in the character list. The characters removed depend upon the mode specified. The function operates in a case-sensitive manner. Available mode values: 0 Remove all instances 1 Remove from the beginning only 2 Remove from the end only 3 Remove from each end Argument mode is optional (defaults to 0).

Examples

removecharacters(Paper, Ppr) Removes P, p, and r from Paper, resulting in ae. The default mode 0 is in effect, removing all instances of the characters specified in the character list. removecharacters(Paper, Ppr, 1) With mode 1 set, only the inital character P is removed, resulting in aper. removecharacters(Paper, Ppr, 2) In mode 2, only one character from the end of the string are removed, leaving "Pape. removecharacters(Paper, Ppr, 3) Both the front and back are affected in mode 3, causing the removal of the leading P and trailing r resulting in ape. removecharacters([artist], /(/)) Removes any ( and ) characters from anywhere within the [artist] field.

(Back to top)

RemoveLeft(…): Trims characters from the beginning of a string

Description	removeleft(string, quantity) The RemoveLeft() function removes a specified quantity of characters from the left side of a string. If the quantity is larger than the length of the string, the output will be empty.
Examples	removeleft(Good Deeds, 5) Removes the first 5 characters from resulting in Deeds being output.

(Back to top)

RemoveRight(…): Trims characters from the end of a string

Description	removeright(string, quantity) The RemoveRight() function removes a specified quantity of characters from the right side of a string. If the quantity is larger than the length of the string, the output will be empty.
Examples	removeright(03-02-1959,5) Removes the last 5 characters from the given date, leaving only the month and year 03-02.

(Back to top)

Replace(…): Replace or remove a string segment

Description

replace(string, old, new) The Replace() function replaces all instances of old within string with new. If new is unspecified, it defaults to an empty value, causing old to be removed. Replace() operates in a case-sensitive manner. Argument new is optional (defaults to EMPTY).

Examples

replace(The Daily Show with John Oliver, hn Oliver, n Stewart) Now that John Oliver has completed his summer stand-in for Jon Stewart, it is time for a replacement. The old sequence hn Oliver will be replaced with the new sequence n Stewart, resulting in The Daily Show with Jon Stewart. replace(Sample String, s, Replaced) In this example, the original string does not contain the old value s anywhere, so no replacement occurs and the original string is returned. replace(Led Zeppelin.[remastered], .[remastered]) Removes the trailing old value .[remastered] from the original string, resulting in Led Zeppelin. Because no new string is specified, the default empty value is used as a replacement, effectively stripping the old value.

(Back to top)

Right(…): Retrieves a specified number of characters from the right of a string

Description	right(string, quantity) The Right() function retrieves the specified quantity of characters from the right of the string. If quantity is larger than the length of string, the original string is returned.
Examples	right([filename], 3) Returns the last three characters from the filename (typically this is the file's suffix).

(Back to top)

List Manipulation

Media Center supports several different types of fields, one of them being the List type. A List type is a library field of type List, or an expression coerced into a list type.

The functions in this section provide the ability to manipulate lists and list items. A list is a sequence of strings, each separated from one another by an arbitrary delimiter. The default delimiter is a semicolon. Media Center does not make a strict distinction between a string and a list of strings. In fact, a list is just a string, and it is safe to think of a string as a list with zero or more arbitrary delimiter sequences. For example, the string "2013-08-17" can be thought of as a dash-delimited list with the three items "2013", "08" and "17".

This weak typing is very useful since a list, for example, "John; Sally" that contains the two items "John" and "Sally" can be manipulated not only using the list functions in this section, but because it is just a string, it can also be manipulated with string functions. For example, taking the same list above and combining it with the string "; Joe" adds a new item to the list "John; Sally; Joe", and removing the first 6 characters with RemoveLeft() would produce a now shortened string/list "Sally; Joe". The list manipulation functions make this job easier, especially when using the default semicolon delimiter. Furthermore, since any character or sequence of characters can be considered as a list delimiter, any string can be treated as a list, and the functions in this section can be used on any string as needed.

In some areas such as a panes column, or a category view, Media Center gives special treatment to List types. For example, using semicolon as the delimiter, a List will be automatically split apart into its individual items.

ListBuild(…): Constructs a list from a series of items

Description

listbuild(mode, delimiter, item1, item2, …) The ListBuild() function constructs a list from item1, item2, ... using a supplied delimter to separate the individual items in the resulting list. The construction mode affects how empty items are handled - they can be included or excluded. The mode typically used exclude empty items, so that lists do not contain empty slots. However, there are occasions when retaining empty slots is useful, such as when using a list to act like an array where data is stored in particular slots so that the ListItem() function may later retrieve values at a given index. It can also be useful when calculating several expressions and combining the results into a single list for presentation; by including all items, items can be made to line-up for visual inspection in a column. Available mode values: 0 Include empty values 1 Exclude empty values The delimiter argument specifies the character or character sequence to be inserted in between items in the list. An unspecified delimiter will result in a delimiterless concatenation of the supplied arguments item1, item2, etc. Argument delimiter is optional (defaults to EMPTY).

Examples

listbuild(1, ;, Bennie, June) Returns a standard semicolon-separated list containing two items Bennie; June. listbuild(1, \, [album artist (auto)], [album]) Builds a backslash-separated list combining the two fields album artist (auto) and album. This is useful for building panes column or categories hierarchies in a view.

(Back to top)

ListClean(…): Various list operations

Description	listclean(list, mode, delimiter) The ListClean() function performs one of the operations specified by mode on the given list. The specified delimiter separates list items. 1 Remove duplicates 2 Reverse the order of items Argument delimiter is optional (defaults to SEMICOLON).
Examples	listclean(c;b;c;a, 1) Removes duplicates from the list, returning c;b;a. listclean(d;c;b;a, 2) Reverses the list items, returning a;b;c;d. listclean(\a\x\x\x\z, 1, \) Removes duplicates from a backslash-separated list, returning \a\x\z.

(Back to top)

ListCombine(…): Combines two delimited lists into a single delimited list

Description

listcombine(list1, list2, input delimiter, output delimiter, mode) The ListCombine() function returns a single list after performing the operation specified by mode on the two lists list1 and list2. An input delimiter and an output delimiter may be specified. The input delimiter is effective for both list1 and list2, and the output delimiter will be used in the returned list, replacing the input delimiter from both list1 and list2. Available mode values: 0 Combine lists removing duplicates (order is preserved). 1 Output only items contained in both lists (order is preserved). Argument input delimiter is optional (defaults to SEMICOLON). Argument output delimiter is optional (defaults to SEMICOLON). Argument mode is optional (defaults to 0).

Examples

listcombine(a;b;e, a;b;c;d) Returns a;b;e;c;d. This example uses the default mode 0 to combine list1 with list2, preserving the order of items. The default ; input delimiter and output delimiter is used. listcombine(a;b;e, a;b;c;d, ;, ;, 1) Returns a;b. The input delimiter and output delimiter are both specified as ;, and mode 1 is used to produce a list of only items that exist in both list1 and list2. listcombine(a-c, c-f, -, ..., 0) Returns a...c...f. The input delimiter is -, while the output delimter is ..., and mode 0 combines both lists. listcombine(a#@#c, c#@#f, #@#, ., 0) Returns a.c.f. This example demonstrates how to combine two lists with duplicates removed while replacing a multi-character input delimiter #@# with a single-character output delimiter .. listcombine([people], [places])&datatype=[list] The result here would be a single, semicolon delimited list containing all the list items from the [people] and [places] fields. For example, if [people] contains Family\Mum; Family\Dad; Family\Gran, and [places] contains UK\Scotland\Edinburgh; UK\Scotland\Edinburgh\Edinburgh Castle, the output list would be Family\Mum; Family\Dad; Family\Gran; UK\Scotland\Edinburgh; UK\Scotland\Edinburgh\Edinburgh Castle. Using the &datatype=[list] cast makes the expression split individual list items in a panes or categories view.

(Back to top)

ListCount(…): Returns the number of items in a list

Description	listcount(list, delimiter) The ListCount() function returns the number of items that exist in a list delimited by delimiter. Argument delimiter is optional (defaults to SEMICOLON).
Examples	listcount([keywords]) Returns the number of keywords for the file. listcount([filename (path)], \) Returns the number of the directories in a Windows drive-based file path. The example demonstrates that non-List type fields can be used with the functions in this section. While the delimiter specified here is \, an escaped forward slash // could be used when applicable.

(Back to top)

ListItem(…): Returns an item from a location in a list

Description	listitem(list, position, delimiter) The ListItem() function returns the item from the specified position in the list. Items in a list are zero-based, so the first item in the list is located at postition 0. Nothing is returned with the position is outside the bounds of the list. Argument delimiter is optional (defaults to SEMICOLON).
Examples	listitem(a;b;c, 1) Returns b, since postion 1 is the second item in the list a;b;c. listitem(1:04:47, 2, :) Using the delimiter :, returns item at position 2, which is the seconds value 47 from the time 1:04:47.

(Back to top)

ListSort(…): Sort a list of values

Description

listsort(list, mode, delimiter) The ListSort() function sorts a list in the order according to mode, using the specified delimiter. Available mode values: 0 Ascending sort 1 Descending sort Argument mode is optional (defaults to 0). Argument delimiter is optional (defaults to SEMICOLON).

Examples

listsort(c;a;b) Returns a;b;c, using the default ascending mode and (:) delimiter. listsort(Joe Baxter/, Sally Henson/, Sue Smith, 1, /,) Returns Sue Smith,Sally Henson,Joe Baxter. Note the requirement to escape the , characters within the list string and in the specified delimiter itself. listsort([artist];[composer]) Sorts the combined artist and composer lists in ascending order. Note the simple manual construction of a single List by combining the two List type fields, and forcing a ; between the two.

(Back to top)

Date and Time Functions

Media Center provides several functions for the conversion, formatting and generation of dates and times. Date and time for a Date-type field is stored internally as a single floating-point number, where the integer portion represents the number of days since the Epoch, and the decimal portion represents the fraction of a day in seconds. The Epoch is defined as December 30th, 1899 at 00:00:01. Certain fractional values and whole numbers are used to encode Time-only and Year-only values. For example, the internal Date value of "2" is considered as 1900, without a time when converted using the DateTime conversion format of FormatDate(), whereas adding a small fraction and using "2.001" instead produces a value of "1/1/1900 12:01 am". These details are only relevant if you are doing conversions.

The Windows locale setting will affect the interpretation and formatting of date and time information.

ConvertDate(…): Converts a human-readable date to the internal format required for use in date fields

Description

convertdate(date_time string) Converts a human-readable date_time string into the internal floating-point representation used by Media Center to store a date and time.

Examples

convertdate(3//6//2012) Returns the value 40974, which is the internal floating-point represenation of the date string 3/6/2012. This value can used by any field of type Date, or in any function that requires as input a Date type value. formatdate(convertdate(12//2//1985), decade)) Converts the date string 12/2/1985 (note: December 2nd, not February 12th) into a Date type value, and then formats the result as a decades grouping, returning 1980's. This might be used for creating decade groupings.

(Back to top)

FormatDate(…): Formats a date value in a specified manner

Description

formatdate(date value, format specifier, empty label) The FormatDate() function provides custom formatting of date and time values through the use of a format specifier. Output will be formatted according to format specifier. The date value is a Media Center interal floating-point date/time representation, stored in Date fields, and output from various functions such as Now() and ConvertDate(). To pass a field of type Date to FormatDate(), use the raw (unformatted) field specification, such as "[Date Imported,0]". The format specifier provides a recipe for converting the internal value into a human-readable string. Supported are a variety of Windows style, strftime() style, and Media Center-specific formats specifiers. Construct the format specifier from any number or combination of those defined in the following table. Additionally, any non-format characters will be output without interpretation. This allows creating rich date/time output strings. To output a word that is a reservered format specifier, surround the word with double-quotes. The empty label argument will be output if the date value is empty. Specifier Description Day d Day Day of the month as digits without leading zeros for single-digit days. dd %d Day of the month as digits with leading zeros for single-digit days. ddd %a Day of the week, abbreviated to three letters. dddd %A Dayname Day of the week. %w Day of the week as a decimal number, Sunday as 0 (0-6). %j Day of the year (001-366) %j Dayordinal Ordinal day of the month (e.g. 1st, 2nd, etc.). Month M Month as digits without leading zeros for single-digit months. MM %m Month as digits with leading zeros for single-digit months. MMM %b Abbreviated month name, three letters (e.g. Apr, Nov). MMMM %B Month Full Month name (e.g. April, November). Year y Year represented only by the last digit. yy %y Year represented only by the last two digits. A leading zero is added for single-digit years. yyyy %Y Year Year represented by a full four or five digits. Decade Year expressed as a decade (e.g. 1970's, 2010's) Hour h Hour Hours with no leading zero for single-digit hours; 12-hour clock. hh %I Hours with leading zero for single-digit hours; 12-hour clock. H Hours with no leading zero for single-digit hours; 24-hour clock. HH %H Hours with leading zero for single-digit hours; 24-hour clock. Minute m Minute Minutes with no leading zero for single-digit minutes. mm %M Minutes with leading zero for single-digit minutes. Second s Second Seconds with no leading zero for single-digit seconds. ss %S Seconds with leading zero for single-digit seconds. AM/PM t One character time marker string, such as A or P. tt %p Multi-character time marker string, such as AM or PM. Combined %x Date Date expressed in the system's format. %X Time Time expressed in the system's format. %c DateTime Date and time expressed in the system's format. ShortDate Age-conditional date formatted as one of "Year", "MMM d", or "MMM d Year". ShortDateTime Date in ShortDate format plus Time. Week Number %U Week number with the first Sunday as the first day of week one (00-53). %W Week number with the first Monday as the first day of week one (00-53). Miscellaneous Elapsed Time expressed as elapsed time (e.g. 2.5 hours). ElapsedAgo Time expressed as elapsed time ago (e.g. 2.5 hours ago). Filename Date and time expressed in filename-friendly format, includes seconds to avoid filename collisions (e.g. 20040521-032221). %% A percent (%) character. Argument date value is optional (defaults to [date,0]). Argument empty label is optional (defaults to EMPTY).

Examples

formatdate(year-month) Outputs the file's date formatted as Year-Month, such as 2012-April. The default date value of [Date,0] is used. formatdate([last played,0], yyyy//MM//dd, Not Yet) Returns the file's last played date as year/month/day without the time, ignoring the system locale setting. If a file has no last played value, the expression will output Not Yet instead. formatdate([date modified,0], month %Y) Returns the file's modification date/time in the form of a long month name and a four-digit year, such as December 2010. formatdate([date imported,0], The "year" is year) Outputs the The year is ####, where #### is the year the file was imported into the Library. Note that the word year must be surrounded in double-quotes to have it considered as literal text, and not the Year format specifier. formatdate([date imported,0], month)&datatype=[month] This examples is the same as the previous example, but includes a cast to the Month type &datatype=[month]. This cast can be used to cause chronological month-sorting, rather than month name alphabetic-sorting, in a panes or category view. Data-type coercion is discussed above. Additional Examples Date formatting development discussion, usage tips and examples.

(Back to top)

Now(…): Retrieve and display the system date

Description

now() The Now() function returns a floating-point value represeting the current system date and time. It is generally useful for performing date arithmatic in expressions that desire to figure out elapsed time. Any raw date field or value representing a date can be subtracted from Now() to realize an elapsed time delta.

Examples

now() When run on Aug 17, 2013 at 19:28:00, returns approximately 41503.811115995. formatdate(now(), date) Returns the current date, without a time component, formatted according to the system's locale settings. formatdate(math(now() - 3, dddd dd MMMM yyyy H:mm) The date from three days ago is formated as something like Wednesday 14 August 2013 19:35. This is accomplished by subtracting the value 3, which would be days, from Now(), and its output formatted by FormatDate().

(Back to top)

File Path and Identifier Functions

The funcions in this section provide specific file-related information such as a file's name, path, volume, and other Media Center internal information.

FileDBLocation(…): Identifies a file's databases

Description

filedblocation(format) The FileDBLocation() function returns identifiers in the specified format specified that indicate to which internal database(s) a file belongs. Media Center maintains several internal databases to track a file's disposition. This function is primarly for technical use only, and will have little utility for most users. Available format values: 0 Semicolon-separated list of formatted database names 1 Numeric value of OR'd database bit flags The table below provides common values output from FileDBLocation(): Database name Bit position Main 0 Playing Now 1 CD 2 Explorer 3 Other (16) 5 Other (6) 6 Grouping 7 Removed 8 Podcast 10 Other (4096) 12 Stacks 14 Category Images 18 Bad 19 Argument format is optional (defaults to 0).

Examples

filedblocation() For a file in the Main and Other (4096) databases, the result would be Main; Other (4096). filedblocation(1) The result from the same file would be 4096 (bit 0 and bit 12 set). Additional Examples Sample expression that uses FileDBLocation() to show a file's databases.

(Back to top)

FileFolder(…): Returns the name of a file's parent

Description

filefolder(filepath, level) The FileFolder() function returns parent sub-folder name for filepath. The level argument specifies which parent sub-folder name to return, working the filepath from right-to-left (i.e. bottom of the folder tree upwards to the top). A value of 0 specifies a file's immediate parent, 1 its grandparent, etc., up to the root of the filepath. A value of Unassigned will be returned when the specified level exceeds the root of the filepath. Argument filepath is optional (defaults to [filename]). Argument level is optional (defaults to 0).

Examples

filefolder() Returns the name of the file's parent folder. filefolder([filename,0], 0) Same as the previous example. filefolder(c:\some\folder\for\a\file.ape, 2) Returns the great grandparent sub-folder named folder. filefolder(c:\some\other\folder\a\, 2) Returns the folder named other. Notice the file name is not required in the filepath. FileFolder() works by looking from the end of the filepath until it finds a backslash \.

(Back to top)

FileKey()(…): Returns a file's unique internal identifier

Description	filekey()() The FileKey()() function returns the unique identifier assosciated with a file. Media Center assigns a unique identifier to each file in the Libary. It is useful in expressions when referring to individual files is necessary. Services such as MCWS use this value to reference a file.
Examples	filekey() Returns a integer value, such as 22029495, unique for eac file in the Library.

(Back to top)

FileName(…): Returns a file's name component

Description	filename(filepath, include suffix) This function returns the file name part of filepath. Inclusion of the file's suffix depends on the include suffix argument. 0 Suppress file suffix 1 Include file suffix Argument filepath is optional (defaults to [filename]). Argument include suffix is optional (defaults to 1).
Examples	filename(C:\Music\File.mp3) The output is File.mp3. filename(C:\Music\File 2.wav, 0) The output does not include the file suffix, and is File 2. filename() Returns the value contained in the field [filename (name)].

(Back to top)

FilePath(…): Returns a file's path component

Description	filepath(filepath) This function will return the path portion of the specified file path. The filepath should be a rooted path. For Windows, this includes the drive letter or leading \\ for UNC paths. For *nix-based systems, this includes the root /. The field [filename (path)] is equivalent to FilePath(), and is generally preferred. Argument filepath is optional (defaults to [filename]).
Examples	filepath(C:\Music\File.mp3) Returns C:\Music. filepath() Returns the value contained in the field [filename (path)].

(Back to top)

FileVolume(…): Returns a file's volume name component

Description	filevolume(filepath) The FileVolume() function returns the volume name component of the specified file path. The path should be a rooted path (see the same comment above for FilePath(). For *nix-based systems, the output is empty. The field [volume name] is equivalent to FileVolume(), and is generally preferred. Argument filepath is optional (defaults to [filename]).
Examples	filevolume(C:\Music\File.mp3) Outputs C:. filevolume() Returns the value contained in the field [volume name].

(Back to top)

Miscellaneous Functions

The functions in this section are varied and have specialized applicability. Some are primarly used internally by MC to generate values available in various Library fields.

AlbumArtist(…): Returns a file's calculated album artist

Description	albumartist() This function calculates the album artist value used in various views and fields. It is used to populate the Library field album artist (auto) with its value. Either the field or AlbumArtist() can be used.
Examples	albumartist() Returns the value present in the album artist (auto) field. Additional Examples Describes the algorithm used by AlbumArtist() to calculate the "album artist (auto)" field's value.

(Back to top)

AlbumKey(…): Returns a unique album key for a file

Description	albumkey() The AlbumKey() function returns "[album artist (auto)] - [album]". It is a convenience function, used to return the generally unique album / artist combination string used to distinguish between two like-named albums such as "Greatest Hits".
Examples	albumkey() For an album named Greatest Hits and an album artist (auto) of The Eagles, returns The Eagles - Greatest Hits.

(Back to top)

AlbumType(…): Returns the album type for a file

Description	albumtype() The AlbumType() function returns a description regarding an album's completeness and its quantity of artists. It is used to populate the Library field album type with its value. Either the field or AlbumType() can be used.
Examples	albumtype() Returns, for example, Single artist (complete), or Multiple artists (incomplete).

(Back to top)

Counter(…): Counts upwards in specified increments

Description

counter(start value, increment) The Counter() function outputs a montonically increasing number (more simply stated, it counts) from a start value, and each time called, increases by the increment value. It is useful for sequentially numbering fields. The Counter() function maintains an internal counter, and it resets itself to zero after five seconds of inactivity. Becuase Counter() continues to count, it should only be used in single-use situations such as assigning its output to some field through field value assignment, for example, =counter(). With proper care, it can be used as part of an expression in the Rename, Move & Copy tool, but see also CustomData(). It is not recommended for use in any context that continually refreshes its content, such as in a panes column, file list, or expression-based custom query. Probably the best way to understand the results is to test the first example below as an expression column in a file list, and move the mouse around over that column. Argument start value is optional (defaults to 1). Argument increment is optional (defaults to 1).

Examples

counter() Outputs values starting at 1, and incrementing by one, it will return 1, 2, 3, ... until no longer called. This might be used, for example, to assign to the [Track #] field of several tracks using the field assignment expression =counter(). padnumber(counter(370, 2), 4) Outputs numbers beginning from 370, incremented by two each, and padded to four digits. For example, 0370, 0372, 0374, etc.

(Back to top)

CustomData(…): Returns internal data to the expression language

Description	customdata(mode) The CustomData() function supports returning Media Center internal data to the expression language. Currently there is only one supported use, which is to use CustomData() in the Rename, Move & Copy tool to assist in numbering files. Available mode values: # Returns a file's row number in the Rename, Move & Copy tool
Examples	Spring_Break_Bash_padnumber(customdata(#), 4) In the Rename, Move & Copy tool, each consecutive file would be named Spring_Break_Bash_ followed by a four digit, zero-padded number starting at 0001.

(Back to top)

Math(…): Evaluates a given mathematical formula

Description

math(expression) The Math() function performs mathematical calculations. Standard arithmetic operators are supported, as are various numerical, trigonometric, and comparative functions. Simple variables are supported, as are multiple statements. Arithmetic Operators + Addition - Subtraction * Multiplication / Division ^ Power % Modulo Boolean Operators ! NOT & AND | OR Grouping Operators ( ) Precedence grouping Comparison Operators } Absolute value maximum (i.e. x or y that is maximum distance from 0). { Absolute value minimum (i.e. x or y that is minimum distance from 0). > Distance between x and y, positive when x greater than y, negative otherwise. < Distance between x and y, positive when x less than y, negative otherwise. Functions abs(x) Returns the absolute value of x. sign(x) Returns the sign of x (1 when x >= 0, -1 when x < 0). log(x) Returns the natural logarithm (base e) of x. log10(x) Returns the common logarithm (base 10) of x. pow(x,y) Returns x raised to the y-th power. rand(x) Returns a random value ranging between 0 to x. randn(x) Returns a random value ranging between -x and x. Comparison Functions min(x,y) Returns the minimum value of x and y. max(x,y) Returns the maximum value of x and y. equal(x,y) Returns 1 when x = y, 0 otherwise. below(x,y) Returns 1 when x < y, 0 otherwise. above(x,y) Returns 1 when x > y, 0 otherwise. Formatting Functions int(x) Returns the integer portion of x. frac(x) Returns the fractional portion of x. round(x) Returns x rounded to the nearest whole number. trunc(x,n) Returns x truncated to n decimal places. Trigonometric Functions atan(x) Returns the arctangent of x. cos(x) Returns the cosine of x. sin(x) Returns the sine of x. tan(x) Returns the tangent of x. abscos(x) Returns the absolute value of cosine(x). abssin(x) Returns the absolute value of sin(x). The order of operator precedence is summarized as follows, from top to bottom: (   )     !     ^   *   / Left to right +   - Left to right |   & Left to right Variables may be assigned and used by specifying a simple string of letters. Examples: math(val=2) or math(x=pow(2,3)). Multiple equations may be specified, each separated by a semicolon. Expressions are evaluated left to right. The final value of the Math() function will be the result of the right-most equation. For example, the equation math(x=4; pow(2^x)) will output 16. Note: Empty fields Fields used inside of Math() are expanded (interpolated) directly. Fields with empty values may produce incomplete Math() statements. For example, if the field [number plays] is empty, an expression such as math([number plays] + 2) would be seen by Math() as + 2. This incomplete expression would produce a syntax error. See the Additional Examples for more information. Note: Locales and Commas Special care must be taken with the Math() function and locales that use , (comma) as a decimal separator. Many Media Center fields and the return values from functions may contain comma as the decimal point. Your expressions will need to Replace() these before passing the values to Math(), which always uses dot . as the numeric decimal point. For example, the expression math(1,5 + 1,5) will fail since Math() does not consider 1,5 to be a valid number. Fields that cause problems are any fields that produce floating-point values, such as any Date type field in raw format (e.g. [date,0], [last played,0], [date modified,0], and [date imported,0]), or any textual field that contains floating-point values that will be used for various calculations (e.g. any of the Dynamic Range variants). Certain functions such as Now() and ConvertTime() also return localized floating-point values. Handling this problem is not difficult. Before passing any floating point number to Math(), use Replace() first. See the examples below.

Examples

math(10 + 4) Returns 14. math(10 + 2 * 25) Returns 60, demonstrating that multiplication has higher precedence than addition. math((10 + 2) * 25) Returns 300, demonstrating that parenthesis grouping has higher precedence than multiplication. math(replace(now(), /,, .) - replace([last played,0], /,, .)) The , is replaced by a . in the output of both Now() and in the raw field value [last played,0]. Note that the comma must be escaped so that it is seen as an argument and not as an argument separator. math(replace(now() - [last layed,0], /,, .)) The same as the previous example, but is more efficient and simpler since it calls Replace() just once on the entire string to be passed to Math(). Additional Examples An explanation and some solutions for fields that evaluate to empty within Math().

(Back to top)

Size(…): Returns a file's size in a format specific to the media type

Description	size() The Size() function returns media size information specific to the particular media type. It is used to populate the Library fields duration and dimensions with their values. Either the field or Size() can be used. Type of information reported by size for the file's media type: Audio Duration Video Duration Image Dimensions Data No information returned.
Examples	size() Returns values such as 400x225 for images, or 3:09 for audio files.

(Back to top)

TrackNumber(…): Returns a file's track # value

Description	tracknumber() The TrackNumber() function returns a file's track #, or 0 if the no value exists. It is used to populate the Library field track # with its value. Either the field or TrackNumber() can be used.
Examples	tracknumber() Returns the value present in the track # field.

(Back to top)

TVInfo(…): Miscellaneous television and other preformatted information

Description

tvinfo(type) The TVInfo() function is multi-purpose, and returns a specific type of information about television recordings, programs, and preformatted informational strings for use in captions, thumbnails, grouping, etc. Available type values: IsProgram Returns 1 if the file is a program, 0 otherwise IsGuideProgram Returns 1 if the file is a guide program, 0 otherwise IsRecordedProgram Returns 1 if the file is a recorded program, 0 otherwise Channel Returns Returns the channel name, given a channel number ChannelKeywords Returns channel keywords Date Returns a program's date DateNoTime Same as Date, but without the time. NameDisplay Returns [name]: [series] or just [name] NameDisplayWithDate NameDisplay + ([year]) Record Returns 1 if the program is scheduled to be recorded, 0 otherwise RecordMark Returns a red dot if the program is schedule to be recorded. SeriesDisplay Returns [series] or [name] SeasonDisplay Returns [season] SeasonEpisode Returns [season].[episode] TimeDisplay Returns program start time (system time format), or "Showing" if program on now TimeDisplayNoOnNow TimeDisplay without on now handling SizeDisplay Returns [duration] ([file size]) or [dimensions] ([file size]) WatchedDisplay Returns Watched() information, such as No, Yes, 80%, etc.

Examples

tvinfo(namedisplay) Returns formatted name and series output. If the file has no [series] value, only [name] is output.

(Back to top)