Xaudio MPEG Audio Analyzer Library


The Xaudio Analyzer Library is designed to analyze the content of an MPEG Audio file on disk.
Due to the format of an MPEG Audio bitstream, it is not possible to know the type and duration of a file by just looking at a header. Some guesses can be made, but for a precise measurement of the contents of an MPEG Audio file, the entire file has to be scanned.
An MPEG Audio file is made up of audio frames. One frame of audio represents 384 (MPEG 1 and MPEG 2 layer 1), 576 (MPEG 2 layer 3), or 1152 (MPEG 1 layers 2 and 3, and MPEG 2 layer 2) sampled points. Each sample results in 2 bytes (mono, 16 bits per sample), or 4 bytes (stereo, 16 bits per sample).
Each frame can be of a different type (layer, mode, bitrate, sampling frequency, etc...). Also, some files contain meta information (pictures, song names, lyrics, etc...) in the form of a header (data at the beginning of the file, before the actual MPEG Audio stream), or footer (data at the end of a file). The Analyzer library allows to do quick information evaluation (this means that just the first few bytes of a file will be looked at, and based on the types of the first few frames of audio, a guess will be made about the entire file). It also allows to perform an extensive scan of the file, and determine exactly how many frames if contains, and whether all frames are of the same, type, the precise total duration, etc...
Finally, the library will retrieve the meta information when stored as an ID3 tag footer (song name, artist name, album name and date, stored at the end of the file).
The usage of the library is extremely simple: first, an analyzer object is instantiated, then the analyzer object can be used to analyze one or more files. When the client is done, it can free the resources allocated by the analyzer by deleting it.

Functions and Structures Index


xanalyzer_new

Instantiates a new analyzer object.
int XA_EXPORT xanalyzer_new(void **analyzer)
 
analyzer Pointer to the variable in which the pointer to the new analyzer object will be returned.
Returns XANALYZE_SUCCESS if the analyzer has been created, or a negative error code if the call failed.
xanalyze.h

xanalyzer_delete

Deletes an analyzer object.
int XA_EXPORT xanalyzer_delete(void *analyzer)
 
analyzer an analyzer object created by xanalzyer_new()
Returns XANALYZE_SUCCESS if the analyzer has been deleted, or a negative error code if the call failed.
xanalyze.h

xanalyzer_process_file

Analyzes the contents of a file.
The analyzer will process the file, frame by frame. When looking for a valid frame, the analyzer will scan the file until a valid SYNC pattern is found. To prevent very long searches in the case of files with corrupted data, or non-MPEG data, a watchdog value can be set. If the analyzer reached the watchdog byte count before having found a valid frame, it will abort the analysis and return XANALYZE_ERROR_WATCHDOG.
The analyzer can be told to only analyze the first few frames of a file (max_frames). This is useful for a quick estimation of the file contents.
The analyzer will detect changes in the frames' attributes. When a change of an attribute occurs, a flag is set in the info structure. A mask of change conditions can be given to the analyzer to tell it to stop analyzing if a certain parameter changes (for instance, the client could tell the analyzer to stop if the sampling frequency of the frames changes, by setting the XANALYZE_REPORT_CHANGING_FREQUENCY bit in the stop_mask). If one of the conditions set in the stop_mask is met, the analyzer returns XANALYZE_ERROR_STOP_CONDITION
int XA_EXPORT xanalyzer_process_file(void *analyzer, const char *name, AnalyzerInfo *info, unsigned long stop_mask, unsigned long watchdog, unsigned long max_frames);
 
analyzer an analyzer object created by xanalzyer_new()
name name of the file to analyze.
info pointer to the structure where the information will be returned.
stop_mask bit mask that tells the analyzer when to stop analyzing.
watchdog byte count of the watchdog used for SYNC pattern detection (0 means that the analyzer will search until a SYNC pattern is found, or the end of the file is reached).
max_frames max number of frames to analyze (a value of 0 means that the entire file will be analyzed).
Returns XANALYZE_SUCCESS if the analyzer has been deleted, or a negative error code if the call failed.
If the call is a success, then info structure will contain the results of the analysis.
xanalyze.h

AnalyzerInfo

typedef struct {

    AnalyzerMpegInfo  stream_type;

    AnalyzerTrackInfo track;

    unsigned long     frames;

    unsigned long     duration;

    unsigned long     flags;

} AnalyzerInfo;
Contains information about the analysis results.
 
stream_type information about the MPEG stream type.
track meta information about the music.
frames number of frames that have been analyzed.
duration duration of the stream in milliseconds.
flags bit flags indicating which, if any, of the parameters of the frames is not constant during the entire stream.
Values are:
  • XANALYZE_REPORT_CHANGING_LEVEL: the MPEG level (MPEG 1 or MPEG 2) is not constant.
  • XANALYZE_REPORT_CHANGING_LAYER: the MPEG layer (1, 2 or 3) is not constant.
  • XANALYZE_REPORT_CHANGING_BITRATE: the bitrate is not constant.
  • XANALYZE_REPORT_CHANGING_FREQUENCY: the sampling frequency is not constant.
  • XANALYZE_REPORT_CHANGING_MODE: the MPEG mode is not constant.
  • XANALYZE_REPORT_CHANGING_CHANNELS: the number of channels (1 for mono, 2 for stereo) is not constant.

AnalyzerMpegInfo

typedef struct {

    int  level;

    int  layer;

    int  bitrate;

    int  frequency;

    int  mode;

    int  channels;

} AnalyzerMpegInfo;
Contains information about the MPEG stream.
 
level MPEG level (1 for MPEG1, 2 for MPEG2, 0 for MPEG2.5).
layer MPEG layer (1, 2 or 3).
bitrate bitrate in bits per second.
frequency sampling frequency (in Hz).
mode MPEG mode (0 for stereo, 1 for joint-stereo, 2 for dual-channel, 3 sor single-channel).
channels number of channels (1 for mono, 2 for stereo).

AnalyzerTrackInfo

typedef struct {

    const char   *title;

    const char   *artist;

    const char   *album;

    const char   *year;

    const char   *comment;

    unsigned char genre;

} AnalyzerTrackInfo;
Contains information about the stream (if any). If no information is available, strings will be empty or NULL.@NOTE: the string pointers are only valid until the analyzer is deleted or a new file is processed. It is recommended that the client make a copy of the strings upon return from the analysis function.
 
title song title.
artist artist name.
album album name.
year year date of song.
comment comments about the song.

 
XANALYZE_ERROR_INTERNAL an internal error has occurred.
XANALYSE_ERROR_OUT_OF_MEMORY not enough memory to complete the operation.
XANALYZE_ERROR_NO_SUCH_FILE the requested file does not exist.
XANALYZE_ERROR_CANNOT_OPEN the requested file cannot be openned.
XANALYZE_ERROR_STOP_CONDITION a stop condition has occurred.
XANALYZE_ERROR_WATCHDOG a watchdog condition has occurred.