name: AudioFrontEnd : public FrontEndBase
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_sp.a

>     AudioFrontEnd();
>     AudioFrontEnd(const AudioFrontEnd& arg);
>     boolean getVector(VectorFloat& coeffs, long channel, long frame_index);
>     AudioFile* getAudio();
>     long getNumChannels() const;
>     DMODE getOutputMode() const;
>     boolean run(const Filename& output, const Filename& input);

quick start:

>     AudioFrontEnd reg_fe0;
>     Filename reg_file(L"$ISIP_DEVEL/doc/examples/data/audio/little_endian.raw");
>     Filename output(L".new_features6.out");

>     Sof sof;
>     sof.open(L"diagnose_recipe.sof");
>     reg_fe0.read(sof, 0);
>     sof.close();

>     reg_fe0.run(output, reg_file);

description:
This AudioFrontEnd class implements a general front end for audio signal data processing. The user specifies what processing should take place by creating a Recipe of general Algorithm objects. The simplest way to create this is with the graphical tool we have developed specifically for this task: transform builder.
The first step of the class is to determine what algorithms from the user's Component graph to apply, and in what order, to attain the desired output from the given inputs. Once determined, the class handles reading inputs, marshaling data in and out of the algorithm apply methods, and (optionally) writing outputs.
The class has two levels of interface. The first is the getVector() method, which allows a higher level program (like the recognizer) to obtain feature vectors on a frame-by-frame basis. The second is the run interface, which is used by the isip_transform driver program to produce an output file for each input file.
dependencies:

- FrontEndBase
- FtrBuffer
- AlgorithmBase
- AudioFile
- FeatureFile
- Filename
- Recipe
- Vector
- SingleLinkedList
- Component
- String
- Float
- Long
- Boolean
- VectorFloat

public constants:

- define the class names:

      static const String CLASS_NAME = L"AudioFrontEnd";

- define i/o related constants:

      static const String PARAM_INPUT_DATA_TYPE = L"input_data_type";

      static const String PARAM_INPUT_FLAG = L"input_flag";

      static const String PARAM_AUDIO_INPUT = L"audio_input";

      static const String PARAM_FEATURE_INPUT = L"feature_input";

      static const String PARAM_FRAME_DURATION = L"frame_duration";

      static const String PARAM_SIGNAL_DURATION = L"signal_duration";

      static const String PARAM_NUMBER_OF_FEATURES = L"number_of_features";

      static const String PARAM_START_TIME = L"start_time";

      static const String PARAM_END_TIME = L"end_time";

      static const String PARAM_CONTEXT_WINDOW = L"context_window";

      static const String PARAM_CHANNEL_INDEX = L"channel_index";

      static const String PARAM_COMPONENT_LIST = L"components";

      static const String PARAM_COEF_NAME = L"coef_name";

      static const String PARAM_DATA_MODE = L"data_mode";

- define default value(s) for i/o related parameters:

      static const FrontEndBase::DATA_TYPE DEF_INPUT_DATA_TYPE = FrontEndBase::DEF_DATA_TYPE;

      static const boolean DEF_INPUT_FLAG = true;

      static const boolean DEF_OUTPUT_TYPE_FLAG = false;

      static const float DEF_FRAME_DURATION = 0.01;

      static const float DEF_SIGNAL_DURATION = 0.1;

      static const long DEF_NUMBER_OF_FEATURES = 39;

      static const float ALL_TIME = -1;

      static const float DEF_START_TIME = 0;

      static const float DEF_END_TIME = ALL_TIME;

      static const float DEF_CONTEXT_WINDOW = ALL_TIME;

- define default value(s) for other signal processing related parameters:

      static const float DEF_SAMPLE_FREQ = 8000.0;

      static const long DEF_NUM_CHANNELS = AudioFile::DEF_NUM_CHANNELS;

      static const long DEF_CHANNEL_INDEX = AudioFile::CHANNEL_TAG_ALL;

- define default arguments to methods:

      static const String DEF_COEF_NAME = L"__output_FEATURES";

      static const String DEF_COMPONENT_LIST = L"<this_file>";

- define some internal constants:

      static const String SAMPLED_DATA_NAME = L"__input_SAMPLED_DATA";

      static const Long SAMPLED_DATA_TAG = Sof::NO_TAG;

- define miscellaneous parameters:

      static const long DEF_COEF_BUF_CAPACITY = 512;

error codes:

- error code indicating AudioFrontEnd class general error:

      static const long ERR = 80000;

      static const long ERR_NOVEC = 80001;

protected data:

- a feature buffer that holds all features in a circular buffer:

      FtrBuffer buf_d;

- the input data type:

      input_data_type_d;

- the data processing mode:

      dmode_d;

- the audio and feature files:

      AudioFile audio_input_d;

      FeatureFile feature_input_d;

- variables to handle the recipe:

      Filename component_list_d;

      Recipe recipe_d;

- an ordered list of the components we will apply:

      Vector< SingleLinkedList<Component> > coef_components_d;

- the name of the required output:

      String coef_name_d;

- parameters for excising:

      Float start_time_d;

      Float end_time_d;

      Long channel_index_d;

      long offset_frame_d;

- how far out of the excised window should we look for signal analysis:

      Float context_window_d;

- other signal processing related parameters:

      Float frame_duration_d;

      Float sample_frequency_d;

      Float signal_duration_d;

      Long number_of_features_d;

      long num_channels_d;

- flag indicating the end of data:

      boolean end_of_data_d;

- input file specification:

      Vector input_filename_d;

- output file specification:

      Vector output_filename_d;

      String output_directory_d;

      String output_basename_d;

      String output_extension_d;

      Long output_preserve_d;

      String output_suffix_d;

      File::TYPE output_type_d;

      boolean output_type_flag_d;

- flag indicating if an input file is needed:

      Boolean input_flag_d;

- flag indicating if partially processing data

      Boolean partial_process_d;

- id for output (generally it is the basename of the input file):

      String id_d;

- static memory manager:

      static MemoryManager mgr_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG level);

- debug methods:

      boolean debug(const unichar* message) const;

      boolean setDebug(Integral::DEBUG level);

- destructor/constructor(s):

      ~AudioFrontEnd();

      AudioFrontEnd();

      AudioFrontEnd(const AudioFrontEnd& arg);

- assign methods:

      boolean assign(const AudioFrontEnd& arg);

- i/o methods:

      long sofSize() const;

      boolean read(Sof& sof_a, long tag, const String& name = CLASS_NAME);

      boolean write(Sof& sof_a, long tag, const String& name = CLASS_NAME) const;

      boolean readData(Sof& sof_a, const String& pname = String::getEmptyString(), long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeData(Sof& sof_a,const String& param = String::getEmptyString()) const;

- equality methods:

      boolean eq(const AudioFrontEnd& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

      boolean setParser(SofParser* parser);

class-specific public methods:

- set methods:

      boolean setInputDataType(FrontEndBase::DATA_TYPE data_type);

      boolean setInputFlag(Boolean arg);

      boolean setAudioInput(AudioFile& arg);

      boolean setOutputDirectory(String& directory);

      boolean setOutputBasename(String& basename);

      boolean setOutputExtension(String& extension);

      boolean setOutputFilename(String& filename);

      boolean setOutputPreserve(long new_preserve_level);

      boolean setOutputSuffix(String& suffix);

      boolean setOutputType(File::TYPE type);

      boolean setFrameDuration(float arg);

      boolean setSignalDuration(float arg);

      boolean setSampleFrequency(float arg);

      boolean setNumChannels(long arg);

      boolean setCoefName(const String& name);

- get methods:

      AudioFile* getAudioInput();

      const AudioFile* getAudioInput() const;

      const boolean getInputFilename(Vector<Filename>& filename) const;

      boolean getInputFlag() const;

      boolean getOutputDirectory(String& directory) const;

      boolean getOutputBasename(String& basename) const;

      boolean getOutputExtension(String& extension) const;

      boolean getOutputFilename(String& filename) const;

      long getOutputPreserve();

      boolean getOutputSuffix(String& suffix) const;

      const File::TYPE& getOutputType() const;

      float getFrameDuration() const;

      float getSignalDuration() const;

      float getSampleFrequency() const;

      long getNumChannels() const;

      long getNumFrames();

      long getNumFeatures();

      String& getCoefName() const;

      String& getID() const;

      boolean isNameInput(const String& name) const;

- FrontEndBase interface contract methods:

      boolean eq(const FrontEndBase& arg) const;

      boolean assign(const FrontEndBase& arg);

      const String& className() const;

      boolean getVector(VectorFloat& coeffs, long channel, long frame_index);

      boolean getVector(Vector<VectorFloat>& coeffs, long frame_index);

      boolean load(const Filename& input);

      boolean open(const Filename& input);

      boolean close();

      boolean run(const Filename& output, const Filename& input);

      boolean init(float start_time, float stop_time, int channel);;

private methods:

- process the next frame and add it to the buffer:

      boolean processNextFrame();

- what processing can be done for the current frame in isolation:

      boolean processFrame();

- what processing can be done for the last frames:

      boolean finishFrames();

- reset the buffer of data:

      boolean resetBuffer();

- get the boundaries of the current buffer:

      long getFirstFrame() const;

      long getLastFrame() const;

- the four stages in Component computation:

      boolean readInput(long& new_offset, long frame_index);

      boolean processComponents(long offset, long pad_offset, boolean append_data = false);

      boolean preconfigureComponents(SingleLinkedList& comps);

      boolean configureComponents();

- other configuration methods:

      boolean getInputNames(Vector<String>& names);

      boolean makeBuffers(SingleLinkedList<Component>& recipe);

- used by the run method:

      boolean outputFeatures();

- process target methods:

      boolean processTarget();

      boolean processTarget(Vector<String>& names);

examples:

- This example demonstrates how to use AudioFrontEnd class:

      AudioFrontEnd reg_fe;
      Filename reg_file(L"$ISIP_DEVEL/doc/examples/data/audio/little_endian.raw");

      // setup the front end
      //
      Sof sof;
      sof.open(L"diagnose_filter.sof");
      reg_fe.read(sof, 0);
      sof.close();

      Filename input(reg_file);
      Filename output(L".new_audio0.raw");
      reg_fe.run(output, input);

notes:

- none.