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
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_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 informations 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_CHILD
-
The list of children for
enumerable objects like playlists.typedef struct
{ PM123_SIZE filesize;
unsigned tstmp;
unsigned attributes;
} PHYS_INFO;
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 |
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.
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. |
NULL |
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 plug-in should try to
use a
default format. |
"" |
decoder | Name of the decoder. This field need not be set by a decoder plug-in 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.
typedef struct
{ PM123_TIME songlength;
int bitrate;
int num_items;
} OBJ_INFO;
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 subitems (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.
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.
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 |
track_gain track_peak album_gain album_peak |
Replay gain values. See www.replaygain.org. Values less or equal to -1000 are considered to be undefined. This indicates that the information is not available. |
-1000 |
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.
Note that objects of type ATTR_INFO should not be copied binary by value because of the embedded xstring.typedef struct
{ unsigned ploptions;
xstring at;
} ATTR_INFO;
Field | Meaning | Undef. value |
---|---|---|
ploptions | Playlist options. This is a bit vector of PL_OPTIONS. | none |
at |
Last playing position as PM123 location string. |
NULL |
PL_OPTIONS
is an enumeration type. It
is bit vector. The values may be ored to
identify combinations.
- force shuffle.
- cancel shuffle.typedef struct
{ int totalsongs;
int totallists;
int invalid;
int unknown;
} RPL_INFO;
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.
typedef struct
{ PM123_TIME totallength;
int unk_length;
PM123_SIZE totalsize;
int unk_size;
} DRPL_INFO;
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.
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.
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 |
pregap postgap |
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;
} 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.
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 plug-in 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).