This page documents how to use the various command-line utilities that come with FeatSynth. These applications can be used to build the components that make up a FeatSynth object (componentmaker, cachetrainer), bundle these objects together into other components (applyeffect, applyremapping, combinesynths, combineextractors), stick them into a FeatSynth object (featsynthmaker), and use that FeatSynth object to synthesize audio from a FeatScore file (featscore, fextractor).

---

Component Makers

These utilities create new components and save them to disk for later use.

componentmaker
usage: componentmaker ComponentType [CtrlParamName cpvalue]* cname

Creates a new FSComp of type ComponentType and saves it in the file cname. Optionally, values for any number of control parameters can be set by specifying the names (CtrlParamName) and values (cpvalue) for those parameters.

cachetrainer
usage: cachetrainer -n N -w winsize -e extractor.ext -s synth.syn -c cache.mch [-o output.mch]
Takes a saved MappingCache and adds N new random parameter-feature pairings. These are determined by choosing a parameter vector for synth.syn at random, synthesizing winsize samples of audio using synth.syn, and using extractor.ext to extract a feature vector from the resulting audio. If an output file (e.g. output.mch) is specified with the -o flag, then the result is saved to that file, otherwise it is saved back to the input file (e.g. cache.mch).

---

Component Combiners

These utilities create new components by combining other subcomponents.

applyeffect
usage: applyeffect s.syn EffectName [CtrlParamName cpvalue]* e.syn

Creates a SynthEffect of type EffectName, uses the ParamSynth in s.syn as input, and saves the result to e.syn.
Optionally, values for any number of control parameters on the SynthEffect can be set by specifying the names (CtrlParamName) and values (cpvalue) for those parameters.

applyremapping
usage: applyremapping s.syn RemappingName paramNum [CtrlParamName cpvalue]* [m.syn]

Creates a Remapping of type RemappingName, applies it to parameter number paramNum of the ParamSynth in s.syn, and saves the result to m.syn (if specified) or s.syn (if not).
Optionally, values for any number of control parameters on the Remapping can be set by specifying the names (CtrlParamName) and values (cpvalue) for those parameters.

combinesynths
usage: combinesynths s1.syn [s2.syn s3.syn...] out.syn

Creates a new ComboSynth and adds the ParamSynths saved in s1.syn, s2.syn, etc., saving the result in out.syn.

combineextractors
usage: combineextractors e1.ext [e2.ext e3.ext...] out.ext

Creates a new ComboExtractor and adds the FeatureExtractors saved in e1.ext, e2.ext, etc., saving the result in out.ext.

featsynthmaker
usage: featsynthmaker [CtrlParamName cpvalue]* -s s.syn -e e.ext [-m m.mtr] [-p p.mtr] -o o.op -c c.mch [-n initialMappings -w winsize] [-W paramWeight] output.fs

Builds a FeatSynth object out of a ParamSynth (s.syn), a FeatureExtractor (e.ext), an Optimizer (o.op), a MappingCache (c.mch), and optionally Metrics to judge distances between parameter and feature vectors (p.mtr and m.mtr respectively - if no Metric is specified then the default Metrics associated with the ParamSynth and FeatureExtractor are used).
Optionally, values for any number of control parameters on the FeatSynth can be set by specifying the names (CtrlParamName) and values (cpvalue) for those parameters.
If the -n flag is included, the MappingCache is initialized with an additional initialMappings mappings between random parameter vectors and the feature vectors they produced for a window size of winsize.
The optional paramWeight parameter specifies how strongly (on a scale from 0.0 to 1.0) to value smooth transitions between parameters from frame to frame. For example -W 0.0 tells the FeatSynth to only consider the feature values, while -W 1.0 would make the FeatSynth only consider closely matching the previous frame's parameter vector (which would be pretty boring). Default is 0.0. Set it higher if you find you're getting very choppy or burbly output from frequent large jumps in synthesis parameters.

alternate usage: featsynthmaker [CtrlParamName cpvalue]* -S SynthType [CtrlParamName cpvalue]* -E ExtractorType [CtrlParamName cpvalue]* [-M MetricType [CtrlParamName cpvalue]*] [-P MetricType [CtrlParamName cpvalue]*] -O OptimizerType [CtrlParamName cpvalue]* -C CacheType [CtrlParamName cpvalue]* -n initialMappings -w winsize [-W paramWeight] output.fs

Instead of using saved components, the -[semoc] flags can be capitalized to instruct featsynthmaker to create new components of the appropriate type. Additionally, one may combine multiple ParamSynths or FeatureExtractors by including multiple -S or -F flags. For example, -S SinSynth -S SinSynth -S WhiteSynth would create a ComboSynth that combined two SinSynths and a WhiteSynth. Any CtrlParamName/cpvalue pairs following one of these flags will be applied to the component specified immediately to the left. Capital and lowercase flags may be freely mixed, e.g.

featsynthmaker maxIterations 15 -S SinSynth -S SinSynth -S WhiteSynth -e e.ext -O GeneticOptimizer -C LSHFCache numHashes 20 -n 100 -w winsize output.fs

would save a FeatSynth object in output.fs whose maxIterations parameter was set to 15, whose ParamSynth was a ComboSynth mixing two SinSynths and a WhiteSynth, whose FeatureExtractor was whatever was saved in e.ext, whose Optimizer was a GeneticOptimizer, and whose MappingCache was an LSHFCache with the numHashes parameter set to 20.

---

Applications

These applications use existing components to analyze or produce audio.

fextractor
usage: fextractor -w winsize -h hopsize -e [e.ext | featsynth.fs] input.wav > out.fsc

Uses the FeatureExtractor saved as e.ext or the FeatureExtractor associated with featsynth.fs to extract feature vectors from sliding windows of a PCM audio file (named, e.g., input.wav), then writes the results in FeatScore format to standard output, which can be redirected using the '>' character to a file (e.g. out.fsc).

OR
usage: fextractor -w winsize -h hopsize -E ExtractorType [CtrlParamName cpvalue]* input.wav > out.fsc

Creates a new FeatureExtractor of type ExtractorType, initializes it with any CtrlParam name/value pairs specified, and uses it to create a FeatScore file as described above.

featscore
usage: featscore [-t tolerance] [-i iterations] featsynth.fs score.fsc outfile.wav

Uses the FeatSynth stored in featsynth.fs to attempt to synthesize audio matching the feature values in score.fsc. The resulting audio is written to outfile.wav.
The tolerance parameter specifies below what error the Optimizer can stop searching for a better solution and move on to the next frame. The default value is 0.0.
The iterations parameter specifies how many iterations the Optimizer should perform before giving up and moving on to the next frame. The default value is 20.