6.2.2 `conf' Files

Many of these can be created and placed in the directory pointed to by db-dir or any of its subdirectories. They contain the options necessary for identifying sound files, analyzing them and extracting information from their filenames. sporchdb does a depth-first directory traversal, reading any conf files it finds before doing the sound analyses. All settings, then, apply to the directory that conf file is in as well as all of its subdirectories. If the same setting appears in a conf file in some subdirectory, that setting is replaced with the new value for that subdirectory and all of its subdirectories. The file system containing the sound files can be organized in any way, then, and can also be constructed out of links to directories and sound files in other locations.

The default values in the .sporch init file don't apply here—if a setting isn't specified then it is set to the default value shown here. Also, see `conf' Files Example, for an example conf file.

dirs

(list of regular expressions) This list specifies the subdirectories that sporchdb should descend into. Only directories with names that match a regular expression in the list are searched. The regular expressions make it possible to easily specify all directories or some set of directories without having to constantly maintain a list of separate strings.

files

(list of regular expressions) This list specifies the sound files that sporchdb should analyze. Only directories with names that match a regular expression in the list are chosen for analysis. The regular expressions make it possible to easily specify all files or some set of files without having to constantly maintain a list of separate strings.

•

These two settings allow the user to organize analyses into groups of collections and instrument models:

coll

(string) Different “collections” of the same instruments can be compiled together into the same database and selected when sporch or libsporch.so is run. This makes it possible to analyze several different sound sample libraries and use them interchangeably. The string value is a unique case-insensitive ID and applies to all sound files in that directory and all subdirectories (until another coll setting is found). The coll and model settings are necessary when there are multiple sets of sound samples for the same instruments.

model

(string) This works with coll and can be thought of as a sort of sub-collection. It's a case-insensitive identifier and should be used to distinguish different instrument models within the same collection of sound samples. The coll and model settings are necessary when there are multiple sets of sound samples for the same instruments.

pref

(integer, default = ‘0’) This attaches a preference value to the sound analyses in this directory and all subdirectories (unless overridden by another pref setting). When sporchdb compiles the database it sorts collections, models and individual analyses by how “smooth” the data is from pitch to pitch or dynamic level to dynamic level. If preference are given, sporchdb sorts everything based on these values instead. The collections, models and analyses with the highest preference values are “preferred” over those with lower values and become the default choices when sporch or libsporch.so is run. The numbers range from -100 to 100.

•

These options define a segment within a sound file. The analysis location is relative to the beginning and end of this segment.

off1

(float or ‘none’, secs.) 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.

off2

(float or ‘none’, secs.) 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.

dur

(float or ‘none’, secs.) 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.

•

Analysis location options:

loc

(‘begin’, ‘middle’, ‘end’ or ‘peak’, default = ‘peak’) 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.

off

(float, secs., default = ‘0’) 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.

default-tune

(string) This sets a default tuning, overriding the one set in insts. All pitch numbers are interpreted with respect to the current default.

•

These are options for specifying or extracting an identifier string from a source file filename. Only one or the other may be used (using one cancels the other):

id

(string) This explicitly specifies a case-sensitive identifier to be used in insts to gather different analyses into one instrument. Use id-parse to extract this ID from the sound source filename.

id-parse

(regular expression) This specifies how to extract an ID string from a filename. The ID is a case-sensitive identifier to be used in insts to gather different analyses into one instrument. sporchdb expects a subexpression (in parentheses) to indicate the location of the id in the filename.

•

Settings for defining the pitch:

•

Pitches can either be specified explicitly or extracted from sound file filenames. Each of the settings in this group come in pairs, one with a -parse suffix and one without. Only one or the other can be used (specifying one cancels the other). Also, the settings pitch and pitch-parse have a third alternative—the pitch can be indicated by a set of separate pitch components: oct, let and acc.

pitch

(float) Explicitly defines the pitch being analyzed. To extract the pitch from the filename, use pitch-parse. The number is interpreted using the default tuning defined in default-tune. Floating point numbers can be used to specify microtones—the number is rounded to the nearest microtone defined in the default tuning.

pitch-parse

(regular expression) This regular expression must contain a subexpression that indicates the location of a number in the sound source filename which identifies the pitch. The extracted pitch can be an integer or a float.

•

Instead of pitch or pitch-parse, the pitch can be added together after parsing the octave, letter (or pitch class), and accidental separately.

pitch-oct

(integer) This number is multiplied by n-divs (defined in the default tuning) and added to the final pitch.

pitch-oct-parse

(regular expression or list of regular expressions) This specifies how to extract the octave number from a filename. The octave number is multiplied by n-divs and added to the final pitch. If a regular expression is given, sporchdb expects a subexpression (in parentheses) to indicate the location of the number in the filename. If a list of regular expressions is given, the first expression that matches the filename indicates the octave number by its position in the list. If the first expression matches the filename, the extracted octave is 0. If the second matches, the octave number is 1, etc..

pitch-let

(integer) This is a number identifying the pitch class (it's called pitch-let though because sound sample filenames usually contain a pitch letter name). It is a number, then, from 0 to 12 (or whatever the value of n-divs is from the default tuning definition).

pitch-let-parse

(regular expression or list of regular expressions) This specifies how to extract the pitch class from a filename. If a regular expression is given, sporchdb expects a subexpression (in parentheses) to indicate the location of the number in the filename. If a list of regular expressions is given, there must be n-divs expressions (from the default tuning definition). If the first expression matches the filename, the extracted pitch class is 0. If the second matches, the pitch class is 1, etc..

pitch-acc

(float) This is a number representing an accidental alteration. The number that is added to the total pitch depends on the value of n-mics in the default tuning. If n-mics is set to 2, for example, then a value of -1 alters the final pitch by -0.5. Use pitch-acc-parse to extract this from the sound file filename.

pitch-acc-parse

(regular expression or list of regular expressions) This specifies how to extract an accidental alteration from a filename. If a regular expression is given, sporchdb expects a subexpression (in parentheses) to indicate the location of the number in the filename. If a list of regular expressions is given, there must be a certain number of expressions depending on the number of microtones in the default tuning. The range of values is basically all allowable microtonal adjustments within a whole tone. If n-mics is 1, then the range is from -1 to 1, so there should be 3 regular expressions in the list (flat, natural and sharp). If n-mics is 2, the range is from -1.5 to 1.5 and there should be 7 expressions, etc.. In the case of 2 microtones, if the first expression matches the filename, the extracted dynamic level is -1.5. If the second matches, the dynamic level is -1, etc..

pitch-plus

(float) This number is always added to the final pitch (however it is defined or extracted). This is useful for correcting offsets in extracted values that are hard to correct otherwise.

•

Settings related to specifying/extracting the dynamic level:

•

The user can explicitly set the dynamic level of the analyses or extract them from the sound file filenames. One or the other must be used (using one cancels out the other):

dyn

(integer) This specifies a dynamic level from 0 to one below n-dyns defined in insts. To extract a dynamic level from a sound file filename, use dyn-parse.

dyn-parse

(regular expression or list of regular expressions) This specifies how to extract a dynamic level from a filename. If a regular expression is given, sporchdb expects a subexpression (in parentheses) to indicate the location of the number in the filename. If a list of regular expressions is given, there must be n-dyns expressions, one for each dynamic level. If the first expression matches the filename, the extracted dynamic level is 0. If the second matches, the dynamic level is 1, etc..

dyn-plus

(integer or ‘none’) Defines a number to add to either dyn or dyn-parse. This might be helpful if the filenames contain numbers that are off by 1, for example.

•

FFT options:

fft-size

(float, secs. or integer in sample frames, default = ‘0.05’) 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.

fft-n

(integer, default = ‘1’) It specifies how many total FFT analyses are taken (over the duration given by fft-span.

fft-span

(float, secs., default = ‘1’) 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.

fft-ave

(integer, default = ‘1’) 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).

•

Settings affecting peak extraction:

amp

(float or ‘none’, dB) If set, amplifies or attenuates the magnitude of each FFT bin by some amount before peaks are extracted.

thresh

(float, default = ‘-120’) It is a required threshold value that specifies the lowest amplitude allowable when extracting peaks from an FFT analysis.

tune

(float or ‘none’, cents) If given, specifies that all frequencies of peaks extracted from an FFT analysis be adjusted by the specified amount.

tune-to-pitch

(integer or ‘none’) If specified, indicates that the analysis should be tuned to the proper pitch. The integer value designates the number of harmonics that are examined and subtracted from the correct frequencies to determine the average amount of error between the analyzed and expected harmonic frequencies. The entire spectrum is adjusted by the average error. A value of ‘1’, for example, specifies that the fundamental frequency (or the first harmonic that is found) must match the calculated frequency for that pitch. A value of ‘2’ means that the fundamental and first octave harmonic must be as close as possible (on average) to the calculated frequencies.

This helps fix analyses of sample libraries that are out of tune.

{ }

A pair of braces ‘{ }’ should be placed in the file somewhere with a files setting inside them to indicate source files that are exceptions (to be analyzed differently than all of the others). Any settings can then appear inside of the brackets as exceptional settings for this file. Files listed in exception braces are removed from the file's global list of sound files. However, exceptions can be specified for the same file or files multiple times.

This is useful for long sound files that contain multiple samples or recordings, since the ‘off1’ and ‘off2’ settings can be changed to specify different locations in the same file. See `conf' Files Example, to see how to do this.