Previous: `sporch.h' Header File, Up: C/C++ API

7.1.2 Library Reference

Data Types and Constants
consts 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).

structs 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 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:

An integer ID that specifies one of the database instruments. Use the sporch_get_inst function to to get the string name.
An integer ID that specifies an instrument techniques. The value ‘0’ is always used for the default technique. Use the sporch_get_tech function to get the string name.
An integer specifying a pitch. The meaning depends on the tuning that was selected when opening the database.
An integer specifying a microtone value (to be added to the pitch). The total number of microtones per semitone are defined by the tuning which is selected when opening the database.
An integer specifying a dynamic level. The range of dynamic levels depends on the default stored in the database or one that the user has specified.
The amount that this match “contributes” to the source spectrum subtraction. The value represents a percent reduction in the initial score of the source spectrum. A value of ‘0.5’, for example, indicates that the match reduced the source spectrum by half and thus contributes 50% to the solution.
The score for this match. It is the total amplitude (the square root of the sum of the amplitudes squared) of the subtracted spectrum at this point (after the instrument/pitch/dynamic level has been subtracted).
This is the score after tweaking by both SPORCH and the user. It is the value that is used as a heuristic in the search and is what SPORCH tries to reduce to zero.

struct sporch_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.

struct sporch_pitchmic_str
          struct sporch_pitchmic_str {
            int pitch;
            int mic;

Used by sporch_get_minpitch and sporch_get_maxpitch.

enum sporch_loc_en
          enum sporch_loc_en {

This is used in the sporch_set_loc and sporch_get_loc functions.

enums sporch_frequnit_en and sporch_ampunit_en
          enum sporch_frequnit_en {
          enum sporch_ampunit_en {

Used by sporch_get_peakdata function.

union sporch_ffttype_en enumeration and sporch_fftsize_un
          enum sporch_ffttype_en {
          union sporch_fftsize_un {
            double f;
            long i;

These are used in the sporch_get_fftsize function.

User Callback Function Types and Setters
This list is expected to expand as SPORCH is improved. The user isn't expected to use all of these—the purpose is to provide control and flexibility over the search process. To register a callback function, call the appropriate 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.

type sporch_init_callback and function sporch_set_init_callback
               typedef void (*sporch_init_callback)();
               int sporch_set_init_callback(sporch_init_callback

This is called once before the entire search has begun.

Preselection occurs before SPORCH searches for a single match. This group of functions allows the user to eliminated all unwanted instrument/pitch/dynamic level combinations before they are actually included in the search.
type sporch_preselect_init_callback and function sporch_set_preselect_init_callback
               typedef void (*sporch_preselect_init_callback)();
               int sporch_set_preselect_init_callback

This is called once before SPORCH searches for a match.

type 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

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.

type 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.

type sporch_preselect_done_callback and function sporch_set_preselect_done_callback
               typedef void (*sporch_preselect_done_callback)();
               int sporch_set_preselect_done_callback

This is called after preselection has finished.

After preselection, SPORCH scores the remaining selections to determine which is the best match. Scoring is based on how much the instrument/pitch/dynamic level spectrum “subtracts” from the previous spectrum (the results of the previous match). This group of callbacks lets the user modify the scores after SPORCH calculates them. The closer to 0 the score is (more generally, the lower the value, in cases where negative values are returned), the better the match.
type 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.

type 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
               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.

type 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.

type 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.

Complete Solution Score
type sporch_complete_score_callback and function sporch_set_complete_score_callback
               typedef double (*sporch_complete_score_callback)
               int sporch_set_complete_score_callback

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.

Inserting/Deleting Matches
type 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.

Database Initialization and Loading
function 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.

function 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.

function sporch_db_isloaded
          int sporch_db_isloaded();

Returns true (non-zero) if a database has been loaded with sporch_load_db.

function 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.

function sporch_orchfile_isloaded
          int sporch_orchfile_isloaded();

Returns true (non-zero) if an orchestra definition file has been loaded.

Getting/Setting Parameters
All of the 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.

function sporch_get_dbdir
          const char* sporch_get_dbdir();

Gets the directory in which the sporch database may be found.

function sporch_get_tuning
          const char* sporch_get_tuning();

Get the name of the tuning system that was used when loading the database.

function sporch_get_orchfile
          const char* sporch_get_orchfile();

Gets the name of the orchestra file that was loaded.

functions 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 can open is valid.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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).

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

functions 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.

Orchestra Info
functions 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.

functions 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).

functions 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.

function 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.

function 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.

function 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.

function 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.

function 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.

function 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.

functions 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.

functions 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.

function 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.

While it is searching, SPORCH places the matches it finds on a stack. The following functions allow callback functions to reference this stack at any time.
functions 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.

function 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.

function sporch_get_errstr
          const char* sporch_get_errstr();

Returns a string describing the last error that has occurred.

Search Execution
function 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.

function sporch_stop
          void sporch_stop();

Stops the current branch of the search and considers whatever is on the solution stack as a complete solution.

function sporch_really_stop
          void sporch_really_stop();

Stops the entire search and considers whatever is on the solution stack as the last complete solution.

function 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.

function sporch_done
          void sporch_done();

Like sporch_stop, only the current match is finished first.

function sporch_all_done
          void sporch_all_done();

Like sporch_really_stop, only the current match is finished first.

function 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.

Solution Stack Modifiers
These are used to push and pop arbitrary matches onto the solution stack before or while a search is in progress. Inserting and erasing matches in the middle of the stack causes scores to be recalculated. If a search is in progress, a call to 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.

functions 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.

functions sporch_erase and sporch_pop
          int sporch_erase(int index);
          int sporch_pop();

Both of these functions take a match off of the stack