Miscellaneous Functions

From wiki.jriver.com
Jump to navigation Jump to search

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

AlbumArtist(…)

Returns a file's calculated album artist.
Description albumartist()

The AlbumArtist() 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)

AudioAnalysisState(…)

Returns the state of audio analysis for a file.
Description audioanalysisstate()

The AudioAnalysisState() function returns a file's state of audio analysis. It can be used to determine if audio analysis (Library Tools > Analyze Audio...) should be performed on a media file. The AudioAnalysisState() function will return a string indicating the state of analysis. Possible values are currently:

NeededAudio analysis is needed
DoneAudio analysis is complete
N/AThe file type does not support audio analysis
Excluded (No Audio)The file type supports analysis, but contains no audio
Failed on <date>Audio analysis failed on the <date> specified
Examples audioanalysisstate()

Returns, for example, Needed for files that require audio analysis, or N/A if the file type does not support audio analysis.

Additional Examples

Describes the improved audio analysis and R128 volume leveling feature.
(Back to top)

Counter(…)

Counts upwards in specified increments.
Description counter(start value, increment)

The Counter() function outputs a monotonically 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.

Because 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 the only supported mode provides a file's row number in a file list, which is useful in the Rename, Move & Copy tool to assist in numbering files. It can also be used in expressions in a playlist to obtain the file's sequence number.

Available mode values:

#Returns a file's row number in a file list
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)

FilePlaylists()

Returns a list of playlists a file belongs to.
Description FilePlaylists()

The FilePlaylists() function will have details entered here. Please check back later. Regards, marko. Available mode values:

#Returns a file's row number in a file list
Examples FilePlaylists()

Using this will return a list of all the playlists a file is in, separated by semi-colons.

(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:

AudioDuration
VideoDuration
ImageDimensions
DataNo 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 pre-formatted information.
Description tvinfo(type)

The TVInfo() function is multi-purpose, and returns a specific type of information about television recordings, programs, and pre-formatted informational strings for use in captions, thumbnails, grouping, etc.

Available type values:

IsProgramReturns 1 if the file is a program, 0 otherwise
IsGuideProgramReturns 1 if the file is a guide program, 0 otherwise
IsRecordedProgramReturns 1 if the file is a recorded program, 0 otherwise
IsTVChannelReturns 1 if the selection is a TV Channel program
ChannelReturns the channel name associated with a given program
ChannelKeywordsReturns channel keywords
ChannelProgramNowReturns the name of a playing TV program on a given channel, empty otherwise
DateReturns a program's date
DateNoTimeSame as Date, but without the time.
NameDisplayReturns [name]: [series] or just [name]
NameDisplayWithDateNameDisplay + ([year])
RecordReturns 1 if the program is scheduled to be recorded, 0 otherwise
RecordMarkReturns a red dot if the program is schedule to be recorded.
RecordStatusReturns a string describing the record status, blank if not to be recorded.
SeriesDisplayReturns [series] or [name]
SeasonDisplayReturns [season]
SeasonEpisodeReturns [season].[episode]
TimeDisplayReturns program start time (system time format), or "Showing" if program on now
TimeDisplayNoOnNowTimeDisplay without on now handling
SizeDisplayReturns [duration] ([file size]) or [dimensions] ([file size])
WatchedDisplayReturns Watched() information, such as No, Yes, 80%, etc.
IsOnNonTopGroupedChannelReturns 1 if an EPG program is on a channel that is grouped as a non-top member, 0 otherwise.
ProgramChannelNumberReturns channel number of the television channel the program is on.
Examples tvinfo(namedisplay)

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

(Back to top)