PM123 common plugin data types



See separate document.


INFOTYPE is an enumeration type. It is bit vector with flags for each individual type of information. The values may be ored to identify combinations. This type is usually used in conjunction with a INFO_BUNDLE structure to identify the valid fields in this structure.

PHYS_INFO - Physical information about an object.

typedef struct
{ PM123_SIZE filesize;
unsigned tstmp;
unsigned attributes;
Field Meaning Undef. value
filesize Physical size of the object in bytes. PM123_SIZE is a floating point type, but it should not contain fractional values. It is used because some compilers do not support 64 bit integers. -1
tstmp Last modification time stamp in Unix time format (seconds since January 1st, 1970). (unsigned long)-1
attributes Bit vector of PHYS_ATTRIBUTES flags. Currently the only valid flag is PATTR_WRITABLE, which indicates that the related object is not read only and the decoder supports writing to the object. This enables for instance the edit meta data function of PM123. none

TECH_INFO - Technical information about an object.

typedef struct
{ int samplerate;
int channels;
unsigned attributes;
xstring info;
xstring format;
xstring decoder;

Note that objects of type TECH_INFO should not be copied binary by value because of the embedded xstrings.

Field Meaning Undef. value
samplerate Sampling rate of the object in Hz. -1
channels Number of audio channels. 1 for mono, 2 for stereo. -1
attributes Bit vector of TECH_ATTRIBUTES. none
info This is a human readable string containing a short description of the technical properties of the item. It is up the the decoder to put some meaningful information here.
The field is also (ab)used to return descriptive errors from the decoder.
format This is an arbitrary format string that can be used by a decoder that supports different file formats. It is reflected to the decoder at decoder_savefile when saving content to retain the current file format.
It can contain for instance an EA type returned by decoder_support to identify the format to save. If the parameter is missing, the plugin should try to use a default format.
decoder Name of the decoder. This field need not be set by a decoder plugin because PM123 automatically fills the right name when decoder_fileinfo returned PLUGIN_OK. ""


TECH_ATTRIBUTES is an enumeration type. It is bit vector. The values may be ored to identify combinations.

TATTR_SONG and TATTR_PLAYLIST are not mutually exclusive. E.g. a decoder might represent CD tracks as song while they still may contain sub entries because of track index locations. In this case you might either play the entire song or play only a indexed section of it. PM123 will not automatically descend to the index tracks unless the user explicitly requests to do so.

OBJ_INFO - Detailed Song Information

typedef struct
{ PM123_TIME songlength;
int bitrate;
int num_items;
Field Meaning Undef. value
songlength Length of the song in seconds. The PM123_TIME type is a floating point type, so you may have fractional seconds too. -1
bitrate Bit rate of the data source in bit/s. Example: 128000 for an 128kbps MP3. -1
num_items Number of immediate sub items (for playlists). -1

Note that the object information always reflects the properties of a physical object. When dealing with slices (start and stop location in item information) the songlength will not change. To get the effective song length of a slice look at the totallength filed of the DRPL_INFO structure.

META_INFO - Meta information

typedef struct
{ xstring title;
xstring artist;
xstring album;
xstring year;
xstring comment;
xstring genre;
xstring track;
xstring copyright;
float track_gain;
float track_peak;
float album_gain;
float album_peak;

Note that objects of type META_INFO should not be copied binary by value because of the embedded xstring.

Field Meaning Undef. value
title Song title. If the object is an album this is the album title. NULL
artist Artist/Performer of a song or album. NULL
album Title of the album or title of the parent object in general. NULL
year Release date in the format YYYY[-MM[-DD]] (month and day are optional). NULL
comment Comment. NULL
genre Music genre. Multiple genres may be separated by comma. NULL
track Track number within the current album. NULL
copyright Copyright information. NULL
Replay gain values. See
Values less or equal to -1000 are considered to be undefined. This indicates that the information is not available.

Note that NULL strings will display the same as "", but they indicate that the information is not available rather than explicitly set to blank. In fact this will rarely make a difference.

ATTR_INFO - Object attributes.

typedef struct
{ unsigned ploptions;
xstring at;
Note that objects of type ATTR_INFO should not be copied binary by value because of the embedded xstring.
Field Meaning Undef. value
ploptions Playlist options. This is a bit vector of PL_OPTIONS. none

Last playing position as PM123 location string.



PL_OPTIONS is an enumeration type. It is bit vector. The values may be ored to identify combinations.

PLO_SHUFFLE and PLO_NO_SHUFFLE are mutually exclusive.

RPL_INFO - Recursive playlist information.

typedef struct
{ int totalsongs;
int totallists;
int invalid;
int unknown;
Field Meaning
totalsongs The total number of playable objects. This includes songs in nested playlists but not the playlists itself since they are not directly playable. For song items this is 1.
totallists The total number of enumerable objects including the top level list and nested objects. For song items this is 0.
invalid The total number of invalid objects (i.e neither song nor playlist) in the nested tree.
unknown Total number of objects with an unknown number of nested objects. If this is non-zero the totalsongs, totallists and invalid counters are incomplete.

The recursive playlist information takes care of slices that only select a part of a nested object. Ranges outside the slice are not part of the aggregation.

Furthermore recursive links in enumerable objects are treated in the way that any recursive object is ignored. See recursive playlists

The unknown counter is used to support incremental updates. E.g. if a playlist currently contains exactly one nested playlist with an unknown number of sub objects the unknown counter is set to 1 and the totalsongs counter collects the songs in all other items. If this nested playlist is removed, the unknown counter is decremented and the totalsongs counter becomes valid without recalculating it's value.

This also implies that the structure has no undefined value. Instead unknown is initially 1 and all other fields 0.

DRPL_INFO - Detailed recursive playlist information.

typedef struct
{ PM123_TIME totallength;
int unk_length;
PM123_SIZE totalsize;
int unk_size;
Field Meaning
totallength Sum of the playing times (TECH_INFO.songlength) of all songs in a playlist including nested lists.
unk_length Total number of objects with unknown or indefinite length. If this is non-zero the totallength is incomplete.
totalsize Sum of the physical object size of all nested objects (PHYS_INFO.filesize). This is always an approximate number, since slices cannot be projected to exact byte numbers in general.
unk_size Total number of objects with unknown object size. If this is non-zero the totalsize is incomplete.

See also notes of RPL_INFO.

ITEM_INFO - Playlist item information.

typedef struct
{ xstring alias;
xstring start;
xstring stop;
float pregap;
float postgap;
float gain;

Note that objects of type ITEM_INFO should not be copied binary by value because of the embedded xstrings.

Field Meaning Undef. value
alias This is an alias name used for locations where the name of an object is shown, like bookmark entries. NULL
start Start location in the referenced object as PM123 location string. NULL => the beginning of the object. NULL
stop Stop location in the referenced object as PM123 location string. NULL => until the end of the object. NULL
Gap in seconds before and after the current item. none
gain Additional playback gain in dB. none


typedef struct
{ PHYS_INFO* phys;
TECH_INFO* tech;
OBJ_INFO* obj;
META_INFO* meta;
ATTR_INFO* attr;
RPL_INFO* rpl;
DRPL_INFO* drpl;
ITEM_INFO* item;

The INFO_BUNDLE structure is a collection of all available information about an object. Depending on the usage context the relevance of the sub structures may be masked either by a INFOTYPE bit vector passed as separate parameter or by setting some of the pointers to NULL.


typedef struct
{ int samplerate;
int channels;

The FORMAT_INFO2 structure is a slice of TECH_INFO that is used to identify the format of samples passed through the plugin chain.


typedef double PM123_TIME;

The PM123_TIME type is a double precision floating point type, so it can have fractional seconds also. If a PM123_TIME value is applied to sample data, the floating point value is rounded to the nearest sample boundary. Even tough it is an approximate number, this gives an accuracy of 1 sample up to about 3000 years of music @ 48kHz sample rate - should be sufficient, I think.


typedef double PM123_SIZE;

Data type used to deal with file sizes. Since some compilers do not support 64 bit integers, a double value is used. This is accurate up to 252 bytes - still more than any now existing file system can hold (including ZFS).