Previous: `sporch.h' Header File, Up: C/C++ API
sporch_none_i and sporch_none_f
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
These constants are used for passing a none value to a function (sporch_none_i is an integer and sporch_none_f
is a (double) floating point value). The macros SPORCH_NONE_I and SPORCH_NONE_F are also provided (which just
evaluated to the constants).
sporch_info_str and sporch_out_str
struct sporch_info_str {
int inst;
int tech;
int pitch;
int mic;
int dyn;
};
struct sporch_out_str {
int inst;
int tech;
int pitch;
int mic;
int dyn;
double contr;
double score;
double mod_score;
};
These are used to read matches made by libsporch.so while it is running and after it is done searching. They are also used in some functions for passing information (user-defined matches) to the program. The struct slots are:
instsporch_get_inst function to
to get the string name.
techsporch_get_tech function to get the string name.
pitchmicdyncontrscoremod_scoresporch_peak_str
struct sporch_peak_str {
double freq;
double amp;
};
Used by sporch_get_peakdata to return peak data. The units of freq and amp depend on the arguments passed to
that function.
sporch_pitchmic_str
struct sporch_pitchmic_str {
int pitch;
int mic;
};
Used by sporch_get_minpitch and sporch_get_maxpitch.
sporch_loc_en
enum sporch_loc_en {
sporch_begin,
sporch_peak,
sporch_middle,
sporch_end
};
This is used in the sporch_set_loc and sporch_get_loc functions.
sporch_frequnit_en and sporch_ampunit_en
enum sporch_frequnit_en {
sporch_pitch,
sporch_hz
};
enum sporch_ampunit_en {
sporch_amp,
sporch_int,
sporch_db,
sporch_intdb
};
Used by sporch_get_peakdata function.
sporch_ffttype_en enumeration and sporch_fftsize_un
enum sporch_ffttype_en {
sporch_float,
sporch_int
};
union sporch_fftsize_un {
double f;
long i;
};
These are used in the sporch_get_fftsize function.
set_ function.
To unregister one, pass a ‘NULL’ or ‘0’ to the appropriate setter.
The functions return non-zero on error (if they are called while a search is in progress).
In all callback functions, the current state of the search can be found by calling
sporch_get_nouts, sporch_get_out and sporch_get_score.
They can also call sporch_stop, sporch_really_stop, sporch_again,
sporch_done, sporch_all_done and sporch_error to terminate the search or execute
other actions. sporch_insert, sporch_push, sporch_erase and sporch_pop
can also be called to modify the search stack before or during the search.
sporch_init_callback and function sporch_set_init_callback
typedef void (*sporch_init_callback)();
int sporch_set_init_callback(sporch_init_callback
init);
This is called once before the entire search has begun.
sporch_preselect_init_callback and function sporch_set_preselect_init_callback
typedef void (*sporch_preselect_init_callback)();
int sporch_set_preselect_init_callback
(sporch_preselect_init_callback
preselect_init);
This is called once before SPORCH searches for a match.
sporch_preselect_order_callback and function sporch_set_preselect_order_callback
typedef int (*sporch_preselect_order_callback)
(const sporch_info_str *info_x, const
sporch_info_str *info_y);
int sporch_set_preselect_order_callback
(sporch_preselect_order_callback
preselect_order);
Allows the user to establish the order in which selections are passed to sporch_preselect_callback.
This must return true (non-zero) if the two structs are in the correct order (info_x comes before info_y)
or false (zero) if not.
sporch_preselect_callback and function sporch_set_preselect_callback
typedef int (*sporch_preselect_callback)(const
sporch_info_str *info);
int sporch_set_preselect_callback
(sporch_preselect_callback preselect);
This is the actual selection function.
It returns true (non-zero) if the instrument/pitch/dynamic level combination is valid
and false (zero) if it should be deleted for this match.
sporch_preselect_done_callback and function sporch_set_preselect_done_callback
typedef void (*sporch_preselect_done_callback)();
int sporch_set_preselect_done_callback
(sporch_preselect_done_callback
preselect_done);
This is called after preselection has finished.
sporch_score_init_callback and function sporch_set_score_init_callback
typedef void (*sporch_score_init_callback)();
int sporch_set_score_init_callback
(sporch_score_init_callback score_init);
This is called once before SPORCH searches for a match.
sporch_score_order_callback and function sporch_set_score_order_callback
typedef int (*sporch_score_order_callback)(const
sporch_out_str *out_x, const sporch_out_str
*out_y);
int sporch_set_score_order_callback
(sporch_score_order_callback score_order);
Allows the user to establish the order in which selections are passed to sporch_score_callback.
This must return true (non-zero) if the two structs are in the correct order (out_x comes before out_y)
or false (zero) if not. The structures that are passed already have SPORCH's substraction and modified scores
in the score and mod_score slots.
sporch_score_callback and function sporch_set_score_callback
typedef double (*sporch_score_callback)(const
sporch_out_str *out);
int sporch_set_score_callback
(sporch_score_callback score);
This is the actual user score function.
The function must return a new modified score or nothing (using sporch_none_f) to indicate no change in the modified score SPORCH provides.
The modified score should most likely be based on the mod_score slot which is SPORCH's own pre-modified score.
The closer to 0 the score is
(more generally, the lower the value, in cases where negative values are returned), the better the match.
If this callback is set, then the user should also consider setting sporch_insdel_score_callback.
sporch_score_done_callback and function sporch_set_score_done_callback
typedef void (*sporch_score_done_callback)();
int sporch_set_score_done_callback
(sporch_score_done_callback score_done);
This is called after scoring has finished.
sporch_complete_score_callback and function sporch_set_complete_score_callback
typedef double (*sporch_complete_score_callback)
();
int sporch_set_complete_score_callback
(sporch_complete_score_callback
complete_score);
When the search is allowed to descend into multiple branches, multiple “complete solutions” are collected which
are presumably just as good or nearly so. By default, SPORCH just picks the one with the best final
score (the modified score of the last match). If this callback is supplied, then the user may replace the final
score with a different value. As in match scoring, the lower the score value, the better the complete solution.
If nothing value is returned (sporch_none_f) then SPORCH uses the final score.
sporch_insdel_score_callback and function sporch_set_insdel_score_callback
typedef double (*sporch_insdel_score_callback)
(const sporch_out_str *out);
int sporch_set_insdel_score_callback
(sporch_insdel_score_callback insdel_score);
If matches are inserted or deleted before or during the search process, SPORCH must rescore any matches that
have been made later in the search. If the user is modifying scores with sporch_score_callback then
the scores should also be modified when they are recalculated as a result of modifying the stack. This is the function
that is called when this happens—in most cases it should probably be set to the same callback function as sporch_score_callback.
sporch_init
int sporch_init(const char *initfile);
Initializes SPORCH and optionally reads an initialization file. If no initialization file is specified (by passing ‘NULL’ or ‘0’),
it looks for .sporch in the user's home directory and reads that. Database and orchestra definition file information must be
reloaded after calling this function. Returns non-zero on error.
sporch_load_db
int sporch_load_db(const char* dbdir, const char* tuning);
Loads instrument spectra from a database file. If no filename is given, it loads whatever default is set by sporch_init.
If a tuning name is given, specifies which tuning to use. If no tuning is specified (by passing ‘NULL’ or ‘0’), the
database's default tuning is loaded. If there is a currently loaded orchestra definition file and the information is incompatible with the
new database information, the orchestra definition is unloaded. Returns non-zero on error.
sporch_db_isloaded
int sporch_db_isloaded();
Returns true (non-zero) if a database has been loaded with sporch_load_db.
sporch_load_orchfile
int sporch_load_orchfile(const char* orchfile);
Loads an orchestra definition file. If no filename is specified (by passing ‘NULL’ or ‘0’),
it loads whatever default is set by sporch_init. Orchestras may be selected once this file has been loaded.
sporch_orchfile_isloaded
int sporch_orchfile_isloaded();
Returns true (non-zero) if an orchestra definition file has been loaded.
set_ functions return non-zero on error. The default values depend on what is found in
.sporch or whichever initialization file was passed to sporch_init—see the section
on intialization files for more information. Defaults can also be obtained by typing
sporch -h at a command prompt—these will represent the hardcoded values plus whatever was found in .sporch.
Setting functions that return a value return non-zero on error.
sporch_get_dbdir
const char* sporch_get_dbdir();
Gets the directory in which the sporch database may be found.
sporch_get_tuning
const char* sporch_get_tuning();
Get the name of the tuning system that was used when loading the database.
sporch_get_orchfile
const char* sporch_get_orchfile();
Gets the name of the orchestra file that was loaded.
sporch_set_srcfile and sporch_get_srcfile
int sporch_set_srcfile(const char* srcfile);
const char* sporch_get_srcfile();
This is the name of the sound file to be sporchestrated. It must be specified before calling sporch_run.
Anything that libsndfile.so can open is valid.
sporch_set_orch and sporch_get_orch
int sporch_set_orch(const char* orch);
const char* sporch_get_orch();
This is the name of an orchestra which is defined in the orchestra definition file (loaded by sporch_load_orchfile).
If none is specified (by passing ‘NULL’ or ‘0’) the first orchestra definition in the file
is selected.
sporch_set_ndyns and sporch_get_ndyns
int sporch_set_ndyns(int ndyns);
int sporch_get_ndyns();
This is the total number of dynamic levels that are shown in the info and out structs.
This is not necessarily the same as the number of dynamic levels that the database was compiled with.
Numbers that are shown to the user are scaled from the database range to the range specified with
this setting.
sporch_set_loc and sporch_get_loc
int sporch_set_loc(sporch_loc_en loc);
sporch_loc_en sporch_get_loc();
This plus off is the point in the file where the FFT (or first FFT if there are more than
one) is centered. If off1 and off2 or dur are set, this location is relative to those values.
sporch_set_off1 and sporch_get_off1
int sporch_set_off1(double off1);
double sporch_get_off1();
If specified, indicates the beginning of the analysis segment. If not set,
the beginning of the analysis segment defaults to the beginning of the sound file. The location given by loc is
relative to this setting.
sporch_set_off2 and sporch_get_off2
int sporch_set_off2(double off2);
double sporch_get_off2();
If specified, indicates the end of the analysis segment. If not set (and dur isn't set),
the end of the analysis segment defaults to the end of the sound file. The location given by loc is
relative to this setting.
sporch_set_dur and sporch_get_dur
int sporch_set_dur(double dur);
double sporch_get_dur();
Specifies that the end of the analysis segment is off1 plus this value. If not set (and off2 isn't set),
indicates that the end of the analysis segment is the end of the sound file. The location given by loc is
relative to this setting.
sporch_set_off and sporch_get_off
int sporch_set_off(double off);
double sporch_get_off();
The value is relative to the location indicated by loc. It
is the point in the file where the FFT (or first FFT if there are more than
one) is centered.
sporch_set_fftsize_i, sporch_set_fftsize_f and sporch_get_fftsize
int sporch_set_fftsize_i(int fftsize);
int sporch_set_fftsize_f(double fftsize);
sporch_ffttype_en sporch_get_fftsize
(sporch_fftsize_un *fftsize);
Specifies the default FFT size used when analyzing sound files. If a floating point value is given, SPORCH
uses the sound file's sample rate and calculates the lowest number of frames that fits that duration. The resulting FFT size
is a power of 2 by default or whatever powers are specified in fft-pow-limit.
sporch_get_fftsize returns the value by modifying the contents of the union passed to it and setting
the type (float or integer) on return.
sporch_set_fftn and sporch_get_fftn
int sporch_set_fftn(int fftn);
int sporch_get_fftn();
It specifies how many total FFT analyses are taken (over the duration given by fft-span.
sporch_set_fftave and sporch_get_fftave
int sporch_set_fftave(int fftave);
int sporch_get_fftave();
Specifies the number of FFT analyses that are averaged together before peaks are extracted. These FFTs are
chosen from the total number specified in fft-n and represent the ones that deviate the
least from the norm (in terms of mean-squared error calculation between pairs of FFTs).
sporch_set_fftspan and sporch_get_fftspan
int sporch_set_fftspan(double fftspan);
double sporch_get_fftspan();
Specifies the duration over which the number of FFTs specified in default-fft-n are taken. The
segment should represent a sustained portion of the sound since the FFTs taken are pruned and then averaged before
peaks are extracted from them.
sporch_set_amp and sporch_get_amp
int sporch_set_amp(double amp);
double sporch_get_amp();
If set, amplifies or attenuates the magnitude of each FFT bin by some amount before peaks are extracted.
sporch_set_thresh and sporch_get_thresh
int sporch_set_thresh(double thresh);
double sporch_get_thresh();
It is a required threshold value that specifies the lowest amplitude allowable when extracting peaks from an FFT analysis.
sporch_set_tune and sporch_get_tune
int sporch_set_tune(double tune);
double sporch_get_tune();
If given, specifies that all frequencies of peaks extracted from an FFT analysis be adjusted by the specified amount.
sporch_set_searchinc and sporch_get_searchinc
int sporch_set_searchinc(double searchinc);
double sporch_get_searchinc();
This is a floating point number (between 0 and 1 or higher) which effectively increases the
depth of SPORCH's search. Technically, it is the maximum difference
between the best score and another score which can exist for a branch to occur at a search node.
If this value is increased then max-branch should be increased too.
‘0’ is the fastest setting and corresponds to linear matching (instruments are added to the solution
sequentially one after the other—no branches ever occur in the search unless two or more matches have the exact same score and max-branch is greater
than 1). An extremely high value (greater than 1) causes SPORCH to execute an exhaustive
depth-first search. Setting this to something reasonable (close to 0) causes SPORCH to branch only when alternate solutions have scores
that are close. Increasing this setting by a small amount causes more branches to occur and the search depth to increase.
sporch_set_maxbranch and sporch_get_maxbranch
int sporch_set_maxbranch(int maxbranch);
int sporch_get_maxbranch();
This constrains the number of branches that can occur at any search node.
It can be used to prevent SPORCH from expanding its depth-first search to the point where it takes forever to return a solution.
SPORCH only expands nodes when the scores of the best choices are sufficiently close to each other (this is controlled by search-inc).
Although the size of each expansion is usually only 1 or a small number, this setting prevents the algorithm from occasionally expanding a node
by some drastic amount and adding a huge amount of unwanted complexity to the search.
sporch_calc_norm, sporch_set_norm and sporch_get_norm
int sporch_calc_norm(double norm);
int sporch_set_norm(double norm);
double sporch_get_norm();
This is an extra amplification that is applied on top of amp. When left unset or set to none (the default),
SPORCH does no normalization. When set, indicates that the source spectra should be amplified so that
its total magnitude (the square root of the sum of the amplitudes squared) equals the given value in dB.
Instrument collections are normalized to 0 dB when their spectra are stored in the database, so the source and the instruments
should be at around the same amplitude levels if this setting is also set to 0.
sporch_calc_norm can also be used to find and set a normalization value based on a certain point in the source sound file (determined by
off1, off2, dur, loc and off).
After a call to sporch_calc_norm, subsequent calls to sporch will be amplified by the same set value until a call
to sporch_set_norm or sporch_calc_norm resets the normalization value to something else.
sporch_get_ninsts, sporch_get_inst, sporch_get_instn
int sporch_get_ninsts();
const char* sporch_get_inst(int index);
int sporch_get_instn(const char* inst);
These functions translate integer values to instrument names and vice versa. The info and out structs
contain integer ids instead of strings for faster comparison and/or indexing into arrays, etc.. Both
sporch_get_ninsts and sporch_get_instn return non-zero on error and sporch_get_inst returns
‘NULL’ on error.
sporch_get_ntechs, sporch_get_tech, sporch_get_techn
int sporch_get_ntechs();
const char* sporch_get_tech(int index);
int sporch_get_techn(const char* tech);
These functions translate integer values to technique names and vice versa. The info and out structs
contain integer ids instead of strings for faster comparison and/or indexing into arrays, etc.. Both
sporch_get_ninsts and sporch_get_instn return non-zero on error and sporch_get_tech returns
‘NULL’ on error. An id of 0 always indicates the default technique for some instrument (default techniques are unnamed or unspecified
when the database is compiled—it's name is a zero-length string).
sporch_get_instntechs and sporch_get_insttech
int sporch_get_instntechs(int inst);
int sporch_get_insttech(int inst, int index);
sporch_get_instntechs returns the number of techniques for a given instrument (specified by its
numeric id). sporch_get_insttech returns the technique id
given the instrument id and an index. Both functions return less-than-zero on error.
sporch_get_nmics
int sporch_get_nmics();
Get the number of microtones per division of the octave for the currently loaded database.
Returns less-than-zero on error.
sporch_get_oct
double sporch_get_oct();
Get the octave ratio (set in the tuning definition when the database was compiled) for the current tuning. It's 2 by default
(a value of 3 would indicate the tuning is based on a tritave, for example). Returns less-than-zero on error.
sporch_get_ndivs
int sporch_get_ndivs();
Get the number of divisions per octave (or whatever base frequency ration is defined in the tuning). Returns less-than-zero on error.
sporch_get_basefreq
double sporch_get_basefreq();
Get the base frequency for the current tuning (used to convert frequencies into pitch numbers and vice versa).
The the frequency returned by sporch_get_basefreq is equal to pitch returned by sporch_get_basepit.
Returns less-than-zero on error.
sporch_get_basepit
double sporch_get_basepit();
Get the base pitch for the current tuning (used to convert frequencies into pitch numbers and vice versa).
The pitch returned by sporch_get_basepit is equal to the frequency returned by sporch_get_basefreq.
Returns less-than-zero on error.
sporch_get_npitches
int sporch_get_npitches(int inst, int tech);
Returns the total number of pitches (including microtones) given an instrument and technique id.
sporch_get_minpitch and sporch_get_maxpitch
int sporch_get_minpitch(int inst, int tech, sporch_pitchmic_str *pitch);
int sporch_get_maxpitch(int inst, int tech, sporch_pitchmic_str *pitch);
Return the minimum and maximum pitches given an instrument and technique id. The result is stored in a
sporch_pitchmic_str struct. Both functions return less-than-zero on error.
sporch_set_min, sporch_set_max and sporch_reset_minmaxes
int sporch_set_min(const char* sect, int min);
int sporch_set_max(const char* sect, int max);
int sporch_reset_minmaxes();
These are used to change the minimum and maximum values that are defined in the orchestra definition file.
The character string references the section name (or the name of the orchestra) as it is defined in the file.
The min or max value resets the minimum or maximum limit respectively. sporch_reset_minmaxes
resets all values to the ones defined in the file. All three functions return non-zero on error.
sporch_get_peakdata
int sporch_get_peakdata
(const sporch_info_str* info,
const sporch_peak_str** peaks,
sporch_frequnit_en frequnit,
sporch_ampunit_en ampunit);
Get peak data for a specified instrument, technique, pitch and dynamic level. The info struct contains
the information to lookup. peaks is modified to point to an array of sporch_peak_str structs.
The return value is the size of the array. Also, the arguments frequnit and ampunit determine
what units or scales the output values are in (choices are sporch_pitch and sporch_hz for frequnit
and sporch_amp, sporch_int, sporch_db and sporch_intdb. Returns less-than-zero on error.
sporch_get_nouts and sporch_get_out
int sporch_get_nouts();
const sporch_out_str* sporch_get_out(int index);
These are used to reference matches that have been placed on the solution stack. An index of 0 references
the first match found, 1 references the next, etc.. sporch_get_out returns ‘NULL’ on error.
sporch_get_score
double sporch_get_progress();
This returns the total “progress” so far. It is a value from 0 to 1 indicating the amount that has been subtracted from the initial source spectrum. A value of 1 would mean the source spectrum has been completely eliminated. This function can be called at any time.
sporch_get_errstr
const char* sporch_get_errstr();
Returns a string describing the last error that has occurred.
sporch_run
int sporch_run();
Begins a search. All parameters should be set using getters and setters before calling this.
Returns non-zero on error.
sporch_stop
void sporch_stop();
Stops the current branch of the search and considers whatever is on the solution stack as a complete solution.
sporch_really_stop
void sporch_really_stop();
Stops the entire search and considers whatever is on the solution stack as the last complete solution.
sporch_again
void sporch_again();
Repeats the current match from the beginning. This is useful, for example, if some important state has changed in
the preselect or scoring callbacks and either of the two functions needs to restart from the beginning.
sporch_done
void sporch_done();
Like sporch_stop, only the current match is finished first.
sporch_all_done
void sporch_all_done();
Like sporch_really_stop, only the current match is finished first.
sporch_user_error
void sporch_user_error();
Called when a user callback function has caused an error. The search then aborts and sporch_run
returns a non-zero value.
sporch_again is also made, since a change to the stack
completely changes the scoring for the current match.
Once a search has completed and before another one has started, the first call to one of these functions automatically clears the entire stack. No manual clearing of the solution stack is necessary.
sporch_insert and sporch_push
int sporch_insert(int index, const sporch_info_str* info);
int sporch_push(const sporch_info_str* info);
Both of these functions insert a match onto the stack.
sporch_erase and sporch_pop
int sporch_erase(int index);
int sporch_pop();
Both of these functions take a match off of the stack