% RP_EXTRACT - Rhythm Patterns Audio Feature Extraction
% version: 0.53
%
% last changed: 30.08.2005 by tml
%
%                                    (c) 2005 by Thomas Lidy
%   Institute of Software Technology and Interactive Systems
%                            Vienna University of Technology
%                      http://www.ifs.tuwien.ac.at/~lidy/rp/
%
% based on:
%  Musik Analysis Toolbox for Matlab Version 0.4
%  (c) 2002 Elias Pampalk
%  Austrian Research Institute for Artificial Intelligence
%  http://www.oefai.at/~elias/
%
% and further development on ma_gui_v04 until version 0.48: 
%  2003 - 2005 by          Thomas Lidy, Stefan Leitich
%
%
% RP_EXTRACT: 
%   Music Analysis, Audio Indexing, Similarity
%   Extraction of the following features:
%   - Rhythm Patterns
%   - Statistical Spectrum Descriptor
%   - Rhythm Histogram
%   - Approximate bpm measure
%
%
% USAGE:
%
% 1) Batch Audio Feature Extraction
%    for multiple files, results written to vector files
%
%    RP_EXTRACT(filelist, dirs [, opts])
%
%    RP_EXTRACT(filelist, optionsfile)
%
%    RP_EXTRACT(optionsfile)
%
%    filelist:  list of audio files, either:
%               filelistarray | filelistfile
%
%    dirs:      directory options, either:
%               dirs_struct | dirs_optionsfile
%
%    opts:      processing options, either:
%               opts_struct | opts_optionsfile
%               (if omitted, default options will be used)
%
%
%   filelistarray: Matlab cell array containing all files to be processed
%   filelistfile:  Ascii file listing all files to be processed
%   
%   dirs_struct:   Matlab struct, containing input/output directory etc.
%   dirs_optionsfile: Ascii file containing directory options
%
%   opts_struct:   Matlab struct with feature extraction options
%   opts_optionsfile: Ascii file containing feature extraction options
%
%   optionsfile:   Ascii file containing both directory and processing options
%
%   If the only argument is optionsfile, it has to include reference to 
%   a filelist Ascii file as well.
% 
%      For more information on directory and processing options
%      see rp_options.txt example file
%
%
% 2) Audio Feature Extraction from single audio file
%    results are returnd as Matlab vectors
%
%    [feat] = RP_EXTRACT('func','process_audiofile',input_filename [, opts])
%
%    input_filename:  complete path to audio file
%
%    opts:     Matlab struct containing feature extraction options 
%              (if omitted, default options will be used)
%
%   return value [feat] is a Matlab struct containing the following fields:
%    feat.rp:  vector with Rhythm Patterns features
%    feat.ssd: vector with Statistical Spectrum Descriptor
%    feat.rh:  vector with Rhythm Histogram features
%    feat.bpm: single value containing approximate bpm peak value