Instr
Extension
ExtensionDescription
An Instrument is a function that has a unique name attached to it and Specs that describe the input and output datatypes.
It is stored in a library by its name and can be retrieved by that name. They can be used to create SynthDefs but also as a general use library of resuable functions.
Instr can be looked up by their name and will be loaded from disk. Every package or quark can have a folder called Instr which will be searched when loading an Instr. So Quarks can be used to share collections of Instr / SynthDefs.
Unlike SynthDef, Instr can take any kind of input for its arguments, not just (including an Integer quantity, symbols or even other functions) and so while a SynthDef has a fixed architecture for a Synth, an Instr can generate multiple SynthDefs of varying architectures. For instance you could specify an Env or a fixed time duration or a quantity (how many parallel voices to create, detuned against each other) or even the name of a UGen (LFSaw, Pulse) to use for the oscillator.
There are methods detailed below for creating SynthDefs from Instr. Instr also support partial application (supplying some of the arguments in advance) and function composition (chaining them together to make a new Instr)
SynthDefs can be created and Synths can be spawned in various convienient ways.
Instr can also be used in Patterns.
Instr can be chained together, used as subroutines and have inputs partially satisfied.
Instr can be chained together using a lisp dialect.
When used with Patch there are some glue functions to make language-server communication much easier and clearer.
------------------------------------------------------------
Whenever you create an Instr it is stored in the library:
and can be retrieved:
or redefined:
Make a SynthDef:
Make a Synth:
A simple reference gui:
Browse your Instr library:
Class Methods
.new
Arguments:
| name |
Valid formats: All quarks/Instr folders are searched |
| func |
the ugenFunc Note: when using your Instrument with Patch THERE IS NO NEED TO USE Out.ar though you may explicitly use it if you wish. It will be appended to your ugen graph func if needed. |
| specs |
Specify what kind of input is required, and the working range of values. somewhat optional - these can be guessed from the argnames. if no spec is supplied, Instr will use the function's argument name to lookup a spec in Spec.specs. eg arg freq -> looks for Spec.specs.at(\freq) If nothing is found there, it will default to a ControlSpec with a range of 0 .. 1 These specs are used by Patch to determine the suitable type of input. They may be used in many other situations, and you will find many uses where you will wish to query the specs. The default/initial value for the Spec is taken from the function defaults. different lazy ways to specify the spec... |
| outSpec |
optional - InstrSynthDef can determine the outputSpec by evaluating the ugenGraph and finding what the spec of the result is. An Instr can be .ar, .kr or can even return an object, a player, or a pattern. |
.prNew
private
.dir
The default directory to look for Instr. Each quark can also contain an Instr/ dir and those will be searched.
Arguments:
| p |
path |
.at
look up an Instr by name, searching and loading from disk if not already loaded.
Arguments:
| name |
.load
loads Instr by name from file
Arguments:
| name |
.loadAll
loads all Instr in all Instr/ directories. This usually doesn't take very long and doesn't take up that much memory. I load all on compile.
.prLoadDir
private
Arguments:
| dir |
.addExcludePaths
Because Instr files are kept in quarks this can greatly increase the number of files that the language compiler will attempt to examine. It won't compile them, but it looks at all of those folders anyway. This adds the paths of all of your Instr folders to the LanguageConfig exclude paths.
.clearAll
clear the Library cache
.ar
As a class method, this looks up (or loads) the Instr and values it with supplied args. It can thus be used as a kind of subroutine or easily reusable function.
Equivalent usage when using an instance:
Arguments:
| name | |
| args |
array or dict |
.kr
see ar
Arguments:
| name | |
| args |
array or dict |
.choose
choose a random Instr from the library.
Arguments:
| start |
if supplied, this is the address of the branch within the Instr library tree from which to choose |
Returns:
an Instr
.leaves
returns all Instr in the library tree in a flat list
Arguments:
| startAt |
if supplied, address of a branch within the tree. eg. Instr.leaves("oscillators") |
Returns:
an Array of Instr
.selectBySpec
filters the Instr library for those matching the output Spec.
Arguments:
| outSpec |
Returns:
an Array of Instr
.chooseBySpec
chooses a random Instr among those matching the outputSpec
Arguments:
| outSpec |
Returns:
an Instr
.put
Arguments:
| instr |
.remove
remove an Instr from the library
Arguments:
| instr |
Returns:
returns the removed Instr or nil it wasn't defined
.orc
a method for creating many related instruments. short for orchestra, but funnier.
Arguments:
| name | |
| pairs | |
| outSpec |
.symbolizeName
convert dotNotation to symbolized list form: [\one,\two,\three] private
Arguments:
| name |
.isDefined
checks if an object by this name is already defined
Arguments:
| name |
Returns:
Boolean
.objectAt
Arguments:
| name |
.findFileFor
Arguments:
| symbolized |
name as list of symbols |
.findFileInDir
private
Arguments:
| symbolized |
name as list of symbols |
| rootPath |
.initClass
private
.singleNameAsNames
private converts dotNotation to symbolized list
Arguments:
| singleName |
Instance Methods
.name
the symbolized version of the name: [\one,\two,\three] dotNotation is usually nicer to work with.
.dotNotation
the canonical instr name with each path element joined by dots : "one.two.three"
Returns:
string
.func
get or set the Instr function
.specs
an array of specs, one for each input
.outSpec
the output Spec of the Instr. if your Instr is not 'audio' rate or is multi channel than it is best to specify an outSpec
.explicitSpecs
those that were declared when creating the Instr, as opposed to those that were not supplied and were guessed by using the argName
.convertArgs
Most methods accept args in the form of a list [ 440, 1.0, Env.adsr ] or as a argName:value dict (env:Env.adsr)
This utility function converts the supplied arguments to the list form.
Arguments:
| args |
array or dict |
Returns:
array
.ar
values the function using the supplied inputs. this is for using Instr as a subroutine or function library.
Arguments:
| ... inputs |
inputs as separate arguments |
.value
inputs as a single array or dict same as .valueArray but should probably change to accept ... inputs
Arguments:
| inputs |
array or dict |
.valueEnvir
values the function with the supplied inputs, filling in any missing ones by looking up by argName in the current Environment
Arguments:
| inputs |
array or dict |
.valueArray
like value but takes a single array
Arguments:
| inputs |
array or dict |
.kr
same as ar
Arguments:
| ... inputs |
array or dict |
.asSynthDef
creates a SynthDef
Arguments:
| args |
array or dict |
| outClass |
if no Out.ar is found in your Instr then it automatically adds one and an argument called \out The default class is Out, but you can specify ReplaceOut or OffsetOut |
.writeDefFile
creates SynthDef and writes it to file
Arguments:
| dir |
directory to write to. the name is unique and is determined by the arguments |
| args |
array or dict |
Returns:
this
.write
same as writeDefFile, older syntax
Arguments:
| dir | |
| args |
array or dict |
Returns:
this
.add
create a SynthDef and add it to the SynthDescLib for use in Patterns. see also Instr-Patterns
Arguments:
| args |
array or dict |
| libname | |
| completionMsg | |
| keepDef |
.store
for Patterns. older system, .add is preferred now
Arguments:
| args |
array or dict |
.after
spawn a Synth into the same Group as a node, directly after that node in the call graph
Arguments:
| anode | |
| args |
array or dict |
| bundle | |
| atTime |
see atTime |
| out |
out bus index |
Returns:
a Synth
.before
spawn a Synth into the same Group as a node, directly before that node in the call graph
Arguments:
| anode | |
| args |
array or dict |
| bundle | |
| atTime |
see atTime |
| out |
out bus index |
Returns:
a Synth
.head
spawn a Synth into the Group, adding it as the first node in that group
Arguments:
| anode | |
| args |
array or dict |
| bundle | |
| atTime |
see atTime |
| out |
out bus index |
Returns:
a Synth
.tail
spawn a Synth into the Group, adding it as the last node in that group
Arguments:
| anode | |
| args |
array or dict |
| bundle | |
| atTime |
see atTime |
| out |
out bus index |
Returns:
a Synth
Discussion:
.replace
spawn a Synth that replace an already playing Synth and frees it
Arguments:
| anode | |
| args |
array or dict |
| bundle | |
| atTime |
see atTime |
| out |
out bus index |
.spawnEvent
sets the Event 'type' = 'instr' and 'instr' = this and then .plays the Event.
Arguments:
| event |
Event to play. Instr arguments will be looked up by name in the Event. |
.next
same as valueArray, for use in Streams
Arguments:
| ... inputs |
array or dict |
<>>
function composition : construct a CompositeInstr by patching this Instr into another one.
Arguments:
| that |
another Instr (or a CompositeInstr or Papplied Instr) |
Returns:
.papply
partial application : fix certain args with the supplied object. returns a PappliedInstr
Arguments:
| ... args |
either a dict or a list. if a list then non nil arguments will |
.rate
\audio \control \scalar \stream If the Instr has an out spec then it will determine the rate. Otherwise its assumed to be the default 'audio'
Returns:
a Symbol
.numChannels
If the Instr has an out spec then it will determine the numChannels. Otherwise its assumed to be the default 1
Returns:
Integer
.path
full path on disk if the Instr was loaded from a file
.maxArgs
same as argsSize
.argsSize
number of arguments / inputs.
.argNames
Returns:
array of Symbols
.defArgs
the defaults for each argument that were specified in the function; eg. for { arg freq=440; } the defArg is 440
Returns:
array of default args
.argNameAt
Arguments:
| i |
.defArgAt
Arguments:
| i |
.initAt
either the default value supplied in the function or the spec's default value.
Arguments:
| i |
.defName
the instr name as a string: "one.two.three"
deprec.
.asDefName
calculates the unique SynthDef name for the supplied arguments. this is fairly efficient and is even used when spawning Events in Patterns
Arguments:
| args |
array or dict the objects that determine the unique SynthDef. they may determine the rate, whether a control input is added or not and they may insert unique objects into the SynthDef. |
Returns:
string
.prepareToBundle
Arguments:
| group | |
| bundle |
.funcDef
.prMakeSynth
Arguments:
| targetStyle | |
| anode | |
| args |
array or dict |
| bundle | |
| atTime |
see atTime |
| out |
out bus index |
.test
creates a Patch, guis it and plays it
Arguments:
| ... args |
Returns:
a Patch
.play
creates a Patch and plays it
Arguments:
| ... args |
Returns:
a Patch
.plot
creates a Patch and plays it for {duration} seconds and plots it
Arguments:
| args |
array or dict |
| duration |
.asString
printable name
.storeArgs
.storeableFuncReference
for storing Instr and objects that have Instr. if the Instr was loaded from disk then the dotNotation instr name is used. if it was created with something like Patch({ SinOsc.ar }) then the source code is used.
.copy
if the name is the same then its the same Instr. so copying just returns self. this might be changed.
Returns:
this
.init
private
Arguments:
| specs | |
| outsp |
outSpec |
.makeSpecs
private
Arguments:
| argSpecs |
.isFilter
a filter is any instr that has an input the same spec as its output.
Returns:
Boolean
.guiClass
.asSingleName
.asInstr
.instr
Arguments:
| ... args |
.proxyControlClass
.wrapInFader
Arguments:
| bus |