PM123 common plugin data types

ATTR_INFO DRPL_INFO FORMAT_INFO2 INFO_BUNDLE INFOTYPE ITEM_INFO META_INFO OBJ_INFO PHYS_INFOPL_OPTIONS PM123_SIZE PM123_TIME RPL_INFO TECH_INFO TECH_ATTRIBUTES xstring

xstring

INFOTYPE

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.

• INFO_NONE - simply zero.
• INFO_PHYS - Physical information about an object. This information can usually be obtained from the context without opening the object itself.
• INFO_TECH - Technical information about an object. Retrieving this kind of information usually requires the object to be physically accessed, but a header access might be sufficient.
• INFO_OBJ - Detailed object information. This information extends the info shown in INFO_TECH. Providing this information might be more expensive.
• INFO_META - The meta information contains descriptive information on a object like artists, title a.s.f.
• INFO_ATTR - Object attributes. It contains special attributes that control the behavior of the object.
• INFO_RPL - Recursive playlist information. This is an aggregate type information that includes info about the number of children of the current object. It is usually calculated by the PM123 core automatically.
• INFO_DRPL - Detailed recursive playlist information. This is an aggregate type information that includes detailed info about all children of the current object. It is usually calculated by the PM123 core automatically. In general it is expensive to obtain.
• INFO_ITEM - Playlist item information. This information is only used for playlist items. This are in fact properties of references to other playable objects.
• INFO_CHILD - The list of children for enumerable objects like playlists.

PHYS_INFO - Physical information about an object.

typedef struct
{ PM123_SIZE filesize;
  unsigned   tstmp;
  unsigned   attributes;
} PHYS_INFO;

TECH_INFO - Technical information about an object.

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

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

TECH_ATTRIBUTES

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

• TATTR_NONE - No of the flags below.
• TATTR_SONG - The item is playable (a song).
• TATTR_PLAYLIST - The item can have sub entries (playlist).
• TATTR_WRITABLE - This item is writable. E.g. decoder_saveinfo can be used.
• TATTR_SAVEABLE - This stream is saveable (DECODER_SAVEDATA is supported).

OBJ_INFO - Detailed Song Information

typedef struct
{ PM123_TIME songlength;
  int        bitrate;
  int        num_items;
} OBJ_INFO;

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;
} META_INFO;

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

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;
} ATTR_INFO;

PL_OPTIONS

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

• PLO_NONE - simply zero.
• PLO_ALTERNATION - alternation list.
  The (enumerable) object does not contain a sequence of objects but a list of equivalent choices. This is used for streaming playlists for instance that contain URIs of different alternate servers. It causes the aggregate information not to descend into deeper levels.
• PLO_SHUFFLE - force shuffle.
  Force shuffle in the (enumerable) object. This can be used in conjunction with PLO_ALTERNATION to achieve load-balancing.
• PLO_NO_SHUFFLE - cancel shuffle.
  Unset shuffle for the current object. This causes the shuffle attribute not to be inherited from the parent object. E.g. if shuffle is turned on in the player and a list of albums is loaded into the player and the individual album lists are marked with PLO_NO_SHUFFLE, the player will play the albums in random sequence but keep the titles in each album in order.

RPL_INFO - Recursive playlist information.

typedef struct
{ int        totalsongs;
  int        totallists;
  int        invalid;
  int        unknown;
} RPL_INFO;

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;
} DRPL_INFO;

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;
} ITEM_INFO;

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

INFO_BUNDLE

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;
} INFO_BUNDLE;

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.

FORMAT_INFO2

typedef struct
{ int        samplerate;
  int        channels;
} FORMAT_INFO2;

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

PM123_TIME

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.

PM123_SIZE

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 2⁵² bytes - still more than any now existing file system can hold (including ZFS).