Next: , Previous: C/C++ API, Up: C/C++ API

7.1.1 `sporch.h' Header File

Here is the sporch.h header file that is installed with

// ----------------------------------------------------------------------------
// SPORCH Header File

// Copyright (c) 2006 David Psenicka.
// See COPYING for terms of use and distribution
// ----------------------------------------------------------------------------

#ifndef SPORCH_H
#define SPORCH_H

#ifdef __cplusplus
extern "C" {
  // --------------------------------------------------------------------------
  // --------------------------------------------------------------------------

  // these are used to set and test for `none' values--they are constants so
  // they can easily be used in other languages or interpretters
  extern const int sporch_none_i;
  extern const double sporch_none_f;
  #define SPORCH_NONE_I sporch_none_i
  #define SPORCH_NONE_F sporch_none_f

  // sporch_info and sporch_out structs contain information on matches in the
  // search process
  struct sporch_info_str {
    int inst;
    int tech;
    int pitch;
    int mic;
    int dyn;
  // contr is percent contribution (as a number between 0 and 1), score is the
  // total amount subtracted from the source at this point (this usually
  // descreases with each match) and mod_score is a score modified by the user
  // and a few other things (currently, the program modifies the score if it is
  // outside the instrument's practical range)
  struct sporch_out_str {
    int inst;
    int tech;
    int pitch;
    int mic;
    int dyn;
    double contr;
    double score;
    double mod_score;

  struct sporch_peak_str {
    double freq;
    double amp;

  struct sporch_pitchmic_str {
    int pitch;
    int mic;

  // enumeration to specify a location relative to off1 and off2/dur
  enum sporch_loc_en {

  // enumerations for `sporch_get_peakdata' function
  enum sporch_frequnit_en {
  enum sporch_ampunit_en {
  // enumeration to indicate whether fftsize is a float or int
  enum sporch_ffttype_en {
  // union to specify fftsize as a float (secs.) or int (sample frames)
  union sporch_fftsize_un {
    double f;
    long i;

  enum sporch_model_en {

  // typedefs for user callback functions:
  typedef void (*sporch_init_callback)();
  typedef void (*sporch_preselect_init_callback)();
  typedef int (*sporch_preselect_order_callback)(const struct sporch_info_str *info_x,
                                                 const struct sporch_info_str *info_y);
  // return non-zero (true) to keep or zero (false) to throw away
  typedef int (*sporch_preselect_callback)(const struct sporch_info_str *info);
  typedef void (*sporch_preselect_done_callback)();
  typedef void (*sporch_score_init_callback)();
  typedef int (*sporch_score_order_callback)(const struct sporch_out_str *out_x,
                                             const struct sporch_out_str *out_y);
  typedef double (*sporch_score_callback)(const struct sporch_out_str *out);
  typedef void (*sporch_score_done_callback)();
  typedef double (*sporch_complete_score_callback)();

  typedef double (*sporch_insdel_score_callback)(const struct sporch_out_str *out);

  // --------------------------------------------------------------------------
  // INPUT
  // --------------------------------------------------------------------------

  // functions for initializing sporch and loading files
  // char* arguments may be NULL
  int sporch_init(const char *initfile); // returns -1 on error
  int sporch_load_db(const char* dbdir, const char* tuning); // returns -1 on
                                                             // error
  int sporch_db_isloaded(); // returns true (1) or false (0)
  int sporch_load_orchfile(const char* orchfile); // returns -1 on error
  int sporch_orchfile_isloaded(); // returns true (1) or false (0)

  // functions for setting/getting information
  // char* return values are only valid until next SPORCH call
  // `set' functions with return values return -1 on error
  const char* sporch_get_dbdir();
  const char* sporch_get_tuning();
  const char* sporch_get_orchfile();
  int sporch_set_srcfile(const char* srcfile);
  const char* sporch_get_srcfile();
  int sporch_set_orch(const char* orch);
  const char* sporch_get_orch();
  int sporch_set_ndyns(int ndyns); // greater than 0, default = 6
  int sporch_get_ndyns();

  int sporch_set_loc(enum sporch_loc_en loc); // sporch_peak, sporch_begin,
                                         // sporch_middle or sporch_end,
                                         // default = sporch_begin
  enum sporch_loc_en sporch_get_loc();
  int sporch_set_off1(double off1); // sporch_none_f or between -10000 and
                                    // 10000 secs., default = sporch_none_f
  double sporch_get_off1();
  int sporch_set_off2(double off2); // sporch_none_f or between -10000 and
                                    // 10000 secs., default = sporch_none_f
  double sporch_get_off2();
  int sporch_set_dur(double dur); // sporch_none_f or between -10000 and 10000
                                  // secs., default = sporch_none_f
  double sporch_get_dur();
  int sporch_set_off(double off); // -10000 to 10000 secs., default = 0
  double sporch_get_off();
  int sporch_set_fftsize_i(int fftsize); // 1 to 1000000 frames, default = 0.05
                                         // secs.
  int sporch_set_fftsize_f(double fftsize); // greater than 0 and less than or
                                            // eqaul to 10 secs., default =
                                            // 0.05 secs.
  // get_fftsize puts the size in fftsize and returns the type
  enum sporch_ffttype_en sporch_get_fftsize(union sporch_fftsize_un *fftsize);
                                                  // returns int or float and
                                                  // sets appropriate value in
                                                  // union argument
  int sporch_set_fftn(int fftn); // 1 to 10000, default = 1
  int sporch_get_fftn();
  int sporch_set_fftave(int fftave); // 1 to 10000, default = 1
  int sporch_get_fftave();
  int sporch_set_fftspan(double fftspan); // greater than 0 and less than or
                                          // equal to 60 secs., default = 1
                                          // sec.
  double sporch_get_fftspan();
  int sporch_set_amp(double amp); // sporch_none_f or -200 to 200 dB, default =
                                  // sporch_none_f
  double sporch_get_amp();
  int sporch_set_thresh(double thresh); // -200 to 0 dB, default = -120
  double sporch_get_thresh();
  int sporch_set_tune(double tune); // sporch_none_f or -10000 to 10000 cents,
                                    // default = sporch_none_f
  double sporch_get_tune();
  int sporch_set_searchinc(double searchinc); // 0 to 1, default = 0,
                                              // implicitly calls
                                              // sporch_again()
  double sporch_get_searchinc();
  int sporch_set_maxbranch(int maxbranch); // between 1 and 30000, default = 2
  int sporch_get_maxbranch();

  int sporch_calc_norm(double norm);
  int sporch_set_norm(double norm); // sporch_none_f or -200 to 200 dB,
                                    // default = sporch_none_f
  double sporch_get_norm();

  // --------------------------------------------------------------------------
  // --------------------------------------------------------------------------

  // functions to register user callback functions

  // called once before the search is begun
  // NULL value indicates no callback
  int sporch_set_init_callback(sporch_init_callback init);
  // called once before preselect is called repeatedly
  int sporch_set_preselect_init_callback(sporch_preselect_init_callback
  // `<' operator for establishing search order
  int sporch_set_preselect_order_callback(sporch_preselect_order_callback
  // filter out unwanted selections before expensive scoreacting and scoring
  int sporch_set_preselect_callback(sporch_preselect_callback preselect);
  // called once after preselect is called repeatedly
  int sporch_set_preselect_done_callback(sporch_preselect_done_callback

  // called once bedore score is called repeatedly
  int sporch_set_score_init_callback(sporch_score_init_callback score_init);
  // `<' operator for establishing search order
  int sporch_set_score_order_callback(sporch_score_order_callback score_order);
  // modify scoring
  int sporch_set_score_callback(sporch_score_callback score);
  // called once after score is called repeatedly
  int sporch_set_score_done_callback(sporch_score_done_callback score_done);

  // score complete solutions (in the order that they are found)
  int sporch_set_complete_score_callback(sporch_complete_score_callback

  // modify scoring (when manually inserting/deleting)
  int sporch_set_insdel_score_callback(sporch_insdel_score_callback

  // --------------------------------------------------------------------------
  // INFO
  // --------------------------------------------------------------------------

  // integer identification of instruments and techniques (one unique integer
  // for each unique name string)
  int sporch_get_ninsts(); // returns -1 on error
  const char* sporch_get_inst(int index); // returns NULL on error
  int sporch_get_instn(const char* inst); // returns -1 on error

  int sporch_get_ntechs(); // returns -1 on error
  const char* sporch_get_tech(int index); // returns NULL on error
  int sporch_get_techn(const char* tech); // returns -1 on error

  // returns number of techniques in an instrument--returns -1 on error
  int sporch_get_instntechs(int inst);
  // returns technique for a given instrument--returns -1 on error
  int sporch_get_insttech(int inst, int index);

  // get various information for laoded database--return -1 on error
  int sporch_get_nmics();
  double sporch_get_oct();
  int sporch_get_ndivs();
  double sporch_get_basefreq();
  double sporch_get_basepit();
  enum sporch_model_en sporch_get_peakmodel();
  int sporch_get_nharms();
  // get the number of pitches--returns -1 on error
  int sporch_get_npitches(int inst, int tech);
  // get the min and max pitches--return -1 on error
  int sporch_get_minpitch(int inst, int tech, struct sporch_pitchmic_str *pitch);
  int sporch_get_maxpitch(int inst, int tech, struct sporch_pitchmic_str *pitch);
  // set section min/max values and implicitly call sporch_again()
  // return -1 on error
  int sporch_set_min(const char* sect, int min);
  int sporch_set_max(const char* sect, int max);
  int sporch_reset_minmaxes();

  // get peaks for instrument in `info'
  // sets peaks to point to the first sporch_peak struct and returns number of
  // peaks.  returns -1 on error
  int sporch_get_peakdata(const struct sporch_info_str* info, const struct sporch_peak_str**
			  peaks, enum sporch_frequnit_en frequnit, enum sporch_ampunit_en
  // --------------------------------------------------------------------------
  // --------------------------------------------------------------------------

  // Return variables (set by SPORCH)
  int sporch_get_nouts();
  const struct sporch_out_str* sporch_get_out(int index); // returns NULL on error
  double sporch_get_progress();

  // Latest error string
  const char* sporch_get_errstr();

  // --------------------------------------------------------------------------
  // --------------------------------------------------------------------------

  // run is the function that executes the search.  the following functions are
  // control functions that can be called at any time during the search.  user
  // callback functions can always check the current list of matches using the
  // get_nouts and get_out functions.  at any time, the user can also modify
  // the list using the insert, push, erase and pop functions.
  // returns -1 on error
  int sporch_run();

  // stop the current branch in the search (can be called at any time from a
  // user callback function)
  void sporch_stop();
  // stop the entire search and all remaining branches
  void sporch_really_stop(); // (stops any additional branches in search)
  // redo the current match (can be called at any time from a user callback
  // function)
  void sporch_again();
  // stop search after the current match is made (but continue other branches)
  void sporch_done();
  // stop entire search after current match is made
  void sporch_all_done(); // (stops any additional branches in search)
  // indicate error during user callback function (alias for sporch_stop())
  void sporch_user_error();
  // manipulate output list (and implicitly call sporch_again)
  // return -1 on error
  int sporch_insert(int index, const struct sporch_info_str* info);
  int sporch_push(const struct sporch_info_str* info);
  int sporch_erase(int index);
  int sporch_pop();

#ifdef __cplusplus