PM123's Remote command reference - Meta data access

PM123 currently understands the following commands for accessing meta information of songs, playlists or folders. See writing meta data to modify the meta data of a song. Optional parameters are enclosed in square brackets.

All info commands return a  sequence of lines terminated by an empty line. Each line except for the terminating empty line has the format KEY=value. Newline characters in string values are escaped by <ESC>r and <ESC>n respectively to keep the value in one line. The escape character itself (27) is escaped by two escape characters <ESC><ESC>. Every other character is returned as it is. This includes 8 bit characters as well as other control characters like backspace and null bytes. The strings are returned in the OS/2 system codepage.

Note that the requests may take a moment to complete if the information has to be obtained first and maybe this causes a network time out.

info format [<url>]

Returns technical and physical format information for the given file or URL. The URL may be enclosed in double quotes ("). If no <url> is specified, the information about the current song is returned.[1]

This query has no means of an error except if you forgot the URL and no song is currently loaded, in which case it will return an empty line. In all other cases, including an invalid URLs at least one line with an invalid tag is returned.

Reply

FILESIZE=18282882 (bytes)
FILETIME=2011-05-03 23:15:58
FILEATTR=writable
SAMPLERATE=44100
CHANNELS=2[.0]
FLAGS=song
TECHINFO=Joint-Stereo, Xing
DECODER=mpg123.dll
FORMAT=MPEG 1 layer 3
SONGLENGTH=566.282000 (seconds)
BITRATE=256000 (bits/second)
SUBITEMS=0

The list is terminated by an empty line. All of the above tags are optional and in arbitrary order.

The file FILEATTR property contains a space delimited list of the following flags:

The format flags (FLAGS=) contains a space delimited list of the following strings:

It is up to the decoder plug-in to fill the TECHINFO string. In case of invalid items this field may contain a descriptive error text.

The SUBITEMS property contains the number of immediate sub items in a playlist or folder regardless if they are playlists, songs, invalid or whatever. It does not include nested songs. If you want to know how many playable song a playlist contains, use info playlist.

info meta [<url>]

Returns meta information of the given file or URL. The URL may be enclosed in double quotes ("). If no <url> is specified, the information about the current song is returned.[1]

In case of an error or if no meta information is available only an empty line is returned. You may use info format to check what is going on.

Reply

TITLE=Fragile
ARTIST=L.S.G.
ALBUM=The Best Of L.S.G.
YEAR=2003
COMMENT=Amazon.com...
GENRE=Dance & DJ
TRACK=4
COPYRIGHT=2003 Superstition...
REPLAYGAIN=-3.1,0.5,-2.8,0

The list is terminated by an empty line. All of the above tags are optional.

Some decoders and file formats may also return month or day information in the YEAR tag. So you should not expect exactly 4 digits.

The Replay Gain values are (in order):

  1. track gain,
  2. track peak gain,
  3. album gain,
  4. album peak gain.
If some of the gain values are undefined/missing, their values are empty strings.

info playlist [<url>]

Returns aggregated information for the given file or URL. The URL may be enclosed in double quotes ("). If no <url> is specified, the information about the current playlist is returned.[1] Note that this is not the currently playing list but the one selected by playlist.

The request may take a while because hundreds of items may be required to calculate the aggregate information.

Reply

SONGS=253
LISTS=7
INVALID=0
TOTALLENGTH=51367.753 (seconds)
TOTALSIZE=1291768215 (bytes)

The list is terminated by an empty line.

pl info item

Returns information on the current playlist item. Use the playlist navigation commands to select the current item. If no current item is selected, only an empty line is returned.

Reply

ALIAS=Radio Chromanova: Ambient
START=<start_location> (location string)
STOP=<stop_location> (location string)
AT=<last_play_pos> (location string)
PREGAP=2.0 (seconds)
POSTGAP=1.0 (seconds)
GAIN=+2 (dB)
OPTIONS=alt shuffle

The list is terminated by an empty line. All of the above tags are optional and in arbitrary order.

The OPTIONS attribute contains a space delimited list of:

pl info format
pl info meta
pl info playlist

Same as info format, info meta and info playlist, but query the information on the current playlist item rather than a specific URL.

Note that these function do not necessarily return the same than info xxx <url> with the URL of the playlist item. Some of the information might be overridden by the playlist item.

info refresh [<url>]

Refresh all meta information for the given file or URL. The URL may be enclosed in double quotes ("). If no <url> is specified, the current song is refreshed.[1] This will not impact any playback.
This command always returns an empty line, but this is not done before the information is really available.

Note that the command will discard any unsaved changes if applied to playlists.

info invalidate [<url>]

Invalidates all meta information for the given file or URL. This is similar to info refresh, but it does not reload any information unless it is really needed and it does not wait for that.

The URL may be enclosed in double quotes ("). If no <url> is specified, the current song is invalidated.[1] This will not impact any playback.
This command always returns an empty line.

Note that the command will discard any unsaved changes if applied to playlists.

Notes

  1. Be aware that using the commands without an URL is intrinsically unsafe because the current song might change at any time if a playlist is currently playing. Even the current playlist might change asynchronously because of a user interaction. So the result might not refer to the item that you expect.