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)

Char(…)

Returns a character from the numeric code of that character
Description Char(Numeric Number Code)

Char() has unicode support, however, only decimal values are supported. If you require a Hex to Decimal convertor, try unicode-search.net, or search for an alternative online.

Examples Char(189)
Returns ½

Char(9679)

Returns ●
(Back to top)   (Function index)

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

This function returns the list of playlists a file is in separated by semi-colons.

Examples FilePlaylists()

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

In and of itself, you might think that this is not 'all that', however, remember that we can combine this with other functions, thus giving us the ability to create expressions with playlist rules. A simple example would be:

[=IsEqual(fileplaylists(),genre,8)]=1

which when used in the search bar, will return all files that appear on any playlist containing 'Genre' in its name

(Back to top)

Literal(…)

Returns a string as given without any formatting or processing
Description Literal(String)

Literal() returns a given string as-is without any formatting or processing

Examples If(IsEqual([Artist], Queen, 1), Literal(If all music was Queen, I would be 10/10ths happy!), Literal(This is not Queen, which makes me sad. :-/))
This does not work, with the sad face breaking the expression completely and generating an error. It should work, suggesting that the Literal() function is currently broken.
This reference will be updated once clarification has been received. In the meantime, as detailed under Expression Language Syntax, using /* ... /* does work as Literal() is expected to. See next example...

/*Left(Theater,3) returns/* Left(Theater,3)

Returns Left(Theater,3) returns The. Here, the first expression function is not evaluated and instead, presented as given, whilst the second function, which is not escaped, is evaluated. Escaping text in this way could be useful if working with a large block of text that might contain parenthesis, forward slashes or other characters that would otherwise require to be escaped individually.
(Back to top)   (Function index)

Repeat(…)

Repeats a given string a specified number of times
Description Repeat(Value, Count)

Repeats "Value", "Count" number of times.

Examples Repeat(*,10)
Returns **********

Repeat(Ha,5)

Returns HaHaHaHaHa
(Back to top)   (Function index)

Row(…)

Returns the row number of a list entry
Description Row()

Row() returns the row number for each item in a list.

Examples Row()
When used as an expression column in a file list, each row is numbered starting at 1, incrementing by 1.
(Back to top)   (Function index)

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)

Translate(…)

Converts an English string found in the program to the current language selected in the language menu
Description Translate(String)

When using Media Center with any language other than English, the Translate() function can be used to translate an English string in the program to the current language.

Examples Translate(Keywords)
If using the French language setting, this will return Mots-clés
(Back to top)   (Function index)

TreeNode(…)

Returns the selected tree path.
Description TreeNode(Mode)
  • Argument mode is optional (defaults to 0).

Available mode values:

0Returns the full tree path
1Returns the currently selected tree node
2Returns the parent of the currently selected tree node
Examples TreeNode()
Will return the full tree path of the currently selected tree item (Uses mode zero by default)

What this function does is self-explanatory. This conversation on the Interact forums demonstrates a practical use-case scenario.

(Back to top)   (Function index)

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)