6.2.1 `insts' File

This file is called insts (unless a different name is specified in .sporch) and must be placed in the directory pointed to by db-dir. Tunings and instruments are specified at the top level of the file within enclosing braces (see `insts' File Example). The following settings occur at the top level:

•

These are all default filenames:

db-conf-name

(string, default = ‘conf’) This is the name of an analysis configuration file, which tells sporchdb how to analyze the sound files that are in the same directory as it. sporchdb looks for files of this name in db-dir and all of its subdirectories. This overrides the same setting in the .sporch init file.

db-name

(string, default = ‘db’) This is the name of the database file, a binary file that contains all of SPORCH's analysis data. sporchdb creates this file in directory db-dir.

This overrides the same setting in the .sporch init file.

•

These settings affect how temporary files are created when sporchdb analyzes sound files.

use-tmp-files

(‘yes’ or ‘no’, default = ‘yes’) Tells sporchdb whether or not to use temporary cache files when analyzing sound files. This overrides the same setting in the .sporch init file.

tmp-file-ext

(string, default = ‘dat’) This is the extension that gets added on to the ends of temporary cache files (created when sporchdb analyzes sound files). These files are also hidden (a dot is placed at the beginning of the filename). This overrides the same setting in the .sporch init file.

rm-extra-tmp-files

(‘yes’ or ‘no’, default = ‘yes’) Tells sporchdb to remove unused cache files. Only files that end in tmp-file-ext are removed. This overrides the same setting in the .sporch init file.

fft-pow-limit

(integer, default = ‘2’) SPORCH chooses FFT sizes that are powers of two by default. Setting this to a higher number allows FFT sizes that are combinations of different powers. (For example, setting this to ‘5’ would allow FFT sizes that are combinations of powers of 2, 3 and 5). This setting exists because SPORCH uses FFTW to do its spectral analyses and FFTW can efficiently perform FFTs of different sizes. It is used specifically when SPORCH must calculate the FFT size from a time duration and the sample rate of a sound file. This overrides the same setting in the .sporch init file.

•

tune

This keyword is followed by a pair of braces (‘{ }’) containing the definition for an equal-temperament tuning. A name and several values are required:

name

(string) This setting is required. It is case insensitive.

base-freq

(float, default = ‘440’) This and the base-pitch setting determine how pitch values are converted to frequencies and vice versa. The value set in base-pitch is equivalent in frequency to the value set in base-freq.

base-pitch

(integer, default = ‘69’) This and the base-pitch setting determine how pitch values are converted to frequencies and vice versa. The value set in base-pitch is equivalent in frequency to the value set in base-freq.

n-divs

(integer, default = ‘12’) This is the number of divisions per octave (or whatever is defined in oct).

n-mics

(integer, default = ‘1’) This is the number of microtonal divisions per pitch. The actual number of pitches per octave, then is n-divs times n-mics. Having two settings allows some control over what appears in the output.

oct

(float, default = ‘1’) Defines the frequency distance that replaces the octave if desired. The default value of ‘2’ specifies one octave (frequency ratio of 2:1). Any other value specifies a multiplier for determining a new ratio. For example, a value of 3 defines a ratio of 3:1 (a tritave, or the interval of a 12th, which can be used to generate a Bohlen-Pierce scale).

inst-min-fdist

(float, default = 0.5 / n-mics) Defines the minimum distance that extracted peaks are allowed to be from each other. The distance is specified in terms of octave divisions so that the distance in Hz between peaks increases exponentially with each octave. The default is the same distance as the “error margin” used to match source peaks with instrument peaks.

inst-min-fdist is used by sporchdb while source-min-fdist is used by sporch and libsporch.so.

source-min-fdist

(float, default = 0.5 / n-mics) Defines the minimum distance that extracted peaks are allowed to be from each other. The distance is specified in terms of octave divisions so that the distance in Hz between peaks increases exponentially with each octave. The default is the same distance as the “error margin” used to match source peaks with instrument peaks.

inst-min-fdist is used by sporchdb while source-min-fdist is used by sporch and libsporch.so. The matching algorithm probably works best if source-min-fdist is at least smaller than inst-min-fdist.

If no tuning is specified, a 12TET tuning is created and set as the default.

default-tune

(string) This is the name of the default tuning for the database. If not specified, the default tuning is set to the first one defined in the file.

•

Settings related to dynamic levels:

n-dyns

(integer, default = ‘6’) This changes the range of dynamic levels that are compiled into the database. Other n-dyns settings that appear elsewhere might refer to the range of levels that appear in the output, which is different. The reason for separating database dynamic values from output values is so that the actual search can be refined by increasing the number of matches that can be made for each instrument. Also, users might want to change the number of output dynamic levels on the fly without having to recompile the entire database. This value can then be set to a larger number (like 20). When actual dynamic levels are output, the database range is scaled to the output range.

n-user-dyns

(integer, default = ‘6’) This is like the default-n-dyns setting described above in the .sporch file, though it's only purpose here is to function as a guide for calculating the distance between data for different pitches and dynamic levels. The distance calculation is used when deciding what data to use when interpolating missing instrument spectra. The larger this number, the more likely it is that sporchdb interpolates data from neighboring pitches (and vice versa). It should be set to the same value as default-n-dyns and reflect the number of dynamic levels desired in the output.

Or just ignore it altogether—the default value should be fine. This nitpicky setting is here only for sake of completeness.

•

These affect how sporchdb decides which pitch or dynamic level to interpolate data from:

interp-dist

(integer, default = ‘2’) This is the maximum distance sporchdb will go to grab data for interpolating missing instrument spectra. The default value of ‘2’ indicates that missing data is interpolated over distances of a whole tone or two dynamic levels (in terms of the n-user-dyns setting in the same file). This is also how far sporchdb looks when determining how “smooth” the peak data is from pitch to pitch and dynamic level to dynamic level. It probably shouldn't be set to anything much higher than the default, unless your instrument samples are missing a lot of pitches and you need to tell SPORCH to interpolate over farther distances.

pitch-pref

(‘high’, ‘low’ or ‘none’, default = ‘low’) When there is no other way of making a decision, this tells sporchdb whether to choose a lower pitch over a higher one or vice versa when interpolating missing data.

dyn-pref

(‘high’, ‘low’ or ‘none’, default = ‘low’) When there is no other way of making a decision, this tells sporchdb whether to choose a lower dynamic level over a higher one or vice versa when interpolating missing data.

inst

This keyword is followed by a pair of braces (‘{ }’) containing a definition for an instrument. The definition must at least contain a name and a list of analysis IDs (extracted from sound file filenames—see `conf' Files, below). The following settings can appear inside an instrument definition:

ids

(list of regular expressions) This is a mandatory setting that specifies which analyses belong to this instrument. The IDs are either explicitly defined or extracted from the filenames of the sound files according to the contents of the conf files. Unlike most of the other names or IDs, these are case sensitive (because they are pulled out of filenames and not explicitly specified).

maxp

(float) This mandatory value is the maximum pitch for the instrument. The frequency it represents is determined by the default tuning defined in the same file.

minp

(float) This mandatory value is the minimum pitch for the instrument. The frequency it represents is determined by the default tuning defined in the same file.

name

(string) This is the name of the instrument. It's case insensitive.

perc

This setting doesn't have a value. It is inserted in place of minp and maxp to indicate that the definition is for a non-pitched percussion instrument.

pract-maxp

(float, default = maxp) This is the maximum practical pitch for the instrument, or the highest pitch that is easy to play. Pitch above this are chosen less often (a penalty is added to the score—the higher the note, the greater the penalty). The frequency is determined by the default tuning defined in the same file.

pract-minp

(float, default = minp) This is the minimum practical pitch for the instrument, or the lowest pitch that is easy to play. Pitch below this are chosen less often (a penalty is added to the score—the lower the note, the greater the penalty). The frequency is determined by the default tuning defined in the same file.

tech

This keyword is followed by a pair of braces (‘{ }’) containing a definition for an instrument technique. By default, the technique inherits all values (minimum and maximum pitches, for example) from the instrument definition, so all that needs to be specified is a name and a list of ids. Any instrument setting can be overwritten, however, by simply including it in the technique definition. For sake of completeness, the technique settings are listed here:

ids

maxp

minp

name

perc

pract-maxp

pract-minp