Next: Library Reference, Previous: C/C++ API, Up: C/C++ API
Here is the sporch.h header file that is installed with libsporch.so:
// ----------------------------------------------------------------------------
// 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" {
#endif
// --------------------------------------------------------------------------
// STRUCTS, ENUMS, CONSTS, TYPES
// --------------------------------------------------------------------------
// 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 {
sporch_begin,
sporch_peak,
sporch_middle,
sporch_end
};
// enumerations for `sporch_get_peakdata' function
enum sporch_frequnit_en {
sporch_pitch,
sporch_hz
};
enum sporch_ampunit_en {
sporch_amp,
sporch_intn,
sporch_db,
sporch_intndb
};
// enumeration to indicate whether fftsize is a float or int
enum sporch_ffttype_en {
sporch_float,
sporch_int
};
// union to specify fftsize as a float (secs.) or int (sample frames)
union sporch_fftsize_un {
double f;
long i;
};
// TODO: DOCUMENT
enum sporch_model_en {
sporch_env,
sporch_harms
};
// THIS SECTION: UPDATE DOCS
// 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();
// UPDATE DOC
int sporch_set_loc(enum sporch_loc_en loc); // sporch_peak, sporch_begin,
// sporch_middle or sporch_end,
// default = sporch_begin
// UPDATE DOC
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
// UPDATE DOC
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();
// --------------------------------------------------------------------------
// CALLBACK FUNCTIONS
// --------------------------------------------------------------------------
// 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
preselect_init);
// `<' operator for establishing search order
int sporch_set_preselect_order_callback(sporch_preselect_order_callback
preselect_order);
// 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
preselect_done);
// 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
complete_score);
// modify scoring (when manually inserting/deleting)
int sporch_set_insdel_score_callback(sporch_insdel_score_callback
insdel_score);
// --------------------------------------------------------------------------
// 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();
// TODO: DOCUMENT
enum sporch_model_en sporch_get_peakmodel();
// TODO: DOCUMENT
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
// UPDATE DOCS
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
// UPDATE DOCS
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
ampunit);
// --------------------------------------------------------------------------
// OUTPUT
// --------------------------------------------------------------------------
// Return variables (set by SPORCH)
int sporch_get_nouts();
// UPDATE DOCS
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();
// --------------------------------------------------------------------------
// EXECUTE
// --------------------------------------------------------------------------
// 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
// UPDATE DOCS
int sporch_insert(int index, const struct sporch_info_str* info);
// UPDATE DOCS
int sporch_push(const struct sporch_info_str* info);
int sporch_erase(int index);
int sporch_pop();
#ifdef __cplusplus
}
#endif
#endif