AC Toolbox
A program to assist algorithmic composition. (www.koncon.nl/downloads/ACToolbox)
Documentation for all available help.
(1/f-choice n sequence)
Returns a closure. When applied, one element is chosen from a sequence according to a 1/F distribution. N is the total (estimated) number of values to be chosen using this generator (example 1).
EXAMPLE 1: (for-example (1/f-choice 20 '(a b c d e f g h i)))
(1/f-value n a z)
Returns a closure. When applied, it returns a number between A and Z according to a 1/F distribution. The type of the number is determined by the type of A and Z. N is the total number of values (estimated) to be produced with this generator (examples 1-3).
A and Z may vary over time (example 4).
EXAMPLE 1: (for-example (1/f-value 20 1 100))
EXAMPLE 2: (for-example (1/f-value 20 1.0 100))
EXAMPLE 3: (plot (1/f-value 200 1.0 100)
:number 200 :min 1 :max 100)
EXAMPLE 4: (plot (1/f-value 200 (line-segment 200 1.0 100) 100)
:number 200 :min 1 :max 100)
(2-masks n outer-mask outer-low outer-high inner-mask inner-low inner-high &optional generator stop)
One mask, OUTER-MASK, is mapped to produce a list with N values chosen randomly between OUTER-LOW and OUTER-HIGH. A second mask, INNER-MASK, is mapped to be in the range between INNER-LOW and INNER-HIGH. The second mask is used to block the choice of values from the first mask. In other words, if the value mapped using the first mask falls within the area of the second mask, the value is rejected and another is generated until one falls outside the inner mask. If that does not happen within STOP number of attempts, an error message is produced (examples 1-5).
The outer and the inner mask can be the same mask but they should not be mapped to the same limits because all values would always be blocked (examples 6-7).
In the standard case, an uniform random distribution is used to choose values between the limits of the outer mask. Another generator which can produce values in the range 0-100 percent can be bound to the optional GENERATOR parameter (example 8). Instead of a generator, a list with percentage values could also be given (example 9).
Optional parameter STOP could be increased to allow for more attempts before stopping but probably the there is an inconsistency in the boundaries which prevents the generation of values (examples 10-11).
If the optional parameter for GENERATOR is bound to t as in the above example, a uniform random distribution is used to pick values between the limits of the mask.
To generate a number of values from a mask without blocking by using another mask, see the tool CONVERT.
EXAMPLE 1: (fill-template specify-mask outer '(50 100 50) '(40 0 20))
EXAMPLE 2: (fill-template specify-mask inner '(100 100) '(0 0))
EXAMPLE 3: (plot outer)
EXAMPLE 4: (plot inner)
EXAMPLE 5: (plot (2-masks 100 outer 1 100 inner 40 60))
EXAMPLE 6: (plot (2-masks 100 inner 1 100 inner 65 80))
EXAMPLE 7: (make-histogram (2-masks 100 inner 1 100 inner 65 80))
EXAMPLE 8: (plot (2-masks 100 outer 1 100 inner 40 60
(beta-value 0.0 100 .1 .1)))
EXAMPLE 8: (plot (2-masks 100 outer 1 100 inner 40 60
'(0 20 40 60 80 100)))
EXAMPLE 10: (plot (2-masks 100 outer 40 80 inner 40 80 t 500))
EXAMPLE 11: (plot (2-masks 100 outer 30 90 inner 40 80))
(a-delay time-in-milliseconds)
Returns an instance of the class SOME-DELAY. It is suitable for use in NOTE STRUCTUREs, NOTE SECTIONs or STRUCTURED SECTIONs. In can be part of a NOTE STRUCTURE such as one constructed with IN-SEQUENCE or IN-PARALLEL.
The TIME-IN-MILLISECONDS represents an actual amount of time for a rest and is not a multiple of a clock time.
Example 1 will wait 1 second in a note structure.
EXAMPLE 1: (fill-template structured-section
section1 200
(in-sequence (a-note 1 60 mf 1) (a-delay 1000)
(a-note 1 67 mf 1)))
(a-note rhythm pitch velocity channel)
Returns an instance of the class SOME-NOTE. It is suitable for use in NOTE STRUCTUREs, NOTE SECTIONs or STRUCTURED SECTIONs. In can be part of a NOTE STRUCTURE such as one constructed with IN-SEQUENCE or IN-PARALLEL.
RHYTHM values are multiples of a clock unit that is specified when a section is made.
PITCH can be MIDI note numbers or a known symbol, such as C3. PITCH can also be a list of note numbers to occur at the same time (a chord).
VELOCITY is a MIDI value (0-127) or a known symbol, such as MF.
CHANNELS are specified between 1-16.
(examples 1-3).
EXAMPLE 1: (fill-template structured-section
section1 200 (a-note 1 60 mf 1))
EXAMPLE 2: (fill-template structured-section
section2 200 (a-note 1 '(c3 e3 g3) mf 1))
EXAMPLE 3: (fill-template structured-section
section3 200
(in-sequence (a-note 1 60 mf 1) (a-note 1 64 mf 1)
(a-note 1 67 mf 1)))
(a-rest rhythm)
Returns an instance of the class SOME-REST. It is suitable for use in NOTE STRUCTUREs, NOTE SECTIONs or STRUCTURED SECTIONs. In can be part of a NOTE STRUCTURE such as one constructed with IN-SEQUENCE or IN-PARALLEL.
RHYTHM values are multiples of a clock unit that is specified when a section is made. When used within another structure, this object represents a rest of a certain length (example 1).
EXAMPLE 1: (fill-template structured-section
section1 200
(in-sequence (a-note 1 60 mf 1)
(a-rest 3)
(a-note 1 67 mf 1)))
ac toolbox
The AC Toolbox is a collection of tools to facilitate the activity commonly known as algorithmic composition.
Several models for defining musical events are included. They can be used by defining objects such as sections, shapes, masks, or note structures.
Menu items are available for defining the various types of objects. It is also possible to play, plot, modify, and examine objects in a number of ways. Extensive online help is available.
In addition to Midi input and output, the AC Toolbox can produce files suitable for use as data in other programs. Score files for Csound and binary OSC files for SuperCollider can be produced and rendered. Floating-point Midi output via a firewire interface to a Capybara or Pacarana is also suported.
An important method of creating data in the Toolbox is the use of generators. A number of generators have been included reflecting various approaches to the creation of musical material including tendency masks, stochastic functions, chaotic systems, transition tables, recursive subdivisions, metric indispensabilities, morphological mutations, etc.
The AC Toolbox is implemented in Lisp and input syntax often reflects the conventions of this language. It is also possible for a user to extend the Toolbox by adding Lisp functions. For example, additional generators can be defined in Lisp to use with the Toolbox.
(act-choose-directory-dialog &key path prompt namestring)
This tool is intended for users programming functions that require selecting a folder with a dialog.
PATH is a suggested path expressed as a string.
PROMPT is a string printed on the top of the dialog.
NAMESTRING will return the path as a namestring if it is bound to t.
EXAMPLE 1: (print-result (act-choose-directory-dialog
:prompt "Pick a folder for my object files"))
(act-choose-file-dialog &key path prompt filter namestring operation)
This tool is intended for users programming functions that require selecting files with a dialog.
PATH is a suggested path expressed as a string.
PROMPT is a string printed on the top of the dialog.
FILTER defaults to all file types but types such as :lisp, :text, :sound, and :midi can be used. FILTER controls which types of files are available for selection.
NAMESTRING will return the path as a namestring if it is bound to t.
OPERATION defaults to :open (the selected file). To save to the selected file bind OPERATION to :save.
EXAMPLE 1: (print-result (act-choose-file-dialog))
EXAMPLE 2: (print-result (act-choose-file-dialog
:prompt "Choose a text file"
:filter :text))
(act-if source &rest conditions)
Returns a closure. When applied, it provides a nested series of IFs which understand how to read and produce data with AC Toolbox objects.
Various generators can be chosen based on a value produced from SOURCE. That value is compared, in succession, to the conditions until either a condition is met, in which case another value is generated and returned or if no condition has been met, the final, default result is used.
Conditions are separated by ELSE.
If the initial condition is not met, then the ELSE clause is dealt with. There must be at least one ELSE clause in the expression (example 1).
In this example, if the value from SOURCE > 20, then the generator (rv 100 200) is applied to produce a value. Otherwise, the generator (rv 1 10) will be used. Each time the generator is applied, the next value from SOURCE is compared.
All values, except for the comparison functions, can be generators, stockpiles, lists, or constants. Each time the generator is applied, the next value from the generator, stockpile, etc. will be used.
Any number of ELSE conditions can be used as long as there is a final condition in case none of the above was true. The conditions are examined in sequence. As soon as one condition is true, a result is produced and the generator stops (example 2).
If the value from SOURCE > 20, generator (rv 100 200) returns a value. Otherwise the comparison value = 20 is made. If true, the next value from the list '(50 60 70 80) is returned. Otherwise if value >= 15, 5 is returned. Otherwise the generator (rv 1 10) will be used.
Since SOURCE can be a stockpiile, list, generator, etc., a stockpile will be defined to use as source (examples 3-4).
Comparisons with only one argument can also be used. In that case, the value from SOURCE will be the input for the comparison (example 5).
If the value from the stockpile is even, the generator (rv 1 10) is applied. Otherwise (rv 100 200) will produce the value.
The current value from SOURCE can be returned by using the symbol current. This can only be used for the result of a comparison. Example 6 returns the result of (rv 10 20) if the value from SOURCE is >= 3. Otherwise, the current value from SOURCE is returned.
The opposite situation is also possible (example 7).
Some obvious examples of Lisp functions which can be used to make the comparisons are:
=, <, >, <=, >=, /=, evenp, oddp
These functions can only be used with numbers.
SOURCE is not limited to numbers. If a generator should be chosen based on a symbol, the comparison function could be EQUAL. The symbols being compared should be quoted (example 8).
This generator can be used to establish a relationship between parameters. A stockpile of values used for one parameter could be the input used to determine generators for another parameter. In examples 9-10, pitches below 60 have larger rhythmic values.
EXAMPLE 1: (for-example
(act-if '(10 20 30)
> 20 (rv 100 200)
else (rv 1 10)))
EXAMPLE 2: (for-example
(act-if '(10 20 30 15)
> 20 (rv 100 200)
else = 20 '(50 60 70 80)
else >= 15 5
else (rv 1 10)))
EXAMPLE 3: (fill-template specify-stockpile stock1 1 2 3 4)
EXAMPLE 4: (for-example
(act-if stock1
> 2 (rv 100 200)
else (rv 1 10)))
EXAMPLE 5: (for-example
(act-if '(1 2 3 4)
evenp (rv 1 10)
else (rv 100 200)))
EXAMPLE 6: (for-example
(act-if '(1 2 3 4)
>= 3 (rv 10 20)
else current))
EXAMPLE 7: (for-example
(act-if '(1 2 3 4)
>= 3 current
else (rv 1 10)))
EXAMPLE 8: (for-example
(act-if (random-choice '(sax1 flute1))
equal 'sax1 (rv 1 10)
else (rv 1 100)))
EXAMPLE 9: (fill-template generate-stockpile pitches 100
(random-value 40 80))
EXAMPLE 10: (fill-template data-section ds1 100 100
(act-if pitches
< 60 (random-value 2.0 4)
else (random-value 1.0 2))
pitches
(random-value mf ff) 1 0)
(add-generator-brief name text)
Adds a brief TEXT description for a generator called NAME.
NAME should be symbol and TEXT should be a string (between "").
NAME and TEXT will appear in the table made by the menu item Brief descriptions (example 1).
EXAMPLE 1: (add-generator-brief 'generate-nothing
"Turn something into nothing")
(add-new-generator name text examples &key basic chaos ...)
Adds the symbol NAME to the list of generators which can be accessed with the help function.
TEXT is the text which will appear in the help window.It should be entered as a string.
EXAMPLES is a string containing examples which can be evaluated in the lower pane of the help dialog.
E.g.
(add-new-generator 'my-generator
"(my-generator parameter)
Helps a lot.
"
"
EXAMPLE 1: (for-example (my-generator 10))
")
Keywords can be used to indicate which category the generator might fit into. A generator can be included in more than one category. In the Annotated Index, various categories can be chosen. These categories correspond to the keywords that can be used with ADD-GENERATOR. If the generator could be considered to produce noise, the keyword should be bound to the t.
E.g.
(add-new-generator 'my-generator
"(my-generator parameter)
Makes a lot of noise.
"
"
EXAMPLE 1: (for-example (my-generator 10))
" :noise t)
If the double quote symbol is needed in the text string, precede it with \.
A simple markup system is available to format help texts. The markup characters are inserted directly into the help text (within the strings). The markup commands all start with an at sign and are followed by another character.
h starts a header
/ ends the header
p starts and ends a paragraph
When a window size is changed, the width of the paragraph also changes.
If no examples are to be entered and the lower pane is not desired, use ADD-GENERATOR with the same arguments except for the string of examples.
(add-new-tool name text examples &key basic chaos ...)
Adds the symbol NAME to the list of tools which can be accessed with the help function.
TEXT is the text which will appear in the help window. It should be entered as a string.
EXAMPLES is a string containing examples which can be evaluated in the lower pane of the help dialog.
E.g.
(add-new-tool 'my-tool
"(my-tool parameter)
Does really interesting things.
"
"
EXAMPLE 1: (print-result (my-tool 10))
")
Tools are grouped into various categories. In the Annotated Index, various categories can be chosen. These categories correspond to the keywords that can be used with ADD-TOOL. To include a tool in a category, the keyword should be bound to t.
E.g.
(add-new-tool 'my-tool
"(my-tool parameter)
Does really interesting things.
"
"
EXAMPLE 1: (print-result (my-tool 10))
" :basic t)
A tool can be included in more than category.
If the double quote symbol is needed in the text string, precede it with \.
A simple markup system is available to format help texts. The markup characters are inserted directly into the help text (within the strings). The markup commands all start with an at sign and are followed by another character.
h starts a header
/ ends the header
p starts and ends a paragraph
When a window size is changed, the width of the paragraph also changes.
If no examples are to be entered and the lower pane is not desired, use ADD-TOOL with the same arguments except for the string of examples.
(add-new-transformer name text examples &key basic chaos ...)
Adds the symbol NAME to the list of transformers which can be accessed with the help function.
TEXT is the text which will appear in the help window. It should be entered as a string.
EXAMPLES is a string containing examples which can be evaluated in the lower pane of the help dialog.
E.g.
(add-transformer 'my-transformer
"(my-transformer amount)
Transforms by adding AMOUNT to the parameter being transformed.
"
"
EXAMPLE 1: (show-transformation (my-transformer 10)
'(10 20 30 40))
")
Transformers are grouped into various categories. In the Annotated Index, various categories can be chosen. These categories correspond to the keywords that can be used with ADD-TRANSFORMER. To include a tool in a category, the keyword should be bound to t.
E.g.
(add-transformer 'my-transformer
"(my-transformer amount)
Transforms by adding AMOUNT to the parameter being transformed.
"
"
EXAMPLE 1: (show-transformation (my-transformer 10)
'(10 20 30 40))
" :pitch t)
If the double quote symbol is needed in the text string, precede it with \.
To show the results of a transformation in a help window, the tool SHOW-TRANSFORMATION is often used. See its help for a description.
A simple markup system is available to format help texts. The markup characters are inserted directly into the help text (within the strings). The markup commands all start with an at sign and are followed by another character.
h starts a header
/ ends the header
p starts and ends a paragraph
When a window size is changed, the width of the paragraph also changes.
If no examples are to be entered and the lower pane is not desired, use ADD-TRANSFORMER with the same arguments except for the string of examples.
(add-to number sequence-or-function)
Returns a closure which adds a value to NUMBER. The value to be added is determined by SEQUENCE-OR-FUNCTION. If it is a sequence, each value from the sequence is added in turn to NUMBER (example 1).
If it is a function, the function is applied each time to get the next value to be added (example 2).
EXAMPLE 1: (for-example (add-to 60 '(0 2 4 5 7 9 11 12)))
EXAMPLE 2: (for-example (add-to 60 (random-value -12 12)))
(add-tool-brief name text)
Adds a brief TEXT description for a tool called NAME.
NAME should be symbol and TEXT should be a string (between "").
NAME and TEXT will appear in the table made by the menu item Brief descriptions (example 1).
EXAMPLE 1: (add-tool-brief 'useless
"Perform a useless task")
(add-transformer-brief name text)
Adds a brief TEXT description for a transformer called NAME.
NAME should be symbol and TEXT should be a string (between "").
NAME and TEXT will appear in the table made by the menu item Brief descriptions (example 1).
EXAMPLE 1: (add-transformer-brief 'make-uglier
"Make something uglier")
(adjust-internal-representation section)
Destructively adjusts a section. This tool gathers notes which occur at the same time in a section into the internal representation of one chord. The longest duration occuring at that start time is assigned to the chord. Note that the destructive change is irreversible.
The basic time to use this tool is if a section has been read in from a midi file, chords occur, and you want to extract pitches from that section, e.g. for a transition table.
Another use would be to create chords within a parallel section so that they can be extracted as a group of pitches.
If a section S1 exists, example 1 would do the adjustment.
The effect of using this tool can be seen in the output produced by section info (example 2).
EXAMPLE 1: (adjust-internal-representation s1)
EXAMPLE 2: (show-text s1)
(alea low high)
Returns a uniformly distributed random number between LOW and HIGH (inclusive). If both LOW and HIGH are integers, the result is an integer (example 1). If one or both of the arguments is a real number, the result is a real number (example 2). If one or both of the arguments is a ratio (e.g. 1/2), a real number is also returned.
ALEA is not a generator. For a generator that does this, see RANDOM-VALUE.
EXAMPLE 1: (print-result (alea 500 1000))
EXAMPLE 2: (print-result (alea 500.0 1000))
(all-intervals elements &key number)
Returns a list of all combinations of the numbers in ELEMENTS in which each interval (distance between numbers) occurs once (example 1).
The possible intervals with the elements 1, 2, 3, 4 are 1, 2, and 3. In the solution in example 1, each of these intervals occurs one time.
The values in ELEMENTS should be numbers. AC Toolbox symbols for pitch, such as c3, can also be used. ELEMENTS may be a list or stockpile (examples 2-3).
For larger numbers of elements, the calculation time can be quite long (from one to several minutes depending on the speed of the computer) (example 4).
To limit the number of solutions, bind the keyword NUMBER to a smaller value (example 5).
Note that the calculation of the all-interval lists will always produce the same series of results if the elements are entered in the same order. To get the output in a different order, change the order of the elements (examples 6-8).
To produce one all-interval list with some largish number of elements, shuffle the elements and then produce only one list. This speeds up the process when only one list is desired (example 9).
A list of intervals can be chosen with a CHOICE generator (examples 10-12).
The values from an all-interval list can be read using READ-PERMUTATION. This will read permutations and return each element one at a time. To randomly choose which permutation to read, bind keyword RANDOM to t (examples 13-14)
If a stockpile contains results of ALL-INTERVALS, that one stockpile can be saved as an environment and reloaded for subsequent use. This eliminates the need to recalculate a stockpile containing lists of all possible all-interval lists.The menu item File > Save Some Objects can be used to save just one object (the stockpile) (example 15).
Many common music theoretical constraints on examining all intervals have not been implemented.
EXAMPLE 1: (for-example (all-intervals '(1 2 3 4)))
EXAMPLE 2: (for-example (all-intervals '(c3 c#3 d3 d#3)))
EXAMPLE 3: (for-example
(stockpile->notename (all-intervals '(c3 c#3 d3 d#3))))
EXAMPLE 4: (for-example
(all-intervals (from 0 11))
:number-per-line 1)
EXAMPLE 5: (for-example
(all-intervals (from 0 11)
:number 10)
:number-per-line 1)
EXAMPLE 6: (for-example (all-intervals '(1 2 3 4)))
EXAMPLE 7: (for-example (all-intervals '(3 4 1 2)))
EXAMPLE 8: (for-example
(all-intervals (rearrange-stockpile'(1 2 3 4) 'shuffle)))
EXAMPLE 9: (for-example
(all-intervals
(rearrange-stockpile (from 0 11) 'shuffle)
:number 1))
EXAMPLE 10: (for-example (series-choice (all-intervals '(1 2 3 4))))
EXAMPLE 11: (fill-template construct-stockpile ints
(all-intervals (from 1 6)))
EXAMPLE 12: (for-example (random-choice ints))
EXAMPLE 13: (for-example
(read-permutation (all-intervals (from 1 5))))
EXAMPLE 14: (for-example
(read-permutation (all-intervals (from 1 5))
:random t))
EXAMPLE 15: (fill-template construct-stockpile all
(all-intervals (from 0 11)))
(allow-larger-quantization-stack)
This tool is only useful when writing a FOMUS file (File>Write FOMUS File) and the quantization option has been chosen. A large section may cause a stack overflow error message. Additional space can be allocated for that stack with this tool (example 1).
Each time the tool is evaluated, the stack size will be increased the next time that a section is quantized. Increasing the stack size too often may limit the effectiveness of the program. There may also be a limit on how much space is available for the stack.
EXAMPLE 1: (print-result (allow-larger-quantization-stack))
(always value)
Returns a closure which always returns a copy of VALUE (example 1).
EXAMPLE 1: (for-example (always 10))
amadeus
Amadeus is an inexpensive sound editor for the Macintosh (example 1).
Spectral output in a text file can be read in the AC Toolbox using READ-SPECTRUM-FILE.
The menu item Analyze>Spectrum can be used to produce the analysis. Save this to a file in the format TEXT (not importable).
EXAMPLE 1: (open-url "http://www.hairersoft.com/Amadeus.html")
(anchor shape n desired-first desired-last lower upper)
Returns a list of values made by mapping a shape. The starting and end point for the shape are specified. If necessary, the shape is adjusted to make the starting and end point possible.
ANCHOR will map either a shape, a list, a stockpile, or a generator to be a list with N values starting with DESIRED-FIRST and ending with DESIRED-LAST.
LOWER and UPPER are used to initially scale the shape, etc. to be between these values (just as is the case with CONVERT). LOWER and UPPER represent lower and upper limits for the shape. This intermediate result is rescaled to force the shape to start and end with the specified values DESIRED-FIRST and DESIRED-LAST. This rescaling process may cause the mapped version of the shape to contain values outside of the range of LOWER and UPPER or to fall short of those values. The aim is insure that the list which is returned will start and end with the desired values. Values in between are adjusted to make this happen and still keep some relation to the shape being mapped.
In examples 1-2, the default shape sine-shape is mapped to be 10 values between 40 80. The beginning and end values are 60.
The shape can be distorted by the choice of DESIRED-FIRST and DESIRED-LAST. In example 3, DESIRED-FIRST is set to 40.
The values in the list are returned as integers if DESIRED-FIRST, DESIRED-LAST, LOWER, and UPPER are all integers. If one or more of these values is a real number, real numbers are returned in the list (example 4).
The choice of values for DESIRED-FIRST and DESIRED-LAST has a strong influence on the result of this function and the range and shape the values assume. Displaying the outcome of the process is an useful way to inform yourself of the result.
EXAMPLE 1: (for-example (anchor sine-shape 10 60 60 40 80))
EXAMPLE 2: (plot (anchor sine-shape 100 60 60 40 80))
EXAMPLE 3: (plot (anchor sine-shape 100 40 60 40 80))
EXAMPLE 4: (for-example (anchor sine-shape 10 60 60 40 80.0))
(apply-function function &rest args)
Returns a closure. When applied, FUNCTION is applied to one result of each of the arguments. ARGS may be generators, stockpiles, lists, constants, etc.
Any number of arguments may be used. Each time the generator is applied, each argument will be asked for a new value. FUNCTION should be preceded by a function quote: #' (examples 1-2).
See generator ON-THE-FLY for an alternative way of doing something similar.
EXAMPLE 1: (for-example
(apply-function #'+ '(10 20 30) '(40 50 60)
'(100 200 300 400)))
EXAMPLE 2: (plot
(apply-function #'+ (convert line-shape 100 1 100)
(random-value -5.0 5)))
(apply-object object)
Intended for use with controllers and schemes.
If OBJECT is a controller, one value is produced by the controller's closure. That value is also added to the controller's history.
If OBJECT is a scheme, the entire scheme-of-variations is executed, i.e. all objects included in the scheme are destructively redefined, in the same order they are included in the scheme.
(arc number-of-steps start finish &key (curve 2))
ARC is a shortcut (abbreviation for EXPONENTIAL-MOTION (examples 1-2).
It returns the next point on a curve. After NUMBER-OF-STEPS values, it starts at the beginning again.
See the help for EXPONENTIAL-MOTION for more information.
EXAMPLE 1: (plot (arc 100 0.0 100))
EXAMPLE 2: (plot (arc 100 0.0 100 :curve 4))
(attacks interval &key low high number)
This tool returns a list of attack times mapped to be between LOW and HIGH. LOW defaults to 0.0 and HIGH to 100.0 making it convenient for use in a density section using a function. With other values for HIGH (and/or LOW) it could be useful in calculating start times for a Csound object or OSC score.
NUMBER defaults to (from-number), e.g. the number specified in a section, Csound object or OSC score.
ATTACKS starts with 0.0 and adds a value produced by INTERVAL to that value. A new value from INTERVAL is added to that result. This continues until NUMBER values have been produced. The resulting list is then mapped to be between LOW and HIGH (example 1).
INTERVAL can be a generator, stockpile, constant, etc.
There are two important points regarding this tool.
1) The new value is added to the previous result. This means that with positive interval values, the list will be in ascending order.
2) The whole list is scaled to be between LOW and HIGH.
These two points suggest that the absolute values produced by INTERVAL are less important than the relationships of successive intervals. The intervals in examples 2-3 have different values but the same relationship. They will therefore produce the same result.
In a density section with a function, attack times between 0 and 100% are mapped to fill a time value in seconds. ATTACKS can produce a list suitable for the attack parameter of a density section. Since NUMBER defaults to (from-number), the number specified in the dialog will be the number of values created by attacks (example 4).
The object produced in example 4 uses a time interval created with exponential-value. This is similar to the idea used by Xenakis in his Stochastic Music Program where a probabilistic function was used to create time intervals between events.
If ATTACKS is not used, the function for the attack parameter will produce absolute start times as percentage values. If exponential-value is used to generate those values, the result is start times clustered near the beginning of the section (since exponential-value tends to produce values near its lower threshold) (example 5).
In example 6, a smaller upper threshold is used for exponential-value. This may decrease the size of the intervals in the result since it decreases the maximum possible (relative) interval size. Compare this with ATTACK1.
Other generators, such as PRIME-NUMBER and FIBONACCI can also be used to determine attack times (example 7).
Start values for a Csound score can be generated with this tool. In this context, LOW and HIGH refer to a duration in seconds (rather than a percentage of a duration as is the case with a density section). The value for HIGH will be the actual attack time for the last event in the score.
Example 8 should be rendered using the instrument definition in 'test csound.orc' found in 'Support/FileExamples'. This can be specified in the Csound File Options dialog. ATTACKS creates the start times for the events. HIGH was set to 20 which means that the last attack time will be at 20 seconds.
Example 9 does something similar with an OSC score. Synthdef sine1 can be found in 'test osc synthdefs.rtf' in 'Support/FileExamples'. It should be compiled (once) in the SuperCollider language application.
ATTACKS should not be used in a dialog which uses UNTIL-TIME to specify the number of events.
EXAMPLE 1: (for-example
(attacks (exponential-value 0.1 .1 100) :number 10))
EXAMPLE 2: (for-example
(attacks '(2 1) :number 10))
EXAMPLE 3: (for-example
(attacks '(4 2) :number 10))
EXAMPLE 4: (fill-template density-section attack1 20 15
(attacks (exponential-value 0.0 0.1 100))
100 (rv 40 80) mf 1)
EXAMPLE 5: (fill-template density-section attack1b 20 15
(exponential-value 0.0 0.1 100)
100 (rv 40 80) mf 1)
EXAMPLE 6: (fill-template density-section attack2 20 15
(attacks (exponential-value 1.0 0.1 10))
100 (rv 40 80) mf 1)
EXAMPLE 7: (fill-template density-section attack3 20 10
(attacks (prime-number))
100 (rv 40 80) mf 1)
EXAMPLE 8: (fill-template csound-score-object attack-csound
"f1 0 8192 10 1
f2 0 8192 20 2 1" nil nil 1 100 1
(attacks (exponential-value 1.0 0.1 30) :high 20)
(rv 0.1 0.2) 5000 (rv 100.0 1000))
EXAMPLE 9: (fill-template osc-score-object attack-osc
100 "sine1" nil nil nil 1
(attacks (exponential-value 1.0 0.1 30) :high 20)
"dur" (rv 0.1 0.2) "amp" 0.2 "freq"
(rv 100.0 1000))
audacity
Audacity is an open source sound editor (example 1).
Spectral output in a text file can be read in the AC Toolbox using READ-SPECTRUM-FILE.
To make the spectral text file:
select the sound to be analyzed
produce a spectrum with Analyze>Plot Spectrum
click on the Export button and save as a text file.
EXAMPLE 1: (open-url "http://audacity.sourceforge.net/")
(average thing &optional number)
Returns the average value of THING if it is a list or stockpile containing numbers (example 1).
The average value of a beta distribution is a/(a+b). This could be tested (example 2-3).
In example 2, both a and b are .2, therefore a/(a+b) = .2/.4 The average result produced above should be about .5
If THING is a generator, it is applied NUMBER of times and the average value is returned (example 4).
The value of NUMBER is 100. To increase the number of applications of the generator, provide NUMBER with a new value (example 5).
EXAMPLE 1: (print-result (average '(1 2 3 4)))
EXAMPLE 2: (fill-template generate-stockpile beta-stock 1000
(beta-value 0.0 1 .2 .2))
EXAMPLE 3: (print-result (average beta-stock))
EXAMPLE 4: (print-result (average (beta-value 0.0 1 .2 .2)))
EXAMPLE 5: (print-result (average (beta-value 0.0 1 .2 .2) 1000))
(backwards object)
Backwards returns a copy of object, but with the elements in reverse order. Backwards is an operator which works on AC Toolbox objects, such as shapes, masks, sections, communities, stockpiles and note structures.
It is the same operator which is available using the Menu item Methods (examples 1-2).
EXAMPLE 1: (plot expo-shape)
EXAMPLE 2: (plot (backwards expo-shape))
(basic-error-message string)
The basic template for printing (error) messages in a message dialog (example 1). The intended use of this tool is to add error messages to functions that a user may choose to add to the AC Toolbox.
EXAMPLE 1: (basic-error-message "This does not work.")
(beta a b)
This function will produce a value between 0 and 1 according to a beta distribution when it is applied. A and B should be > 0 and < 1. The smaller the value of A is, the greater the probability that a result near 0 will be produced. The smaller the value of B is, the greater the probability that a result near 1 will be produced (examples 1-2).
A check has been included to prevent A or B from being set to 0 (since this would cause divide by 0 errors). In this case, a minimum value of 0.0001 is used.
See BETA-VALUE for an application of this tool to produce values between specified limits.
See BETA-CHOICE for aan application of this tool to select values from a list or stockpile.
EXAMPLE 1: (for-example (generate (beta .3 .3)))
EXAMPLE 2: (for-example (generate (beta .1 .1)))
(beta-choice sequence a b)
Returns a closure. When applied, a value is chosen from the sequence according to a beta distribution. This distribution tends to choose values near its two limits. A and B should be > 0 and < 1. The smaller the value of A, the greater the probability that an element near the beginning of the sequence will be chosen. The smaller the value of B, the greater the probability that an element near the end of the sequence will be chosen (examples 1-2).
A and B can change over time (example 3).
EXAMPLE 1: (for-example (beta-choice '(a b c d e f g h) .5 .5))
EXAMPLE 2: (for-example (beta-choice '(a b c d e f g h) .1 .1))
EXAMPLE 3: (for-example (beta-choice '(a b c d e f g h)
(line-segment 20 .5 .1) .1))
(beta-tendency-choice sequence mask1 ...)
Returns a closure. When applied, chooses an element from SEQUENCE according to a tendency mask. Similar to the closure returned by TENDENCY-VALUE except that the random choice between the changing boundaries is made with a beta function.
The mask values are: (N A1 A2 Z1 Z2 A B). A and B are the parameters for the beta function. A1, A2, Z1, Z2 should be expressed in percentages (0-100) (example 1).
See the help for the generator TENDENCY-CHOICE and for the tool BETA for more information.
EXAMPLE 1: (for-example
(beta-tendency-choice '(a b c d e f g h i)
'(20 0 20 80 100 .2 .2)))
(beta-tendency-value mask1 ...)
Returns a closure. When applied, produces a numerical result in a way similar to the closure returned by TENDENCY-VALUE. The difference is that the random-choice between the moving boundaries is made with a beta function instead of an uniform random distribution as is the case with an ordinary tendency mask. See the help for the generator TENDENCY-VALUE for a discussion of the parameters of a tendency mask. See the help for the tool BETA for a discussion of the parameters of the beta function.
A mask should contain (N A1 A2 Z1 Z2 A B) where A and B are the parameters for the beta function (examples 1-2).
Any number of masks may be used (example 3). The type of the returned values is determined by the type (integer or real) of the mask boundaries (A1 A2 Z1 Z2).
Another way of realizing this concept is to define a mask object and use the tool CONVERT to produce a list of values within this mask. BETA-VALUE could be used as a generator with CONVERT to produce the values. See CONVERT.
EXAMPLE 1: (for-example (beta-tendency-value
'(20 1 100 90 100 .2 .2)))
EXAMPLE 2: (plot (beta-tendency-value
'(100 1 100 90 100 .2 .2)))
EXAMPLE 3: (plot (beta-tendency-value
'(50 1 100 90 100 .1 .1)
'(50 1 100 100 1 .1 .1)))
(beta-value low high a b)
Returns a closure. When applied, it will produce a number between LOW and HIGH according to a beta distribution. A and B should be > 0 and < 1. The smaller the value of A, the greater the probability that a value near LOW will result. The smaller the value of B, the greater the probability that an element near HIGH will result. The type of the output (integer or real) is determined by the type of LOW and HIGH (examples 1-6).
LOW, HIGH, A, and B can vary over time (examples 7-8).
The average value of a beta distribution is a/(a+b) (example 9).
EXAMPLE 1: (for-example (beta-value 60 72 .5 .5))
EXAMPLE 2: (for-example (beta-value 60 72 .1 .1))
EXAMPLE 3: (for-example (beta-value 0.0 100 .2 .2))
EXAMPLE 4: (make-histogram (beta-value 1 100 .5 .5))
EXAMPLE 5: (make-histogram (beta-value 1 100 .2 .2))
EXAMPLE 6: (plot (beta-value 1 100 .2 .2))
EXAMPLE 7: (plot (beta-value (line-segment 100 1 50)
(line-segment 100 10 60) .2 .2))
EXAMPLE 8: (plot
(beta-value 1 100 (line-segment 100 .5 .1) .2))
EXAMPLE 9: (print-result (average (beta-value 0.0 1 .2 .2) 1000))
(block-interval generator interval-or-list &key pitch-class stop previous)
Returns a closure. When applied, a value is returned by applying GENERATOR. The value will not create an interval which is blocked. Blocked intervals are included in INTERVAL-OR-LIST.
To prevent a value from being repeated, block 0 (example 1).
To prevent a value from forming an interval of size 0 or 1 (example 2).
The blocking refers to the numeric interval created by two adjacent values.
The user is responsible for GENERATOR being able to produce a non-blocked interval. If the generator has not been able to do that after STOP number of attempts, the execution will abort and an error message will appear. The default value for STOP is 100 attempts (example 3).
Sometimes the reason that the generator cannot produce an appropriate value is that after the first value is chosen, no allowed intervals are possible. A dummy value for the first previous value can be bound to the keyword PREVIOUS (example 4).
If the values produced by GENERATOR are to be considered pitches and for instance, both unisons and octaves should be blocked, the values produced by generator should be reduced to their pitch-class before the intervals are calculated. Binding the keyword PITCH-CLASS to t will do this (example 5).
EXAMPLE 1: (for-example (block-interval (random-value 1 5) 0))
EXAMPLE 2: (for-example (block-interval (random-value 1 5) '(0 1)))
EXAMPLE 3: (for-example
(block-interval (random-value 1 5)
'(0 1 2 3 4) :stop 500))
EXAMPLE 4: (for-example (block-interval (random-value 1 5)
'(0 1 2 3) :previous 1))
EXAMPLE 5: (for-example
(block-interval
(random-choice '(c3 c#3 d3 d#3 e3 f3 c4 c#4 d4 d#4 f4))
'(0 1) :pitch-class t))
(bpm number)
Converts a NUMBER of beats per minute into a value in milliseconds which is appropriate to use as a clock unit in a section specification (examples 1-2).
EXAMPLE 1: (for-example (bpm 125))
EXAMPLE 2: (fill-template data-section my-secton (bpm 140) 280
1 c2 ff 1 0)
(bundle time message)
Bundle is intended for use with OSC score objects. It contains a time value in seconds for sending the message and a message to be send.
Bundles can be specified in the Include edit item of an OSC Score Object. Bundles can also be specified in a OSC Score Bunch Object (menu item Bunch of Bundles).
The message should be specified using the tool message. The message can contain any number of valid SuperCollider Server commands.
Each bundle can only contain one message.
In both the Include edit item and the OSC score bunch object, one or more bundles can be specified (example 1).
This bundle would send a message at time 0 to allocate buffer space and read a sound file into that buffer.
Example 2 uses this in a OSC score object with synthdef filteredbuf.
It is also possible to test synthdefs by writing a file with SuperCollider Server commands though it is probably more sensible to do this using the SuperCollider language application or a OSC score object.
Example 3 starts synthdef sine1 and assigns values to the dur and freq arguments. The c_set message is the final one to allow the synthdef time to sound.
SuperCollider Server commands can be found in the SuperCollider documentation.
The source for the synthdefs sine1 and filteredbuf can be found in Support/FileExamples/test osc synthdefs.rtf.
EXAMPLE 1: (print-result
(bundle 0 (message "/b_allocRead" 0 "sounds/a11wlk01-44_1.aiff")))
EXAMPLE 2: (fill-template osc-score-object osc2 1 "filteredbuf"
(gather-bundles (bundle 0 (message "/b_allocRead" 0 "sounds/a11wlk01-44_1.aiff")))
nil nil 1 0 "dur" 2 "freq" 500 "amp" 1 "rq" 0.5)
EXAMPLE 3: (fill-template osc-score-bunch bunch2 "(bundle 0 (message \"s_new\" \"sine1\" -1 1 0 \"dur\" 5 \"freq\" 800))
(bundle 6 (message \"c_set\" 0 0))")
(bv low high a b)
BV is a shortcut (abbreviation) for BETA-VALUE (example 1).
See the help for BETA-VALUE for more information.
EXAMPLE 1: (make-histogram (bv 40 80 .2 .2))
(cal object1 operator1 object2 &rest expressions)
Calculates arithmetic expressions using infix notation. Objects may be constants, lists, stockpiles, or generators. Operators are Lisp functions such as + or *. A number or a list of numbers is returned depending on the input (examples 1-5).
CAL returns a list of values if a list or stockpile is used in an expression. Otherwise, a single number is returned.
Several operations can be used. They will be evaluated from left to right, as is the case with Supercollider and unlike the normal custom of mathematics (example 6).
A generator which is similar is ON-THE-FLY. CAL wil produce a fixed number of results. ON-THE-FLY will produce a new result each time it is applied (examples 7).
EXAMPLE 1: (print-result (cal 10 + 2))
EXAMPLE 2: (print-result (cal '(1 2 3) * 10))
EXAMPLE 3: (print-result (cal '(10 20 30) + (rv -1.0 1)))
EXAMPLE 4: (fill-template construct-stockpile
stock (from 1 10))
EXAMPLE 5: (for-example (cal stock + (rv -1.0 1)))
EXAMPLE 6: (print-result (cal 3 + 2 * 2))
EXAMPLE 7: (for-example (on-the-fly '(10 20 30) + (rv -1.0 1)))
capybara/pacarana
A Capybara and a Pacarana are hardware sound computation engines produced by the Symbolic Sound Corporation. They both are rodents.
For more information see example 1.
If a Capybara or Pacarana is available, Midi output can be routed to it via Midi Setup.
EXAMPLE 1: (open-url "http://www.symbolicsound.com")
(cauchy-choice stockpile alpha)
Returns a closure. When applied, a value is chosen from the stockpile according to a Cauchy distribution. STOCKPILE can be a list, stockpile, etc.
Cauchy spreads values symmetrically around a point. In this generator, the Cauchy distribution is used to generate index values to read the stockpile. Values are spread around the index for the middle of the stockpile. ALPHA controls the amount of the spread. Half of the values will be within the interval -ALPHA to +ALPHA (examples 1-3).
EXAMPLE 1: (for-example (cauchy-choice '(a b c d e f g h i j k) 2))
EXAMPLE 2: (for-example (cauchy-choice '(a b c d e f g h i j k) 5))
EXAMPLE 3: (plot (cauchy-choice (from 1 100) 10))
(cauchy-value threshold alpha &optional lower upper)
Returns a closure. When applied, a value reflecting a Cauchy distribution is returned. Cauchy spreads values symmetrically around the threshold value. ALPHA controls the width of the spread. About half of the values are within the interval -ALPHA to +ALPHA (example 1).
There is no limit to the values which are produced. To discard results which are too small or too large, optional values for LOWER and UPPER can be provided. If a value is smaller than LOWER or larger than UPPER, it wll be discarded and the generator will try again to produce a boundary within the specified limits (examples 2-3).
When values for LOWER and UPPER are provided, care should be taken when specifying values. If the generator has trouble finding values in the interval between LOWER and UPPER, an error message will occur.
THRESHOLD, ALPHA, LOWER, and UPPER may vary over time (example 4).
EXAMPLE 1: (plot (cauchy-value 0 10))
EXAMPLE 2: (plot (cauchy-value 0 10 -50 50))
EXAMPLE 3: (plot (cauchy-value 60 5 30 90))
EXAMPLE 4: (plot (cauchy-value (line-segment 100 30 60)
5 20 90))
(cg generator low high)
This generator is a shortcut for CLIP-GENERATOR.
It clips values produced by GENERATOR to be within the limits LOW and HIGH (see example 1).
If LOW is NIL and HIGH is included, the value is allowed if it is < HIGH (example 2).
If HIGH is NIL (or omitted), the value is allowed if it is > LOW (example 3).
See the documentation for CLIP-GENERATOR for more information and examples.
EXAMPLE 1: (for-example (cg (line 20 1 20) 10 15))
EXAMPLE 2: (for-example (cg (line 20 1 20) nil 15))
EXAMPLE 3: (for-example (cg (line 20 1 20) 10))
(change-octave new-octave)
Returns a closure which presumably should be applied to pitch. When applied, the MIDI note number of the pitch is adjusted to reflect the octave specified by NEW-OCTAVE. Octave reflects the current preference for middle C (either c3 or c4). If c4 is the preference, octaves should range from -1 to 9. For c3, use -2 to 8. The preference is specified in the Preferences dialog.
NEW-OCTAVE can change over time and may be a constant, list, generator, etc. (examples 1-2).
EXAMPLE 1: (show-transformation (change-octave 2)
'(60 64 67))
EXAMPLE 2: (show-transformation (change-octave (random-value 0 4))
'(60 64 67))
changing stockpiles in a generator
It is not possible to vary stockpiles over time inside a -choice generator, such as series-choice. To use different stockpiles with a generator, create several generators and select among them with SELECT-GENERATOR. See the help for select-generator for examples.
(changing-weights number value1 weight1 value2 weight2 ...)
Returns a closure. When applied, a value is chosen from a group of possibilities according to a specified weight. The weight reflects the possible frequency of occurance for the corresponding value.
This generator is similar to ratio-choice except that the weights can vary over time. The syntax is also different.
Any of the parameters may be bound to a constant, list, generator, etc. and therefore can vary over time.
NUMBER is the number of values chosen before the next group of weights is used. In example 1, 10 values are chosen using the weight 5 for value 1 and 1 for value 2. After 10 results have been chosen, 10 more are chosen with the weight 5 for 1 and 2 for 2. After 10 results have been chosen, 10 more are chosen with the weight 5 for 1 and 3 for 2. Etc.
When the process has been exhausted, it starts again from the beginning.
NUMBER could change over time by being a list, generator, etc. (example 2).
Values and their weights could also be specified using generators. In example 3, the number of choices before the weights change is determined by a generator: (random-value 5 10). Each time a number if needed, the generator is applied.
The weight for value 1 is determined by a generator: (random-value 1 5). Each time a new weight is needed, the generator is applied. The weight for value 2 is read from a list: '(1 2 3 4 5). Each time a new weight is needed, the next value from the list is read. The last value is determined by a generator: (series-value 3 5). Its weight is a constant: 1. One value is chosen with the generator each time a new stockpile of values is filled according to the weights.
A weight of 0 is allowed. To have a value available at the beginning of the selection process but not at the end, the weight could move to 0 (example 4).
EXAMPLE 1: (for-example
(changing-weights 10
1 5
2 '(1 2 3 4 5))
:number 50)
EXAMPLE 2: (for-example
(changing-weights '(6 7 8 9 10)
1 5
2 '(1 2 3 4 5))
:number 40)
EXAMPLE 3: (for-example
(changing-weights (random-value 5 10)
1 (random-value 1 5)
2 '(1 2 3 4 5)
(series-value 3 5) 1)
:number 40)
EXAMPLE 4: (for-example
(changing-weights 10
60 '(5 4 3 2 1 0)
61 '(5 4 3 2 1 0)
62 '(5 5 5 5 1 1))
:number 60)
(chaotic-notes &key function number x y z rhythm pitch velocity channel plot defaults)
Returns a lists of note objects which have been created by mapping a chaotic function. This list is suitable for use as the notes in a note section.
In example 1, only default values were used. To see a list of the default parameters printed in a window, use example 2.
By default, a henon generator is used. It will produced a two-dimensional series of values.
To plot the results (in two dimensions) bind the keyword :plot to t (example 3).
The chaotic function used to create the notes must have at least 2 dimensions and no more than 3 dimensions. For example, with 2 dimensions, one dimension could be mapped to be pitch and the other could be mapped to be rhythm. X, Y, and possibly Z can be mapped to PITCH, RHYTHM, VELOCITY, or CHANNEL.
By default, X is mapped to pitches between c3 and c6, Y to rhythms between 1.0 and 3, and Z to velocities between 50 and 90. If only a 2-dimensional result is being mapped, then by default, only X and Y will be mapped.
To use a different function, use the keyword FUNCTION (examples 4-5).
The number of notes produced by the chaotic function is controlled with the NUMBER keyword. The default value is 200 (example 6).
With a generator which produces two-dimensional output such as henon and when X is mapped to pitch and Y to rhythm, velocity and channel both need values. They both have defaults values which can be replaced by other constant value, list, or generator (example 7).
In S4, X will be mapped to pitch (default), Y will be mapped to rhythm (default), velocity will be generated with (random-value 40 70).
In example 8, the channels for the notes will be 1 2 3 in succession. (The first note will be in channel 1, the second in channel 2, the third in channel 3, the fourth in channel 1, etc.).
If X should be mapped to pitch, but in the range of c3 to c4 instead of in the default range, see example 9.
To create pitch values that are real numbers, use at least one real number when specifying the range to map the pitches (example 10).
The keywords X, Y, and Z (if a three-dimensional list is produced), should be bound to a form with the parameter, lower boundary, and upper boundary, e.g.
:x (assign-to 'pitch c2 c5).
If X should be mapped to pitch and Y to velocity, rhythm will be assigned the default value (example 11).
Instead of using the default rhythmic value as in the example 11, rhythm will be the result of generator (random-value 1.0 2) in example 12.
With a three-dimensional generator, X, Y, and Z can be mapped. The default is X to pitch, Y to rhythm, and Z to velocity. To map X to rhythm, Y to velocity, and Z to pitch (example 13).
EXAMPLE 1: (fill-template note-section s1 100 200 (chaotic-notes) 0)
EXAMPLE 2: (chaotic-notes :defaults t)
EXAMPLE 3: (chaotic-notes :plot t)
EXAMPLE 4: (chaotic-notes :function (henon 0 0 1.4 0.2 1 :xy t)
:plot t)
EXAMPLE 5: (fill-template note-section s2 100 200
(chaotic-notes
:function (lorenz 0.1 0.1 0.1 10 28 3/8 1 :xyz t)
:plot t)
0)
EXAMPLE 6: (fill-template note-section s3 100 400
(chaotic-notes
:function (henon 0 0 1.4 0.2 1 :xy t)
:number 400)
0)
EXAMPLE 7: (fill-template note-section s4 100 200
(chaotic-notes
:function (henon 0 0 1.4 0.2 1 :xy t)
:velocity (random-value 40 70))
0)
EXAMPLE 8: (fill-template note-section s5 100 200
(chaotic-notes
:function (henon 0 0 1.4 0.2 1 :xy t)
:channel '(1 2 3))
0)
EXAMPLE 9: (fill-template note-section s6 100 200
(chaotic-notes
:x (assign-to 'pitch c3 c4))
0)
EXAMPLE 10: (fill-template note-section s7 100 200
(chaotic-notes
:x (assign-to 'pitch 60.0 72))
0)
EXAMPLE 11: (fill-template note-section s8 100 200
(chaotic-notes
:x (assign-to 'pitch c3 c4)
:y (assign-to 'velocity 50 90))
0)
EXAMPLE 12: (fill-template note-section s9 100 200
(chaotic-notes
:x (assign-to 'pitch c3 c4)
:y (assign-to 'velocity 50 90)
:rhythm (random-value 1.0 2))
0)
EXAMPLE 13: (fill-template note-section s10 100 200
(chaotic-notes
:function (lorenz 0.1 0.1 0.1 10 28 3/8 1 :xyz t)
:plot t
:x (assign-to 'rhythm 1.0 3)
:y (assign-to 'velocity 50 90)
:z (assign-to 'pitch c3 c5))
0)
(choice-generator stockpile generator)
Returns a closure. This is a general means to use a generator to look up values in stockpile. The generator should produce values in the range 0 - 100 % which can be translated to indices for reading in the stockpile (or list). This generator is useful if a choice generator has not been defined for a particular algorithm (example 1).
EXAMPLE 1: (for-example (choice-generator
'(1 2 3 4 5 6 7 8 -8 -5 -3 -2 -1)
(map/time (henon 0 0 1.37 0.3 1)
-1.28 1.27 0.0 100)))
(choose-interpolation chooser thing1 thing2 ...)
Returns a closure. When applied, it chooses between values from two adjoining things. The choice could be between a value from THING1 or THING2, or a value from THING2 or THING3, etc. There can be an indefinite number of things from which to choose.
The choice is made using the value of CHOOSER. If CHOOSER is 1 (or less), a choice will be made from THING1. If CHOOSER is 2, a choice will be made from THING2. If CHOOSER is 1.5, there is a 50-50 chance to choose from THING1 or THING2. If CHOOSER is 1.2, there is a greater chance to choose from THING1 than from THING2.
If three things are specified, a value of 2.5 for CHOOSER would cause a choice between THING2 and THING3 to be made.
CHOOSER can vary over time.
THING1, THING2, etc. can be lists, stockpiles, generators, etc.
This generator is similar to the generator INTERPOLATE. The difference is that INTERPOLATE changes over time based on a shape. CHOOSE-INTERPOLATION could change over time if the value of CHOOSER changed over time.
If a choice is made from values from two lists, the choice is between the first value from THING1 and the first value from THING2. Then the choice is between the second value from THING1 and the second value from THING2. Etc. (examples 1-3).
Lists do not need to have the same length. The generator will loop through them to find the next value (example 4).
The things to be interpolated can be generators (example 5).
If the value for CHOOSER should be derived from a shape or mask, it can be converted using CONVERT (example 6).
EXAMPLE 1: (for-example
(choose-interpolation 1.5 '(a b c) '(1 2 3)))
EXAMPLE 2: (for-example
(choose-interpolation 2.2 '(a b c) '(1 2 3) '(x y z)))
EXAMPLE 3: (for-example
(choose-interpolation
(line-segment 20 1.0 3) '(a b c) '(1 2 3) '(x y z)))
EXAMPLE 4: (for-example
(choose-interpolation 1.5 '(a b c) '(1 2)))
EXAMPLE 5: (for-example
(choose-interpolation
(line-segment 20 1.0 2)
(random-value 20 30)
(random-value 50 60)))
EXAMPLE 6: (for-example
(choose-interpolation
(convert sine-shape 20 1.0 2)
'(a b c) '(1 2 3)))
(chord-multiplication chord1 chord2 &key name)
Returns a closure. When applied, a chord (expressed as a list of Midi notenumbers) is returned. The chord contains for each pitch of CHORD1, a chord based on the interval structure of CHORD2.
Chords are expressed as a list of Midi notenumbers. They could also be derived from a list of chords, a stockpile, a generator, etc.
Example 1 produces a chord based on notenumber 50 using the intervals of CHORD2: 4 and 7. That result is 50 54 57. A chord based on notenumber 52 is also produced. Again the intervals of CHORD2 are used. That result is 52 56 59. The list produced by the generator contains both of these chords.
CHORD1 and CHORD2 may contain any number of pitches (example 2).
Both CHORD1 and CHORD2 may vary over time (examples 3-4).
Keyword NAME controls whether pitches are printed as numbers or as note names. When it is bound to T, note names are printed (example 5).
EXAMPLE 1: (for-example
(make (chord-multiplication '(50 52) '(60 64 67))))
EXAMPLE 2: (for-example
(make (chord-multiplication '(c3 e3 g3) '(c3 d3))))
EXAMPLE 3: (for-example
(chord-multiplication
(make-chord (random-value c2 b2) 3)
'(60 64 67))
:number 5 :number-per-line 1)
EXAMPLE 4: (for-example
(chord-multiplication
'(60 64 67)
(make-chord (random-value c2 b2) 3))
:number 5 :number-per-line 1)
EXAMPLE 5: (for-example
(make (chord-multiplication '(50 52)
'(60 64 67)
:name t)))
(chromatic start)
Returns a closure. When applied, a note number corresponding to the next value in a chromatic scale is generated. The first value in the series is START. The series could continue indefinitely (examples 1-2).
EXAMPLE 1: (for-example (chromatic 60))
EXAMPLE 2: (for-example (chromatic c2) :number 13)
(clean-up-blanks section)
Destructively adjusts a section. Some transformers, in particular remove-successive, may result in section events having no pitch. While this is not a problem in terms of the functioning of the Toolbox, it results in the number of events being higher than the number played, displayed, printed, etc. For this reason, anal retentive users might want to clean out events with no pitch. This tool does that.
Note that the change is irreversible.
Example 1 defines a section.
Transform this section with remove-successive to remove repetitive notes in successive chords (example 2).
Show the text version of the sections ds4 and ds4t. Notice that there is an empty spot for pitch in ds4t (examples 3-4).
Clean-up-blanks removes the event with no pitch from section ds4t (examples 5-6).
EXAMPLE 1: (fill-template data-section ds4 200 4 1
'((60 64 67) (60 64 67) (60 60 65) (60 65 67))
mf 1)
EXAMPLE 2: (fill-template transform ds4t ds4 :pitch (remove-successive))
EXAMPLE 3: (show-text ds4)
EXAMPLE 4: (show-text ds4t)
EXAMPLE 5: (clean-up-blanks ds4t)
EXAMPLE 6: (show-text ds4t)
(clear-preference-file
Clears the current preference file and blocks the AC Toolbox from storing a new one when the application is closed. This allows the AC Toolbox to start with all of the default preferences for window positions, etc. (example 1).
Clearing the preference file only takes effect when the application is restarted. It only effects the next restart. Subsequent restarts will store the preference file and use it on restart.
EXAMPLE 1: (clear-preference-file)
(clip low high)
Returns a closure that can be used as a transformer. If the value to be transformed is lower than LOW, LOW is used. If the value to be transformed is higher than HIGH, HIGH is used. Otherwise no change occurs (example 1).
LOW and HIGH may vary over time using generators, etc.
CLIP should not be confused with CLIP-GENERATOR which is NOT a transformer but functions as a generator.
EXAMPLE 1: (show-transformation (clip 0 10)
'(5 10 15 2 -1 0))
(clip-generator generator &optional low high)
Returns a closure. When applied, the value produced by GENERATOR is clipped to be in the range LOW-HIGH. If the value is < LOW, LOW is returned. If it is > HIGH, HIGH is returned (examples 1-2).
If LOW is NIL and HIGH is included, the value is allowed if it is < HIGH (example 3).
If HIGH is NIL (or omitted), the value is allowed if it is > LOW (example 4).
GENERATOR can be a generator, stockpile, list, etc.
LOW and HIGH can vary over time (example 5).
If LOW > HIGH, the values for LOW and HIGH are switched (example 6).
CLIP-GENERATOR can be abbreviated to CG (example 7).
CLIP-GENERATOR should not be confused with CLIP. CLIP is a transformer and only works with the transform method or with functions such as TRANSFORM/TIME.
EXAMPLE 1: (for-example (1/f-value 20 1 100))
EXAMPLE 2: (for-example
(clip-generator (1/f-value 20 1 100) 50 65))
EXAMPLE 3: (for-example
(clip-generator (line 20 1 50) nil 30))
EXAMPLE 4: (for-example
(clip-generator (line 20 1 50) 20))
EXAMPLE 5: (for-example
(clip-generator (line 20 1 20)
1 (line 20 20 10)))
EXAMPLE 6: (for-example
(clip-generator (line 20 1 20) 15 5))
EXAMPLE 6: (for-example (cg (line 20 1 50) 10 20))
(clock->mm 50)
Converts a clock unit in milliseconds to a metronome indication. This tool can be used to determine an appropriate tempo value when exporting a MIDI file (examples 1-3).
EXAMPLE 1: (print-result (clock->mm 100))
EXAMPLE 2: (print-result (clock->mm 50))
EXAMPLE 3: (print-result (clock->mm 10))
closure
A closure is a type of function. AC Toolbox generators return a closure which is later applied to get a value.
For most purposes, it is not necessary for a user to understand the difference between a closure and a 'regular' function.
(collect-things closure-or-symbol closure-or-symbol ...)
Returns a list of values. If an element is a closure, it is applied to produce a value. If the element is not a closure, it is returned as is (example 1).
This tool can also be used as part of a rule stockpile specification. See the help for REWRITE for additional examples.
EXAMPLE 1: (for-example (collect-things (random-value 1 10)
(random-choice '(a b c d))
(random-choice '(e f g h)) 5))
(combine object1 object2 &key function)
Returns a closure. When applied, one result from object1 is combined with one result from object2 according to FUNCTION. By default, FUNCTION is +. The objects may be constants, lists, stockpiles, or generators as is customary in the AC Toolbox (examples 1-2).
The keyword FUNCTION can be used to provide another way of combining the two objects. The function should be preceded with a function quote: #' (example 3).
To combine more than two objects, use the generator APPLY-FUNCTION. ON-THE-FLY allows the combination of several objects using infix notation.
EXAMPLE 1: (for-example (combine '(1 2 3 4 5 6 7 8 9 10)
(random-value 1.0 2))
:number 10)
EXAMPLE 2: (plot (combine (convert line-shape 100 1 100)
(random-value -5 5.0)))
EXAMPLE 3: (for-example (combine '(1 2 3 4 5 6 7 8 9 10)
'(1 2)
:function #'*))
(combine-all stockpile1 stockpile2 &key function)
Returns a list combining each value from STOCKPILE1 with each value from STOCKPILE2. The combination is done with FUNCTION. By default, function is #'+ (examples 1-3).
STOCKPILE1 and STOCKPILE2 may be lists or stockpiles.
Example 4 using another function for the combination.
EXAMPLE 1: (for-example (combine-all '(1 2 3 4) '(10 20 30)))
EXAMPLE 2: (for-example (combine-all '(f3 f#3 g3 a3) '(0 1 2 4)))
EXAMPLE 3: (for-example (stockpile->notename
(combine-all '(f3 f#3 g3 a3) '(0 1 2 4)))
:number-per-line 4)
EXAMPLE 4: (for-example (combine-all '(1 2 3 4) '(1 2 3)
:function #'*))
(combine-mutation source target index
&key first second
clumping start offset override
low high))
Returns a closure. When applied, one value of a combined mutation is returned.
COMBINE-MUTATION combines two morphological mutations in sequence. These mutation functions are discussed in the help for MUTATE. All parameters, except for FIRST and SECOND, have the same meaning as the parameters with same name in MUTATE.
FIRST designates which mutation function should be applied first. As in MUTATE, these functions have types 1,2,3 or LCM,IUIM, ISIM or CONTOUR, SOME-SOURCE, SOME-TARGET. The default for FIRST is type 1.
SECOND designates which mutation function should be used next. The default value is type 2.
The combination of a type 1 mutation, followed by a type 2 mutation, has the property that the target is reached when the index is 1 (examples 1-4).
Maarten van Walstijn contributed code for this generator.
EXAMPLE 1: (print-result (produce 8
(combine-mutation
'(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0)))
EXAMPLE 2: (print-result (produce 8
(combine-mutation
'(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
.3)))
EXAMPLE 3: (print-result (produce 8
(combine-mutation
'(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
.7)))
EXAMPLE 4: (print-result (produce 8
(combine-mutation
'(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1)))
community
A community is a group of sections, midi objects or other communities joined in name only. A community can provide a mechanism for manipulating objects as a group.
compatibility
Environments that were made in previous (non-Universal) versions of the AC Toolbox can be read with the current version. Environments saved on either a PPC or an Intel machine can be read on the other platform.
Environments saved in the New Format (as specified in the Preferences dialog) cannot be read in older, non-Universal versions. Environments saved in the Old Format will not remember size and position information and can be read in older versions.
(compose function ...)
Returns a lexical closure representing the composition of an unlimited number of functions (example 1). (See Paul Berg, Elements of Design for a discussion of function composition.)
Compose can be used to combine two or more transformers (example 2).
In example 2, the values are first transposed, then the double values are removed.
EXAMPLE 1: (print-result (funcall (compose #'first #'rest) '(1 2 3 4 5)))
EXAMPLE 2: (show-transformation
(compose (remove-doubles) (transpose 12))
'(60 (60 64 60 60)))
(compress factor middle-line)
Returns a closure. FACTOR is expressed as a percentage value, from 0 - 100. MIDDLE-LINE is a number. The value being transformed is compressed toward the middle line by FACTOR. If compressed 100%, the value becomes the value of the MIDDLE-LINE. If compressed 0%, the value does not change (examples 1-4).
FACTOR and MIDDLE-LINE may vary over time.
EXAMPLE 1: (show-transformation (compress 25 50)
'(0 20 40 50 60 75 80 100))
EXAMPLE 2: (show-transformation (compress 100 50)
'(0 20 40 50 60 75 80 100))
EXAMPLE 3: (show-transformation (compress 0 50)
'(0 20 40 50 60 75 80 100))
EXAMPLE 4: (show-transformation (compress 50 50)
'(0 20 40 50 60 75 80 100))
controller
A controller is used to control parameter values on a larger scale. A controller exists outside the boundaries of a section or any other object. See the tutorial for a detailed example of the use of controllers.
controller features
In the 'Show Objects' dialog, when the popup menu for Controllers is chosen, buttons labeled history and reset are available.
History will be produce a window of the recent values produced by this controller. There is a maximum length to this history to prevent memory from being clogged if the controller is used a lot. Once this maximum length has been reached, history is erased and starts again.
Example 1 shows how long history is.
Example 2 changes the length of history.
Reset will remake the controller and erase its history. It will behave as if it was made for the first time.
EXAMPLE 1: (print-result *history-length-limit*)
EXAMPLE 2: (setf *history-length-limit*
(* *history-length-limit* 2))
(controller-filter parameter filter)
Since the filter template has no button for filtering MIDI controller values that may be in a midi-controller-object or a midi-section, a filter definition will have to be produced if you want to filter MIDI controller values.
Choose OTHER as the filter type then use CONTROLLER-FILTER to produce an appropriate filter definition.
PARAMETER can be:
VALUE
NUMBER
CHANNEL
VALUE is the controller value while NUMBER is the controller number such as 7 for volume. CHANNEL is the MIDI channel.
FILTER can be a Lisp expression reflecting the available filter types:
(low-pass threshold)
(high-pass threshold)
(band-pass low high)
(band-reject low high)
(bank low1 high1 low2 high2 ...)
(shot-gun percentage)
If Midi controller object CONT1 exists, it can be filtered with example 1.
Click on SET PARAMETERS to see the filter definition. A low-pass filter for midi-controller values will be produced.
EXAMPLE 1: (fill-template filter cont2 cont1
(other (controller-filter 'value (low-pass 60)))
'whatever nil)
(controller-transform parameter transformer)
This transformer builds another transformer which can be used with the WHATEVER parameter (and only with the WHATEVER parameter) to transform MIDI controller commands. MIDI controller commands are only found in midi-controller-objects or midi-sections.
CONTROLLER-TRANSFORM 'encapsulates' the other transformer and makes it suitable for use with MIDI controller commands.
The available values for PARAMETER are:
value
number
channel
VALUE would build a transformer to transform the controller values.
NUMBER would transform the controller number (such as 7 for volume).
CHANNEL transforms the MIDI channel assignment for the controller commands.
The parameter values should be quoted.
TRANSFORMER can be any available transformer such as TRANSPOSE.
If object midi1 exists, it can be transformed with example 1.
EXAMPLE 1: (fill-template transform midi2 midi1
:whatever (controller-transform 'value (transpose -12)))
(convert object n low high &optional generator interval-or-list pitch-class stop previous)
Returns a list of values.
CONVERT is a mapping function which will map either a shape, a mask, a list, a stockpile, or a generator to be a list with N values within certain limits.
The optional parmeters, e.g. GENERATOR, are only used for mapping masks.
If LOW or HIGH is a real number, the list will contain real numbers. Otherwise, integers are returned.
IF THE OBJECT IS A SHAPE:
A shape will be mapped into a list with N values ranging from LOW to HIGH (example 1).
IF THE OBJECT IS A LIST OR STOCKPILE:
The list (or stockpile values) will be expanded or contracted to produce N values between LOW and HIGH (example 2).
IF THE OBJECT IS A GENERATOR (FUNCTION):
The closure will be applied N times and the results will be scaled to be between LOW and HIGH and returned as a list (example 3).
IF THE OBJECT IS A MASK:
Returns a list of values between LOW and HIGH. The type of LOW and HIGH determine the type of the result.
The mask is divided into N segments. Each time a new value is needed, the appropriate boundaries are determined. A generator is applied to determine a value between the boundaries.
By default, the generator used for determining a value between the boundaries is RANDOM-VALUE. Other generators could be used. They should produce a percentage value between 0 and 100.
Define a mask named MASK1. This can be done either by drawing, specifying, or generating a mask using the corresponding menu item or by evaluating example 4 (example 5).
Examples 6-7 produce 50 values between 40 and 80 using mask1.
Examples 8-9 use a different generator to produce the values with a mask.
GENERATOR could also be a list of values. CONVERT will loop through the values. The values should be percentages (example 10).
Note that the generator should produce values between 0 and 100 (percent). In the case of the beta-value generator, values will tend to concentrate near the lower and upper mask limits.
The other options for converting a mask relate to the possibility of blocking certain intervals from following each other. INTERVAL-OR-LIST can a single value or a list of values to be blocked (i.e. the next value chosen should not form that interval with the previous value).
To prevent the repetition of the same value, block 0 (example 11).
Note that a value for the optional parameter GENERATOR needs to be entered if any of the other optional parameters are to be used. T will signify that the default generator, (random-value 0.0 100) should be used. Instead of T, another generator could be specified.
To prevent the repetition of the same value or one which is one step higher or lower (example 12).
If the values produced are to be considered pitches and both unisons and octaves should be blocked, the values should be reduced to their pitch-class before being compared. Binding the optional parameter PITCH-CLASS to T will do this (example 13).
The user is responsible for CONVERT being able to produce a non-blocked interval. If CONVERT has not been able to do that after STOP number of attempts, the execution will abort and an error message will appear. The default value for STOP is 100 attempts. The value for this parameter could be increased. Sometimes the shape of a mask may be so narrow at a particular point that an unblocked interval is seldom possible. In that case, the user can either try again until an entire list is produced, or not block any intervals, or change the mask.
Sometimes the reason that CONVERT cannot produce an appropriate value is that after the first value is chosen, no allowed intervals are possible. A dummy value for the first previous value can be bound to the optional parameter PREVIOUS.
The help for the generator BLOCK-INTERVAL can be consulted for more examples of the use of these parameters when blocking intervals.
Another tool available for mapping a shape, etc. is ANCHOR. With it, the first and last value can be specified.
A generator for converting a shape, etc. is SPRAY. An object is converted and a random deviation is added.
Another generator for converting a shape, mask, etc. is CONVERT/TIME. It works similarly to CONVERT but it does not return a list. Instead, one value is returned each time the generator is applied. This uses less memory than CONVERT.
A mask can be converted using 2-MASKS. With this tool, one mask is used to generate values while another mask is used to block values from a portion of the mask.
EXAMPLE 1: (for-example (convert sine-shape 100 40 80))
EXAMPLE 2: (for-example (convert '(0 100 50) 50 10 20))
EXAMPLE 3: (for-example (convert (random-value 1 100) 50 40 60))
EXAMPLE 4: (fill-template specify-mask mask1 '(20 100) '(1 80))
EXAMPLE 5: (plot mask1)
EXAMPLE 6: (for-example (convert mask1 50 40 80))
EXAMPLE 7: (plot (convert mask1 50 40 80))
EXAMPLE 8: (for-example
(convert mask1 50 40 80
(beta-value 0.0 100.0 .2 .2)))
EXAMPLE 9: (plot
(convert mask1 50 40 80
(beta-value 0.0 100.0 .2 .2)))
EXAMPLE 10:(plot
(convert mask1 50 40 80
'(0 20 40 60 80 100)))
EXAMPLE 11: (for-example (convert mask1 50 40 80 t 0))
EXAMPLE 12: (for-example (convert mask1 50 40 80 t '(0 1)))
EXAMPLE 13: (for-example (convert mask1 50 40 80 t 0 t))
(convert-stockpile stockpile low high &key chord)
Returns a list made by mapping STOCKPILE to the range LOW to HIGH. STOCKPILE may be a list or stockpile (example 1).
If either LOW or HIGH is a real number, the output is a real number (example 2).
This tool differs from CONVERT in that there is no number parameter. In CONVERT the number of values in the resulting list can vary. In CONVERT-STOCKPILE, the output list always has the same number of elements as the input stockpile.
If the stockpile contains lists, e.g. chords, each value in the chord is converted (example 3).
If the stockpile contains lists representing the result of a multi-dimensional function, such as lists with the XY values of a chaotic function, it is possible to convert the X and Y values separately. In this case, a list with the low values for each parameter should be used as well as a list with high values for each parameter. The keyword CHORD should be bound to nil to do this. Note that all elements of stockpile should have the same length.
In examples 4-5, X values are mapped to the range 60-80. Y values are mapped between 20-30.
EXAMPLE 1: (for-example (convert-stockpile '(1 2 3 4 5) 10 100))
EXAMPLE 2: (for-example (convert-stockpile '(1 2 3 4 5) 10.0 100))
EXAMPLE 3: (for-example
(convert-stockpile '((60 62) (60 64 67) (69 72 76))
30 40))
EXAMPLE 4: (fill-template generate-stockpile stockpile1 20
(henon 0.0 0.0 1.4 .3 1 :xy 1))
EXAMPLE 5: (for-example (convert-stockpile stockpile1
'(60 20) '(80 30) :chord nil))
(convert-to-lookup-table object low-key high-key low-value high-value)
Intended to make a lookup table to use with generator LOOKUP.
A lookup table contains pairs of keys and values. LOOKUP looks up a key in the table and the value is returned.
CONVERT-TO-LOOKUP-TABLE makes a lookup table by converting an object such as a shape into the values for the table. The object is mapped to be between LOW-VALUE and HIGH-VALUE.
The table contains entries for keys ranging from LOW-KEY to HIGH-KEY. Each of these keys is associated with a value mapped from the OBJECT.
E.g. (convert-to-lookup-table line-shape 1 10 40 80)
would produce a lookup table with the following pairs of keys and values:
KEY VALUE
1 40
2 44
3 49
4 53
5 58
6 62
7 67
8 71
9 76
10 80
To use the lookup table, you could construct a stockpile, and then use the table with the generator LOOKUP (examples 1-2).
In addition to converting shapes, anything else which can be converted with the tool CONVERT, such as masks, functions, and lists, can also be used as the object in CONVERT-TO-LOOKUP-TABLE (examples 3-4).
For help on the way that CONVERT deals with masks or lists, see CONVERT. For a different method of constructing a lookup table, see MAKE-LOOKUP-TABLE.
EXAMPLE 1: (fill-template construct-stockpile table
(convert-to-lookup-table sine-shape
1 10 40 80))
EXAMPLE 2: (for-example (lookup '(1 2 3 4 5 6 7 8 9 10) table)
:number 10)
EXAMPLE 3: (fill-template construct-stockpile table2
(convert-to-lookup-table
(henon 0.0 0.0 1.4 .3 1)
1 10 40 80))
EXAMPLE 4: (for-example (lookup '(1 2 3 4 5 6 7 8 9 10)
table2)
:number 10)
(convert/time object n low high
&optional generator interval-or-list pitch-class stop previous)
Returns a closure. When applied, one value is returned which has been mapped from an object, such as a shape, mask, list or stockpile. It does not map generators.
This generator is similar to the tool CONVERT which will map an object into a list with N values within certain limits.
CONVERT/TIME does NOT return a list. Instead, each time the closure is applied, the next value is returned. For this reason, it makes more efficient use of memory than CONVERT. This can be important if an object is to be converted into a large number of values (e.g. tens of thousands of values which might happen when generating granular score data for Csound or when controlling an external device using streams.) The increase in efficiency primarily occurs with masks.
If LOW or HIGH is a real number, the result will be a real number. Otherwise, integers are returned.
LOW and HIGH can vary over time. For shapes, this has no effect on the amount of memory used. For masks, changing these parameters over time severely limits efficiency though it is still more effecient than using CONVERT.
IF THE OBJECT IS A SHAPE:
A shape will be mapped so that N applications of this generator will return N values ranging from LOW to HIGH (example 1).
The optional generator is not used to map a shape.
IF THE OBJECT IS A LIST OR STOCKPILE:
The list (or stockpile values) will be expanded or contracted so that N applications of this generator will produce N values between LOW and HIGH (example 2).
The optional generator is not used to map a list or stockpile.
IF THE OBJECT IS A MASK:
N applications of the generator produce N values between LOW and HIGH. The type of LOW and HIGH determine the type of the result.
The mask is divided into N segments. Each time a new value is needed, the appropriate boundaries are determined. A generator is applied to determine a value between the boundaries.
The mask in examples 3-4 can be used to produce values between 40 and 80 (example 5).
By default, the generator used for determining a value between the boundaries is RANDOM-VALUE. Other generators could be used. They should produce a percentage value between 0 and 100 (example 6).
GENERATOR could also be a list of values between 0 and 100 percent. In that case, CONVERT will loop through the values (example 7).
The remaining parameters for CONVERT/TIME (INTERVAL-OR-LIST, PITCH-CLASS STOP, and PREVIOUS) only work with masks. The usage is identical with their use in CONVERT. See the help for CONVERT for an extended description of these parameters.
CONVERT/TIME is primarily useful when dealing with masks. The gain in speed and memory efficiency is dramatic compared to CONVERT. This gain is achieved when LOW and HIGH do not change over time. If either or both of these parameters change over time, the efficiency gains are much less.
With shapes, speed decreases though there is some gain in reduced memory allocation. For shapes, the primary benefit is that LOW and HIGH can vary over time.
EXAMPLE 1: (for-example (convert/time line-shape 20 40 80))
EXAMPLE 2: (for-example (convert/time '(0 100 50) 20 10 20))
EXAMPLE 3: (fill-template specify-mask mask1 '(20 100) '(1 80))
EXAMPLE 4: (plot mask1)
EXAMPLE 5: (plot (convert/time mask1 100 40 80))
EXAMPLE 6: (plot
(convert/time mask1 100 40 80
(beta-value 0.0 100 .2 .2)))
EXAMPLE 7: (plot
(convert/time mask1 100 40 80
'(0 20 40 60 80 100)))
(create type number generator)
Creates an object of the desired type (if a method has been defined for that type) containing the results of NUMBER of applications of the GENERATOR.
Methods for lists (example 1) and vectors (example 2) exist in any case.
EXAMPLE 1: (print-result (create 'list 10 (random-value 1 10)))
EXAMPLE 2: (print-result (create 'vector 10 (random-value 1 10)))
(create-sequence n generator)
Creates an object of the type SOME-SEQUENCE which is suitable for use as input to a STRUCTURED SECTION, a NOTE SECTION, or a NOTE STRUCTURE. The sequence contains N objects which were created or chosen by applications of GENERATOR. This is equivalent to doing
(in-sequence object1 object2 ... objectN)
Assuming section S1 exists, a section containing a sequence with 5 random choices from section S1 can be made (example 1).
EXAMPLE 1: (define s3
(make-structured-section
100
(create-sequence 5 (random-choice s1))))
(create-text-file header-string
foot-string
number
&rest to-generate-parameters)
Produces a text file as output. This tool is useful to use the facilities provided in the AC Toolbox (such as generators) to produce a text file which might be used as input for another program, e.g. a Max coll object.
The HEADER-STRING is printed at the beginning of the file. Then a NUMBER of lines in the text file contain the results of using all of the parameters which are gathered into TO-GENERATE-PARAMETERS. These parameters can be symbols, numbers, lists, stockpiles, or generators. The values will be produced in the customary AC Toolbox manner, i.e. with the generator DO-THE-NEXT-THING.
NUMBER is the number of lines in the file. Each line contains the result of using all of the parameters which are gathered in TO-GENERATE- PARAMETERS.
The FOOT-STRING is printed at the end of the file (example 1).
Commas can be written to a file by specifying character #\,. Semicolons are #\;.
To write a text file in a format usable in a Max Coll object see example 2.
CREATE-TEXT-WINDOW can be used to write to a window instead of a file.
EXAMPLE 1: (create-text-file "Data for some program"
"; end of data"
20 (from 1 20) (random-value 1 100) (random-value 50.0 70))
EXAMPLE 2: (create-text-file "" "" 20 (from 1 20)
#\, (random-value 1 100) (random-value 50 70)#\;)
(create-text-window header-string
foot-string
number
&rest to-generate-parameters)
Prints the values produced by several generators, etc. to a window. Each line will contain results from all of the specified generators. This tool may be a convenient way to produce sets of data for perusal.
The HEADER-STRING is printed at the beginning of the window.
NUMBER is the number of lines to be printed to the window.
Each line contains the result of using all of the parameters which are gathered in TO-GENERATE- PARAMETERS. These parameters can be symbols, numbers, lists, stockpiles, or generators. The values will be produced in the customary AC Toolbox manner.
The FOOT-STRING is printed at the end of the window.
This tool is similar to CREATE-TEXT-FILE except that the information is printed to a window instead of a file (example 1).
EXAMPLE 1: (create-text-window "Some Data"
"" 10 (random-choice '(a b c d))
(random-value 1 100) '(500 1000)
20 (random-value 1 5))
csound
A widely-available software synthesis program originally designed by Barry Vercoe. More information can be found at the url in example 1.
The AC Toolbox works with Csound5. See the installation instructions for details.
EXAMPLE 1: (open-url "http://www.csounds.com")
csound files: filtering
Csound csd files can be filtered using the dialog produced by Methods>Filter>Csound File. The result of the filtering operation is a new file. The original file is not changed.
Select a Csound file by clicking on the 'Select' button.
It is possible to filter up to four parameters in the file using this dialog. If a parameter is to be filtered, select the parameter number. Select a filter type for that parameter using the corresponding popup menu. Parameters, such as a threshold value for a low-pass filter must be specified. To do this, click the button 'Set Parameters' and fill in the appropriate value(s).
If the filter type is 'None', the corresponding parameter will not be filtered.
When a file is filtered, only note statements are examined. Function statements, etc. are ignored. When filtering a file, if a line of note information is allowed to pass, it is copied to a new file. If the line is filtered away, it is not copied.
If more than one filter have been specified, a choice must be made on how to combine the results of the filters to determine if a line should be copied or not. If 'Or' is selected, a line is copied if one ore more of the filters would allow it to be copied. If 'And' is selected, it is copied only if all of the filters would allow it to be copied.
For example, imagine two filters have been specified for P5: a low-pass filter with a threshold of 200 and a high-pass filter with a threshold of 1000. Combining the filters with 'Or' would result in a file containing only those lines with P5 values <= 200 or with P5 values >= 1000. If those filters were combined with 'And', the resulting file would have no note statements, since it is not possible for P5 to be both <= 200 and >= 1000.
Combining filters with 'And' can be useful when filtering different parameters, e.g. when selecting only those lines where P3 is below a certain value and P5 is above another value.
An example of writing a Lisp expression to use for a filter of type 'Other' is given in Help>Lisp>Your Own.
The filtered file is rendered or not according to the various choices made in the Csound File Options dialog. Note that the orchestra is not replaced when a file is filtered. The rendering options are changed to what is current in the Csound File Options dialog.
csound files: transforming
Csound csd files can be transformed using the dialog produced by Methods>Transform>Csound File. The result of the transformation is a new file. The original file is not changed.
Select a Csound file by clicking on the 'Select' button.
It is possible to transform up to four parameters in the file using this dialog. If a parameter is to be transformed, sett the parameter number. In the corresponding dialog box, fill in a transformer expression such as (transpose 500) which would add 500 to the value of the corresponding P parameter. Available transformers can be found in the Annotated Index (Help>Annotated Index).
A transformer is applied to the specified parameter of every note statement in the Csound score file. Function statements, etc. are not changed.
The transformed file is rendered or not according to the various choices made in the Csound File Options dialog. Note that the orchestra is not replaced when a file is transformed. The rendering options are changed to what is current in the Csound File Options dialog.
csound object
A Csound object contains the specification to generate a Csound score file.
(csound-frame-size frequency &optional sr)
Calculates the minimum frame size to capture a specified frequency in a phase vocoder analysis (pvanal) for Csound.
The result of evaluating this tool in the For Example dialog, a Listener, or an edit window can be used to select the frame size for pvanal in the Csound Analysis dialog.
FREQUENCY is the desired frequency. SR is the sample rate which defaults to 44100 (examples 1-2).
EXAMPLE : (print-result (csound-frame-size 50))
EXAMPLE : (print-result (csound-frame-size 50 96000))
(csound-table-size seconds &optional sr)
Returns the table size in samples which is appropriate for use with the Csound gen1 statement. This tool can be evaluated in the For Example dialog, a Listener, or an edit window. It should not be directly used in the definition of a Csound score. The outcome of using this function should be entered.
SECONDS is the desired duration of the table. SR is the sample rate which defaults to 44100.
Csound expects the table size for gen 1 to be a power of 2 or a power of 2 plus one. This tool returns a power of 2.
Example 1 calculates the number of samples needed for 10 seconds.
Example 2 calculates for 10 seconds with a sample rate of 96000.
The resulting value could be used in a header such as this:
f1 0 524288 -1 42 0 0 1
EXAMPLE 1: (print-result (csound-table-size 10))
EXAMPLE 2: (print-result (csound-table-size 10 96000))
csound: parallel objects
Csound score objects can be combined in parallel in 2 ways. The groups of objects can be specified by name or the group can be generated using a generator etc. to determine the order of the available scores. In both cases, each time another score object is applied, it is generated anew.
To specify a group of score objects to be joined in parallel, use the 'Parallel Scores' menu item. In the space for score objects, the names of score objects can be entered.
Scores used in a parallel score should have been specified or applied before using them in a definition.
For the examples in this help, the instruments defined in test csound.orc will be used (examples 1-3)
As many objects as desired can be entered. The objects can be Csound score objects, sequential score objects, or parallel score objects.
The start of an object can be delayed by a time specified as a number (in seconds). If no offset is desired, no number need be entered. The time offset is not the time between objects (as is the case with a sequential score) but the time since the beginning of the parallel score object (example 4).
In example 4, score1 and score2 will start at the same time. The second instance of score1 will start 3 seconds later. Note that the two applications of score1 may result in different score files (depending on the way that score1 was specified). If score1 contains generators with random aspects, the files will probably be different.
To generate a group of score objects to occur in parallel, use the menu item 'Generate Parallel Scores'.The number of scores to be generated, something to produce an offset value (from the beginning of the parallel object), and a generator etc. to choose the group of scores should be entered (example 5).
The offset value can be a constant, list, generator, etc. If the offset is 0, all scores will start at the same time. In any case, the first score always starts at time 0. The offset is applied to the start time of the remaining scores.
If the total amplitude of the result of a parallel section is too large, the amplitude values in the score text can be transformed with the transform method for Csound files. If the transformer (stretch .7) is applied to P4 (if that is the amplitude parameter), the P4 parameter of the selected score file will be rescaled. See the help for 'Csound Files: Transforming' for more information on transforming Csound files.
The scores can be chosen with a generator as in example 5. A list could be given in which case the scores occur in the same order as they occur in the list (example 6).
The name of a single score could be used (example 7).
Note that F statements in the score object headers are not changed by a parallel combination. It is the responsibility of the user to ensure that function definitions are appropriate.
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 100 1
(random-value 0.0 10)
(rv .1 .2)
(rv 5000.0 10000)
(rv 1000.0 1500))
EXAMPLE 2: (fill-template csound-score-object score2
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 3 100 1 0
(random-value 0.1 0.2)
(scale-by-layers 20000)
(walk 440.0 (random-value -20.0 20) 100 1000))
EXAMPLE 3: (fill-template parallel-score-object parallel-score1
score1 score2)
EXAMPLE 4: (fill-template parallel-score-object parallel-score2
score1 score2 3 score1)
EXAMPLE 5: (fill-template generate-parallel-score-object
generate-parallel-score1 5
(random-value 0.0 2)
(random-choice '(score1 score2)))
EXAMPLE 6: (fill-template generate-parallel-score-object
generate-parallel-score2 5
(random-value 0.0 2)
'(score1 score2))
EXAMPLE 7: (fill-template generate-parallel-score-object
generate-parallel-score3 5
(random-value 0.0 5)
score1)
csound: score objects
A Csound score object can be used to specify an algorithm to generate a Csound score file. When an object is specified, the algorithm is saved but no file is generated. When an object is applied, the specification is saved and a file for Csound is generated.
When a Csound score object is written to a file, the result wil be in the unified file format (extension .csd) which contains both orchestra and score data as well as some options.
Csound score objects can be joined in sequence or in parallel which means that when applied, several scores will be generated as part of one score.
Sequential Csound objects are described in the help for Csound: Sequential Objects.
Parallel Csound objects are described in the help for Csound: Parallel Objects.
The remainder of this document describes the use of the dialog box for a Csound score object.
Header
The header is printed at the beginning of the file. Typically this would contain function statements, etc.
Layers
In the score file, one or more layers can be produced. Layers are parallel combinations of outputs. The parameter LAYERS may be a constant, list, generator, etc.
Number
Number is the number of events in a layer. It may be a constant, list, generator, etc.
Instrument, Start, Duration
Instruments should be referred to by a number, such as 1. Each line will use the next value from instrument.
If start is a constant number, the first start-time in the score will be this value. Subsequent values for the start-time of events will be the previous value plus the previous duration. If start is a generator, list, etc., the values for all of the actual start-times will be produced with it.
Duration is the length of an event. Negative values will cause a rest. The remaining parameter values for that line of the score file will be lost. By default, one beat is one second.
The instrument, start, and duration parameters may be a constant, list, generator, etc. Each score object must have values for these three parameters.
Example
The examples in this help text will use the instrument definitions of 'test csound.orc' found in 'Support/FileExamples'. In the Csound File Options dialog, select this file as the orchestra. Also select a sound directory (for writing the output files) and a sample directory (to read sample files if requested).
In example 1, a score object was made with only three parameters specified: instrument, start-time, and duration, (p1 - p3). When the specify button is used, the information in this dialog is saved as an object. When the apply button is used, the information is saved and a Csound score file with ten score lines is produced. There is 1 layer.
Each line of the score file may contain additional parameters. For each desired parameter, include a constant, list, generator, etc. to produce the next value.
If score1 is rendered, no sound is produced since no frequency, duration, or waveform information was provided.
Header
In example 2, the header specifies function generation methods. Function 1 will be one period of a sine wave and is used by instrument 1 as the waveform for an oscillator. Function 2 produces a Hanning window which is used as the envelope in instrument 1. Ten score lines will be produced. The score starts at time 0. Each duration is 1.
In instrument 1 (in test csound.orc), P4 is the parameter for amplitude, P5 for frequency. In score2, each p4 is 32000. Amplitude values for instrument 1 can vary between 0 and 32767. P5 contains random values between 220 and 880.
Rests
Negative durations produce rests. The values produced for the other parameters are lost (if there is a rest). This produces 'gaps' in the score file as if holes had been shot in it. The file will only contain the score lines which are not rests (example 3).
Until-Time
UNTIL-TIME can be used to determine the number of values to be calculated. UNTIL-TIME indicates that events should be generated until a certain length of time in seconds has been reached. It can only be used if START is a constant value.
When the score file in example 4 is made, events will be generated until 10 seconds have been filled. The last event is not truncated to fit within the 10 seconds but is allowed its full duration. This could mean that the total length of the score is longer than 10 seconds.
The use of UNTIL-TIME assumes that duration is expressed in seconds and that no additional Csound tempo indications will be used.
In example 4, FROM-NUMBER was used to convert line-shape for P4. (from-number) returns the number of events calculated to fill 10 seconds.
Using a Generator for Start
Example 5 uses a generator for start.
The start-times of the events are randomly chosen between 0.0 and 10 beats. Note that the events are no longer generated in chronological order. If the other parameters are in random order, this does not really matter. See the section below on shapes and masks for an example of how to generate start-times when the order matters.
Using a Shape to Determine the Density
DENSITY-OF-START-TIMES makes a list of start times by mapping a shape to represent varying density between a minimum and maximum density.
In example 6, LINE-SHAPE represents a linearly increasing density that is mapped between 1 event per second to 30 events per second in the course of 10 seconds.
The NUMBER parameter is related to the number of events generated by the DENSITY-OF-START-TIMES expression by using (from-start-times) as input.
Several Layers
For each layer, generators are made again. This means that they forget their history and start at the beginning (though not necessarily with the same results). In this example, P5 (frequency) uses the WALK generator. The walk for each layer will start at 440. The amplitude parameter P4 uses SCALE-BY-LAYERS. This scales the value produced by the number of layers specified (example 7).
Shapes or Masks
If one of the parameters is to be derived from a shape or a mask, it is important that the start-times be in ascending order. If a constant value is used for start-time, then there is no problem. If a generator is used for start-time, it is possible that the order of the shape or mask is destroyed after Csound sorts the start-times. To prevent this, you should sort the start-times using the tool MAKE&SORT.
Ten values made by the generator RANDOM-VALUE are sorted and returned in a list in examples 8-9.
Extra
The dialog for extra may contain generators, etc. for additional parameters, starting with p11. Data for an unlimited number of parameters can be included in this dialog (example 10).
Note that this score object cannot be rendered with the example orchestras since none of them uses 11 parameters.
Per Layer
This box can be used to indicate which (if any) objects that have already been defined should be remade before each layer is calculated. When an object is remade, the input specification is used to make a new output which replaces the previous output of that object.
For example, the mask (examples 11-12) could be converted to produce frequency values (P5) in example 13.
In example 13, all layers used the same mask.
If the mask is remade for each layer, the values for P5 will be defined per layer (example 14).
This example produces 3 layers. MASK1 is remade for each layer so that P5 has different values in each layer.
Several objects can be remade per layer. Even if only 1 layer is specified, the objects are remade before the first layer is calculated.
Per Score
This box can be used to indicate which (if any) objects that have already been defined should be remade before each score object is calculated. When an object is remade, the input specification is used to make a new output which replaces the previous output of that object.
When an object is remade per score, this would allow all layers to use the same object but each time the score is applied, a new object would be made for use in all layers (example 15).
Remaking objects per score is useful if sequential or parallel scores are made. If, for example, a sequential score is generated, the input specification of an existing score is used to generated several scores which are joined in sequence. Each time a new object would be generated per score. All layers within one score would share the same mask. Each new score in the sequence would use a new mask (example 16).
Soundfile Names
Csound unit generators such as soundin require either the number of a soundfile (e.g. 20 for file soundin.20) or a name enclosed in double quotes (a string). A string in the AC Toolbox Csound score dialog will be inaccurately represented in the score except if the tool SF-NAME or the generator GENERATE-SF-NAME is used.
This example uses instrument 3 in test csound.orc. It reads a fragment from a sample file and multiplies it with an amplitude envelope. The sample file should be in available in the sample file directory which is chosen in the Csound File Options dialog (example 17).
If a choice is to be made between several names, GENERATE-SF-NAME could be used. Note that the sample files should be available in the sample file directory (example 18).
See the help for GENERATE-SF-NAME for an example of relating soundfile names to different durations.
Overlapping Start Times
The generator OVERLAP can be used to guarantee that start times for adjacent events will overlap. The amount of overlap can be a time value in seconds (example 19).
The amount can also be expressed as a percentage of the previous duration (example 20).
Note the use of FROM-OVERLAP for the duration parameter when the generator OVERLAP is used.
Miscellaneous
Files created from a Csound score object can be plotted using the dialog produced by the menu item 'Tools>Plot >Csound File'.
A histogram of a Csound score object can be made using the dialog produced by the menu item 'Tools>Histogram>Csound File'.
Files created from a Csound score object can be filtered or transformed using items in the Methods menu. These processes are described in the help item for 'Csound Files: Filtering' and 'Csound Files: Transforming'
The tools FROM-NUMBER,FROM-LAYERS, SCALE-BY-LAYERS may be useful when specifying Csound score objects. See their respective help texts for a description.
The generator PAR allows a Csound score object to read the values of other parameter fields when the object is applied. The help text contains examples.
EXAMPLE 1: (fill-template csound-score-object score1
"" nil nil 1 10 1 0
(random-value 0.1 1))
EXAMPLE 2: (fill-template csound-score-object score2
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1
0 1 32000 (random-value 220 880))
EXAMPLE 3: (fill-template csound-score-object score3
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1 0
(random-choice '(-1 1)) 32000
(walk 220 100))
EXAMPLE 4: (fill-template csound-score-object score4
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1
(until-time 10) 1 0
(random-value .5 1)
(convert line-shape
(from-number) 1000 32000)
(random-value 220 880))
EXAMPLE 5: (fill-template csound-score-object score5
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 100 1
(random-value 0.0 10)
(rv .1 .2)
(rv 5000.0 10000)
(rv 1000.0 1500))
EXAMPLE 6: (fill-template csound-score-object score6
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1
(from-start-times) 1
(density-of-start-times
10
line-shape 1 30)
(random-value 0.1 .2)
(convert line-shape
(from-number) 1000 5000)
(random-value 1000.0 1500))
EXAMPLE 7: (fill-template csound-score-object score7
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 3 100 1 0
(random-value 0.1 0.2)
(scale-by-layers 20000)
(walk 440.0 (random-value -20.0 20) 100 1000))
EXAMPLE 8: (for-example
(make&sort 10 (random-value 0.0 10)))
EXAMPLE 9: (fill-template csound-score-object score8
"f1 0 8192 10 1
f2 0 8192 20 2 1" nil nil 1 20 1
(make&sort 20 (random-value 0.0 10))
(random-value 0.1 0.2) 10000
(convert line-shape 20 200.0 500))
EXAMPLE 10: (fill-template csound-score-object score9
"" nil nil 1 10 1 0 2 1
(random-value 220 880)
.1 .2 .3 (random-value 1.0 2)
5 6 3 2 (random-value 1.0 10) 4)
EXAMPLE 11: (fill-template generate-mask
mask1 4 (rv 1 100)
(rv 1 100))
EXAMPLE 12: (plot mask1)
EXAMPLE 13: (fill-template csound-score-object score10
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 3 100 1 0
(random-value 0.05 0.1)
(scale-by-layers 10000)
(convert mask1 (from-number) 600.0 1000.0))
EXAMPLE 14: (fill-template csound-score-object score10b
"f1 0 8192 10 1
f2 0 8192 20 2 1" '(mask1) nil 3 100 1 0
(random-value 0.05 0.1)
(scale-by-layers 10000)
(convert mask1 (from-number) 600.0 1000.0))
EXAMPLE 15: (fill-template csound-score-object score11
"f1 0 8192 10 1
f2 0 8192 20 2 1" nil '(mask1) 3 100 1 0
(random-value 0.05 0.1)
(scale-by-layers 10000)
(convert mask1 (from-number) 600.0 1000.0))
EXAMPLE 16: (fill-template generate-sequential-score-object
score12 4 (rv 0.5 1.5) score11)
EXAMPLE 17: (fill-template csound-score-object score13
"" nil nil 1 30 3 0
(random-value 0.1 0.2)
(sf-name "roscoe.aiff")
(rv 0.0 5) 1 0.01 0.01)
EXAMPLE 18: (fill-template csound-score-object score14
"" nil nil 1 30 3 0
(random-value .1 .2)
(generate-sf-name
(random-choice '("roscoe.aiff" "partch")))
0 1 .01 .01)
EXAMPLE 19: (fill-template csound-score-object score15
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 100 1
(overlap 0
(random-value 0.05 0.1)
0.01)
(from-overlap) 10000
(random-value 100.0 1000))
EXAMPLE 20: (fill-template csound-score-object score16
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 100 1
(overlap 0
(random-value 0.05 0.1)
50 :percent t)
(from-overlap) 10000
(random-value 100.0 1000))
csound: sequential objects
Csound score objects can be combined in sequence in 2 ways. The sequence of objects can be specified by name or the sequence can be generated using a generator etc. which will choose from among available scores. In both cases, each time another score object is applied, it is generated anew.
To specify a sequence of score objects, use the 'Sequential Scores' menu item. In the space for score objects, the names of score objects can be entered.
Scores used in as sequential score should have been specified or applied before using them in a definition.
For the examples in this help, the instruments defined in test csound.orc will be used (examples 1-3).
As many objects as desired can be entered. The objects can be csound score objects, sequential score objects, or parallel score objects.
A time delay between objects can be specified as a number (in seconds). If no delay is desired, no number need be entered.
In the example 4, a gap of 3 seconds will occur between the end of score2 and the beginning of score1. Note that the two applications of score1 may result in different score files (depending on the way that score1 was specified). If score1 contains generators with random aspects, the files will probably be different.
To generate a sequence of score objects, use the menu item 'Generate Sequential Scores'.
The number of scores to be generated, something to produce an offset value (between the scores), and a generator etc. to choose the sequence of scores should be entered (example 5).
The offset value can be a constant, list, generator, etc. If the offset is 0, there will be no time gap between the end of one score and the beginning of another. The first score always starts at time 0.
The scores can be chosen with a generator as in example 5. A list could be given in which case the scores occur in the same order as they occur in the list (example 6).
The name of a single score could be used (example 7).
Note that the calculation in any F statements in the header is not changed by a sequential combination. It is the responsibility of the user to ensure that function definitions are appropriate.
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 100 1
(random-value 0.0 10)
(rv .1 .2)
(rv 5000.0 10000)
(rv 1000.0 1500))
EXAMPLE 2: (fill-template csound-score-object score2
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 3 100 1 0
(random-value 0.1 0.2)
(scale-by-layers 20000)
(walk 440.0 (random-value -20.0 20) 100 1000))
EXAMPLE 3: (fill-template sequential-score-object sequential-score1
score1 score2)
EXAMPLE 4: (fill-template sequential-score-object sequential-score2
score1 score2 3 score1)
EXAMPLE 5: (fill-template generate-sequential-score-object
generate-sequential-score1 5
(random-value 0.0 2)
(random-choice '(score1 score2)))
EXAMPLE 6: (fill-template generate-sequential-score-object
generate-sequential-score2 5
(random-value 0.0 2)
'(score1 score2))
EXAMPLE 7: (fill-template generate-sequential-score-object
generate-sequential-score3 5
(random-value 1.0 3)
score1)
(current function argument generator-or-thing)
(current function generator-or-thing)
(current generator-or-thing)
This tool is intended to be used as part of the specification for the generator SELECT-GENERATOR-BY-CONDITION.
The tool exists in the three forms listed above. An example of each form:
(current #'= 1 (random-value 1 10))
(current #'evenp (random-value 20 40))
(current (random-value 1 100))
These examples and their usage are explained in the help for SELECT-GENERATOR-BY-CONDITION
(custom-density-choice shape stockpile)
Returns a closure. When applied, a value is randomly chosen from STOCKPILE. The probability density function of the random value which is used as an index for reading the stockpile reflects the curve of SHAPE mapped between the first and last index value of STOCKPILE.
This generator allows the user to create any desired random distribution. The larger the number of values chosen with this generator, the closer the desired probability density function is approximated.
SHAPE should be a shape object or a list representing a shape.
STOCKPILE may be a list, stockpile object, etc. (example 1).
The basic algorithm for this generator was published in:
Dodge, C. and T. Jerse. (1997). Computer Music: Synthesis, composition, and performance. 2nd edition. New York: Schirmer Books.
EXAMPLE 1: (make-histogram
(custom-density-choice expo-shape (from 1 100)))
(custom-density-value shape low-value high-value)
Returns a closure. When applied, a random value between LOW-VALUE and HIGH-VALUE is returned. The probability density function of this random distribution reflects the curve of SHAPE mapped between LOW-VALUE and HIGH-VALUE.
This generator allows the user to create any desired random distribution. The larger the number of values chosen with this generator, the closer the desired probability density function is approximated.
SHAPE should be a shape object or a list representing a shape. If LOW-VALUE and HIGH-VALUE are integers, the result is an integer. Otherwise the result is a real number.
LOW-VALUE and HIGH-VALUE cannot vary over time (examples 1-2).
The basic algorithm for this generator was published in:
Dodge, C. and T. Jerse. (1997). Computer Music: Synthesis, composition, and performance. 2nd edition. New York: Schirmer Books.
EXAMPLE 1: (make-histogram (custom-density-value expo-shape 1 100))
EXAMPLE 2: (make-histogram (custom-density-value '(50 100 1) c1 c5))
data section
A section where the input for each of the parameters (rhythm, pitch, velocity, and channel) is specified separately.
default objects
A few objects have been included with the AC Toolbox. These are the default objects. Among them are three shapes (line-shape, sine-shape, and expo-shape), a note-structure called WILHELMUS, and a stream named TESTING.
When ALL is selected in the OBJECTS dialog, these objects can be seen in the table. They can be examined or played as appropriate. They cannot be removed.
The three shapes have been included for convenience when using tools that require shapes. Many of the examples in the help windows use one or more of these shapes (example 1).
The WILHELMUS can be used to make a structured section (example 2).
WILHELMUS (and other note-structures) can be used with -CHOICE generators, e.g. RANDOM-CHOICE, BETA-CHOICE, etc. to produce notes in a note-section (example 3).
TESTING can be used to test if the Midi connections have been setup right. TESTING will produce an endless series of events with Midi note number 60 in channel 1 when played. To play TESTING, select ALL or STREAMS in the OBJECTS dialog.
The options for the OBJECTS dialog provide a mechanism to hide the default objects.
EXAMPLE 1: (for-example (convert sine-shape 20 40 80))
EXAMPLE 2: (fill-template structured-section wil-section 150
wilhelmus)
EXAMPLE 3: (fill-template note-section my-song 150 62
(random-choice wilhelmus) 0)
(define name object &optional comment size position)
DEFINE is used to associate objects with names. The primary use is with the text version of the toolbox. Any AC Toolbox object (such as a section, community, shape, etc.) can be defined with this tool. Occasionally, objects in help files are also defined with it (example 1).
See the Help menu for Lisp for examples of using it in Lisp code.
COMMENT is an optional parameter which can be used to associate a comment with an object. It should be a string (example 2).
A comment can be accessed by applying GET-COMMENT to the object (example 3).
The optional parameters for SIZE and POSITION are used by the program to save the size and position of the dialogs which make the object definition. The values should be valid values for window sizes and positions (example 4).
To see the dialog for specifying stockpile2, choose the Input button in the Objects dialog.
EXAMPLE 1: (define section1
(make-data-section
10 50 1
(random-value 40 80) mf 1))
EXAMPLE 2: (define stockpile1
(specify-stockpile 1 2 3 4)
"This is a stupid stockpile.")
EXAMPLE 3: (print-result (get-comment stockpile1))
EXAMPLE 4: (define stockpile2 (specify-stockpile 1 2 3 4)
"" '(400 200) '(100 100))
(define-scale interval-list)
Returns a closure which expects one input parameter which should be a number. INTERVAL-LIST is a series of intervals which are added to the previous output of the closure. This tool is convenient for defining functions which generate scales (examples 1-2).
DEFINE-SCALE can be evaluated in the examples pane of a help window, within a pane for a Lisp Editor (File > Text > New), or within a Listener.
EXAMPLE 1: (define my-scale (define-scale '(1 2 2 1)))
EXAMPLE 2: (for-example (my-scale c4) :number 8)
(density time shape minimum-density maximum-density
&key (function (random-value 0 100)) (unit 1))
This tool is a shortcut for DENSITY-OF-START-TIMES.
It can be used when generating Csound or OSC score files.
Its purpose is to calculate a list of start times for events using a shape (or mask) to determine the density of events per some UNIT of time.
TIME is the total amount of time in the score.
SHAPE is the name of the shape or mask to use to determine the varying density. SHAPE is mapped to produce values between MINIMUM-DENSITY and MAXIMUM-DENSITY.
The default for UNIT is 1 seconds (example 1).
See the documentation for DENSITY-OF-START-TIMES for more information and examples.
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1" nil nil 1
(from-start-times) 1
(density 10 line-shape 1 10)
(random-value 0.5 1)
5000
(random-value 220 880))
density section
A section where time is the most important parameter. An amount of time is specified and later filled with a specified number of notes.
This is different from other section specifications where the total length of the section is the sum of the lengths of all of the notes.
(density-of-start-times time shape
minimum-density maximum-density
&key (function (random-value 0 100))
(unit 1))
This tool can be used when generating Csound or OSC score files.
Its purpose is to calculate a list of start times for events using a shape (or mask) to determine the density of events per some UNIT of time.
TIME is the total amount of time in the score or note list.
SHAPE is the name of the shape to use to determine the varying density. The shape is mapped to produce values between MINIMUM-DENSITY and MAXIMUM-DENSITY.
The default for UNIT is 1 second.
In example 1, a list of start-times filling 10 seconds is produced. The shape will be mapped to determine the density per 1 second (the default value for UNIT).
Note that in this example, there is one start time between 0 and 1 seconds, two start-times between 1 and 2 seconds, 3 start-times between 2 and 3 seconds, etc. The density is increasing linearly because line-shape increases linearly.
Note also that the start-times are sorted to be in ascending order.
This tool should be used as input for the START parameter when generating Csound or OSC files. In that case, the input for NUMBER should be (from-start-times).
Example 2 is a dialog for generating Csound score files using this tool.
The resulting Csound score could be rendered with test csound.orc in Support/FileExamples.
A binary OSC file could be written with this object using synthdef sine1 (example 3).
The source code for the synthdef sine1 can be found in test osc synthdefs.rtf in Support/FileExamples.
To change the unit of time for the density calculation, the keyword UNIT should be used. The default value is 1. It is expressed in seconds. Example 4 produces twice as many values. Instead of starting with a density of 1 per second, the density is 1 per .5 second.
The keyword FUNCTION determines where within a time interval the start-time will occur. The default function is (random-value 0 100). The arguments refer to percentages: 0 percent of the available time interval to 100 percent of the available time interval. The default function causes the start-times to be more or less uniformly spread within the interval. A different function would spread them differently. BETA-VALUE would tend to group events near the begin and end of a time unit which per default is 1 second (example 5).
EXAMPLE 1: (for-example
(density-of-start-times 10 line-shape 1 10))
EXAMPLE 2: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1" nil nil 1
(from-start-times) 1
(density-of-start-times
10 line-shape 1 10)
(random-value 0.5 1)
5000
(random-value 220 880))
EXAMPLE 3: (fill-template
osc-score-object osc-score1
(from-start-times) "sine1" nil 'nil 'nil 1
(density-of-start-times 10 line-shape 1 10)
"dur" (random-value 0.5 1) "amp" 0.1
"freq" (random-value 220 880))
EXAMPLE 4: (for-example
(density-of-start-times
10 line-shape 1 10 :unit .5))
EXAMPLE 5: (for-example
(density-of-start-times
10 line-shape 1 10
:function (beta-value 0 100 .1 .1)))
(derive-transition-table source order &key key)
This tool constructs a transition table which can be used with the generator TRANSITION (see transition's help window).
SOURCE should be a list, stockpile, note structure, or section containing the material from which the transition table will be made. If SOURCE is a section, the notes of a section will be used in their order of occurence but without reference to any simultaneities or overlappings.
ORDER refers to the order of the transition table. Order 0 considers 0 previous values. Order 1 considers 1 previous value, etc. (examples 1-4)
KEY is by default #'GET-ELEMENT which selects an element from the list. If the list contains number, KEY returns one number. If the note-structure contains notes, KEY returns the input description of the note. For dealing with note structures, the selectors NOTE-PITCH, NOTE-RHYTHM, and NOTE-VELOCITY have been included. They return a list of pitches, rhythms, or velocities (example 5).
Example 6 uses TRANSITION and DERIVE-TRANSITION-TABLE in the definition of a note section.
EXAMPLE 1:
(for-example (derive-transition-table '(a b c d e a b c) 0))
EXAMPLE 2:
(for-example (derive-transition-table '(a b c d e a b c) 1)
:number-per-line 1)
EXAMPLE 3:
(for-example (derive-transition-table '(a b c d e a b c) 2)
:number-per-line 1)
EXAMPLE 4:
(for-example (derive-transition-table wilhelmus 0)
:number-per-line 1)
EXAMPLE 5:
(for-example
(derive-transition-table wilhelmus 1 :key #'note-pitch)
:number-per-line 1)
EXAMPLE 6:
(fill-template note-section another-wil 150 100
(transition (derive-transition-table wilhelmus 2))
0)
display
has been renamed PLOT.
(do-the-next-thing object)
Returns a closure. When applied, it will produce the next element (or thing) from the object.
If the OBJECT is a function, it is returned as is since the function will return the next thing when it is applied (example 1). If the OBJECT is a sequence or stockpile, it is encapsulated in a loop-through closure which, upon application, will produce the next value of the sequence (example 2). If the object is a constant, it will be repeated each time the generator is applied (example 3).
DO-THE-NEXT-THING is useful when programming generators, etc. in Lisp.
EXAMPLE 1: (for-example (do-the-next-thing (random-value 1 10)))
EXAMPLE 2: (for-example (do-the-next-thing '(1 2 3)))
EXAMPLE 3: (for-example (do-the-next-thing 143))
(duffing x y A B G omega giant &key eye xy (stepsize 0.01) first)
Returns a closure. When applied returns the next value of a dynamical system, described by the following formula:
x'=y
y'=-Ay-Bx^3+Gcos(omega*t)
The default output variable is X. By using the keyword EYE the variable Y is returned. Both variables will be returned in a list by using the keyword XY.
The parameter GIANT determines after how many iterations the value is returned. This can be useful for filling a list with a small number of values describing the behaviour of the system over a longer period.
The system is a driven oscillator with a non-linear compliance term (Bx^3).
By setting G and OMEGA to zero, the system is non-driven (example 1).
The driven oscillator can behave in a chaotic way (example 2).
If the damping is large, the transient part of the oscillation will soon fade away (example 3).
It is not easy to predict the maximum and minimum of the output values. To map the output of this function to useful values, use CONVERT (example 4).
The initial values for X and Y are not returned. If the initial values should be returned as the first result of the generator, keyword FIRST should be bound to t (examples 5-6).
This generator was contributed by Gijs de Bruin.
EXAMPLE 1: (plot (duffing 1.0 1.0 0.0 1.0 0.0 0.0 10)
:number 300)
EXAMPLE 2: (plot (duffing 1.0 1.0 0.1 5.6 0.7 pi 10)
:number 600)
EXAMPLE 3: (plot (duffing 4.0 4.0 5.6 8.7 9.0 0.7 10)
:number 300)
EXAMPLE 4: (for-example
(convert (duffing 1.0 1.0 0.1 5.6 0.7 pi 10) 100 c2 c5))
EXAMPLE 5: (for-example
(duffing 1.0 1.0 0.0 1.0 0.0 0.0 10))
EXAMPLE 6: (for-example
(duffing 1.0 1.0 0.0 1.0 0.0 0.0 10 :first t))
(duplicates &key diversity)
Duplicates produces a function appropriate for use with WITHOUT. It will return a function which will disallow any value that has already occurred (example 1).
A problem will arise with the use of DUPLICATES if the generator is not able to produce a value that has not already occurred (example 2).
This could be addressed by binding a value to the keyword DIVERSITY. This value defines how many new values have to be chosen before all values are again available to be chosen (example 3).
Example 4 chooses groups of three unique values from all available values.
The value bound to the keyword DIVERSITY can be a constant, list, generator, etc. If the value is not a constant, a new value for diversity will be chosen each time all values are again available to be chosen. Example 5 chooses 3 unique values, then 4 unique values, then 5 unique values, etc.
EXAMPLE 1: (for-example
(without (duplicates)
(random-value 1 20)))
EXAMPLE 2: (for-example
(without (duplicates)
(random-value 1 10)))
EXAMPLE 3: (for-example
(without (duplicates :diversity 10)
(random-value 1 10)))
EXAMPLE 4: (for-example
(without (duplicates :diversity 3)
(random-value 1 10))
:number 21 :number-per-line 3)
EXAMPLE 5: (for-example
(without (duplicates :diversity '(3 4 5))
(random-value 1 5)))
element
has been renamed CURRENT.
environment
Various types of objects can be created with the Toolbox. These include sections, shapes, masks, stockpiles, etc. Objects are stored as part of the current Environment. The Environment contains a list of all objects which have been defined by a user during a session. The dialog for OBJECTS has a popup menu to list the objects according to their various types. Choosing the menu item ALL will show a list of definitions made in a session.
OBJECTS allows you to get information about the objects created. For all objects it is possible to see the input specification. TOOLS > REMOVE OBJECTS allows you to remove an object from the environment. TOOLS > REMOVE ALL OBJECTS allows you to remove all objects in the environment at once.
All objects included in the Environment are saved to a disk file when the FILE > SAVE ALL OBJECTS is chosen. When the menu item REPLACE ALL OBJECTS is chosen, the current Environment is replaced with one that has been previously saved in a file. The menu item LOAD OBJECTS adds the contents of an Environment file to the current Environment.
Environments saved in this version of the AC Toolbox cannot be read in version 4.3.x or earlier unless 'Old Format' is chosen in the Preferences dialog.
Environments saved in earlier versions of the AC Toolbox can be read in this version.
environment does not load
If an environment gives as error message upon loading, this could be caused by some arcane dependency of the objects being loaded and the order in which this happens. This is a very rare occurence and mostly involves streams.
If the error message was similar to this:
Unbound variable: CONT1
this might be solved by evaluating the following expression in the Listener but substituting the name of the unbound variable for CONT1.
(setf cont1 nil)
The environment file should be loaded again. If this does not solve the problem and there are no more messages of this type and you recognize the name of the offending object, define it again (or a very simple version of it) and then reload the environment. An easy way to define an object is to pick one from the dialog examples and make it with the appropriate name.
If the environment will still not load, then you could open the file with the 'File>Text>Open' menu item and maybe you can figure out what to delete. Maybe not. Good luck.
In any case, at least part of the environment was probably read in before the error occurred.
errors
When the AC Toolbox catches errors, a message dialog containing the error message is placed on the screen. These errors include things such as not filling all the boxes of a dialog, using undefined objects, etc. The message should help you fix the problem.
Errors missed by the Toolbox but noticed by the underlying Lisp environment are also printed in a dialog. These messages tend to be about obscure things such as divide by zero. The message may or may not help you fix the problem.
In very exceptional cases, an underlying Lisp error could cause a message to be printed in a window of the Terminal application.
In that case, type :a in the Terminal window.
If that doesn't help, type :top.
If that doesn't help, try :top or :a again.
If the Terminal window presents options, type :c 1 if you want to do option 1,
:c 2 if you want to do option 2, etc.
If a message appears in the Terminal concerning stack overflow, choose :c 2 to extend the stack. This may need to be done a couple of times.
If an object with many events is to be plotted, and the pizza wheel of death spins for a long time and a Terminal window opens, try typing :c to force a list of options, then choose :c 2 to extend the stack.
There have been reports that the printing in the Terminal window may be followed by a message from the system that the AC Toolbox crashed. Close the Terminal Window, click on Reopen in the crash message, and you may be able to continue working where you left off in the AC Toolbox.
(exponential-value threshold gamma &optional upper-boundary)
EV is a shortcut for EXPONENTIAL-VALUE.
It returns values chosen with an exponential distribution with THRESHOLD being the lowest possible value (examples 1-2).
GAMMA controls the spread of values. The larger the value for GAMMA, the greater the probability of producing values near THRESHOLD (examples 3-4).
See the documentation for EXPONENTIAL-VALUE for more information.
EXAMPLE 1: (make-histogram (ev 0.0 .1))
EXAMPLE 2: (make-histogram (ev 10.0 .1))
EXAMPLE 3: (make-histogram (ev 0 .01))
EXAMPLE 4: (make-histogram (ev 0 .1))
(ex controller-number low high)
EX is a shortcut (abbreviation) for EXTERNAL-VALUE.
See the help for EXTERNAL-VALUE for more information.
(expand factor middle-line)
Returns a closure. FACTOR is a percentage from 0 to infinity. MIDDLE-LINE is a number. Expanding a value to 0% of its value makes it equal to the MIDDLE-LINE. Expanding 100% is its original value (examples 1-4).
FACTOR and MIDDLE-LINE may vary over time.
EXAMPLE 1: (show-transformation (expand 50 50)
'(0 20 40 50 60 75 80 100))
EXAMPLE 2: (show-transformation (expand 0 50)
'(0 20 40 50 60 75 80 100))
EXAMPLE 3: (show-transformation (expand 100 50)
'(0 20 40 50 60 75 80 100))
EXAMPLE 4: (show-transformation (expand 200 50)
'(0 20 40 50 60 75 80 100))
(exponential-choice sequence gamma)
Returns a closure. When applied, one element of the sequence is returned. The index of the element was chosen with an exponential distribution. GAMMA determines the spread of the distribution and should be > 0. The larger the value of GAMMA, the greater the probability of producing values near 0 (in this case, picking the first element of the sequence) (examples 1-5).
GAMMA may vary over time.
EXAMPLE 1: (for-example
(exponential-choice '(a b c d e f g h i) .01))
EXAMPLE 2: (for-example
(exponential-choice '(a b c d e f g h i) .1))
EXAMPLE 3: (for-example
(exponential-choice '(a b c d e f g h i) .2))
EXAMPLE 4: (for-example
(exponential-choice '(a b c d e f g h i) .5))
EXAMPLE 5: (for-example
(exponential-choice '(a b c d e f g h i)
(line-segment 20 .01 .2)))
(exponential-motion n start finish &key (curve 2))
Returns a closure. When applied, it returns the next of the N values describing an exponential movement from START to FINISH. The type of result is determined by START and FINISH (examples 1-5).
Keyword CURVE controls the shape of the curve. Any positive value may be used. Values > 2 increase the 'sharpness' of the curve (examples 6-7).
The shortcut ARC can be used for EXPONENTIAL-MOTION (example 8).
EXAMPLE 1: (for-example (exponential-motion 20 0 100))
EXAMPLE 2: (for-example (exponential-motion 20 100 0))
EXAMPLE 3: (for-example (exponential-motion 20 0.0 100))
EXAMPLE 4: (plot (exponential-motion 100 0.0 100))
EXAMPLE 5: (plot (exponential-motion 100 100.0 0))
EXAMPLE 6: (plot (exponential-motion 100 0.0 100 :curve 4))
EXAMPLE 7: (plot (exponential-motion 100 100.0 0 :curve 8))
EXAMPLE 8: (plot (arc 100 0.0 100 :curve 8))
(exponential-value threshold gamma &optional upper-boundary)
Returns a closure. When applied, a number >= THRESHOLD is returned. If the optional UPPER-BOUNDARY is supplied, the number will be <= to it. The number returned follows an exponential distribution. The type of the number is the type of THRESHOLD. GAMMA determines the spread of the distribution and should be > 0. The larger the value of GAMMA, the greater the probability of producing values near THRESHOLD (examples 1-6).
THRESHOLD, GAMMA, and UPPER-BOUNDARY may vary over time.
The average value for this distribution is 1/gamma (example 7).
EXPONENTIAL-VALUE can be abbreviated to EV (example 8).
EXAMPLE 1: (for-example (exponential-value 0.0 .1))
EXAMPLE 2: (make-histogram (exponential-value 0 .1))
EXAMPLE 3: (make-histogram (exponential-value 0 .5))
EXAMPLE 4: (plot (exponential-value 0.0 .5))
EXAMPLE 5: (for-example (exponential-value 40 .1 80))
EXAMPLE 6: (plot
(exponential-value (line-segment 100 0.0 50) .1))
EXAMPLE 7: (print-result (average (exponential-value 0.0 .1) 10000))
EXAMPLE 8: (make-histogram (ev 0 .1))
(external-value controller-number low high)
Returns a closure. When applied it returns the value of a Midi controller which has been mapped to the range LOW - HIGH. CONTROLLER-NUMBER is the number of the Midi controller.
If the preference for 'External-Value' has been set to 'Channels', CONTROLLER-NUMBER will not be the controller number but the number of the Midi channel. This is useful if the external device for instance only uses controller 7 on different channels.
This generator assumes of course that an external Midi controller is connected and an appropriate Midi setup has been defined.
Example 1 controls the range of random numbers with a Midi controller in a data stream (example 1).
External-value is useful when controlling streams in real-time.
Controller numbers should be in the range 1-127. If 'Channels' has been selected in the preferences, numbers should be in the range 1-16.
External-value may be abbreviated to ex. E.g. (ex 1 c1 c3).
EXAMPLE 1: (fill-template
make-midi-data-stream stream1 100 1
(rv (external-value 1 40 80) (external-value 2 40 80))
f 1)
(extract parameter object)
Returns a list of values extracted from a section, note structure, community, or midi performance objects. Which values are extracted are determined by PARAMETER. The values are in the order of occurance in the section.
Possible parameters are
PITCH which returns a list of pitch values (as midi note numbers)
RHYTHM which returns a list of rhythmic values (including rests)
DURATION which returns a list of durations in milliseconds (sections)
VELOCITY which returns a list of velocity values
NOTE which returns a list containing note objects
ATTACK which returns a list of attack times (as percentage of the total duration.)
RAW-ATTACK which returns a list of attack times in milliseconds.
CONTROLLER-VALUES which returns controller values from a midi controller object or from a section.
PROGRAM-NUMBERS which returns program numbers from a midi program object or from a section.
CHANNEL which returns a list of channel values.
If section S1 has been defined, example 1 will extract pitch.
Parameters PITCH, RHYTHM, VELOCITY return a list which can be used as input in a data section and reproduce the original section. Rests will be negative numbers in the rhythm list. The corresponding positions in a pitch list or a velocity list will contain a 0.
Example 2 extracts a list suitable for use in a note section.
A note-list is a one-dimensional list containing each note from an object, one after another, sorted according to their starting time. Extracting the note list in a note section means that all layers will be flattened into one. One note will only start after the previous is finished. This tool is most suitable for a section that is a single, non-overlapping melody.
Example 3 would return the appropriate value for the clock unit in defining a note section or a data section. Extracted rhythmic values are expressed as a multiples of this value.
WILHELMUS is a predefined note structure in the AC Toolbox (example 4).
It is not possible to extract the duration of a note structure since no clock unit has been applied to a note structure.
EXAMPLE 1: (for-example (extract 'pitch s1))
EXAMPLE 2: (for-example (extract 'note s1))
EXAMPLE 3: (print-result (get-rhythmic-unit s1))
EXAMPLE 4: (for-example (extract 'pitch wilhelmus))
(fibonacci &optional seed1 seed2)
Returns a closure. When applied, it will generate the next value in the Fibonacci series.
In the Fibonacci series, the next value is the sum of the previous two values. The series starts with 0 and 1 (example 1).
Some composers like to have deviant versions of the Fibonacci series. In this case values for the optional parameters SEED1 and SEED2 should be provided. The first value returned will be SEED1, SEED2, then SEED1 + SEED2, etc. In this case it is important that arguments are provided for both SEED1 and SEED2 (example 2).
To return a list of Fibonacci values that are <= some limit, the tool GENERATE-RANGE could be used (example 3).
EXAMPLE 1: (for-example (fibonacci))
EXAMPLE 2: (for-example (fibonacci 100 200))
EXAMPLE 3: (for-example (generate-range (fibonacci) 500000))
(fill-gaps section)
Returns a closure which should be used for the DURATION parameter of a transformation. SECTION must be a section since this transformer only works with sections. Presumably, SECTION would be the name of the section being transformed.
This transformer will add to the duration of any note that does not continue at least until the beginning of the next note. It will not shorten a note that continues past the start of the next note (examples 1-4).
EXAMPLE 1: (fill-template density-section ds1
10 3 (random-value 0.0 100) 100
(random-value 40 80) f 1)
EXAMPLE 2: (plot ds1)
EXAMPLE 3: (fill-template transform transform1 ds1
:duration (fill-gaps ds1))
EXAMPLE 4: (plot transform1)
(fill-template type name &rest data)
FILL-TEMPLATE fills the dialog boxes available under the DEFINE menu items with initial values. This is primarily useful when writing documentation. The type should agree with the type under the menu, except all word combinations should be hypenated. Data section should be data-section, note section should be note-section, etc. Other than types that can be derived from the menu, the following are available: community, data-section, density-section, density-curve-section, note-section, parallel-section, scheme, sequential-section, structured-section, timed-section, xy-section, rule-stockpile, controller-density-object, controller-data-object, program-density-object, program-data-object, data-stream, csound-score-object, sequential-score-object, parallel-score-object, generate-sequential-score-object, generate-parallel-score-object, and osc-score-object.
The remaining values for the dialog should be filled in, from top to bottom, left to right. E.g. for data-section: name, clock unit, number, rhythm, pitch, velocity, channel, delay (example 10.
When in doubt about the appropriate form for entering the data for a particular type of object, look at the way that the input in stored for the object to see how it should be entered.
If object MY-DATA has been made, the input can be accessed with get-input:
EXAMPLE 1: (fill-template data-section my-data 10 100 1
(random-value c2 c5) mf 1 0)
EXAMPLE 2: (print-result (get-input my-data))
(filter-stockpile stockpile filter)
Returns a list made by filtering STOCKPILE. STOCKPILE may be a list or stockpile. FILTER should be an expression such as:
(low-pass threshold)
(high-pass threshold)
(band-pass low high)
(band-reject low high)
(bank low1 high1 low2 high2 ...)
(shot-gun percentage)
(pass-stockpile-filter stockpile)
(repetition-filter)
or some other suitable filter expression
(see Help>Lisp>Your Own for information about making filters.)
The low-pass filter passes values <= 5 (example 1).
The repetition-filter removes repetitions (example 2).
The pass-stockpile-filter passes values contained in its list or stockpile (example 3).
The predicate tool can be used to construct a filter expression (example 4). If the predicate returns a true value, the element from the stockpile is passed through.
EXAMPLE 1: (print-result
(filter-stockpile '(1 2 3 4 5 6 7 8 9 10)
(low-pass 5)))
EXAMPLE 2: (print-result
(filter-stockpile '(1 2 2 3 3 4 4 5 6 7 8 9 10)
(repetition-filter)))
EXAMPLE 3: (print-result
(stockpile->notename
(filter-stockpile '(c#3 d3 f3 f#3 g3)
(pass-stockpile-filter
'(c3 f3 g3)))))
EXAMPLE 4: (print-result
(filter-stockpile (from 1 10)
(predicate < 5)))
(find-range thing &key n chord parameter)
Returns a list with strings for the minimum and maximum values of THING. If THING is a generator, it is applied N times to find the range. N defaults to 1000 times.
THING can be a list, stockpile, generator, shape, section etc (examples 1-4).
If THING contains or produces elements which are lists (e.g. chords), the min and max value within the chords are determined. The keyword CHORD defaults to t and causes this behavior (example 5).
If CHORD is bound to nil, a range is returned for each position in the list (example 6).
When CHORD is bound to nil, all elements should have the same length. The primary use of binding CHORD to nil, is to return separate minimum and maximum values for each dimension in a multi-dimensional (chaotic) result (example 7).
If THING is a section, the pitch range will be returned. Example 8 assumes section1 exists.
The range of other section parameters can be found by binding the PARAMETER keyword to DURATION or VELOCITY (example 9).
Knowing the expected range is important if you are using the generator MAP/TIME which assumes you know the possible range of the input values. It is also useful with MAP-TRANSFORMER.
EXAMPLE 1: (for-example (find-range '(2 10 5 6)))
EXAMPLE 2: (for-example
(find-range (henon 0.0 0.0 1.4 0.3 1)))
EXAMPLE 3: (for-example
(find-range (henon 0.0 0.0 1.4 0.3 1) :n 20))
EXAMPLE 4: (for-example (find-range sine-shape))
EXAMPLE 5: (for-example
(find-range '((60 64 67) (67 34 88))))
EXAMPLE 6: (for-example
(find-range '((60 64 67) (67 34 88)) :chord nil))
EXAMPLE 7: (for-example
(find-range (henon 0.0 0.0 1.4 .3 1 :xy t) :chord nil))
EXAMPLE 8: (for-example (find-range section1))
EXAMPLE 9: (for-example (find-range section1 :parameter 'velocity))
(flatten list-or-stockpile)
Returns a list containing no inner parentheses. All nested lists are 'flattened' into a list with only one level (example 1).
Flatten works with lists or stockpiles.
EXAMPLE 1: (print-result (flatten '(a (b c) (d (e (f (g)))))))
(fn)
This tool is a shortcut for FROM-NUMBER.
It can be used when specifying input for sections and most Midi objects. It can also be used when creating Csound or OSC files.
It returns the number of events which have been specified or calculated for the NUMBER parameter of the object (example 1).
See the documentation for FROM-NUMBER for more information and examples.
EXAMPLE 1: (fill-template data-section data-section1 200
20 '(2 1)
(random-value c1 g#4)
(convert line-shape (fn) pp ff) 1 0)
(follow shape object low high)
Returns a closure. A shape determines the 'shape' of the transformation. A SHAPE is adjusted to produce the same number of values as exist in OBJECT (which may be the name of a section, a community or just some number of values). The values of SHAPE will range between LOW and HIGH. These values will be used to multiply the values being transformed. This allows a transformation which changes over time following the shape of SHAPE.
SHAPE may be drawn or specified via the DEFINE menu. A shape may also be a list of numbers,a mask, or a generator.
If SECTION1 has been defined, it can be transformed with example 1.
Some standard shapes have been included in the AC Toolbox environment:
line-shape
sine-shape
expo-shape
line-shape provides an ascending line.
sine-shape is a sinusoidal motion.
expo-shape is an ascending exponential motion.
The shape could also just be a list of values:
(follow '(0 100) section1 1 5)
If SHAPE is a mask, random choices are made between the boundaries of the mask. If SECTION1 and MASK1 have been defined, section1 can be transformed with example 2
If SHAPE is a generator, the output of the generator (in whatever range it uses) is mapped to between the LOW and HIGH values of this transformer (example 3).
EXAMPLE 1: (fill-template transform section2 section1
:tempo (follow line-shape section1 1 5))
EXAMPLE 2: (fill-template transform section2 section1
:tempo (follow mask1 section1 1 5))
EXAMPLE 3: (fill-template transform section2 section1
:tempo (follow (random-value 0 100) section1 1 5))
fomus
FOMUS is a music notation formatting tool that can produce output suitable for the LilyPond notation program or for the MusicXML interchange format which can be read by Sibelius, Finale, and other programs.
The AC Toolbox expects FOMUS to be installed in /usr/local/bin which is where the FOMUS installer puts it. If LilyPond is chosen as the preferred output mode, it should be installed in the Applications folder.
FOMUS is available via SourceForge (example 1). The AC Toolbox menu item to write files in this format is 'File>Write FOMUS File'.
The AC Toolbox assumes that FOMUS version 0.1.10 or higher is installed.
EXAMPLE 1: (open-url "http://fomus.sourceforge.net/")
(for-example generator &key number number-per-line recycle)
Prints the results of applying the GENERATOR a NUMBER of times in a window. NUMBER-PER-LINE values are printed per line (example 1).
The default number of results is 20. This can be overridden by binding another value to the keyword NUMBER (example 2).
The default number of values per lines is 5. This can be overridden by binding another value to the keyword NUMBER-PER-LINE (example 3).
The primary use of this tool is in help windows which document the use of generators and tools.
If the RECYCLE keyword is bound to t, the example data is written to the previous example or show-transformation window (after erasing the previous data). This helps cut down on screen clutter. If the value is nil, a new window is made each time example data is requested.
The default behaviour for this keyword is specified in the Preferences dialog.
GENERATOR could also be a list, a stockpile, or a tool that produces a list (example 4).
EXAMPLE 1: (for-example (random-value 1 100))
EXAMPLE 2: (for-example (random-value 1 100) :number 50)
EXAMPLE 3: (for-example (random-value 1 100) :number-per-line 7)
EXAMPLE 4: (for-example (gather-until (random-value 1 5) 50))
(force-int &optional transformer)
Returns a closure which forces the result of the transformation to be an integer value (example 1).
If no TRANSFORMER is specified, the value to be transformed is returned as an integer value (example 2).
Lisp function round is used to force the value to be an integer.
EXAMPLE 1: (show-transformation
(force-int (transpose 12.5))
'(60 60.5 61 6.5))
EXAMPLE 2: (show-transformation
(force-int) '(60 60.5 61 61.5))
(frequency-shift-chord chord offset &key round name base)
Returns a closure. When applied, a chord (expressed as a list of Midi notenumbers) is returned. The chord contains a simulation of frequency shifting each pitch of CHORD by a frequency OFFSET specified in Hz.
OFFSET is added to the frequency equivalent of each pitch in CHORD. The result is converted to Midi note numbers.
This generator reflects ideas present in the field of spectral composition.
CHORD can be a list, stockpile, a generator which produces a list, etc. (example 1).
Example 2 produces a table of the frequency equivalents of all Midi notenumbers.
Example 3 shows the frequency equivalent of one notenumber, e.g. 60.
Example 4 shows the note number closest to a certain frequency, e.g. 100 Hz.
CHORD and OFFSET may change over time (examples 5-6).
The default value for ROUND is t. This will round off the Midi note numbers to be integers. If real numbers are desired, ROUND should be bound to NIL (example 7). If ROUND is bound to another number, such as 0.5, the values will be quantized using that value. 0.5 rounds to quarter-tones (example 8).
Keyword NAME controls whether pitches are printed as numbers or as note names. When it is bound to T, note names are printed (example 9).
When note names are printed, pitches can be printed with the digits after the decimal point by binding ROUND to nil (example 10).
Keyword BASE is for specifying a reference frequency for Midi note number 69 (a). It defaults to 440.0 Hz (example 11).
EXAMPLE 1: (for-example
(make (frequency-shift-chord '(60 64 67) 100)))
EXAMPLE 2: (show-midi->hz)
EXAMPLE 3: (for-example
(make (midi->hz 60)))
EXAMPLE 4: (for-example
(make (hz->midi 100 :round t)))
EXAMPLE 5: (for-example
(frequency-shift-chord (make-chord (walk 60 3) 3) 100)
:number-per-line 1 :number 3)
EXAMPLE 6: (for-example
(frequency-shift-chord '(60 64 67) '(100 200 300))
:number-per-line 1 :number 3)
EXAMPLE 7: (for-example
(make (frequency-shift-chord
'(60 64 67) 100 :round nil)))
EXAMPLE 8: (for-example
(make (frequency-shift-chord
'(60 64 67) 100 :round 0.5)))
EXAMPLE 9: (for-example
(make (frequency-shift-chord
'(60 64 67) 100 :name t)))
EXAMPLE 10: (for-example
(make (frequency-shift-chord
'(60 64 67) 100 :round nil :name t)))
EXAMPLE 11: (for-example
(frequency-shift-chord '(60 64 67) '(100 200 300)
:base 415)
:number-per-line 1 :number 3)
(from begin end &key type step)
Returns a a sequence of values from BEGIN to END. Default output type is a list. Default for STEP is 1 (examplse 1-2).
Example 3 uses a step of 0.5.
BEGIN, END, and STEP can be generators. The generator will be applied once to determine a value (example 4).
To return a vector instead of a list, bind the keyword TYPE to vector (example 5).
Note that there can be floating point deviations in the values if the step size is a floating point number. If this is a problem, a possible solution is to express the step size as a rational number such as 1/10 instead of .1 (examples 6-7).
When BEGIN > END, the step size should be a positive number (example 8).
EXAMPLE 1: (for-example (from 40 80))
EXAMPLE 2: (for-example (from 10 1))
EXAMPLE 3: (for-example (from 1 10 :step 0.5))
EXAMPLE 4: (for-example
(from (random-value 1 20) (random-value 1 20)))
EXAMPLE 5: (print-result (from 40 50 :type 'vector))
EXAMPLE 6: (print-result (from 0 1 :step .1))
EXAMPLE 7: (print-result (from 0 1 :step 1/10))
EXAMPLE 8: (print-result (from 10 1 :step .5))
(from-layers)
This tool can be used when creating Csound or OSC files. It returns the number of layers that have been specified or calculated for the LAYERS parameter. It is a convenient way to use the number of layers in another parameter (example 1).
The resulting Csound score could be rendered with test csound.orc in Support/FileExamples.
In object score1, the value of the p4 parameter, which in some instrument could be the amplitude parameter, is scaled by the number of layers. If the number of layers is changed in the specification (or is the result of applying a generator), the correct value for the number of layers is available for use in the P4 parameter.
Amplitude scaling can also be done with the tool SCALE-BY-LAYERS.
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 5 100 1 0 (random-value .1 .2)
(/ 32000 (from-layers))
(random-value 100.0 1000))
(from-number)
This tool can be used when specifying input for sections and most Midi objects. It can also be used when creating Csound or OSC files.
It returns the number of events which have been specified or calculated for the NUMBER parameter of the object.
It is a convenient way to use the number of notes in a different parameter. If you change the number of notes, the value in the other parameters also change (example 1).
If the number of notes is unknown at the moment that the specification is made, (from-number) will return the calculated number (examples 2-5).
The source code for the synthdef sine1 can be found in test osc synthdefs.rtf in Support/FileExamples.
EXAMPLE 1: (fill-template data-section data-section1 200
20 '(2 1)
(random-value c1 g#4)
(convert line-shape (from-number) pp ff) 1 0)
EXAMPLE 2: (fill-template data-section data-section2 200
(until-time 10) '(2 1)
(random-value c1 g#4)
(convert line-shape (from-number) pp ff) 1 0)
EXAMPLE 3: (fill-template data-section data-section3 200
(random-value 20 50) '(2 1)
(random-value c1 g#4)
(convert line-shape (from-number) pp ff) 1 0)
EXAMPLE 4: (fill-template density-curve-section density-curve1
20 expo-shape 1 50 1
(random-value 100 200)
(walk c3 (random-value -5 5) c1 c#5)
(convert line-shape (from-number) pp ff) 1)
EXAMPLE 5: (fill-template osc-score-object osc-score1
(until-time 10) "sine1" nil nil nil 1 0
"dur" (random-value 0.1 0.2)
"amp" 0.3
"freq" (convert line-shape (from-number) 200.0 800))
(from-overlap)
This tool is intended to be used together with the OVERLAP generator when producing Csound or OSC files. When OVERLAP has been used, a list of duration values is generated so that the overlap in start times may be calculated. This list can be recovered using from-overlap.
When the START parameter of a Csound score dialog or an OSC score object contains OVERLAP, the DURATION parameter of that Csound score dialog should use (from-overlap) (example 1).
The resulting Csound score could be rendered with test csound.orc in Support/FileExamples.
Example 2 produces an OSC score using FROM-OVERLAP.
The source code for the synthdef sine1 can be found in test osc synthdefs.rtf in Support/FileExamples.
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1
(overlap 0 (random-value 0.5 1.5) 0.25)
(from-overlap) 32000
(random-value 100.0 1000))
EXAMPLE 2: (fill-template osc-score-object osc-score1 10 "sine1"
NIL NIL NIL 1
(OVERLAP 0 (RANDOM-VALUE 0.5 1.5) 0.25)
"dur" (FROM-OVERLAP) "amp" 0.5
"freq" (RANDOM-VALUE 100.0 1000))
(from-start-times)
This tool can be used when specifying input for Csound or OSC files.
It should only be used in combination with the tool DENSITY-OF-START-TIMES.
(from-start-times) should be the input for NUMBER when DENSITY-OF-START-TIMES is used as input to START. This is the only intended use for this tool.
(from-start-times) will return the total number of events calculated with DENSITY-OF-START-TIMES. Any other expressions needing to know the number of values should use (from-number).
See the help for DENSITY-OF-START-TIMES for an example of a form using this tool.
(function-of-x function &key low-x high-x number)
Returns a closure. When applied, a value is returned which is the result of using X in a function.
FUNCTION should be a Lisp expression which contains the symbol X. Each time the generator is applied, the value of X changes which could result in a different output from the generator (examples 1-2).
By default, X will receive values in the range 0 - 1. The lower limit can be changed by binding a new value to the keyword LOW-X. The upper limit can be changed by binding a value to the keyword HIGH-X (examples 3-7).
Example 8 is a somewhat more complex function, used in Crux by Simon Cummings.
The keyword NUMBER controls the number of different values X will receive. The default value is 100. This means that after 100 values, X will return to LOW-X and the series will repeat (example 9).
This generator could be used, for example, to generate shapes or to produce lists using CONVERT (examples 10-11).
EXAMPLE 1: (plot (function-of-x (* x x)))
EXAMPLE 2: (plot (function-of-x (sin (* 2 pi x))))
EXAMPLE 3: (plot (function-of-x (sin x)))
EXAMPLE 4: (plot (function-of-x (sin x) :low-x -5 :high-x 5))
EXAMPLE 5: (plot (function-of-x (exp x)))
EXAMPLE 6: (plot (function-of-x (exp x) :low-x -5 :high-x 5))
EXAMPLE 7: (plot (function-of-x (* x x) :low-x -3 :high-x 3))
EXAMPLE 8: (plot (function-of-x (+ (* 0.714285714 x)
(* 2.3 (sin (expt x 2.19))))
:low-x 0. :high-x 5))
EXAMPLE 9: (plot (function-of-x (sin x) :number 50))
EXAMPLE 10: (fill-template generate-shape shape1 100
(function-of-x (sin x)))
EXAMPLE 11: (for-example
(convert (function-of-x (sin x) :number 10) 10 1 10))
(funnel list)
Returns a closure which forces the value being transformed to be one of the values included in the LIST. LIST may be a list or stockpile. If a value is equidistant between two values in LIST, a random choice is made between the values (example 1).
The values in the funnel can be floating-point numbers (example 2).
The idea for this transformer was adapted from the sieve funnel in AthenaCL (example 3).
Example 4 shows a sieve segment which is the union of two sieves.
This sieve segment can be used with funnel (example 5)
See the help for the tool SIEVE for more information about sieves.
EXAMPLE 1: (show-transformation
(funnel '(1 3 5 7 9))
'(1 2 3 4 5 6 7 8 9 10))
EXAMPLE 2: (show-transformation
(funnel (from 60.0 65. :step .5))
(convert line-shape 20 60.0 65))
EXAMPLE 3: (open-url "http://www.athenacl.org")
EXAMPLE 4: (for-example
(sieve-union (sieve 3 40 40 80)
(sieve 4 40 40 80)))
EXAMPLE 5: (for-example
(transform/time
(random-value 40 80)
(funnel (sieve-union (sieve 3 40 40 80)
(sieve 4 40 40 80)))))
(gather-until input total &optional clock-unit always-less)
Returns a list of values whose combined absolute values are >= TOTAL. As soon as TOTAL has been reached (or just exceeded) no more values are added to the list.
INPUT can be a constant, a list, or a generator (examples 1-3).
If the optional parameter CLOCK-UNIT is specified, TOTAL is considered to be a time in seconds instead of any other unit such as beats. INPUT values will be considered to be multiples of the CLOCK-UNIT. GATHER-UNTIL will gather until that amount of time has been filled (example 4). To demonstrate the way that CLOCK-UNIT works, example 4 is rewritten using multiples of 150 ms as the input values and 5000 ms for the total (example 5).
If the sum of the values returned by GATHER-UNTIL should always be <= to TOTAL (but never exceeding it), ALWAYS-LESS should be bound to t (examples 6-9). Note that if no CLOCK-UNIT is specified, a nil should be entered before the value for ALWAYS-LESS.
EXAMPLE 1: (for-example (gather-until (random-value 1 5) 50))
EXAMPLE 2: (for-example (gather-until '(1 2 4) 40))
EXAMPLE 3: (for-example (gather-until (split 96 6 .6 2) (* 10 96)))
EXAMPLE 4: (for-example (gather-until '(1 2 4) 5 150))
EXAMPLE 5: (for-example (gather-until '(150 300 600) 5000))
EXAMPLE 6: (for-example (gather-until 3 20))
EXAMPLE 7: (for-example (sum (gather-until 3 20)))
EXAMPLE 8: (for-example (gather-until 3 20 nil t))
EXAMPLE 9: (for-example (sum (gather-until 3 20 nil t)))
(gaussian-choice sequence standard-deviation mean)
Returns a closure. When applied, it returns one element of the sequence. The index for that element is chosen according to a Gaussian distribution. Both the STANDARD-DEVIATION and the MEAN should be expressed as index values (relative to the sequence) (example 1).
STANDARD-DEVIATION and MEAN may vary over time.
EXAMPLE 1: (for-example (gaussian-choice '(a b c d e f g h i) 3 5))
(gaussian-value standard-deviation mean
lower-boundary upper-boundary
&key conversion)
Returns a closure. When applied, it returns a number according to a Gaussian distribution. Most (ca. 68%) of the results will occur within ± STANDARD-DEVIATION from the MEAN. To keep things under control a bit, all values < LOWER-BOUNDARY or > UPPER-BOUNDARY are discarded (examples 1-3). CONVERSION has as its default the function truncate. This means all values will be truncated (to integers). If this is not desired, bind this keyword to NIL or use the name of a different conversion function (example 4).
STANDARD-DEVIATION, MEAN, LOWER-BOUNDARY and UPPER-BOUNDARY may vary over time.
EXAMPLE 1: (for-example (gaussian-value 5 50 40 60))
EXAMPLE 2: (make-histogram (gaussian-value 12 60 40 80))
EXAMPLE 3: (plot (gaussian-value 5 50 40 60))
EXAMPLE 4: (for-example (gaussian-value 5 50 40 60
:conversion nil))
general midi
In addition to using Midi objects to control a General Midi device, instruments can be assigned to Midi channels via Other>General Midi. This Midi setup can be saved via File>Save GM Selections and loaded at some other time via File>Load GM Selections.
(generate tool)
Returns a closure. When applied, the tool (or Lisp expression) is evaluated and the result is returned.
This generator in fact converts a tool into the form necessary to be used as a generator.
TOOL can be an AC Toolbox tool or some valid Lisp expression.
ALEA is a tool that returns a random value between two limits. It is not a generator and can therefore not be used with FOR-EXAMPLE to generate several values (example 1).
By enclosing it within a GENERATE expression, this would be possible (example 2).
Other simple examples are (examples 3-5).
An example using a controller.
The basic idea is to define a controller which will produce a value and a generator which will return the negative version of that value. TAKE will be used to produce one value from the controller and then the negative value from the generator.
Define the controller (example 6)
Note that the controller could be also be defined using the dialog produced by the Controller menu item.
To generate the value from the controller and then the negative value from the generator see (example 7).
EXAMPLE 1: (for-example (alea 1 100))
EXAMPLE 2: (for-example (generate (alea 1 100)))
EXAMPLE 3: (for-example (generate 10))
EXAMPLE 4: (for-example (generate '(1 2 3)))
EXAMPLE 5: (for-example (generate (+ 2 2)))
EXAMPLE 6: (define cont1 (make-controller '(1 2 3 4)))
EXAMPLE 7: (for-example
(take 1 (do-the-next-thing cont1)
1 (generate (- (get-most-recent cont1)))))
generate parallel section
The dialog box produced by this menu item allows variants of one or more sections to be made and then combined in parallel.
Example 1 creates a section to vary.
Example 2 generates a parallel section using this section.
In example 2, three variants will be made of section DS1 and these variants will be combined in parallel. In this case, a variant is a new section using the input data of a previous one. The offset time is 0 which means that all variants will start together.
The first variant always starts at time 0. Subsequent variants can start later if the offset parameter produces a value > 0. Offset time is expressed in seconds (example 3).
Sometimes it is useful to remake stockpiles (or other objects) before making a variant of a section.
Example 4 makes a stockpile to determine the rhythm values for the section in example 5.
Example 6 calculate new rhythmic values for each layer in the parallel section:
A generator can be used to determine which sections should be varied (example 7).
In example 7, five layers will be produced. For each layer, a choice will be made between varying ds1 or ds2.
EXAMPLE 1: (fill-template data-section
ds1 100 30
(random-value 1 5)
(random-value 40 80)
(beta-value 60 100 .2 .1) 1)
EXAMPLE 2: (fill-template new-generate-parallel-section
parallel1 3 0 ds1
nil nil nil nil)
EXAMPLE 3: (fill-template new-generate-parallel-section
parallel2 3
(random-value 0.0 5) ds1
nil nil nil nil)
EXAMPLE 4: (fill-template generate-stockpile
st 30 (random-value 1 5))
EXAMPLE 5: (fill-template data-section
ds2 100 30
st (random-value 40 80)
(beta-value 60 100 .2 .1) 1)
EXAMPLE 6: (fill-template new-generate-parallel-section
parallel3 3 0 ds2 st
nil nil nil)
EXAMPLE 7: (fill-template new-generate-parallel-section
parallel4 5
(random-value 0.0 5)
(random-choice '(ds1 ds2))
st nil nil nil)
generate sequential section
The dialog box produced by this menu item allows variants of one or more sections to be made and then combined in sequence.
Example 1 creates a section to vary.
Examples 2-3 generate sequential sections using this section.
Three variants will be made of section DS1 and these variants will be combined in sequence. In this case, a variant is a new section using the input data of a previous one. The offset time is 0 which means that each variant will start immediately after the previous one is finished.
The first variant always starts at time 0. Between subsequent variants there can be a time delay if offset produces values > 0. Offset time is expressed in seconds.
Sometimes it is useful to remake stockpiles (or other objects) before making a variant of a section.
The stockpile in example 4 is used to determine the rhythmic values for a section (example 5).
Example 6 calculates new rhythmic values for each layer in the sequential section.
A generator can be used to determine which sections should be varied (example 7).
In example 7, 5 variants will be produced. For each variant, a choice will be made between varying ds1 or ds2. A time delay will occur between each variant.
EXAMPLE 1: (fill-template data-section
ds1 100 30
(random-value 1 5)
(random-value 40 80)
(beta-value 60 100 .2 .1) 1)
EXAMPLE 2: (fill-template generate-sequential-section
sequential1 3 0 ds1
nil nil nil nil)
EXAMPLE 3: (fill-template generate-sequential-section
sequential2 3
(random-value 1.0 3)
ds1 nil nil nil nil)
EXAMPLE 4: (fill-template generate-stockpile
st 30 (random-value 1 5))
EXAMPLE 5: (fill-template data-section
ds2 100 30
st (random-value 40 80)
(beta-value 60 100 .2 .1) 1)
EXAMPLE 6: (fill-template generate-sequential-section
sequential3 3 1 ds2 st
nil nil nil)
EXAMPLE 7: (fill-template generate-sequential-section
sequential4 5
(random-value 1.0 3)
(random-choice '(ds1 ds2))
st nil nil nil)
(generate-diversity number generator &key pitch-class (stop 1000))
Returns a list of values produced by the GENERATOR. Values are added to the list until the desired amount of diversity (measured in the number of different values) is reached. NUMBER refers to the number of different values which should be present before generation stops (examples 1-2).
If diversity should be measured in terms of pitch-classes, bind the keyword PITCH-CLASS to t (example 3).
This tool could be used for instance to generate rhythmic loops which can contain a certain number of different values. It also could construct pitch sequences with a certain number of different pitch-classes present.
The user is responsible for ensuring that the generator which is used is capable of producing the desired amount of diversity. If that is not possible after STOP number of tries, the execution will abort and an error message will appear. The default value for STOP is 1000.
EXAMPLE 1: (for-example (generate-diversity 5 (random-value 1 12)))
EXAMPLE 2: (for-example (generate-diversity 5
(random-choice '(c3 c4 d#3 d2 d#5 b2 b3 b4 a5))))
EXAMPLE 3: (for-example (generate-diversity 5
(random-choice '(c3 c4 d#3 d2 d#5 b2 b3 b4 a5))
:pitch-class t))
(generate-line start n end &key exponential (curve 2))
Returns a closure. When applied, a point on a line between START and END is returned. The first point will be START. The next point will move along the line so that the Nth point will be END. The interpolation between START and END is linear (by default) but can also be set to exponential.
After N points have been produced, a new value for N and a new value for END are generated. Points will be produced between the current value and the new value for END. Then a new value for N and a new value for END are produced. And so on.
Both N and END can vary over time and therefore can be constants, lists, stockpiles, generators, etc. The value for START is only used once but can also be a constant, generator, etc.
In example 1, 10 values between 1 and 10 are produced. Remaining values are on the line from 10 to 10.
In example 2, 10 values between 1 and 10 are produced. Then 10 values between 10 and 5.
If the value for START and/or END are floating point numbers, the output will be floating point numbers. Otherwise the values will be rounded to integers (example 3).
If more values are desired, the generator will loop through the list (example 4).
END can also be a generator. Each time a new value for the end of the line is needed, the generator will be applied (example 5).
N can be a generator. Each time a new value for the number of values is needed, the generator will be applied (example 6).
If the keyword EXPONENTIAL is t, the interpolation between the values will be exponential (example 7). Keyword CURVE is ony used when EXPONENTIAL is t. The default value is 2. Any positive value may be used for CURVE. Values > 2 increase the 'sharpness' of the curve (examples 8-9).
A more complex use of GENERATE-LINE will produce pitches in a data section (example 10).
In example 10, a line is generated. Its output is added (using otf, a shortcut for on-the-fly) with the output of another generator which produces a random value in the range -5 to 5. Pitch will follow the generated line with a deviation between 5 notes lower than the generated value to 5 notes higher than the generated value.
GENERATE-LINE can also be used to produce a continuous series of mask segments. To do that, one generator should be used for the bottom line of the mask and another generator for the top line. The two generators can then be used as the arguments for random-value (example 11).
GENERATE-LINE can be abbreviated to GL (example 12).
EXAMPLE 1: (for-example (generate-line 1 10 10))
EXAMPLE 2: (for-example (generate-line 1 10 '(10 5)))
EXAMPLE 3: (for-example (generate-line 1.0 10 ' (10 5)))
EXAMPLE 4: (for-example
(generate-line 1.0 10 '(10 5))
:number 40)
EXAMPLE 5: (plot
(generate-line 1.0 10 (random-value 10 20)))
EXAMPLE 6: (plot
(generate-line 1.0 (random-value 5 20)
(random-value 1 20)))
EXAMPLE 7: (plot
(generate-line (random-value 1.0 5)
(random-value 5 10)
(random-value 1 10)
:exponential t))
EXAMPLE 8: (plot
(generate-line 1.0
25
'(10 7 2 1)
:exponential t))
EXAMPLE 9: (plot
(generate-line 1.0
25
'(10 7 2 1)
:exponential t :curve 4))
EXAMPLE 10: (fill-template
data-section test1 100 400 1
(otf (generate-line (random-value c2 g#5)
(random-value 5 30)
(random-value c2 g#5)
:exponential t)
+ (random-value -5 5))
mf 1 0)
EXAMPLE 11: (fill-template
data-section test2 100 400 1
(random-value
(generate-line (random-value c2 g#5)
(random-value 40 80)
(random-value c2 g#5)
:exponential t)
(generate-line (random-value c2 g#5)
(random-value 40 80 )
(random-value c2 g#5)
:exponential t))
mf 1 0)
EXAMPLE 12 : (plot (gl 1.0 (rv 5 20) (rv 1 20)))
(generate-range generator limit &key stop)
Returns a list of values created by applying the generator until a certain limit has been reached.
This could be useful for constructing scales where the generator would be an existing scale generator, such as major or melodic minor, or a user-defined scale defined with the tool define-scale (examples 1-3).
Other generators can be applied until the LIMIT is reached (example 4).
The user is responsible for GENERATOR being able to reach LIMIT. If this tool has not been able to do that after STOP attempts, an error message occurs. STOP could be bound to a higher value if desired (example 5).
EXAMPLE 1: (for-example (generate-range (major 36) 72))
EXAMPLE 2: (define my-scale (define-scale '(1 2 2 1)))
EXAMPLE 3: (for-example (generate-range (my-scale c1) c4))
EXAMPLE 4: (for-example (generate-range (prime-number) 100))
EXAMPLE 5: (for-example (generate-range (always 1) 100))
(generate-scale first intervals)
Returns a closure. When applied, FIRST is returned. Then an interval produced by INTERVALS is added to FIRST. Another interval is produced and added to the previous result. Etc.
INTERVALS would typically be a list and represent the intervals in a scale (examples 1-2).
EXAMPLE 1: (for-example (generate-scale 60 '(2 2 1 2 2 2 1)))
EXAMPLE 2: (for-example (midi->notename
(generate-scale c3 '(2 2 1 2 2 2 1))))
(generate-sf-name generator)
Returns a closure. When applied, the GENERATOR will choose among possible soundfile names which then will be adjusted to be in the appropriate format for a Csound score file.
If the file is a sound file, it should be in the sample directory. If it is an analysis file, it should be in the analysis directory.
In example 1, random-choice is the generator choosing from the list of two possible soundfile names. Each soundfile name should be a string (enclosed in double quotes). Replace "sax1" and "harry" with the names of files found in your sample directory.
The examples in this help text can be rendered using 'test csound.orc' found in 'Support/FileExamples'.
GENERATOR may be a generator, stockpile, list, etc. (example 2). It should not be just a string reflecting one file name. Use SF-NAME for that case.
If the choice of sound file is generated and a different duration is desired based on that choice, the following steps could be taken:
1. Make a stockpile choosing the sound files (example 3).
2. Make a lookup table with the file names and durations (example 4).
3. Use these two stockpiles in the csound score description (example 5).
EXAMPLE 1: (fill-template csound-score-object score1
"" nil nil 1 10 3 0
(random-value .5 1)
(generate-sf-name
(random-choice '("sax1" "harry")))
0 1 .01 .01)
EXAMPLE 2: (fill-template csound-score-object score1 ""
nil nil 1 10 3 0
(random-value .5 1)
(generate-sf-name '("sax1" "harry"))
0 1 .01 .01)
EXAMPLE 3: (fill-template generate-stockpile stock1 10
(random-choice '("sax1" "flute")))
EXAMPLE 4: (fill-template construct-stockpile table1
(make-lookup-table
"sax1" 10.33 "flute" 9.66))
EXAMPLE 5: (fill-template csound-score-object score1 ""
nil nil 1 10 3 0
(lookup stock1 table1)
(generate-sf-name stock1)
0 1 .01 .01)
(generate-sum expression &optional (number 5))
Returns a closure. When applied, the next NUMBER of values from EXPRESSION are added and the sum is returned.
NUMBER has the default value of 5. Example 1 adds 5 outputs from the generator (random-value 1 10).
Example 2 adds 20 outputs of the generator.
If EXPRESSION is a list, the first NUMBER of values from the list are summed, then the next NUMBER are summed, etc. (example 3).
EXPRESSION can change over time.
A different way to produce a sum is discussed in the help for the tool SUM.
EXAMPLE 1: (for-example (generate-sum (random-value 1 10)))
EXAMPLE 2: (for-example (generate-sum (random-value 1 10) 20))
EXAMPLE 3: (for-example (generate-sum (from 1 10)))
generators
A generator is a function which returns the next value in some series each time it is used. A generator for producing increasing integers would return the value 1 the first time it is used, then 2, then 3, ... A generator for producing Midi note numbers for a major scale starting with 60 (c4) would return 60, then 62, 64, 65, 67, etc.
Generators tend to have one of two suffixes.
Value means values will be produced between two limits (a bandwidth), e.g. (random-value 1 100) would produce a value in the range between 1 and 100.
Choice means values will be chosen from an available supply of values, e.g. from a list. (random-choice Ô(a b c d e)) chooses a value from the list Ô(a b c d e).
Individual help windows for each generator are available via the Annotated Index or the Index.
(get-intervals stockpile &key first between)
Returns the list of intervals. By default, the intervals are from the first value to each other value in STOCKPILE. STOCKPILE may be a list or stockpile (examples 1-2).
If the first interval (between the first value and itself) should be included, bind the keyword FIRST to t (example 3). This faciliates the derivation of pitch sets.
Alternatively, the intervals between each value in STOCKPILE can be returned. In that case, BETWEEN should be bound to t (example 4). If both FIRST and BETWEEN are bound to t, BETWEEN takes precedence and FIRST is ignored.
EXAMPLE 1: (for-example (get-intervals '(60 64 67)))
EXAMPLE 2: (for-example (get-intervals '(c4 e4 g4)))
EXAMPLE 3: (for-example (get-intervals '(60 64 67) :first t))
EXAMPLE 4: (for-example (get-intervals '(60 64 67) :between t))
(get-length object)
Returns the number of elements, objects, or points in some AC Toolbox object (example 1).
STOCKPILE: the number of values is returned.
SECTION: the number of separate start times is returned.
COMMUNITY: the number of sections or communities in this one.
SHAPE: the number of points defining the shape.
NOTE STRUCTURE: the number of notes in a structure. Rests are not counted.
EXAMPLE 1: (print-result (get-length wilhelmus))
(get-most-recent controller)
Returns the most recent value that a controller has produced. If none has been produced, the controller is applied to produce a value.
(get-object-duration object &key seconds)
Returns the duration of a section or community in milliseconds (examples 1-2).
Bind the keyword SECONDS to t to return a value in seconds (example 3).
EXAMPLE 1: (fill-template data-section ds1 100 100 1 (rv 40 80) f 1)
EXAMPLE 2: (print-result (get-object-duration ds1))
EXAMPLE 3: (print-result (get-object-duration ds1 :seconds t))
(get-rhythmic-unit section-or-community)
Derives a clock-unit that could have been used in the section or community.
If section S1 exists, example 1 returns the rhythmic unit.
EXAMPLE 1: (print-result (get-rhythmic-unit s1))
(get-stockpile object)
Returns a list of values from OBJECT.
STOCKPILE: returns a list of the values in the stockpile (example 1 and 1b).
SECTION: returns a list of note objects. The notes are in order but without their start time.
NOTE STRUCTURE: returns a list of notes, rests, and delays in the note structure (example 1).
SHAPE: returns a list of values describing the shape (example 2).
COMMUNITY: returns a list of objects (sections or communities) in the community.
CONTROLLER: returns a list of values which have been produced by the controller since it was last reset.
GET-STOCKPILE would probably be primarily used when writing your own Lisp code, e.g. your own generators.
EXAMPLE 1: (define stock1 (generate-stockpile 10 (rv 1 100)))
EXAMPLE 1b: (print-result (get-stockpile stock1))
EXAMPLE 2: (for-example (get-stockpile wilhelmus))
EXAMPLE 3: (for-example (get-stockpile sine-shape))
(gl start n end &key exonential (curve 2))
GL is a shortcut for GENERATE-LINE.
It returns a point on a line between START and END. The first point is START. The Nth point is END. New values for N and END are produced and a line is made from the current value to the new value of END in N steps (examples 1-3).
See the documentation for GENERATE-LINE for more information.
EXAMPLE 1: (plot (gl 0 50 '(100 50)))
EXAMPLE 2: (plot (gl 0 (rv 5 15) (rv 0 100)))
EXAMPLE 3: (plot (gl 0 (rv 10 20) (rv 0 100) :exponential t :curve 4))
(group for-value for-repetitions)
Returns a closure. When applied, it produces one value which can be of any type. FOR-VALUE is used to produce a value. FOR-VALUE may be a constant, a list, or a generator. This value occurs a number of times as determined by FOR-REPETITIONS (which also may be a constant, list, or generator to produce a number).
Each application of the closure returns one value. If that value should occur 4 times, the next 3 applications of the closure result in the same value being returned (examples 1-2).
FOR-VALUE and FOR-REPETITIONS can vary over time.
EXAMPLE 1: (for-example (group (random-choice '(a b c d e))
(random-value 2 6)))
EXAMPLE 2: (for-example (group '(60 64 67) '(2 5)))
(grow start growth &key n lower upper (reset t) (function #'*))
Returns a closure. When applied, a geometric or arithmetric series of numbers will be produced. By default, a geometric series (multiplication of the previous value by a growth factor) will occur.
Example 1 is an endless geometric series. The first value is START. The second value is START * GROWTH. The next value is the previous value * GROWTH. There is no upper limit.
Example 2 is a decreasing series. Each application of the closure with decrease the value. There is no lower limit.
The series can be limited to N values. The value N+1 will again be START (example 3).
The series can be clipped to be within the range LOWER and UPPER (examples 4-5).
An arithmetic series (adding GROWTH to the previous value) can be realized by binding #'+ to FUNCTION (example 6).
All parameters except RESET can vary over time. They can be constants, lists, stockpiles, generators, etc.
If a series has N values and one or more parameters that vary over time, the new parameter values will be produced every N values (example 7).
By default, RESET is set to t. If it is bound to nil, the series will continue from its current value instead of resetting the series to the START value (examples 8-9). There must be a value for N for this to have any effect.
If START changes over time and RESET is t, then START will receive a new value after each N values (example 10).
Example 11 produces a data section with a rhythm controlled by grow. START is chosen each N times. The series will start at the new start point every N times. N is also a generator.
Example 12 produces a data section where the rhythmic series is continuous. It changes every N times but does not reset to the start value. It continues from where it was.
EXAMPLE 1: (for-example (grow 1 1.1))
EXAMPLE 2: (for-example (grow 1 .9))
EXAMPLE 3: (for-example (grow 1 1.1 :n 5))
EXAMPLE 4: (for-example (grow 1 .8 :lower .4))
EXAMPLE 5: (for-example (grow 1 1.1 :upper 2))
EXAMPLE 6: (for-example (grow 1 2 :function #'+))
EXAMPLE 7: (for-example (grow 1 (random-choice '(.9 1.1)) :n 5))
EXAMPLE 8: (for-example (grow 1 (rc '(.9 1.1)) :n 5 :reset nil))
EXAMPLE 9: (plot (grow 1 (rv .9 1.1) :n 10 :reset nil))
EXAMPLE 10: (for-example (grow (rv 1 3) 1.1 :n 5))
EXAMPLE 11: (fill-template data-section section1 100 100
(grow (rv 1.0 3) 0.9 :n (rv 5 20)
:lower 0.01)
c4 f 10)
EXAMPLE 12: (fill-template data-section section2 50 200
(grow 2 (rv 0.9 1.1) :n (rv 5 10)
:lower 0.01 :upper 10 :reset nil)
c4 f 10)
(harmonic-chord fundamental-pitch harmonics &key number round name distortion)
Returns a closure. When applied, a chord (expressed as a list of notenumbers) is returned. The chord contains notes which are harmonics of the specified fundamental-pitch.
FUNDAMENTAL-PITCH should be a Midi notenumber or a pitch symbol such as c4 derived from a constant, list, stockpile, generator, etc.
HARMONICS contains the desired harmonics. It may be a list, stockpile, generator, etc. (example 1).
When HARMONICS is a list, the resulting chord will contain the same number of notes as are specified for the harmonics. Note that if the fundamental is desired, harmonic 1 should be specified.
If HARMONICS is not a list, the number of harmonics chosen is specified with the keyword NUMBER. This value defaults to 4. (examples 2-3).
When a generator is used for HARMONICS and the FUNDAMENTAL-PITCH should be included in the chord, generator TAKE can be used (example 4).
The default value for ROUND is t. This will round off the Midi note numbers to be integers. If real numbers are desired, ROUND should be bound to NIL (example 5). If ROUND is bound to another number, such as 0.5, the values will be quantized using that value. 0.5 rounds to quarter-tones (example 6).
DISTORTION allows the spectrum to be (slightly) stretched or compressed. The technique is based on a description by Joshua Fineberg in his doctoral dissertation, Sculpting Sound.
DISTORTION values above 1 stretch the spectral. Values below 1, compress the spectrum. DISTORTION may be a constant, list, stockpile, generator, etc. The default value is 1 (no distortion) (examples 7-9).
The distortion formula is:
(* fundamental-freq (expt partial-no distortion))
This formula produces the results mentioned in Fineberg's dissertation. The formula he includes does not.
Keyword NAME controls whether pitches are printed as numbers or as note names. When it is bound to t, note names are printed (example 10).
When note names are printed, pitches can be printed with the digits after the decimal point by binding ROUND to nil (example 11).
FUNDAMENTAL-PITCH, HARMONICS, and DISTORTION may vary over time. FUNDAMENTAL-PITCH and DISTORTION are chosen once per chord.
To vary FUNDAMENTAL-PITCH over time, a generator could be used (example 12).
EXAMPLE 1: (for-example
(make (harmonic-chord 24 '(1 4 7))))
EXAMPLE 2: (for-example
(make (harmonic-chord 24 (random-value 1 10))))
EXAMPLE 3: (for-example
(make (harmonic-chord 24
(random-value 1 10) :number 6)))
EXAMPLE 4: (for-example
(make (harmonic-chord 24
(take 1 1 5 (random-value 1 16))
:number 6)))
EXAMPLE 5: (for-example
(make (harmonic-chord 24 '(1 4 7) :round nil)))
EXAMPLE 6: (for-example
(make (harmonic-chord 24 '(1 4 7) :round 0.5)))
EXAMPLE 7: (for-example
(make (harmonic-chord 24 (from 1 5) :distortion 1)))
EXAMPLE 8: (for-example
(make (harmonic-chord 24 (from 1 5) :distortion 1.1)))
EXAMPLE 9: (for-example
(make (harmonic-chord 24 (from 1 5) :distortion 0.9)))
EXAMPLE 10: (for-example
(make (harmonic-chord 24 '(1 4 7) :name t)))
EXAMPLE 11: (for-example
(make (harmonic-chord 24 '(1 4 7)
:name t :round nil)))
EXAMPLE 12: (for-example
(harmonic-chord (random-value c0 c2) '(1 4 7))
:number-per-line 1)
(harmonic-minor start)
Returns a closure. When applied, a note number corresponding to the next value in an ascending harmonic-minor scale is generated. The first value in the series is START. The series could continue indefinitely (examples 1-2).
EXAMPLE 1: (for-example (harmonic-minor 60) :number 8)
EXAMPLE 2: (for-example (harmonic-minor 55) :number 8)
help
Help Tags
When the mouse is held over a text input item, a button, etc. a help-tag (the yellow dialog with help) will appear after a certain amount of time. Help-tags generally do not appear for text items.
?
Many dialogs have a button with a question mark. Clicking this button will produce a window with the relevant help for that dialog. All dialogs which define objects have this help button. A few others such as the Csound File Options dialog also have it.
Generators, Tools, Transformers
Information about many generators, tools, and transformers which are available in the AC Toolbox can be found by selecting the item in the Index table or in the Annotated Index. The Index just includes item names. The Annotated Index includes a brief description. In the Annotated Index either the name or description can be searched.
Alternatively, the name of a generator etc. can be selected. Help can be found by then typing the key combination Command-=. (That is holding the command key while pressing the = key). This is the shortcut for the menu item 'Help>Lookup Selection'.
Objects
Information about objects which have been defined by a user in the Toolbox can be found in the Objects dialog. If it is not open, use the menu item 'Tools>Show Objects'. The dialog has a table containing all defined objects. Each time a new object is defined, it is added to the table. Using a popup menu, a table of only objects of a particular type can be selected. The input specification for an object can be requested. Various other actions can be performed. Objects can also be removed from the environment by choosing the Remove option.
Dialog Examples
Examples of dialogs used to define various objects can be chosen from the table produced by the 'Dialog Examples' menu item in the Info menu. Each dialog will include an example of appropriate input to that dialog.
Annotated Index
Online help entries for generators, transformers, and tools can be found in the annotated index table together with a brief description of what the generator, etc. does. Check boxes allow choosing among the possible items which can be displayed. A popup menu allows limiting the displayed items to those belonging to a category such as 'Chaos' or 'Rhythm'. A filter allows searching either the item names or the item descriptions.
Index
All online help entries for generators, transformers, tools, and general information can be found in the index table. This table can be filtered to only include entries containing some group of letters or words. In the options, a choice can be made to only include general information or only include generators, tools, and transformers.
The index can be selected via the Info menu or with the key combination Command-I.
If a generator is chosen in the index, its help window is opened.
Index also includes entries for general information. This includes topics that otherwise would 'fall between the cracks'. Information about all of the menu items can be found per menu. Each menu has an entry in the table similar to Menu: File describing each menu item. Each object which can be defined using the Define menu has an entry similar to Objects: Sections describing that class of objects.
Help->File
A tool with the name HELP->FILE can be used to write all or some online help to one file. This file can be in html or text format and can be searched or browsed without using the AC Toolbox. The tool allows an optional type parameter to limit the information being gathered in the window. See the help for this tool for details.
Lisp
More detailed information about the Lisp functions used within the Toolbox to create and manipulate objects can be found in the help files associated with the different types of objects or operators. These help files can be opened by selecting the object type from the menu item Lisp (in the Info menu). The embedded lines of Lisp code (indicated with EVALUATE: ) can be evaluated by using the ENTER key. The result is printed in the echo area (under the editor pane). Information about writing your own generators, transformers, etc. can be found under that same Lisp menu with the item 'Your Own'.
help windows
Template
A help window for a generator always starts with a template for using that generator. This template includes the name and parameters of the generator, e.g. (1/f-value n a z).
The name of the generator is 1/F-VALUE. The parameters are N, A, and Z. The role of the parameters is always explained in the help window.
A generator such as WALK contains the word &OPTIONAL in its template. This means that all parameters after this word are optional, i.e. they do not have to be used. The user never uses the word &OPTIONAL in an expression.
A generator such as RAMP includes the word &KEY in its template. The parameters that follow are keywords and may be ignored. If they are to be used, the keyword is preceded by a colon. The template for RAMP is:
(ramp begin end increment &key conversion (wrap t))
There are two keywords in that template: CONVERSION and WRAP. The expression (wrap t) in that template means that the keyword WRAP has the default value T. The help files for generators with keywords show examples of how to use the keywords in an expression.
The help windows for transformers and tools both begin with similar templates.
Examples
Help windows for generators, tranformers, and tools usually include a separate pane with examples of Lisp expressions which can be evaluated to produce some sample results which are printed or plotted. To produce these results, place the cursor at the end of the expression and press the ENTER key (which is different than the return key). The Lisp expression could also be selected and evaluated with the menu item, 'Edit>Evaluate Selection'.
For-Example
The function FOR-EXAMPLE applies a generator several times and prints the result in a window. Usually FOR-EXAMPLE will produce 20 values. Example 1 is such an expression. It means that FOR-EXAMPLE will use the generator 1/F-VALUE to produce some sample results.
FOR-EXAMPLE also has keywords available to adapt the output. Some expressions make use of these keywords. Example 2 uses the generator PRODUCE-PULSE to produce 12 values which will be printed six values to a line.
If the expression in FOR-EXAMPLE is not a generator, it is evaluated once and the result is printed in a window.
Plot
Plot produces a graph related to its input expression. If the input is a generator, that generator is applied a number of times and the values are plotted. When example 3 is evaluated, 100 hundred values produced by the generator RANDOM-VALUE are plotted.
If the input is a list, the values in the list are plotted.
PLOT has keywords available to adapt its output. NUMBER allows a generator to be applied a specified number of times instead of the default 100 times. MIN and MAX allow a minimum and maximum value to be specified for plotting the results. If these values are not specified, PLOT will use the actual minimum and maximum value derived from the results.
In example 4, the generator 1/F-VALUE is applied 200 times. Even though this generator seldom reaches its specified minimum and maximum value, the plot will use a minimum value of 1 and a maximum value of 100.
Show-Transformation
Help windows for transformers use the function SHOW-TRANSFORMATION in the expressions which produce sample results.
Example 5 prints the result of applying the transformer, in this case (TRANSPOSE 12), to each value in the list.
Fill-Template
FILL-TEMPLATE creates a dialog box used for defining an object. The expression may seem confusing but does not need to be understood. If you evaluate the expression, a familiar looking dialog should appear. FILL-TEMPLATE is just a way to make the dialog (example 6).
Open-Url
OPEN-URL will open an url supplied as a string.
Example 7 makes an internet connection and opens (if possible) the browser page from the AC Toolbox. A few help items include an url for getting more information.
Show-Info
Provides information about a section, Midi object, or a community in a window. The information includes the total number of events and the total duration of the object.
If section S1 exists, example 8 will open or update a section info window.
Show-Text
This is another way to examine the output of a section, Midi object, or stockpile. A more or less readable version of the object is printed in a window.
If section S1 exists, example 9 will print out the starttime, duration, channel, velocity, and pitch of each event.
Print-Result
Prints the result of applying a tool or Lisp function in a window (example 10).
EXAMPLE 1: (for-example (1/f-value 20 1 100))
Example 2: (for-example (produce-pulse '(5 0 2 4 1 3) 2)
:number 12 :number-per-line 6)
EXAMPLE 3: (plot (random-value 1 100))
EXAMPLE 4: (plot (1/f-value 200 1.0 100)
:number 200 :min 1 :max 100)
EXAMPLE 5: (show-transformation (transpose 12)
'(60 62 64 65))
EXAMPLE 6: (fill-template specify-stockpile stock1 c3 c#3 64 66 69 b3)
EXAMPLE 7: (open-url "http://www.koncon.nl/ACToolbox")
EXAMPLE 8: (show-info s1)
EXAMPLE 9: (show-text s1)
EXAMPLE 10: (print-result (cal '(10 20 30) + 2))
(help->file &key type prose brief html)
This tool gathers online help windows into one file which can be read without the AC Toolbox. The file could also be searched, formatted, and/or printed in another program.
The online help for generators, tools, transformers, general, and the glossary can be gathered with this tool. If no TYPE is specified, all of the above are gathered in alphabetical order. This takes a while (example 1).
TYPE can also be set to GENERATORS, TOOLS, TRANSFORMERS, GENERAL, or GLOSSARY which results in only the appropriate items being gathered. If type is EVERYTHING, (the default case), all help items are gathered (examples 2 - 6).
Generators, tools and transformers have been divided into various subcategories. These subcategories can also be used to collect only the help for that subcategory.
The available subcategories are (examples 7-9):
basic chaos chord csound file filters koenig mapping masks&shapes
method noise note numbers others pitch programming representation
rhythm select shortcuts spectral stream transformation transitions utility
Two or more categories can be included in a list and all help files for those categories will be gathered (examples 10 - 11).
By default, the file with include some simple html formatting. If keywork HTML is nil, the file with be a plain text file without any html formatting (example 12).
The Annotated Index menu item makes a table of brief descriptions of generators, tools, and/or transformers.
To print these brief descriptions to a file, the keyword for BRIEF should be t. Everything, generators, tools, and transformers can be printed briefly. The brief file will always be without html formatting (examples 13-14).
If keyword PROSE is nil, the introductory bit of prose will not precede the help documentation in the window (example 15).
The default values for the key words are:
TYPE everything
PROSE t
BRIEF nil
HTML t.
EXAMPLE 1: (help->file)
EXAMPLE 2: (help->file :type 'generators)
EXAMPLE 3: (help->file :type 'tools)
EXAMPLE 4: (help->file :type 'transformers)
EXAMPLE 5: (help->file :type 'general)
EXAMPLE 6: (help->file :type 'glossary)
EXAMPLE 7: (help->file :type 'basic)
EXAMPLE 8: (help->file :type 'masks&shapes)
EXAMPLE 9: (help->file :type 'noise)
EXAMPLE 10: (help->file :type '(generators tools))
EXAMPLE 11: (help->file :type '(noise pitch rhythm))
EXAMPLE 12: (help->file :type 'generators :html nil)
EXAMPLE 13: (help->file :type 'everything :brief t )
EXAMPLE 14: (help->file :type 'generators :brief t)
EXAMPLE 15: (help->file :type '(noise koenig) :prose nil)
help->window
has been replaced with HELP->FILE.
(henon x y a b giant &key eye xy first)
Returns a closure. When applied returns the next value of a dynamical system, described by the following formula:
x(n+1)=y(n)+1-ax(n)^2
y(n+1)=bx(n)
The default output variable is X. By using the keyword EYE the variable Y is returned. Both variables will be returned in a list by using the keyword XY.
X and Y are the initial values for the system and should both be a number close to zero. A and B control the behaviour of the system. Both should be a positive value. The system will be stable if the values for A and B are set following this general guideline:
A<=(2.0-B)
The parameter GIANT determines after how many iterations the value is returned. This can be useful for filling a list with a small number of values describing the behaviour of the system over a longer period.
Small deviations from these values should be possible.
This system shows both periodic and chaotic behaviour. Periodic behaviour generally occurs for small values for A (example 1).
However, if A is small, it depends on the value of B (example 2).
Chaotic behaviour is obtained for higher values for A (examples 3-5).
The initial values for X and Y are not returned. If the initial values should be returned as the first result of the generator, keyword FIRST should be bound to t (examples 6-7).
The Henon-map is can be see with example 8.
It is not possible to predict the maximum and minimum of the output values. To map the output of this function to useful values, use CONVERT (example 9).
A and B may vary over time. Extreme care must be taken that the time-variant values remain in an acceptable range to avoid computational errors (example 10).
If HENON is used in a stream, it may not be convenient to use CONVERT to map the values. In that case, MAP/TIME can be used. This is a generator which maps values on the fly. The minimum and maximum value is however needed to do this mapping.
Tool FIND-RANGE returns the minimum and maximum values of an object or a generator. By default, a generator is applied 1000 times (examples 11-12).
See Bidlack,R. (1992). "Chaotic Systems as Simple (but Complex) Compositional Algorithms". Computer Music Journal, 16(3).
This generator was contributed by Gijs de Bruin.
EXAMPLE 1: (plot (henon 0.0 0.0 1.0 0.3 1) :plot nil)
EXAMPLE 2: (plot (henon 0.0 0.0 1.0 0.45 1) :plot nil)
EXAMPLE 3: (plot (henon 0.0 0.0 1.4 0.3 1) :plot nil)
EXAMPLE 4: (plot (henon 0.0 0.0 1.4 0.3 1 :eye t) :plot nil)
EXAMPLE 5: (plot (henon 0.0 0.0 1.4 0.3 10) :plot nil)
EXAMPLE 6: (for-example (henon 0.0 0.0 1.4 .3 1))
EXAMPLE 7: (for-example (henon 0.0 0.0 1.4 .3 1 :first t))
EXAMPLE 8: (plot (henon 0.0 0.0 1.4 0.3 1 :xy t) :number 1000)
EXAMPLE 9: (for-example (convert (henon 0.0 0.0 1.4 0.3 1)
100 c2 c5))
EXAMPLE 10: (plot (henon 0.0 0.0 (line-segment 100 1.4 1.8) .3 1)
:plot nil)
EXAMPLE 11: (for-example (find-range (henon 0.0 0.0 1.4 .3 1)))
EXAMPLE 12: (fill-template make-midi-data-stream stream1 100 1
(map/time (henon 0.0 0.0 1.4 .3 1) -1.28 1.27
50.0 72) f 1)
hetro
Hetro is an analysis program which is available with Csound. Hetrodyne filter analysis is performed on a sound file, producing an analysis file of amplitude and frequency tracks. The analysis file can be read into the AC Toolbox (using READ-TRACKS-FILE) to produce note information. The tracks can also be read with READ-SPECTRUM-FILE in which case one pitch and amplitude value per track will be returned.
If Csound5 is installed, a Hetro analysis file can be made from within the AC Toolbox. Select Other>Csound File Options. Click on the Analysis Programs button and select Hetrodyne Filter (hetro) as the analysis type.
More information about Hetro can be found in the Csound manual.
(hz->midi frequency &key round name base)
Returns a closure. When applied one frequency value in Hz is converted to a Midi note number (example 1). The choice of C4 or C3 for middle C can be made in the Preferences dialog.
FREQUENCY can be a constant, list, stockpile, generator, etc. (example 2).
If keyword ROUND is t, the result is rounded to an integer value (example 3). If it is bound to some other number, the result is quantized using that number. E.g., 0.5 would result in quarter-tones (example 4).
By default, ROUND is bound to NIL and the result is a real value. Real numbers can be used for Midi playback using QuickTime or a Capybara.
The keyword NAME, when bound to t, prints out the notename, such as C3, instead of the Midi note number when the generator is applied. ROUND should be bound to t for integer values (example 5).
To print note names with the digits after the decimal point, bind NAME to t and do not bind ROUND to t (example 6).
The keyword BASE is a reference frequency for A4. It defaults to 440.0 Hz (example 7).
This generator is useful if one wants to know the relationship between a frequency value in Hz and a Midi note number. It is also useful when writing generators which need to translate spectral values in Hz to Midi note numbers.
To translate Midi note numbers to a value in Hz, see the generator MIDI->HZ.
EXAMPLE 1: (print-result (make (hz->midi 440)))
EXAMPLE 2: (for-example (hz->midi '(100 200 300 400))
:number 4 :number-per-line 1)
EXAMPLE 3: (for-example (hz->midi '(100 200 300 400) :round t)
:number 4 :number-per-line 1)
EXAMPLE 4: (for-example (hz->midi '(100 200 300 400) :round 0.5)
:number 4 :number-per-line 1)
EXAMPLE 5: (for-example (hz->midi '(100 200 300 400)
:name t :round t)
:number 4 :number-per-line 1)
EXAMPLE 6: (for-example (hz->midi '(100 200 300 400)
:name t)
:number 4 :number-per-line 1)
EXAMPLE 7: (for-example (hz->midi '(100 200 300 400) :base 415)
:number 4 :number-per-line 1)
(in-parallel structure1 structure2 ...)
Returns an instance of the class SOME-PARALLEL. The note structures included in parallel are interpreted to occur at the same time. An indefinite number of structures can be specified to occur in parallel. Structures which can be used in parallel include structures resulting from A-NOTE, A-REST, A-DELAY, IN-SEQUENCE, or IN-PARALLEL. A structure could also be the name of a section.
Example 1 uses two notes in parallel.
Example 2 has two sequences in parallel:
If sections S1, S2, and S3 exist, three sections in parallel could be expressed as in example 3.
IN-PARALLEL can be used in defining NOTE STRUCTURES, STRUCTURED SECTIONS, and NOTE SECTIONS.
EXAMPLE 1: (fill-template
structured-section
section1 200
(in-parallel (a-note 2 c3 mf 1) (a-note 1 c#3 f 2)))
EXAMPLE 2: (fill-template
structured-section
section1 200
(in-parallel (in-sequence (a-note 1 60 mf 1)
(a-rest 3)
(a-note 1 67 mf 1))
(in-sequence (a-note 2 67 mf 1)
(a-note 1 60 mf 1))))
EXAMPLE 3: (fill-template
structured-section
section1 200
(in-parallel s1 s2 s3))
(in-sequence structure1 structure2 ...)
Returns an instance of the class SOME-SEQUENCE. The note structures included in the sequence, when the sequence is used, are interpreted to occur one after another (in sequence). Note structures used in sequence can be made with A-NOTE, A-REST, A-DELAY, IN-SEQUENCE,or IN-PARALLEL. A structure could also be the name of a section. An indefinite number of structures can be included in sequence (example 1).
In example 2, two sequences are ordered in parallel. When they are both finished, the final note occurs.
IN-SEQUENCE can be used in defining NOTE STRUCTURES, STRUCTURED SECTIONS, and NOTE SECTIONS.
EXAMPLE 1: (fill-template
structured-section
section1 200
(in-sequence (a-note 1 60 mf 1)
(a-rest 3)
(a-note 1 67 mf 1)))
EXAMPLE 2: (fill-template
structured-section
section1 200
(in-sequence
(in-parallel (in-sequence (a-note 1 60 mf 1)
(a-rest 3)
(a-note 1 67 mf 1))
(in-sequence (a-note 2 67 mf 1)
(a-note 1 60 mf 1)))
(a-note 5 c3 f 1)))
input
A dialog box, such as the one for data section, must be filled with text.
Numbers may be entered.
Symbols may be used. Symbols may include the names of objects defined within the environment of the AC Toolbox. Symbols may also be one of several predefined symbols for potentially useful quantities such as pitch and dynamics.
The available dynamic symbols are:
ppp pp p mp mf f ff fff
Dynamics may also be expressed with MIDI velocity values (0-127).
Pitches are represented either by MIDI note numbers (0 - 127) or symbols containing the pitch class and octave. The octave of middle C is considered to be 4. The symbolic representation for middle C in the Toolbox is c4. A half tone higher is c#4 or df4. The lowest available pitch is c-1 and the highest is g9. Note that sharps are # and flats are f in this representation. Via the 'Preferences' dialog, it is possible to assign Midi note number 60 to the symbol c3. All other input symbols for pitch are then adjusted accordingly.
Pitches may be expressed using floating-point numbers: 60.5 is a quarter tone higher than 60. Floating-point output can be seen in various options for printing values. It can be heard if playback is done with QuickTime or Capybara/Pacarana as the chosen destination. Section data sent to FOMUS for formatting for use in a notation program can also use quartertones. For other output destinations and for Midi files, pitch is rounded to an integer value.
Lists may be used as input. A list is represented as a quote, a left-parenthesis, zero or more elements separated by a space, and a right parenthesis:
'(1 2 3)
is a list with three elements.
A function which produces an appropriate result can also be used as input. In Lisp, a function is a list without a quote. The first element in the list is the name of the function. If there are any other elements in the list, they represent data to which the function is applied.
(random-value 1 100)
Random-value is the name of the function. 1 and 100 are the data.
(random-choice '(c4 e4 f#4))
Random-choice is the name of the function. '(c4 e4 f#4) is a list used as a data.
Generators and tools are functions which may be used as input in a dialog box.
In most generators, if the input data contains one or more floating-point numbers, the output is a floating-point number. Otherwise the output is an integer. Some generators have keywords such as round or conversion controlling the conversion of output to integer values.
(random-value 40 80) produces integer values. (random-value 40.0 80) produces floating-point values. (random-value c4 (float g#4)) also produces floating-point values.
In a data section, if a single value is a list, it is considered to be a chord: '((60 64 67) (62 67 69)) represents 2 chords.
Rests are represented by negative values for the rhythm parameter.
(inside-osc rhythm value)
This tool can be used during the creation of OSC scores. It allows a synthdef argument to be updated during a current OSC event, e.g. frequency could be changed during a sound.
RHYTHM is a constant, generator, etc. which specifies a time value in seconds for making the next update. The first update happens when the OSC event is created. An OSC event is considered to be the event which is created when parameters which are not made with INSIDE-OSC are specified.
VALUE is a generator, list, etc. which produces the update values for changing a parameter inside an event.
The examples use synthdef sine1 which can be found in test osc synthdefs.rtf in Support/FileExamples.
Example 1 updates the frequency parameter of synthdef sine1 every 0.1 seconds. The frequency values are produced with generator WALK. The total duration of the event is between 1 and 3 seconds long. The event duration is articulated with an attack and decay.
Example 2 generates three of the OSC scores from Example 1 in parallel.
Example 3 shows how a rest between OSC events can be created with negative durations. One random duration between 2.0 and 4 seconds is chosen followed by one random rest between 1.0 and 2 seconds. Also, the rhythm for updating the freq parameter using INSIDE-OSC is chosen with a random value.
Example 4 triggers events according to a generator in the Start parameter of the OSC score.
Files made with INSIDE-OSC can be rendered, plotted, transformed, and used as an input for making a histogram. They cannot (yet) be filtered.
INSIDE-OSC also cannot be used when making an osc file from a section with SECTION->OSC.
EXAMPLE 1: (fill-template osc-score-object inside1
10 "sine1" nil nil nil 1 0
"dur" (rv 1.0 3)
"freq"
(inside-osc 0.1
(walk 1400 (rv -100 100.0) 1000 2000))
"amp" 0.1 "decay" 0.4)
EXAMPLE 2: (fill-template generate-parallel-osc-score-object
inside2 3 (rv 0.0 0.1) inside1)
EXAMPLE 3: (fill-template osc-score-object inside3 10 "sine1"
nil nil nil 1
0
"dur" (take 1 (rv 2.0 4) 1 (rv -1.0 -2))
"amp" 0.2
"freq"
(inside-osc (rv 0.2 1.5)
(rv 100.0 1000)))
EXAMPLE 4: (fill-template osc-score-object inside4
5 "sine1" nil nil nil 1 (rv 0.0 30)
"dur" (rv 5.0 10)
"freq"
(inside-osc (rv 0.5 1.5)
(walk (rv 200 800)
(rv -20 20) 100 1000))
"amp" 0.1)
installing csound
Csound5 is the redesigned version of the classical Csound software environment. When the AC Toolbox refers to Csound, Csound5 is assumed. The user should install it in /usr/local/bin. The installer available from SourceForge will install it in this location.
The Csound5 installer can be downloaded with example 1.
If Csound5 has not been installed, it is not possible to render Csound files or use the analysis programs such as pvanal.
The Manual button on the Csound File Options dialog assumes that the Csound manual is installed as:
/Library/Frameworks/CsoundLib.Framework/Resources/Manual/index.html
This is the location where some installers from SourceForge install it. If the manual is requested and not found at that location, the user will be asked to locate the index.html file for the manual.
Additional information about Csound can be accessed with example 2.
If errors occur rendering files in the AC Toolbox, check the default directories for soundfiles, etc. (found in the Csound File Options dialog).
EXAMPLE 1: (open-url "http://csound.sourceforge.net/")
EXAMPLE 2: (open-url "http://www.csounds.com/")
(interpolate thing1 thing2 number &key shape finish)
Returns a closure. When applied one value from an interpolation between THING1 and THING2 is returned. The interpolation takes place in the course of NUMBER of elements.
During each step of the interpolation, either an element from THING1 or an element from THING2 is returned. In the default case, the probability that an element from THING2 will be returned increases linearly during the interpolation.
THING1 and THING2 can be lists, stockpiles, note structures or anything else that DO-THE-NEXT-THING can deal with.
In example 1, either a or 1 is returned, b or 2, etc.
THING1 and THING2 do not have to have the same length. Each one cycles through its elements. If THING1 has 3 elements, and THING2 has 4, then either a or 1 is returned, b or 2, c or 3, a or 4, etc (example 2).
THING1 and/or THING2 could be a generator (example 3).
Instead of a linearly increasing probability that an element from THING2 will be chosen, any shape can be specified with the shape keyword (example 4).
In order to know how many interpolated values are needed to end the process at the end of THING1 or THING2, the FINISH keyword should receive the value 1 or 2. The number of values needed is printed in the Text Output window. The number of values requested could then be adjusted to correspond to this value if that is desired (example 5).
This generator is derived from an idea by Rainer Boesch which he realized in Cadenza.
EXAMPLE 1: (for-example (interpolate '(a b c d) '(1 2 3 4) 40)
:number 40 :number-per-line 4)
EXAMPLE 2: (for-example (interpolate '(a b c) '(1 2 3 4) 40)
:number 40 :number-per-line 3)
EXAMPLE 3: (for-example (interpolate (random-value 1 10)
'(a b c d e) 40)
:number 40)
EXAMPLE 4: (for-example (interpolate '(a b c d e)
'(1 2 3 4 5) 40
:shape sine-shape)
:number 40)
EXAMPLE 5: (for-example (interpolate '(a b c) '(1 2 3 4) 43
:finish 2)
:number 43 :number-per-line 4)
(interpolate-chords chord1 chord2 number-of-steps &key exponential conversion name)
Returns a closure. When applied, one chord expressed as a list of Midi note numbers is returned. The first application of the generator returns CHORD1. Each notenumber in CHORD1 is interpolated to the notenumber in the corresponding position in CHORD2 in the course of NUMBER-OF-STEPS.
By default, the interpolation is linear.
CHORD1 and CHORD2 should each be a list. This list could come from a stockpile or a generator but cannot change over time (example 1).
For a logarithmic interpolation, the keyword EXPONENTIAL should be bound to t (example 2).
Keyword NAME controls whether pitches are printed as numbers or as note names. When it is bound to t, note names are printed (example 3).
The conversion keyword is by default bound to #'round which will round off values to the nearest integer. Another Lisp function could be used to convert the results. #'truncate returns the whole number portion of a value and ignores everything after the decimal point. #'float returns a value as a floating point value. If conversion is bound to nil, no conversion will take place (examples 4-5).
EXAMPLE 1: (for-example
(interpolate-chords '(50 59 63) '(60 64 67) 10)
:number-per-line 1 :number 10)
EXAMPLE 2: (for-example
(interpolate-chords '(50 59 63) '(60 64 67) 10
:exponential t)
:number-per-line 1 :number 10)
EXAMPLE 3: (for-example
(interpolate-chords '(50 59 63) '(60 64 67) 10 :name t)
:number-per-line 1 :number 10)
EXAMPLE 4: (for-example
(interpolate-chords '(50 59 63) '(60 64 67) 10
:conversion nil)
:number-per-line 1 :number 10)
EXAMPLE 5: (for-example
(interpolate-chords '(50 59 63) '(60 64 67) 10
:conversion #'float)
:number-per-line 1 :number 10)
(interpolate-loops loop1 loop2 number-of-steps &key exponential conversion)
Returns a list starting with LOOP1 and ending with LOOP2. Between these two loops, each value in LOOP1 will be incremented or decremented in value until LOOP2 is reached. The first value of LOOP1 will change into the first value of LOOP2, the second of value of LOOP1 will change into the second value of LOOP2. The transition will occur in a NUMBER-OF-STEPS (this is the total number of steps including the values from the two loops) (examples 1-2).
LOOP1 and LOOP2 may be lists or stockpiles.
The transition is linear. To have an exponential transition, bind the keyword EXPONENTIAL with t (example 3).
The default situation is that no conversion of the resulting numbers takes place. If a conversion is desired for a linear interpolation, bind the keyword CONVERSION with a Lisp conversion function such as #'round which will round to the nearest integer or #'float which ensures that a number is a floating point number (example 4).
EXAMPLE 1: (for-example
(interpolate-loops '(1 1 1 1 1) '(.5 1 1.5 2 3) 10))
EXAMPLE 2: (plot
(interpolate-loops '(1 1 1 1 1) '(.5 1 1.5 2 3) 10))
EXAMPLE 3: (for-example
(interpolate-loops '(1 1 1 1 1) '(.5 1 1.5 2 3) 10
:exponential t))
EXAMPLE 4: (for-example
(interpolate-loops '(1 1 1 1 1) '(.5 1 1.5 2 3) 10
:conversion #'float))
(interpret-pulse produce-pulse &optional max-indispensability low high)
Returns a closure. When applied, it returns one interpreted value from a pulse (indispensability) interpreted either as a rhythmic value or some other value (e.g. a velocity). This generator does not thin the pulses (as is the case with generator produce-pulse).
The standard interpretation is for rhythmic values; 1 or -1 is produced depending if the pulse-value is positive or negative (examples 1-2). If the optional parameters are included, the interpretation is for velocity (or some other parameter). Negative pulse values are 0 and positive values are mapped between LOW-VALUE and HIGH-VALUE (examples 3-4).
The pulse value is determined by how indispensable it is and what the level of thinning is. Both of these concepts come from Clarence Barlow in CMJ 11,1.
This generator assumes that the value produced by parameter PRODUCE-PULSE is already thinned (if it indeed is to be thinned). This pulse value is taken as is and interpreted.
EXAMPLE 1: (for-example (interpret-pulse (thin '(5 0 3 4 1 2) 2))
:number 24 :number-per-line 6)
EXAMPLE 2: (for-example (interpret-pulse '(5 0 2 4 1 3))
:number 12 :number-per-line 6)
EXAMPLE 3: (for-example (interpret-pulse (thin '(5 0 2 4 1 3) 2)
5 50 90)
:number 12 :number-per-line 6)
EXAMPLE 4: (for-example (interpret-pulse '(5 0 2 4 1 3) 5 50 90)
:number 12 :number-per-line 6)
(interpret-sieve pattern sieve type)
Returns a list reflecting the application of a sieve to a list (pattern). Four types of interpretations of possible. Each of these interpretations assumes a rhythmic usage.
Type 1: The sieve indicates the index (in the pattern) of values that are on. All other values are out: i.e. made negative. The index of the first value in the pattern is 1 (example 1).
Type 2: The sieve indicates the index (in the pattern) of values that are on. The subsequent values are added to the preceding value to create a longer ON value and no rests (example 2).
Type 3: The inverse of 1. The sieve values are off and others are on (example 3).
Type 4. The inverse of 2. Only the notes which are not in the sieve are on. The duration lasts until the next 'off' note (example 4).
PATTERN and SIEVE can be lists or stockpiles.
For information regarding the application of sieves to durations, see the paper by Amiot etal in the 1986 ICMC Proceedings.
EXAMPLE 1: (for-example(interpret-sieve '(1 1 1 1) '(1 3) 1))
EXAMPLE 2: (for-example(interpret-sieve '(1 1 1 1) '(1 3) 2))
EXAMPLE 3: (for-example (interpret-sieve '(1 1 1 1) '(1 3) 3))
EXAMPLE 4: (for-example(interpret-sieve '(1 1 1 1) '(1 3) 4))
(invert)
Returns a closure which reverses the direction of intervals in the parameter being transformed. The first value is not changed.
The process of inversion is typically applied to pitch (example 1).
The result of inverting a chord has been defined as the inversion of each interval in the chord. The first value in the chord is not changed (example 2).
EXAMPLE 1: (show-transformation (invert) '(60 62 67 65 62))
EXAMPLE 2: (show-transformation
(invert)
'((60 64 67) (67 64 62) (46 76 45)))
(iterate function initial-value)
Returns a closure which will apply FUNCTION to the INITIAL-VALUE. Subsequent applications of the closure, apply FUNCTION to the previous result (examples 1-2).
EXAMPLE 1: (for-example (iterate #'1+ 1))
EXAMPLE 2: (for-example (iterate #'(lambda (x) (* x 2)) 1))
(join object1 object2...)
Two or more objects of the same type may be joined into one object of that type. The resulting object can be used anywhere that an object of that type can be used (example 1).
The objects can be stockpiles, shapes, masks, sections, etc.
When it is desirable that shapes and masks have the same number of values in the object made with join, the last argument should be t (example 2-3).
JOIN is the same operator which is available using the menu item from Methods.
EXAMPLE 1: (plot (join sine-shape expo-shape))
EXAMPLE 2: (plot (join line-shape sine-shape))
EXAMPLE 3: (plot (join line-shape sine-shape t))
(jump start step chunk &optional lower upper vary-step (loop 1))
Returns a closure. When applied, the first value is produced by START. The next value is START plus STEP. STEP is added again to this result until CHUNK number of values have been produced. At that time, a leap is made to a new value produced by START and the process repeats. Basically this generator takes some steps, jumps, and takes some more steps (examples 1-3).
LOWER and UPPER boundaries may be specified as optional parameters. Once a boundary is reached, a new value is chosen and the process starts over again (example 4).
If LOOP > 1, the previous CHUNK number of values are repeated. LOOP should be a positive number. The default value is 1 (example 5).
START, STEP, CHUNK, LOOP, LOWER, and UPPER may vary over time. START, STEP, CHUNK, and LOOP are chosen once per jump. LOWER and UPPER are updated with each value (examples 6-8).
If VARY-STEP is t, then the value for STEP is chosen each time instead of once per jump (examples 9-10). In examples 9-10, LOWER and UPPER are not used and therefore must be bound to nil if parameter VARY-STEP is to be bound to t.
This generator could also be used to generate index values for reading a list or stockpile, etc (examples 11-12).
JUMP can be used to 'slide' through a group of values. In Example 13, the start values for three note groups increase by 1 so that the first group is 1,2,3 and the second group is 2,3,4, etc.
EXAMPLE 1: (for-example (jump (random-value 1 20) 1 3))
EXAMPLE 2: (plot (jump (random-value 1 20) 1 3))
EXAMPLE 3: (for-example (jump (random-value 1 20) -1 4))
EXAMPLE 4: (for-example (jump (random-value 1 20)
(random-choice '(-1 1)) 3 1 20))
EXAMPLE 5: (for-example (jump (random-value 1 20) 1 3 1 20 nil 2))
EXAMPLE 6: (for-example (jump (random-value 1 20)
(random-choice '(-1 1))
(random-value 2 5) 1 20))
EXAMPLE 7: (plot (jump (random-value 1 100)
(plus-min (random-choice '(1 2 3)) .5)
(random-value 2 5) 1 100))
EXAMPLE 8: (plot (jump (random-value 1 18)
1 3 1 20 nil (random-value 2 4)))
EXAMPLE 9: (for-example (jump '(1 10 20) '(1 2 3) 4 nil nil t))
EXAMPLE 10: (for-example (jump (rv 1 20) (rv 1 3) 4 nil nil t))
EXAMPLE 11: (for-example (read-from (from 40 80)
(jump (random-value 1 41)
(random-choice '(-1 1))
3 1 41)))
EXAMPLE 12: (fill-template note-section section1 150 100
(read-from wilhelmus
(jump (random-value 1
(get-length wilhelmus))
(random-choice '(-1 1))
5 1 (get-length wilhelmus))))
EXAMPLE 13: (for-example (jump (walk 1 1) 1 3))
keyboard shortcuts
COMMAND-CLICK MAKE button
The object is specified rather than made. This means that the input specification is stored but the data is not evaluated. This can be useful if the objects are not specified in sequential order (i.e. an object is used in another object before is has been made.
ENTER
If the cursor is at the end of a Lisp expression in an edit window, e.g. the pane with the examples in a help window, the expression is evaluated.
NO LONGER SUPPORTED
Keyboard shortcuts involving CTRL-CLICK which were available in earlier versions of the AC Toolbox are no longer supported.
kyma
Kyma is a sound design language which produces code that runs on a Capybara or a Pacarana. Kyma sounds which have been downloaded to a Capybara or Pacarana can be controlled with the AC Toolbox. Check in the index for 'Midi output using a Capybara/Pacarana' for a description of this process.
(lehmer-choice stockpile &key a b m seed)
Returns a closure. When applied, a value is chosen from the stockpile (or list) using the lehmer-value generator. When the same seed is used, the same series of outputs is produced (examples 1-3).
Behavior is controlled by A,B, and M. These values may change over time.
The default values for the keywords are:
A pi
B 0.25
M 1.0
SEED 1
Bret Battey provides the following general description of the behaviors:
If m = 1:
- if a < 1 and b = 0, the result will always be an exponential decay from the seed to 0.
- if b > 0 and a = 0, the system resolves immediately to b
- when a + b < 1.0, x goes to a steady state
- when a + b > 1.0, simple periodicity arises
- the most complex behavior results when a > 1
For more information on pattern generation with this algorithm, see
Battey, B. (2004). "Musical Pattern Generation". Organised Sound, 9(2).
EXAMPLE 1: (for-example (lehmer-choice '(a b c d e f g h)))
EXAMPLE 2: (plot (lehmer-choice (from 1 100))
:plot nil)
EXAMPLE 3: (plot (lehmer-choice (from 1 100) :seed .5)
:plot nil)
EXAMPLE 4: (plot (lehmer-choice (from 1 100) :a .45 :b .5)
:plot nil)
EXAMPLE 5: (plot (lehmer-choice (from 1 100) :a 1.23 :b .92)
:plot nil)
(lehmer-value low high &key a b m seed)
Returns a closure. When applied, it will produce a value in the range LOW-HIGH using the Lehmer's Linear Congruential formula. While this formula is traditionally used to generate random numbers (given carefully selected arguments), it can also be used as a pattern generator. The default values for A, B, and M facilitate its use as a pattern generator.
Where X(n) is the seed, the algorithm implements this formula:
X(n+1) = a*X(n) + b mod m
The default values for the keywords are:
A pi
B 0.25
M 1.0
SEED 1
This generator is deterministic. Given the same input, it will always produce the same output. Changing the seed, changes the sequence of output values (examples 1-2).
Changing A, B, and/or M changes the behavior of the generator (examples 3-6).
Bret Battey provides the following general description of the behaviors:
If m = 1:
- if a < 1 and b = 0, the result will always be an exponential decay from the seed to 0.
- if b > 0 and a = 0, the system resolves immediately to b
- when a + b < 1.0, x goes to a steady state
- when a + b > 1.0, simple periodicity arises
- the most complex behavior results when a > 1
A, B, M, LOW, and HIGH may vary over time.
LOW and HIGH determine the type of the output. If they are both integers, the output is an integer. If one or more is a real number, the output is a real number.
For more information on pattern generation with this algorithm, see
Battey, B. (2004). "Musical Pattern Generation". Organised Sound, 9(2).
EXAMPLE 1: (plot (lehmer-value 1 100)
:plot nil)
EXAMPLE 2: (plot (lehmer-value 1 100 :seed .75)
:plot nil)
EXAMPLE 3: (plot (lehmer-value 40 80 :a .7 :b 0.0)
:plot nil)
EXAMPLE 4: (plot (lehmer-value 40 80 :a .9 :b 0.1)
:plot nil)
EXAMPLE 5: (plot (lehmer-value 40 80 :a .98 :b 0.4)
:plot nil)
EXAMPLE 6: (plot (lehmer-value 40 80 :a 1.23 :b 0.92)
:plot nil)
lilypond
LilyPond is an open source music notation program (example 1). It can be used in combination with FOMUS to produce sketches of notated musical material. The AC Toolbox can write section data to a FOMUS file and FOMUS in turn can produce a LilyPond file. This is done via the menu item 'File>Write FOMUS File'.
If used together with FOMUS, LilyPond should be installed in the Applications folder.
EXAMPLE 1: (open-url "http://lilypond.org")
(limit stockpile low high &key reject)
This tool returns a list containing part of a list or stockpile. It can return values that are between or outside LOW and HIGH. It can also just return values <= HIGH or >= LOW.
Example 1 returns the values from the list that are between (and including) LOW and HIGH.
Example 2 returns values from the list that are not between LOW and HIGH.
Example 3 binds HIGH to nil so only values >= LOW are returned.
Example 4 binds LOW to nil to only values <= HIGH are returned.
This tool could be used in combination with the various generators that select from a stockpile, such as all of the generators ending in -CHOICE.
Example 5 defines a stockpile with a scale.
Example 6 prints the generated values.
Example 7 chooses from the stockpile with RANDOM-CHOICE.
Examples 8-9 choose from part of the stockpile.
EXAMPLE 1: (for-example (limit (from 40 80) 60 70))
EXAMPLE 2: (for-example (limit (from 40 80) 60 70 :reject t))
EXAMPLE 3: (for-example (limit (from 40 80) 60 nil))
EXAMPLE 4: (for-example (limit (from 40 80) nil 60))
EXAMPLE 5: (fill-template generate-stockpile scale1 30
(walk 30 (random-value 1 3)))
EXAMPLE 6: (for-example scale1)
EXAMPLE 7: (for-example (random-choice scale1))
EXAMPLE 8: (for-example (random-choice (limit scale1 60 70)))
EXAMPLE 9: (for-example (random-choice (limit scale1 60 nil)))
(limit-range low high &optional modulo)
Returns a closure which limits the range of the parameter being transformed. LOW and HIGH are the limits.
If a parameter is less than LOW, MODULO is added to the parameter until it is within the range. By default, MODULO is 12.
If a parameter is higher than HIGH, MODULO is subtracted from the parameter until it is within the range.
Values between LOW and HIGH are not changed (example 1).
To use a different value for MODULO, specify a number as the optional third argument to LIMIT-RANGE (example 2).
If the distance between LOW and HIGH is less than MODULO, it may not be possible for a number to be squeezed into the range. In that case a warning message is given and the parameter value is not changed (example 3).
EXAMPLE 1: (show-transformation
(limit-range 60 72) '(50 60 62 72 75))
EXAMPLE 2: (show-transformation
(limit-range 60 72 2) '(50 60 62 72 75))
EXAMPLE 3: (show-transformation
(limit-range 60 61) '(50 60 62 72 75))
(line number-of-steps start finish &key conversion wrap)
LINE is a shortcut (abbreviation) for LINE-SEGMENT (example 1).
It returns the next point on a line. After NUMBER-OF-STEPS values, it starts at the beginning again.
See the help for LINE-SEGMENT for more information.
EXAMPLE 1: (plot (line 100 1 100))
(line-segment number-of-steps start finish &key conversion wrap)
Goes from START to FINISH in NUMBER-OF-STEPS (examples 1-3).
The default value for the keyword WRAP is nil. This indicates that after FINISH has been reached, the next value will be START. If WRAP is T, the current increment is added to START (example 4).
If results should be converted to integers, a conversion function should be indicated with keyword CONVERSION (examples 5-6).
EXAMPLE 1: (for-example (line-segment 20 1 20))
EXAMPLE 2: (for-example (line-segment 20 20 1))
EXAMPLE 3: (for-example (line-segment 10 1 10))
EXAMPLE 4: (for-example (line-segment 10 1 10 :wrap t))
EXAMPLE 5: (for-example (line-segment 20 1 7))
EXAMPLE 6: (for-example (line-segment 20 1 7 :conversion #'round))
(linear-choice stockpile &optional direction)
Returns a closure. When applied, one value from STOCKPILE is chosen using a linear distribution. This distribution primarily returns values with a lower index. The probability of choosing values with a higher index decreases linearly (examples 1-3).
By default, DIRECTION is 0 which favors lower values. If DIRECTION is 1, the probability density will increase linearly, favoring higher values (examples 4-6).
STOCKPILE may be a list, stockpile, etc.
DIRECTION may change over time (example 7).
EXAMPLE 1: (for-example (linear-choice '(a b c d e f g h i j)))
EXAMPLE 2: (plot (linear-choice (from 1 100 :step 4)))
EXAMPLE 3: (make-histogram (linear-choice (from 1 100)) :number 1000)
EXAMPLE 4: (for-example (linear-choice '(a b c d e f g h i j) 1))
EXAMPLE 5: (plot (linear-choice (from 1 100 :step 4) 1))
EXAMPLE 6: (make-histogram (linear-choice (from 1 100) 1) :number 1000)
EXAMPLE 7: (plot (linear-choice (from 40 60) (group '(0 1) 50)))
(linear-value low high &optional direction)
Returns a closure. When applied, one random value with a linear distribution is returned. A linear distribution favors lower values. The probability density decreases linearly (examples 1-3).
By default, DIRECTION is bound to 0 which favors lower values. If DIRECTION is bound to 1, higher values are favored and the probability density increases linearly (examples 4-6).
LOW, HIGH, and DIRECTION can change over time (examples 7-9).
The algorithm for a linear distribution produces 2 random numbers and returns the lower of the two. If DIRECTION is 1, the higher value is returned.
EXAMPLE 1: (for-example (linear-value 40 60))
EXAMPLE 2: (plot (linear-value 40 60))
EXAMPLE 3: (make-histogram (linear-value 1 100) :number 1000)
EXAMPLE 4: (for-example (linear-value 40 60 1))
EXAMPLE 5: (plot (linear-value 40 60 1))
EXAMPLE 6: (make-histogram (linear-value 1 100 1) :number 1000)
EXAMPLE 7: (plot (linear-value (line-segment 100 1 100) 100))
EXAMPLE 8: (plot (linear-value 1 (line-segment 100 20 100) 1))
EXAMPLE 9: (plot (linear-value 1 20 (group '(0 1) 50)))
(lisp expression)
This tool can be used to insert Lisp expressions into edit boxes in cases where the AC Toolbox error checking might otherwise report some error (such as that the expression is not an AC Toolbox object or generator).
EXPRESSION should be a valid Lisp expression (example 1). Note that example 1 is not written to use any of the existing example Csound orchestras but is just an example of how this tool can be used in a dialog.
EXAMPLE 1: (fill-template csound-score-object
score1 nil nil nil 1 13 1 0 1
(lisp (loop for x from 0 to 12
collect (expt 2 (/ x 12.0)))))
listener
A listener can be created using the menu item 'Other>Listener'. Lisp commands can be evaluated by typing them in this dialog. AC Toolbox tools can also be evaluated.
(load-sound-file &key (size 1000) (average t))
Returns a list containing values read from a 16-bit, mono AIFF of WAVE file.
Since the length of the list can become quite long if the file has a sampling rate of 44.1 kHz, it is often more practical to use groups of samples. SIZE governs the size of the group. If AVERAGE is true, the average of the absolute value of the group is returned (example 1). If AVERAGE is nil, the first value in each group is returned (example 2).
The default value of SIZE is 1000, which for a one second sound recorded at 44.1 kHz would return 44 values (example 3).
The default value for AVERAGE is t. Bind AVERAGE to nil if the values in the group should not be averaged.
The minimum and maximum values returned by this tool are printed in the Listener. This information could be used to map the values to some other range.
If long sound files are read, it make take some time to create a list of all of the values. These lists may be too long to be very useful.
The values returned by LOAD-SOUND-FILE correspond to instantaneous sample values or the amplitude envelope. They do not reflect the frequency content of the recorded signal. See Tutorial 20 in the AC Toolbox tutorial for information about obtaining and using spectral information.
EXAMPLE 1: (plot (load-sound-file))
EXAMPLE 2: (plot (load-sound-file :average nil))
EXAMPLE 3: (plot (load-sound-file :size 1000))
loading definitions
To automatically include definitions, assignments, or forms to load files when the AC Toolbox is loaded, make a file containing these forms and select the file using the dialog produced with the menu-item 'Choose Init File'.
Previous environments can also be loaded by including a form such as
(load "my-old-environment.act")
in this file.
"my-old-environment.act" should be the name of the environment file you want
to include. The filename should include the complete path to the file.
(logist start growthfactor maxpop giant &key first)
Returns a closure. When applied returns the next value of a dynamical system, described by the following formula:
x(n+1)=mu*x(n)*{1-x(n)}
This formula describes the growth of a population. It accounts for the effects of overpopulation and a shortage of food on the size of the next generation.
The output is the size of the population. The maximum output value is MAXPOP, the minimum is zero.
START sets the fraction of the maximum size of the population possible. This maximum size is determined by MAXPOP. GROWTHFACTOR controls the behaviour of the system.
The parameter GIANT determines after how many iterations the value is returned. This can be useful for filling a list with a small number of values describing the behaviour of the system over a longer period.
This system is capable of chaotic behaviour. This is controled by the parameter GROWTHFACTOR. The value of GROWTHFACTOR must be a number between 0.0 and 4.0. For values smaller than about 3.7 the system is periodic (example 1).
For higher values for GROWTHFACTOR, the system is chaotic (example 2).
To map the output of this function to useful values, use CONVERT (example 3).
GROWTHFACTOR may vary over time (example 4).
The initial value for START is not returned. If the initial value should be returned as the first result of the generator, keyword FIRST should be bound to t (examples 5-6).
This generator was contributed by Gijs de Bruin.
EXAMPLE 1: (plot (logist 0.1 3.4 100 1)
:number 50 :plot nil)
EXAMPLE 2: (plot (logist 0.1 3.8 100 1)
:number 50 :plot nil)
EXAMPLE 3: (for-example (convert (logist 0.1 3.8 100 1) 50 c2 c5))
EXAMPLE 4: (plot (logist 0.1 (group (line-segment 10 4.0 3.0) 10)
100 1)
:plot nil)
EXAMPLE 5: (for-example (logist 0.1 3.4 100 1))
EXAMPLE 5: (for-example (logist 0.1 3.4 100 1 :first t))
(logist2 x y growthfactor maxpop giant &key eye xy first)
Returns a closure. When applied returns the next value of a dynamical system, described by the following formula:
x(n+1)=mu*x(n)*{1-x(n)-y(n)}
y(n+1)=mu*x(n)*y(n)
This formula describes the growth of two populations. One population is the hunter, the other the prey. The size of the both populations depend on each other.
The default output is the size of the X-population. By using the keyword EYE, the size of the Y-population is returned. Both values will be returned in a list by using the keyword XY.
X and Y set the fraction of the maximum size of the populations possible. This maximum size is set by MAXPOP. GROWTHFACTOR controls the behaviour of the system.
The parameter GIANT determines after how many iterations the value is returned. This can be useful for filling a list with a small number of values describing the behaviour of the system over a longer period.
This system is capable of chaotic behaviour. This is controlled by the parameter GROWTHFACTOR. The value of GROWTHFACTOR must be a number between 0.0 and 4.0. For values smaller than about 3.4 the system is periodic (example 1).
For higher values for GROWTHFACTOR, the system is chaotic (examples 2-5).
To map the output of this function to useful values, use CONVERT (example 6).
GROWTHFACTOR may vary over time (example 7).
The initial values for X and Y are not returned. If the initial values should be returned as the first result of the generator, keyword FIRST should be bound to t (examples 8-9).
This generator was contributed by Gijs de Bruin.
EXAMPLE 1: (plot (logist2 0.1 0.1 3.0 100 1) :plot nil)
EXAMPLE 2: (plot (logist2 0.1 0.1 3.6 100 1) :plot nil)
EXAMPLE 3: (plot (logist2 0.1 0.1 3.6 100 1 :eye t) :plot nil)
EXAMPLE 4: (plot (logist2 0.1 0.1 3.6 100 1 :xy t) :number 500)
EXAMPLE 5: (plot (logist2 0.1 0.1 3.0 100 1 :xy t) :number 500)
EXAMPLE 6: (for-example (convert (logist2 0.1 0.1 3.6 100 1) 100 c2 c5))
EXAMPLE 7: (plot (logist2 0.1 0.1 (group (line-segment 10 4.0 3.0) 10)
100 1)
:plot nil)
EXAMPLE 8: (for-example (logist2 0.1 0.1 3.0 100 1))
EXAMPLE 9: (for-example (logist2 0.1 0.1 3.0 100 1 :first t))
(lookup to-produce-value some-table &key interpolate)
Returns a closure. When applied, it returns one value from SOME-TABLE which should be a list or stockpile defined by MAKE-LOOKUP-TABLE (example 1) or CONVERT-TO-LOOKUP-TABLE (example 7).
TO-PRODUCE-VALUE can be a constant, a list, a stockpile, or a generator. The value it produces is used as a key to search for an entry in SOME-TABLE. If the key is found, the corresponding value associated with the key in the table is returned (examples 1-2).
If the key is a number and it is not found, the value associated with the nearest key (in value) is returned. If the key is not a number and it is not found, an error is signaled.
MAKE-LOOKUP-TABLE returns a list of values appropriate for a lookup table. This list may also be used in constructing a stockpile. The values which follow should be a key and then some other value to be returned if the key is looked up.
E.g.
(make-lookup-table 1 60 2 50 3 40 10 100 20 45))
has 1,2,3,10, and 20 as the keys
and 60,50,40,100, and 45 as the associated values.
If 1 is looked up in this table, 60 will be returned.
If 2 is looked up, 50 will be returned, etc.
5 will return the number associated with the nearest key without interpolation. In this case, it will be 40.
If interpolation is desired, the keyword INTERPOLATE should be bound to t. Numbers which are not found in the table will be interpolated between the nearest values (examples 3-4).
The keys in the lookup table do not need to be numbers (examples 5-6).
CONVERT-TO-LOOKUP-TABLE makes a lookup table by converting an object such as a shape into the values for the table (examples 7-8).
(convert-to-lookup-table object low-key high-key low-value high-value)
The object is mapped to be between LOW-VALUE and HIGH-VALUE. The table contains entries for keys ranging from LOW-KEY to HIGH-KEY. Each of these keys is associated with a value mapped from the OBJECT.
E.g. (convert-to-lookup-table line-shape 1 10 40 80)
would produce a lookup table with the following pairs of keys and values:
KEY VALUE
1 40
2 44
3 49
4 53
5 58
6 62
7 67
8 71
9 76
10 80
LOOKUP is a one way to relate two parameters. The values for the first parameter could be stored in a stockpile. That stockpile could be used to look up values for the second parameter.
Example 9 generates values for pitch and stores them in a stockpile. This stockpile is used for the pitch parameter in the data section (example 10). The pitches are related to the velocity values using a lookup table. The table is defined to have keys from 40 to 80 (the possible pitches). The values for the keys will decrease from 100 to 40. This means that the low keys (the pitches) have higher (velocity) values than the high keys. The values decrease according to the line-shape.
A lookup table could also be defined with only a few values (example 11). Three keys will be used: 40, 60, and 80. Values near 40 receive one value, near 60 another, and near 80 a third value (example 12).
To perform lookup operations and return generators instead of numeric values, see SELECT-GENERATOR-BY-NUMBER and SELECT-GENERATOR-BY-CONDITION.
EXAMPLE 1: (fill-template construct-stockpile table1
(make-lookup-table 1 60 2 50 3 40 10 100 20 45))
EXAMPLE 2: (for-example (lookup '(1 2 3 4 5 6 7 8 9 10 15 25)
table1)
:number 12)
EXAMPLE 3: (plot (lookup (from 1 20) table1)
:number 20)
EXAMPLE 4: (plot (lookup (from 1 20) table1 :interpolate t)
:number 20)
EXAMPLE 5: (fill-template construct-stockpile table2
(make-lookup-table 'sax1 10.33 'flute 9.66))
EXAMPLE 6: (for-example (lookup '(sax1 flute) table2))
EXAMPLE 7: (fill-template construct-stockpile table3
(convert-to-lookup-table line-shape
40 80 100 40))
EXAMPLE 8: (plot table3)
EXAMPLE 9: (fill-template generate-stockpile pitches 100
(random-value 40 80))
EXAMPLE 10: (fill-template data-section ds1 100 100 1
pitches (lookup pitches table3) 1 0)
EXAMPLE 11: (fill-template construct-stockpile table4
(make-lookup-table 40 100 60 64 80 40))
EXAMPLE 12: (fill-template data-section ds2 100 100 1
(from 40 80) (lookup (from 40 80) table4) 1 0)
(loop-through sequence &key start backwards low high step)
Returns a closure that returns successive values from a sequence (list, vector, or stockpile). After all values have been returned once, it loops around to the beginning of the sequence (example 1).
Keyword START is an offset for finding the first value to be returned. By default it is 0. When the offset is 2, the first two values are skipped and the loop begins with the third value (example 2).
Keyword BACKWARDS indicates the direction to loop through the sequence. The default is nil (which means it will not loop through the sequence backwards). To loop through backwards, it should be T (example 3).
Keywords LOW and HIGH can be used to map the value from the loop to another range. Both LOW and HIGH must be specified if the value is to be mapped. LOW and HIGH may change over time (examples 4-5).
Keyword STEP is the increment used to read from the list. The default value is 1 which means every value is read. If STEP is 2, values 1,3,5 ... are read (examples 6-7).
EXAMPLE 1: (for-example (loop-through '(a b c d)))
EXAMPLE 2: (for-example (loop-through '(a b c d) :start 2))
EXAMPLE 3: (for-example (loop-through '(a b c d) :backwards t))
EXAMPLE 4: (plot (loop-through '(1 3 5 7 9) :low 1 :high 50))
EXAMPLE 5: (plot (loop-through '(1 3 5 7 9)
:low (line-segment 100 1 9)
:high (line-segment 100 9 50)))
EXAMPLE 5: (for-example (loop-through '(a b c d e f g h i j k)
:step 2))
EXAMPLE 6: (for-example (loop-through '(a b c d e f g h i j k)
:backwards t :step 2))
(lorenz x y z sigma R B giant &key eye zet xy xyz (stepsize 0.01) first)
Returns a closure. When applied returns the next value of a dynamical system, described by the following formula:
x'=sigma*(y-x)
y'=Rx-y-xz
z'=xy-Bz
x = x + (x'*stepsize)
y = y + (y' * stepsize)
z = z + (z' * stepsize)
The default output variable is X. Y and Z are returned by using the keywords EYE and ZET, respectively. A list with the values for X and Y is returned by using the keyword XY. All variables will be returned in a list by using the keyword XYZ.
The parameter GIANT determines after how many iterations the value is returned. This can be useful for filling a list with a small number of values describing the behaviour of the system over a longer period.
X, Y, and Z set the initial conditions. SIGMA, R, and B control the behaviour of the system. In general, higher values for R and B increase the chaos, while the same is true for lower values for SIGMA (examples 1-5).
The phase plot of the system is obtained by example 6.
It is not easy to predict the maximum and minimum of the output values. To map the output of this function to useful values, use CONVERT (example 7).
The initial values for X, Y, and Z are not returned. If the initial values should be returned as the first result of the generator, keyword FIRST should be bound to t (examples 8-9).
See Bidlack,R. (1992). "Chaotic Systems as Simple (but Complex) Compositional Algorithms". Computer Music Journal, 16(3).
This generator was contributed by Gijs de Bruin.
EXAMPLE 1: (plot (lorenz 1.0 1.0 1.0 10 28 1.0 10)
:number 300 :plot nil)
EXAMPLE 2: (plot (lorenz 1.0 1.0 1.0 10 28 3/8 10)
:number 300 :plot nil)
EXAMPLE 3: (plot (lorenz 1.0 1.0 1.0 10 28 5.2 10)
:number 300 :plot nil)
EXAMPLE 4: (plot (lorenz 1.0 1.0 1.0 2 28 3/8 10)
:number 300 :plot nil)
EXAMPLE 5: (plot (lorenz 1.0 1.0 1.0 10 40 3/8 10)
:number 300 :plot nil)
EXAMPLE 6: (plot (lorenz 0.1 0.1 0.1 10 28 3/8 1 :xyz t)
:number 3000)
EXAMPLE 7: (for-example
(convert (lorenz 1.0 1.0 1.0 10 28 3/8 10) 100 c2 c5))
EXAMPLE 8: (for-example
(lorenz 1.0 1.0 1.0 10 28 1.0 10))
EXAMPLE 9: (for-example
(lorenz 1.0 1.0 1.0 10 28 1.0 10 :first t))
(major start)
Returns a closure. When applied, a note number corresponding to the next value in a major scale is generated. The first value in the series is START. The series could continue indefinitely (examples 1-2).
EXAMPLE 1: (for-example (major 60) :number 8)
EXAMPLE 2: (for-example (major 55) :number 8)
(make generator)
MAKE applies a generator. If the result is a symbol, it then evaluates the produced result. Otherwise the result is returned. This is useful for instance if you want to make a choice among object names with a generator and then evaluate the name to get the object itself to use as input to a function.
Assuming the existence of two masks - MASK1 and MASK2 - a choice between them can be made for use in CONVERT (example 1).
It is also useful if you want only one value from a generator and do not want that value to change over time (example 2).
In example 2, a lower boundary and an upper boundary are chosen and used to determine all values.
EXAMPLE 1: (plot
(convert (make (random-choice '(mask1 mask2))) 100 1 100))
EXAMPLE 2: (for-example (random-value (make (random-value 1 40))
(make (random-value 50 100))))
(make&sort number generator &optional predicate)
Returns a list produced by applying the GENERATOR a NUMBER of times. The list is sorted in ascending order. The primary use of this tool is for making Csound or OSC files (example 1).
To sort the list in a different way, supply a predicate to use during the sort (example 2).
This generator is useful if a Csound or OSC score object generates (random) values for start times but also uses a mask or shape in another parameter. To make sure that the mask or shape is presented in the right order, the start times should be sorted. With MAKE&SORT you can generate values and then sort them.
The Csound score produced by example 3 can be rendered with test csound.orc in Support/FileExamples.
The source code for the synthdef sine1 (used in example 4) can be found in test osc synthdefs.rtf in Support/FileExamples.
MAKE&SORT can be abbreviated to MS (example 5).
EXAMPLE 1: (for-example (make&sort 10 (random-value 1 50)))
EXAMPLE 2: (for-example (make&sort 10 (random-value 1 50) #'>))
EXAMPLE 3: (fill-template csound-score-object
score1 "f1 0 8192 10 1
f2 0 8192 20 2 1" nil nil 1 20 1
(make&sort 20 (random-value 0.0 10))
(random-value 1.0 2)
5000
(convert expo-shape 20 200.0 400))
EXAMPLE 4: (fill-template osc-score-object osc-score1
20 "sine1" nil nil nil 1
(make&sort 20 (random-value 0.0 10))
"dur" (random-value 1.0 2)
"amp" 0.2 "freq"
(convert expo-shape 20 200.0 400))
EXAMPLE 5: (fill-template osc-score-object osc-score1
20 "sine1" nil nil nil 1
(ms 20 (random-value 0.0 10))
"dur" (random-value 1.0 2)
"amp" 0.2 "freq"
(convert expo-shape 20 200.0 400))
(make-chord source-object size-object &key block pitch-class stop allow-repeats limit)
Returns a closure. A chord is a list of note numbers in either a data section or a note section. This closure, when applied, will produce a list of note numbers that could be used as chords for either of those two types of sections.
SOURCE-OBJECT can be a list, stockpile, generator etc. capable of providing numerical values. These values are grouped in succession to produce a chord. If SOURCE-OBJECT is a list and each chord should have 4 values, each successive 4 values are taken from the list. If need be, the closure will wrap around to the beginning of list to get more values.
SIZE-OBJECT indicates the number of pitches to be included in the chord (list). It may be a constant, generator, stockpile, etc. (examples 1-2).
Keyword BLOCK will prevent certain intervals from being present in a chord. To do this, BLOCK should be bound to an interval or a list of intervals. These intervals will be blocked. Before a value is included in a chord, it is checked to see that it does not create a forbidden interval. Intervals are expressed as a number of semitones.
Some of the chords in example 3 will probably contain a the same pitch more than once.
The chords in example 4 will not contain any pitch doublings, since the unison is blocked.
The chords in example 5 will not contain any unisons or minor thirds.
If unison intervals are blocked, it is still possible that a chord would contain an octave. To prevent this, values should be reduced to their pitch class before the intervals are examined. This can done by binding keyword PITCH-CLASS to t (examples 6-7).
If one or more intervals are being blocked, it is the responsibility of the user to make sure that a chord of the desired size can actually be created without using the blocked intervals. The Toolbox will give up after trying STOP number of times (examples 8-9).
If successive chords should not contain common pitches, bind ALLOW-REPEATS to nil. This will prevent the selection of any pitch used in the previous chord. If this is not possible, the Toolbox will give up after STOP number of attempts.
The example 10 prevents repetitions in successive chords but allows a pitch to be used more than once within a chord. The example 11 also blocks the repetition of a pitch within a chord.
Keyword LIMIT can limit the range of the chord to be within ±limit steps of the first value chosen for the chord. The first value chosen for the chord is the last one listed in the printed representation of the chord (examples 12-14). If a value cannot be found within the requested limits, the Toolbox will stop trying after STOP number of attempts.
SOURCE-OBJECT, SIZE-OBJECT, and LIMIT may vary over time.
Example 15 uses MAKE-CHORD in a data-section.
EXAMPLE 1: (for-example (make-chord '(60 62 64 65 67 69 71) 3))
EXAMPLE 2: (for-example (make-chord (random-value 40 80)
(random-value 2 4)))
EXAMPLE 3: (for-example (make-chord (random-value 60 72) 4))
EXAMPLE 4: (for-example
(make-chord (random-value 60 72) 4 :block 0))
EXAMPLE 5: (for-example
(make-chord (random-value 60 72) 4
:block '(0 3)))
EXAMPLE 6: (for-example
(make-chord (random-value 48 72) 4 :block 0
:pitch-class t))
EXAMPLE 7: (for-example
(midi->notename
(make-chord (random-value 48 72) 4 :block 0
:pitch-class t)))
EXAMPLE 8: (for-example
(make-chord (rv 60 62) 4 :block 0))
EXAMPLE 9: (for-example
(make-chord (rv 60 62) 4 :block 0 :stop 500))
EXAMPLE 10: (for-example
(make-chord (rv 60 65) 3 :allow-repeats nil))
EXAMPLE 11: (for-example
(make-chord (rv 60 65) 3 :block 0 :allow-repeats nil))
EXAMPLE 12: (for-example
(make-chord (rv 40 80) 4 :block 0 :limit 6))
EXAMPLE 13: (for-example
(make-chord (rv 40 80) 4 :block 0
:limit (line 20 3 12)))
EXAMPLE 14: (plot
(make-chord (rv 40 80) 4 :block 0
:limit (line 100 3 12)))
EXAMPLE 15: (fill-template
data-section section1 400 20 1
(make-chord (random-value 48 72) 3 :block '(0 4 7)
:pitch-class t)
mf 1 0)
(make-conditional-table
entry possibilities
entry possibilities
...)
Constructs a table for use with transition. An ENTRY is a list of one or more previous values. POSSIBILITIES is a list of elements and their probabilities that could follow the entry.
Any number of entries and possibilities can be made. Traditionally probability is expressed as a value between 0 and 1. 0 is never. 1 is always. In this tool, probability can be any positive value and will be scaled to the proper range.
Example 1 constructs a first-order table, i.e. that one previous value is examined. If the previous value is A, then the next value is either B (30% probability) or C (70% probability). If the previous value is B, then C will always follow. If the previous value is C, then either A or B will follow.
Examples 2-3 show using a conditional table with the generator TRANSITION.
See the help for TRANSITION for more information.
EXAMPLE 1: (for-example
(make-conditional-table
'(a) '(b .3 c .7)
'(b) '(c 1)
'(c) '(a .5 b .5)))
EXAMPLE 2: (for-example
(transition (make-conditional-table
'(a) '(b .3 c .7)
'(b) '(c 1)
'(c) '(a .5 b .5))))
EXAMPLE 3: (for-example
(transition (make-conditional-table
'(a) '(b 1 c 3)
'(b) '(c 1)
'(c) '(a 5 b 2))))
(make-histogram sequence-or-function &key title print number replace round min max)
If SEQUENCE-OR-FUNCTION is a sequence (list or vector), a histogram is drawn in a window reflecting the contents of the sequence. It is assumed that the sequence will only contain numbers (example 1).
If keyword PRINT is bound to t, the values and their frequency of occurence are printed in a window instead of graphed (example 2).
If SEQUENCE-OR-FUNCTION is a lexical closure (a generator), a histogram is drawn reflecting the result of applying that closure a number of times (example 3). The default number of times is 100. This can be changed with the key word NUMBER (example 4).
It is assumed that the closure will only produce numbers.
Keyword ROUND can be bound to a number which is used as the unit to quantize values before the histogram is made (examples 5-7).
Keyword REPLACE determines if the previous histogram window will be closed after a new one is made (example 8).
The default value for REPLACE is specified in the Preferences dialog.
Keyword TITLE allows a string to be used to give the window a title (example 9).
Normally the representation is scaled to have the lowest value on the left and the highest value on the right. If other boundaries are desired, they can be specified with MIN and MAX (example 10). If the actual minimum value < MIN or the actual maximum value is > MAX, the actual value is used (example 11).
EXAMPLE 1: (make-histogram '(1 2 1 1 1 2 2 2 1 2 3 4 5))
EXAMPLE 2: (make-histogram '(1 2 1 1 1 2 2 2 1 2 3 4 5) :print t)
EXAMPLE 3: (make-histogram (random-choice '(1 2 3 4 5)))
EXAMPLE 4: (make-histogram (random-choice '(1 2 3 4 5)) :number 200)
EXAMPLE 5: (make-histogram (rv 1.0 10))
EXAMPLE 6: (make-histogram (rv 1.0 10) :round 1)
EXAMPLE 7: (make-histogram (rv 1.0 10) :round 0.5)
EXAMPLE 8: (make-histogram (rv 1 20) :replace t)
EXAMPLE 9: (make-histogram (noise-value 100 1 100 -1.5)
:title "Pink/Brown Noise")
EXAMPLE 10: (make-histogram (rv 40 80) :min 1 :max 100)
EXAMPLE 11: (make-histogram (rv 1 100) :min 40 :max 80)
(make-lookup-table key value key value ...)
MAKE-LOOKUP-TABLE returns a list of values appropriate for a lookup table. This list may also be used in constructing a stockpile. The values which follow should be a key and then some other value to be returned if the key is looked up (examples 1-2).
E.g.
(make-lookup-table 1 60 2 50 3 40 10 100 20 45)
has 1,2,3,10,and 20 as the keys
and 60,50,40,100,and 45 as the associated values.
If 1 is looked up in this table, 60 will be returned.
if 2 is looked up, 50 will be returned, etc.
A lookup table is used by the generator LOOKUP.
For a different method for making a lookup table, see CONVERT-TO-LOOKUP-TABLE.
EXAMPLE 1: (fill-template construct-stockpile table
(make-lookup-table 1 60 2 50 3 40 10 100 20 45))
EXAMPLE 2: (for-example
(lookup '(1 2 3 4 5 6 7 8 9 10 15 25)
table)
:number 12)
(make-many-variants names object &rest to-make)
This tool will generate one or more variants of OBJECT. It is intended for use in the Listener or in an editor window.
NAMES should be a list of symbols to use as the names for the variants.
Example 1 can be used to define a stockpile. Example 2 creates three variants of this stockpile which are called STOCK1B, STOCK1C, STOCK1D. When the expression is evaluated, the names of these new stockpiles will appear in the Objects dialog.
Any AC Toolbox object can be used as OBJECT, though it only makes sense if the input specification involves some kind of random values.
It is also possible to remake one or more existing objects before making the variant. If an object is remade, the original values are lost. Example 3 can be used to define a data section which uses the values of STOCK1 for pitch. Rhythm is also derived from the values of STOCK1. Lower pitches will have longer durations. Example 4 generates 2 new sections which are variants of DS1. Before each variant is generated, STOCK1 is remade.
Any number of objects can be remade but only one object can be varied (examples 5-7).
EXAMPLE 1: (fill-template generate-stockpile stock1 20 (random-value 40 80))
EXAMPLE 2: (make-many-variants '(stock1b stock1c stock1d) stock1)
EXAMPLE 3: (fill-template data-section ds1 100 20
(otf 1.0 / stock1 * 100) stock1 f 1)
EXAMPLE 4: (make-many-variants '(ds1b ds1c) ds1 stock1)
EXAMPLE 5: (fill-template generate-stockpile stock2 20
(random-choice '(pp p f ff)))
EXAMPLE 6: (fill-template data-section ds2 100 20
(otf 1.0 / stock1 * 100) stock1 stock2 1)
EXAMPLE 7: (make-many-variants '(ds2b ds2c) ds2 stock1 stock2)
(make-note-function duration-object pitch-object velocity-object channel-object)
Returns a closure. When applied, one note (as an object for a note section) is produced. The input parameters may be single values, sequences, or generators (examples 1-2).
EXAMPLE 1: (fill-template note-section note1 150 20
(make-note-function 1 '(60 64 67) '(96 64) 1) 0)
EXAMPLE 2: (fill-template note-section note2 150 20
(make-note-function (random-value 1 10)
(major 60)
(random-value 50 90)
(random-value 1 2)) 0)
(make-permutation elements &key number length)
Returns a list of all possible permutations of the elements in ELEMENTS. ELEMENTS is usually a list or a stockpile (example 1).
Each permutation is also a list.
The number of possible permutations of a series of elements is the factorial of the number of elements. For example, four elements have 24 possible combinations.
The following table shows that the number of possible combinations increases very quickly as the number of elements grows:
elements combinations
2 2
3 6
4 24
5 120
6 720
7 5040
8 40320
9 362880
10 3628800
11 39916800
12 479001600
Unless the AC Toolbox has an exceptionally large stack size, creating all 479 million combinations of twelve elements is probably not a practical activity. Permutations of up to seven or eight elements seem to fit into a standard AC Toolbox memory partition.
If some permutations of a larger number of elements is desired, the keyword NUMBER can be set to the number of permutations desired. This allows that NUMBER of permutations to be created even though it is practically impossible to produce all permutations of all the elements (example 2).
Note that the permutations are constructed according to a fixed algorithm. Each time a permutation is made with the same elements, the same permutation results. If a different order of permutations is desired, the permutation should be read with a generator such as SERIES-CHOICE which could read the permutations in a different order (example 3).
A different group or order of permutations can also be made by putting the elements to be permuted in a different order (examples 4-5).
If a permutation should have a length smaller than the number of elements, use the keyword LENGTH. For example, if you want to permute 4 elements in groups of 3 (example 6)
See the help for the generator READ-PERMUTATION for examples of reading single elements from a permutation.
EXAMPLE 1: (for-example (make-permutation '(0 4 7)))
EXAMPLE 2: (for-example
(make-permutation '(1 2 3 4 5 6 7 8 9 10 11 12)
:number 10)
:number-per-line 1)
EXAMPLE 3: (for-example
(series-choice (make-permutation '(1 2 3 4)))
:number 24 :number-per-line 1)
EXAMPLE 4: (for-example
(make-permutation '(4 1 2 3))
:number-per-line 1)
EXAMPLE 5: (for-example
(make-permutation (rearrange-stockpile '(1 2 3 4) 'shuffle))
:number-per-line 1)
EXAMPLE 6: (for-example
(make-permutation '(ppp p f ff) :length 3))
(make-unconditional-table element probability element probability ...)
Constructs a table for use with transition. Any number of elements may be entered together with a corresponding probability of occurence. Traditionally probability is expressed as a value between 0 and 1. 0 is never. 1 is always. In this tool, probability can be any positive value and will be scaled to the proper range (examples 1-3).
See the help for TRANSITION for more information.
EXAMPLE 1:
(for-example
(make-unconditional-table 'this .4 'that .4 'is .2))
EXAMPLE 2:
(for-example
(transition
(make-unconditional-table 'this .4 'that .4 'is .2)))
EXAMPLE 3:
(for-example
(transition
(make-unconditional-table 'this 10 'that 5 'is 20)))
manipulating spectra
Spectra created with the programs SPEAR, Hetro, Audacity or Amadeus can be read into the AC Toolbox with the tool READ-SPECTRUM-FILE and used in a variety of ways.
In SPEAR, data should be exported using the 'text - partials' format. This will produce a text file.
For the Csound utility Hetro, the standard file format is used.
In Audacity a spectral plot should be exported as a text file.
In Amadeus, the spectrum can be saved as a text file (not importable).
When entered in the AC Toolbox, this data will be a static spectrum (one set of data for the entire sound). The peaks are sorted according to descending amplitude.
A list of pitches derived from this spectrum can be returned with SPECTRUM->PITCH. With this tool, the pitches can also be mapped to a different pitch space. If five pitches are requested, they will be the five pitches with the highest amplitudes.
A list of velocities derived from a spectrum can be returned with SPECTRUM->AMP. The velocities can be mapped to a different range. A list of frequencies can be made with SPECTRUM->FREQ.
A chord in the form of a parallel note structure can be created with SPECTRUM->STRUCTURE. A number of pitches from the spectrum will occur at the same time using their corresponding velocity values. The chord can be to a different pitch space. A duration and Midi channel for each member of the chord can be specified (or generated).
SPECTRUM->CHORD is a generator which will produce lists of pitches suitable for use as a chord in a data section. The size of the chord and the selection of peaks can change over time with this generator.
A table of information from a spectrum can be produced with SPECTRUM->WINDOW. For each peak, a frequency, floating-point Midi number, note name, amplitude, and velocity value will be displayed.
The number of peaks returned by READ-SPECTRUM-FILE can be queried with PEAKS?.
To read in a spectral analysis that changes over time use READ-TRACKS-FILE.
Additional information can be found in the help for each of the mentioned tools or generators. Tutorial 20 in Using the AC Toolbox discusses spectral data and its use.
(map-text text &key block low high replace)
Converts TEXT which may be a string, list, or stockpile into a list of ASCII codes corresponding to the characters in TEXT (example 1).
Specific ASCII codes can be blocked from inclusion in the list using BLOCK which may a single value or a list of ASCII codes (examples 2-3).
The resulting list can be mapped to values between LOW and HIGH. Both of these keywords must be specified if the list is to be mapped (example 4).
If BLOCK, LOW and HIGH are all specified, the blocking of the ASCII occurs before the resulting list is mapped between LOW and HIGH (example 5).
Values which are blocked can be replaced with the value bound to REPLACE (example 6).
The value is replaced before the mapping between LOW and HIGH occurs (example 7).
In example 7, space (character 32) is replaced with character 105 (which is i). Since this occurs before the mapping, the highest value in the resulting list is the one corresponding to t and the lowest corresponds to e.
Values in a list are not stored in a case-sensitive manner (i.e. there is no difference between upper and lower case). Case-sensitive texts should be entered as a string (examples 8-9).
In a list or stockpile, punctuation marks such as : or , are not allowed. To use these punctuation marks, enter the text as a string.
A text can be read from a stockpile (examples 10-11).
This stockpile can be used to determine pitch in a section (example 12).
A string can be used in a stockpile for a case sensitive text (examples 13-14).
Spaces in a text could be used to produce rests by choosing a generator which produces negative values for rhythm if the ascii code is 32 (space) or less and another generator if that is not the case (example 15).
When a rest occurs in a section, the corresponding pitch value is discarded. That is the reason in the above example why spaces were not just removed but replaced. The value that is discarded is the one in the place of the space. The space was replaced was so that the mapping between LOW and HIGH would not be influenced by the low value of space.
Example 16 can read in a text file (which should not include punctuation marks).
A text file read in with READ-TEXT-FILE is not case-sensitive.
LOW and HIGH can vary over time, i.e. they may be generators, lists, etc. in addition to constant values (example 17).
EXAMPLE 1: (print-result (map-text "hi there"))
EXAMPLE 2: (print-result (map-text "hi there" :block 32))
EXAMPLE 3: (print-result (map-text "hi there" :block '(32 101)))
EXAMPLE 4: (print-result (map-text "hi there" :low 40 :high 80))
EXAMPLE 5: (print-result (map-text "hi there" :block 32
:low 40 :high 80))
EXAMPLE 6: (print-result (map-text "hi there" :block 32 :replace 0))
EXAMPLE 7: (print-result (map-text "hi there" :block 32 :replace 105
:low 40 :high 80))
EXAMPLE 8: (print-result (map-text '(Hi There)))
EXAMPLE 9: (print-result (map-text "Hi There"))
EXAMPLE 10: (fill-template specify-stockpile text1
this is a stockpile about
nothing in particular)
EXAMPLE 11: (for-example (map-text text1))
EXAMPLE 12: (fill-template data-section text-pitch1 100 47 1
(map-text text1 :low 40 :high 80) mf 1)
EXAMPLE 13: (fill-template specify-stockpile text2
"This is a Stockpile about Nothing in Particular" "")
EXAMPLE 14: (for-example (map-text text2))
EXAMPLE 15: (fill-template data-section text-pitch2
100 47
(act-if (map-text text2)
<= 32 (random-value -1.0 -3)
else (random-value 1.0 3))
(map-text text2 :block 32 :replace 105
:low 40 :high 80) mf 1)
EXAMPLE 16: (for-example (map-text (read-text-file)))
EXAMPLE 17: (plot (map-text "la la la la la la la la"
:low (line-segment 23 40 70)
:high 80))
(map-tracks analysis tracks channel &key min-vel max-vel filter)
This tool maps data derived from a sound analysis made either with SPEAR or the Hetro analysis utility of Csound. Both of these programs produce data containing frequency and amplitude tracks, though they use different methods to create this data.
This tool can map a selection of those tracks to Midi data suitable for use in a section. It can also filter out pitch repetitions and duplicates. To quantize the pitches, see READ-TRACKS-FILE.
ANALYSIS should either be the result of using READ-TRACKS-FILE or the name of a stockpile which was constructed with READ-TRACKS-FILE.
Sample Hetro files are available in Support/FileExamples. One is called 'test hetro (intel).het'. The other is 'test hetro (ppc).het'. Select the file whiich is appropriate for your processor.
Example 1 will read in a hetrodyne analysis file and map tracks 1 through 10 to Midi channel 1 without quantizing pitch or filtering repetitions. MAP-TRACKS is expects the clock unit in a structured section to be 1. A higher value will stretch the tempo of the event list.
SPEAR analysis files are available in folder Support/FileExamples.
Examples 2-3 construct a stockpile and use that stockpile in MAP-TRACKS. Select 'test spear voice.txt'. It contains 30 tracks with different durations and start times. The stockpile contains tracks with the pitch rounded to semitones.
Section2 is created by mapping tracks 1-30 from the analysis contained in stockpile voice1. The number of available tracks is printed in the Text Output window when a file is read. The clock unit in the example is 1 since the track data is expressed in milliseconds.
SPEAR partial track files contain partials which do no necessarily last for the duration of the sound. In SPEAR, it is possible to select, edit, and manipulate partials before exporting the partials as text. To see the partials included in the sample file 'test spear voice.txt', open that file in SPEAR. It can also be resynthesized in SPEAR.
TRACKS can have a constant, a list, or a vector as input. If the value is constant, one track will be mapped. If the value is a list or vector, the track numbers contained in the list or vector will be mapped (example 4).
MIDI-CHANNELS can be a constant, list, generator, etc. Each track will be assigned to the next available Midi channel (example 5).
The five tracks chosen in the above example will be assigned to Midi channels 1, 2, 3, and 4 respectively. If fewer channels are specified than tracks, the channel data will loop to provide new data.
Amplitude values from the analysis file are scaled to be velocity values in the range MIN-VEL to MAX-VEL. The default values are 20 and 64 (example 6).
The analysis tends to produce a lot of similar frequencies in succession. When these frequencies are mapped to pitch, particularly when the pitch is quantized to semi or quarter-tones, this produces a large number of repetitions of the same pitch. The analysis tends to produce a lot of data anyway since it is intended for sound resynthesis and not note synthesis (example 7).
One way to deal with the repetitions, is to bind FILTER to t. This removes all successive (or simultaneous) repetitions of the same pitch (examples 9-10). This filter uses a different method than the filter in READ-TRACKS-FILE. The filter in READ-TRACKS-FILE only filters within a track. In MAP-TRACKS, the tracks are turned into note data before they are filtered. This filter will filter pitches regardless of which track in which they originally occurred.
If the number of tracks in the track data are forgotten for whatever reason, use tool TRACKS? to return the number.(example 10).
EXAMPLE 1: (fill-template structured-section
section1 10
(map-tracks (read-tracks-file :type 'hetro) (from 1 10) 1))
EXAMPLE 2: (fill-template construct-stockpile
voice1 (read-tracks-file :type 'spear :round 1))
EXAMPLE 3: (fill-template structured-section section2 1
(map-tracks voice1 (from 1 30) 1))
EXAMPLE 4: (fill-template structured-section section3 1
(map-tracks voice1 (from 1 30 :step 2) 1))
EXAMPLE 5: (fill-template structured-section section4 1
(map-tracks voice1 '(1 3 10 15 30) '(1 2 3 4)))
EXAMPLE 6: (fill-template structured-section section5 1
(map-tracks voice1 (from 1 30) 1
:min-vel 10 :max-vel 80))
EXAMPLE 7: (show-info section5)
EXAMPLE 8: (fill-template structured-section section6 1
(map-tracks voice1 (from 1 30) 1
:filter t))
EXAMPLE 9: (show-info section6)
EXAMPLE 10: (print-result (tracks? voice1))
(map/time value input-low input-high output-low output-high &key chord)
Returns a closure which can be used to map a VALUE between INPUT-LOW and INPUT-HIGH to the range between OUTPUT-LOW and OUTPUT-HIGH. All parameters can vary over time and may be constants, lists, stockpiles, generators, etc. This generator is a time-varying generator version of the tool MAPVALUE. If OUTPUT-LOW or OUTPUT-HIGH is a real number, the result is also a real number (examples 1-2).
A chaotic generator such as HENON can seem to have unpredictable results. To determine the minimum and maximum results to use with such a generator in MAP/TIME, use the tool FIND-RANGE which returns the minimum and maximum value generator, list, stockpile, etc. If the input is a generator, FIND-RANGE returns the minimum and maximum values found in 1000 applications of the generator (examples 3-4).
If an external controller is connected, controller 1 could be used to control OUTPUT-LOW and controller 2 to determine OUTPUT-HIGH when defining the pitch of a data stream:
(map/time (henon 0.0 0.0 1.4 0.3 1) -1.28 1.27
(external-value 1 c1 c5)
(external-value 2 c1 c5))
If the data being mapped contains chords, the minimum and maximum value can be determined with FIND-RANGE and then mapped with MAP/TIME (examples 5-6).
If a chaotic function producing 2 or more dimensions is being mapped, keyword CHORD should be bound to nil so that each dimension returns and uses its own minimum and maximum value. In example 7, X is mapped to be between 40 and 80. Y is mapped between 20 and 40.
EXAMPLE 1: (for-example
(map/time (henon 0.0 0.0 1.4 0.3 1) -2 2 c1 c5))
EXAMPLE 2: (for-example
(map/time (henon 0.0 0.0 1.4 0.3 1) -2 2 60.0 65))
EXAMPLE 3: (for-example
(find-range (henon 0.0 0.0 1.4 0.3 1)))
EXAMPLE 4: (for-example
(map/time (henon 0.0 0.0 1.4 0.3 1) -1.28 1.27 40 80))
EXAMPLE 5: (for-example (find-range '((60 64 67) (55 65 75))))
EXAMPLE 6: (for-example
(map/time '((60 64 67) (55 65 75)) 55 75 60 65))
EXAMPLE 7: (for-example
(find-range (henon 0.0 0.0 1.4 .3 1 :xy t) :chord nil))
EXAMPLE 8: (for-example
(map/time (henon 0.0 0.0 1.4 .3 1 :xy t)
'(-1.28 -0.38) '(1.27 0.38)
'(40 20) '(80 40) :chord nil))
(mapvalue x a b c d)
All arguments should evaluate to numbers. Number X, in the range A to B, is mapped to the range C to D. Output type is determined by C and D. Example 1 returns an integer and example 2 returns a real number.
EXAMPLE 1: (print-result (mapvalue .5 0 1 0 100))
EXAMPLE 2: (print-result (mapvalue .5 0 1 0.0 100))
mask
A mask is represented by two lines. It is a field which changes over time. Values can be calculated to be within a mask. Calculating values within a mask allows parameter values to change in time. CONVERT is a tool that can be used with masks to convert them to some useable parameter values.
(masks&values top bottom n new-top new-bottom
&key conversion generator distance)
Returns a closure. When applied, a point on a top line and a point on a bottom line are produced. A returned value is chosen randomly between those two points.
The two lines can be seen as describing a tendency mask. This generator could produce an endless series of mask segments and values chosen from them.
The first point on the top line is TOP. The first on the bottom line is BOTTOM. The next point will move along those lines so that the Nth point will be NEW-TOP and NEW-BOTTOM respectively.
After N points have been produced, new values for N, NEW-TOP, and NEW-BOTTOM are generated. Points will be produced between the current values and the new values. Then a new values for N, NEW-TOP, and NEW-BOTTOM are produced. And so on.
The output of the generator is a value chosen between the current points on the two lines.
N, NEW-TOP, NEW-BOTTOM and DISTANCE can vary over time and therefore can be constants, lists, stockpiles, generators, etc (example 1).
This generator will produce new destinations for the top and bottom lines after 100 values. This process is continuous.
If more values are displayed, more segments will be produced (example 2).
N may vary over time (example 3).
The values for TOP and BOTTOM are only used once but can also be a constant, generator, etc (example 4).
The choice between the two lines is by default made with random-value. Another generator can be used by binding it to the GENERATOR keyword. The generator should produce values between 0 and 100 (percent). This amount refers to the distance between the two lines (example 5).
If it is necessary to ensure that the output of the generator is of a certain type, a conversion function can be bound to the keyword CONVERSION. ROUND, TRUNCATE, and FLOAT are among the possibilities (examples 6-7).
The key word DISTANCE ensures that there is a minimum distance between the two lines defining the mask. By default, the value for DISTANCE is nil which means that no check is made for a minimum distance. If DISTANCE is bound to a number, the lines will be checked to ensure that the minimum distance is available. If it is not available, the top line is raised. DISTANCE may vary over time (example 8).
EXAMPLE 1: (plot (masks&values 80 40 100
(random-value 30 90)
(random-value 30 90)))
EXAMPLE 2: (plot (masks&values 80 40 100
(random-value 30 90)
(random-value 30 90))
:number 1000)
EXAMPLE 3: (plot (masks&values 80 40 (random-value 10 200)
(random-value 30 90)
(random-value 30 90))
:number 1000)
EXAMPLE 4: (plot (masks&values (random-value 70 90)
(random-value 30 50)
(random-value 10 200)
(random-value 30 90)
(random-value 30 90))
:number 1000)
EXAMPLE 5: (plot (masks&values (random-value 70 90)
(random-value 30 50)
(random-value 10 200)
(random-value 30 90)
(random-value 30 90)
:generator (beta-value 0.0 100 .2 .2))
:number 1000)
EXAMPLE 6: (for-example (masks&values (random-value 70 90)
(random-value 30 50)
20 (random-value 30.0 90)
(random-value 30 90)
:conversion #'float))
EXAMPLE 7: (for-example (masks&values (random-value 70 90)
(random-value 30 50)
20 (random-value 30.0 90)
(random-value 30 90)
:conversion #'round))
EXAMPLE 8: (fill-template make-midi-data-stream ds1 20 1
(masks&values
(random-value 70 90)
(random-value 30 50)
(random-value 10 50)
(random-value 50 60)
(random-value 50 60)
:distance 4)
ff 1)
(melodic-minor start)
Returns a closure. When applied, a note number corresponding to the next value in an ascending melodic minor scale is generated. The first value in the series is START. The series could continue indefinitely (examples 1-2).
EXAMPLE 1: (for-example (melodic-minor 60) :number 8)
EXAMPLE 2: (for-example (melodic-minor 55) :number 8)
menu: define
Various objects can be defined in the AC Toolbox. All objects which may be defined are included as menu items in this menu.
Each object has a separate entry in the Index (as part of the general information).
Undo Definition will undo the last object definition if an object with that name was previously defined.
menu: edit
Most of the items in this menu refer to ways of dealing with text. The text could be in a text file but could also be the input entered in a dialog box item.
The last four items need some special attention.
Insert Newline
Many dialog items have room for more than one line of text but do not necessarily go to the next line if return is entered. To go to the next line in those dialogs, use this menu item.
Evaluate Last Form
Evaluates the Lisp expression preceding the cursor.
Evaluate Selection
Evaluates a chosen text, i.e. it treats the text as a Lisp expression and tries to calculate the result.
Evaluate All
Evaluates an entire text file. This is useful if the file contains Lisp
expressions such as function definitions which a user wants to add to
the toolbox.
menu: file
The File menu provides ways to load and save AC Toolbox objects, open and save text files, import and export MIDI files, and to create files which can be used with other programs.
Text
Text files may have been created in another program, may contain additional Lisp definitions which should be evaluated, may contain notes taken by a user, etc.
Text files can be opened, edited, and savedusing the various items of this menu.
Load Objects
AC Toolbox objects (such as sections, shapes, masks, etc.) which have previously been saved to a file can be loaded. The objects from the file will be added to the current environment.
Replace All Objects
AC Toolbox objects which have previously been saved to a file can be loaded. The objects from the file will replace the objects contained in the current environment.
Recent Environments
Object files (environments) which have been previously loaded or saved are listed in this menu. Selecting the file name will load the file if it still exists in the same location. The most recent file is the first menu item.
Load Examples
Files containing examples of object specifications, such as those found in the folder AC Toolbox tutorials, can be loaded. A table will list the objects defined in the file. Typically, an example file will only contain an input specification. To use the examples, the user should click on input and make the object.
Recent Examples
Example files which have been loaded or saved are listed in this menu. The most recent file is the first menu item. Selecting the file name from the menu will load the file if it still exists in the same location.
Save All Objects
All AC Toolbox objects which have been defined in the current environment will be saved to a file. Both the input specification and the values which were calculated are saved. Csound and OSC score objects and streams only save the input specification. If an environment has been previously saved, the objects will be saved to a file with that name (replacing the previous file). To see the name of the current file, use the menu item CURRENT ENVIRONMENT FILE?
Save All Objects As
All AC Toolbox objects which have been defined in the current environmenet will be saved to a new file.
Save Some Objects
Objects can be chosen from a table to be saved to a file.
Save as Examples
Saves the input of all objects in the environment. They are saved according to the time at which they were made. The first objects made are saved first. This menu item is useful if you are making examples or tutorials for the AC Toolbox or if you only want to save the general information about objects as opposed to their specific event values.
Current Environment File
If the environment has been saved during the current session, the most recent file name used for the environment is displayed.
Import Midi
A Midi file can be imported and used as a section or Midi object. A Midi file containing notes should be imported as a section. A file containing only MIDI controller data should be imported as a controller object. A file containing only program change information should be imported as a program object. A file containing combinations of the above should be imported as a section.
Export Midi
A section or a Midi object can be exported to a Midi file. Midi file formats 1 and 0 are supported. File format 1 supports multiple tracks. File format 0 uses only one track.
Load Lisp File
Load either a text file containing Lisp code or a binary file which was compiled to work with the AC Toolbox. This would presumably add features to the AC Toolbox.
Choose Init File
A file can be chosen to be loaded every time the AC Toolbox is started. This file could contain for example Lisp functions and definitions or instructions to load files, such as (load "myfile.lisp").
Midi Setup
Creates a dialog to select one input and one output for Midi data. Output can be routed to use QuickTime Musical Instruments or a CoreMidi destination such as a port of a Midi interface. If a Capybara or Pacarana sound computation engine is available, it can be chosen as the output destination for Midi data.
Load GM Selections
A previously saved file containing General Midi instrument selections can be loaded. The file will contain selections made using the dialog box created when the General Midi menu item is chosen.
Save GM Selections
General Midi instrument selections are saved to a file. The selections were made using the dialog box created when the General Midi menu item is chosen.
Write FOMUS File
Creates a dialog to to pick various options for the FOMUS notation formatting program. A section can be written to a file in this format (with the extension .fms). FOMUS can prepare data for LilyPond or the interchange format MusicXML which can be read by programs such as Sibelius and Finale.
Write Sound File
Creates a dialog to write a sound file based on an object. The assumption is that the file will contain integers between -32768 and 32767. The range can also be smaller.
The Options dialog for this feature allows the user to specify the number of values to be written to the file, the sample rate, and the file format. The minimum and maximum value is used only in converting shapes and masks.
Since the minimum and maximum values are only used for shapes and masks, they have no influence on other objects. If a generator is used to produce values for the sound file, the values produced by the generator are written to the file without modification (and are not forced to be in the range specified in the options dialog).
Typically Write Sound File would be used to produce a waveform which could be accessed in another program.
The sound file can use either the AIFF or WAVE file format.
Write Max Table
Creates a dialog to generate a table of the specified size suitable for use in Max.
menu: help
The menu contains various possibilities for getting additional information about the AC Toolbox.
Getting Information is a text describing several ways to get help about things within the Toolbox.
Lookup Selection tries to find information about a selected text if it occurs in an AC Toolbox dialog or window. If the selected text is the name of a generator, transformer, or tool, the associated help window is opened. If the selected text is the name of an object, the object is selected in the Objects table.
The keyboard shortcut for Lookup Selection is Command-=.
Go Back Help Page displays the previous help page if one has been displayed during this session. A help page is the page produced by selecting an item in the Index, Annotated Index, or with Lookup Selection. If a page has been displayed but no help page is currently visible, the last one displayed is displayed again.
Go Forward Help Page navigates forward in the list of help pages that have been displayed.
Section Info makes an info window using the object selection in the Objects dialog if the object is a section, community, or Midi performance object. Otherwise it brings the Section Info window to the front if it is open. Info describes an object's type, number of events, and total duration.
LISP contains a submenu with different topics for people who want to know how to use Toolbox objects when writing Lisp code.
Tutorial opens the AC Toolbox Tutorial in a browser window if possible. This may not work with all browsers. It should work if Safari or Firefox is the default browser.
Dialog examples is a table containing examples with possible values for each dialog which creates an object in the AC Toolbox. Selecting an item will open the example.
Annotated Index is a table which contains the names of generators, tools, and transformers as desired along with brief descriptions of what they do. These items can be searched using a text filter for either names or the description. The generators, tools, and transformers can be selected using a popup menu suggesting various categories. Selecting an item will open the corresponding help window.The option to close a previous help window when a new one is opened is controlled in the options for index.
Index is a table of most available online help. This table can be filtered by entering letters or words in the filter dialog. Only items containing these letters or words will be included in the table. Selecting the item will open the help. Dialog examples and Lisp help files are not included in the index.
menu: methods
The menu items are methods (functions) which can be applied to various types of objects. In some cases, there are also methods for applying to a Csound score file or a binary OSC file.
Backwards will reverse an object.
Filter allows an object to be filtered in a number of different ways. A Csound score file and a binary OSC file can also be filtered.
Join will join two or more objects of the same type together. Optionally, shapes or masks could be normalized to the same length before being joined together.
Make Variant will make a variant of an object. A variant is an object with the same input specification as another object although the values of the object may be different.
Slice will slice (cut) out a portion of an object. The chosen portion can be specified with percentage values. In the case of a section, the percentages refer to a percentage of the total duration. The chosen portion can also be selected be specifying index values (the first value is 1, the second is 2, etc.).
Transform allows an object to be transformed by using one or more of the available transformers. For example, the pitch parameter could be transposed or the rhythm stretched. A Csound score file and a binary OSC file can also be transformed.
menu: other
Kill
Stops all processes which are running, including playback and the rendering of Csound or OSC files. It does not stop runaway functions.
Add Comment
Short comments can be added to the dialogs associated with an object. The comment will be saved with the object in the environment for future reference. To edit a previously made comment, click on it. Only one comment can be added to a dialog. ADD COMMENT adds the comment to the front dialog if that dialog can be used to define an AC Toolbox object.
Csound File Options
Creates a dialog box which can be used to set options for writing and rendering Csound files. There is an option to automatically generate names. Sample format and audio header type can be chosen. The choice between rendering the Csound file to an audio file or in realtime can be made. Other command line flags can also be specified. A button is available to open the Csound manual in a browser. Another button opens a dialog for using the Csound utilities pvanal and hetro. Csound5 is assumed to be installed in /usr/local/bin.
OSC File Options
Creates a dialog box which can be used to set options for the writing and rendering of binary OSC files. Most options are only relevant if the OSC file is also rendered to an audio file by the AC Toolbox using the SuperCollider scsynth application. In that case, the audio header, sample format, and number of channels can be chosen. In this dialog, the automatic file naming procedure for OSC files can be also turned on or off.
General Midi
Creates a dialog box which can be used to select instruments for specified channels on a General Midi device. This only works if a General Midi device (such as QuickTime) is available. The Current button shows the most recent instrument selections per channel in a window.
Listener
A Listener window is opened. Lisp expressions, such as (+ 2 2) can be evaluated in this window.
menu: tools
Play
If the object is a section, Midi object, or a community, it can be played. This item plays the object selected in the Objects dialog (Tools>Show Objects). The Objects dialog must be open for an object to be played.
If however, the dialog for Play Selection/Loop is the top dialog, the section specified in that dialog is played. If the Play Selection/Loop dialog is not on top, the selected object in the Objects dialog will be played.
While the object is playing, selecting this item again will stop performance.
Play Selection/Loop
A dialog is produced to play a section. It is possible to select the start and end points in the section to play. Playing can also loop the selection.
Make Object (or Do Action)
The object specified in a dialog can be made with this menu item (or keyboard shortcut) as an alternative to clicking on the Make button. In most other dialogs, the function associated with the button in the lower right corner will be applied with this menu item.
Plot
Sections and communities can be plotted in various ways. A parameter of a Csound score file or an OSC file can be displayed. 'Other' allows generators, lists, stockpiles, etc. to be plotted. 'Selected Object' plots the most recently selected object in the Objects dialog. This is often the object that was just made; it can therefore be plotted without having to use the button in the Objects dialog.
Histogram
Sections and communities can have histograms made of the values for the parameters pitch, rhythm, and velocity. If the option 'Print instead' is checked, the values and their frequencies are printed in a window instead of plotted. A histogram can also be made of a Csound score file or a binary OSC file. 'Other' allows a histogram of generators, lists, stockpiles, etc.
Text Score
A text score is a simple, text representation of the values present in a section.
Selected Object as Text
A text version of an object's values is printed. This is available in any case for sections, stockpiles, controllers, and midi performance objects.
For Example
A generator, tool, or lisp expression can be entered.
A generator is applied a number of times and the results are printed in a window. This allows one to see some examples of using a particular generator. The 'Options' button lets the user change the number of times a generator is applied, specify the number of values that are printed on one line, etc.
If a tool or a Lisp expression is entered in this dialog, the result of applying the expression is printed to a window.
Test Value
Creates a dialog with boxes where numbers can be entered when a stream is being played. These numbers can be read in the stream by using the generator test-value. See the help for test-value for an example. The only purpose of this dialog is to send values to the test-value generator.
Section -> Csound
Translates an existing section to a Csound file. File options can be chosen in the Csound File Options dialog.
Section -> OSC File
Translates an existing section to a binary OSC file. If desired, the file will be rendered and the resulting audio file can be opened for performance. The rendering is done with scsynth (which is part of the SuperCollider distribution). SuperCollider must be installed in order for the OSC file to be rendered. Options concerning writing, rendering and performing files can be chosen in the OSC File Options dialog.
Show Objects
A dialog shows a table with all objects in the environment. The objects in the table can be listed according to their creation time or alphabetically. A popup menu contains the names of all the types of Toolbox objects. When a type is chosen, a table is presented listing all objects of that type that are in the current environment. An object can be chosen from the table, the input of the object can be examined, and various other actions can be requested.
Remove Objects
A table containing all objects in the current environment is presented. An object can be chosen and removed from the environment. Default objects such as wilhelmus are not presented in this table.
Remove All Objects
All objects in the environment (except for default objects such as wilhelmus) are removed. There is a query to make sure you want to do this.
menu: window
Close Window
The top (active) window is closed.
Cleanup Windows
All AC Toolbox windows except the Objects dialog are closed.
Cleanup Windows and Objects
All AC Toolbox windows except the Objects dialog are closed. If objects have been defined, the user is asked if all objects should be removed. This item is intended as a convenience so that the Remove All Objects menu item does not have to be invoked separately.
Examples Window to Front
If an examples file was loaded and the window listing the examples is open, that window is brought to the front.
The remaining menu items are the titles of windows which exist within the AC Toolbox. Windows may be chosen by selecting a menu item.
(message commands ...)
Message is intended for use with bundle for specifying OSC commands for OSC score objects. The message can contain any number of valid SuperCollider Server commands (example 1).
See the help for BUNDLE for a description.
EXAMPLE 1:
(print-result
(bundle 0 (message "/b_allocRead" 0 "sounds/a11wlk01-44_1.aiff")))
(metric-fractions generator)
Returns a closure. When applied, a fractional value < 1 is returned. GENERATOR should return an integer value. METRIC-FRACTIONS returns 1 divided by that value until the sum would be 1. The number 4 would produce 1/4 1/4 1/4 1/4 (example 1). After the sum is 1, a new divisor is chosen.
GENERATOR can be a generator, list, stockpile, etc. If it produces a non-integer value, that value is truncated to be an integer. (examples 2-3).
The purpose of this generator is to simplify the rhythmic organization of groups of values.
EXAMPLE 1: (for-example (metric-fractions (random-value 1 5)))
EXAMPLE 2: (for-example (metric-fractions '(2 3 4)))
EXAMPLE 3: (for-example (metric-fractions (random-choice '(2 3.5 4.2))))
(metric-pattern n value &optional lower-limit upper-limit)
Returns a list consisting of N values. Each value is an integer divisor of VALUE. Each value is repeated until the sum of the repetitions is equal to VALUE. Then a new divisor is chosen at random.
LOWER-LIMIT is a threshold for the smallest possible divisor that may be chosen.
UPPER-LIMIT is a boundary for the largest possible divisor that may be chosen (examples 1-2).
EXAMPLE 1: (for-example(metric-pattern 40 48))
EXAMPLE 2: (for-example(metric-pattern 40 48 10 24))
(metric-values value &optional lower-limit upper-limit)
Returns a closure. When applied, one value which is an integer divisor of VALUE is returned. Each divisor is repeated until the sum of the repetitions is equal to VALUE. Then a new divisor is chosen at random (example 1).
LOWER-LIMIT is a threshold for the smallest possible divisor that may be chosen. If none is provided, it defaults to 1.
UPPER-LIMIT is a boundary for the largest possible divisor that may be chosen. If none is given, it will equal the value produced by VALUE.
VALUE, LOWER-LIMIT, and UPPER-LIMIT may vary over time. Changes only take effect when a new divisor is chosen (examples 2-3).
Care should be taken when specifying lower and upper limits to make sure that at least one divisor is possible within those limits.
EXAMPLE 1: (for-example (metric-values 48) :number 40)
EXAMPLE 2: (for-example (metric-values '(48 30 35)) :number 40)
EXAMPLE 3: (for-example (metric-values 48 10 20))
microtones
Microtones are expressed as floating-point numbers. 60 is c4. 60.5 is a quarter-tone higher. Any value after the decimal point is possible but may not be meaningful.
To generate floating-point numbers, it is sufficient for most generators or tools to use a floating-point number for one or more of the input parameters (examples 1-2).
If symbols such as c4 are desired to express pitch values, a floating-point value can be produced by enclosing the symbol in the expression float (example 3).
QuickTime (available to all users) and a Capybara or Pacarana (available to some users) can perform microtones. The fractional resolution of the Capybara and Pacarana is higher that the resolution of Quicktime. These output options can be selected via File>>Midi Setup. Other output options will round off the pitch values to integer values (example 4).
To avoid using microtones, do not specify floating-point numbers for pitch (example 5).
Microtones can also be printed in a Text Score via the menu item Tools>>Text Score. There is a check box to allow fractions to be printed.
Section data can be formatted for musical notation using FOMUS (menu item 'File>Write FOMUS File'). FOMUS allows the formatting of output data using quartertones. LilyPond will print quartertones. Applications reading MusicXML data may or may not respond to requests for quartertones.
A list or stockpile of desired microtones can be specified and used as the input to a generator ending with -choice: (example 6).
FROM produces numbers between two limits with a specified step size between values. It could be used to create a list of quarter-tones, etc. (example 7).
ROUND-OFF will round-off input values to multiples of some unit. This unit does not have to be an integer value. Floating-point values can be rounded off to units of .5, .25, etc. (examples 8-9).
A descending MASK1 can be defined (examples 10-11).
This mask can be used to produce values rounded to quarter tones (example 12).
If a mask should be used to read an arbitrary set of microtones (which are not spaced at equal steps from each other), READ-FROM could be used. The stockpile being read is spread on the Y-axis and the mask is used to read from those values. Mask values are considered positions on the Y axis expressed as percentages.
Example 13 uses MASK1.
Various generators and tools produce floating-point values as their standard output. SPECTRUM->PITCH is an example of this. It includes a key word ROUND to allow rounding output to semitones (integers), quartertones (multiples of 0.5), etc..
DEFINE-SCALE returns a closure (generator) which can be used to generate a scale, e.g. to fill a stockpile. The list of intervals can include floating-point numbers (examples 14-17).
EXAMPLE 1: (for-example (random-value 60 72))
EXAMPLE 2: (for-example (random-value 60.0 72))
EXAMPLE 3: (for-example (random-value (float c4) c5))
EXAMPLE 4: (fill-template data-section micro1 100 50 1
(random-value 60.0 63) 64 1)
EXAMPLE 5: (fill-template data-section integers1 100 50 1
(random-value 60 63) 64 1)
EXAMPLE 6: (for-example
(random-choice
'(70.6 71 70.2 67.2 69.8 35.7 53.8 67.7 66.8 54.8)))
EXAMPLE 7: (for-example (random-choice (from 60 72 :step .5)))
EXAMPLE 8: (for-example (round-off (random-value 60.0 72) .5))
EXAMPLE 9: (for-example (round-off (random-value 60.0 72) .25))
EXAMPLE 10: (fill-template specify-mask mask1 '(100 20) '(80 0))
EXAMPLE 11: (plot mask1)
EXAMPLE 12: (for-example
(round-off (convert mask1 20 60.0 72) .5))
EXAMPLE 13: (for-example
(read-from '(35.7 53.8 54.8 66.8 67.2
67.7 69.8 70.2 70.6 71)
mask1 20))
EXAMPLE 14: (define my-scale (define-scale '(1 2 2.5 1)))
EXAMPLE 15: (for-example (my-scale c3) :number 8)
EXAMPLE 16: (fill-template generate-stockpile my-stockpile 24 (my-scale c2))
EXAMPLE 17: (for-example my-stockpile)
midi controller input
The generator EXTERNAL-VALUE reads Midi controller input. The input is mapped between a LOW and HIGH value.
The menu item External-value in the Other menu controls what is used in the EXTERNAL-VALUE generator. If the choice is CONTROLLER NUMBERS, the number of the Midi controller is used regardless of which channel it is received on. The generator (external-value 1 c2 c4) would map the values of Midi controller 1 to be between the Midi note numbers for c2 and c4.
If the choice is CONTROLLER CHANNELS, the channel of the MIDI controller is used regardless of which controller it is. The generator (external-value 1 c2 c4) would map the values of the Midi controller using channel 1 to be between the Midi note numbers for c2 and c4.
See the help for the generator EXTERNAL-VALUE for more information.
midi controller output
Midi controller data can be organized into a MIDI-CONTROLLER-OBJECT either setting just one controller value or changing controller values in a way similar to a data section or density section. Only 7-bit controllers are supported.
A Midi Controller Value Object will set a Midi controller to one specified value.
When the object made with example 1 is played, the Midi pan controller will be set to 0 which is as far left as it will go. To reset all Midi controllers, the menu option Kill and Reset can be chosen.
A Midi Controller Data Object is specified in a manner similar to the specification of a data section. It represents rhythm as a multiple of a clock unit, and allows controller values and controller numbers to be specified in the customary toolbox manner: as a constant, a list, a stockpile, a function, a generator, etc. The template to produce such an item can be created by selecting the DEFINE>MIDI OBJECT >CONTROLLER DATA menu item (example 2).
The object with contain 100 controller values. Every 100 milliseconds (rhythm 1 * clock unit of 100), a new value generated by random-value will be output when the object is played. The values are assigned to controller number 7 and Midi channel 1.
If the controller should be reset at the end of the object, check the RESET box in the template and enter the value to which the controller should be reset (0-127). After the last value specified for the section, the reset value will be sent.
A Midi Controller Density Object is similar to a density section. A certain amount of time (expressed in seconds) is filled with attack points. The attack points are specified using a function which produces values between 0.0 and 100 per cent of the available time. Each attack point will be assigned a controller value, number, and channel all of which can be expressed in the customary manner (constant, list, stockpile, generator, etc.). A controller maintains its value until it receives a new one therefore there is no separate parameter for duration. The template to produce such an item can be created by selecting the CONTROLLER DATA menu item.
In example 3, thirty seconds will be filled with 100 events. The attack points are chosen with random-value to be between 0.0 and 100 per cent of the available time (30 seconds). At each attack point, a controller value between 0 and 127 is sent to controller 7 on Midi channel 1.
To reset the controller at the end of the object, check the RESET box
and enter a reset value.
Attack points can also be entered as a list of values between 0 and 100 (percent). In that case, the number of values entered in the list will determine the number of attack points. The parameter number would be ignored in this case.
Example 4 contains only 11 events, one corresponding to each percentage in the attacks, and not the 100 events indicated in the number parameter.
If a Capybara has been selected as the output device in the Midi Setup, controller values may be floating-point numbers. Currently, controller 1 will be sent to !cc01 in the Capybara. controller 2 will go to !cc02, etc.
EXAMPLE 1: (fill-template make-midi-controller-value-object
pan-left 0 10 1)
EXAMPLE 2: (fill-template controller-data-object data1 100 100 1
(random-value 0 127) 7 1)
EXAMPLE 3: (fill-template controller-density-object dense1 30 100
(random-value 0.0 100)
(random-value 0 127) 7 1)
EXAMPLE 4: (fill-template controller-density-object dense2 30 100
'(0 10 20 30 40 50 60 70 80 90 100)
(random-value 0 127) 7 1)
midi files
Importing Midi
A Midi file can be imported and used as a section or Midi object. A Midi file containing notes should be imported as a section. A file containing only MIDI controller data should be imported as a controller object. A file containing only program change information should be imported as a program object. A file containing combinations of the above should be imported as a section.
To import a Midi file, use the menu item FILE>IMPORT MIDI.
Exporting Midi
A section or a Midi object can be exported to a Midi file. Midi file formats 1 and 0 are supported. File format 1 supports multiple tracks. The AC Toolbox will write each Midi channel to a separate track. File format 0 uses only one track. Note that Midi files only support the use of integer values for pitch and velocity. If a section being exported contains floating-point values for these parameters, they will be rounded off when exported.
To export a Midi file, use the menu item FILE>EXPORT MIDI.
If the Midi file is to be used in a notation program, the tempo setting may be important to get useful input in the notation program. The tool clock->mm can be used to convert a clock unit in milliseconds to a metronome indication.
EXAMPLE 1: (print-result (clock->mm 100))
midi object
A midi object contains Midi controller values or program changes.
midi objects: filtering
The filter template has no button for filtering midi objects. Instead the option for OTHER filter should be chosen. An expression which will produce an appropriate filter expression should be entered. The idea is similar to what is used with transform: a filter expression is encapsulated in a specifier which indicates which parameter is to be filtered.
E.g.
(controller-filter 'value (low-pass 60))
would create a low-pass filter for controller values.
To see an example of this usage, evaluate example 1 and then select SET PARAMETERS.
The various filters should be entered as a Lisp expression:
(low-pass threshold)
(high-pass threshold)
(band-pass low high)
(band-reject low-high)
(bank low1 high1 low2 high2 ...)
(shot-gun percentage)
The available specifiers:
(controller-filter 'value filter)
(controller-filter 'number filter)
(controller-filter 'channel filter)
(program-filter 'number filter)
(program-filter 'channel filter)
EXAMPLE 1: (fill-template
filter cont2 cont1
(other (controller-filter 'value (low-pass 60)))
'whatever nil)
midi objects: transforming
The transform dialog has no box for choosing a transform for a controller value, for example. To be able to transform a controller value, the whatever box should be used together with a function that specifies that the transform should be applied to the controller value. This function should 'encapsulate' the transform function (example 1).
Other parameters can be transformed by encapsulating a transform in another specifier:
(controller-transform 'number transform)
(controller-transform' channel transform)
The specifier functions for controllers only affect controller messages. If a section contains both note messages and controller messages, only the controller messages will be transformed by a controller-value.
Create a section containing both note messages and controller messages (examples 2-4).
If all three objects were made, a midi-section called p3 should exist. To transpose the pitches in this section by 12 and to transpose the controller-values by 60 see example 5.
To transform program change commands in a midi-program-object or in a section, the whatever parameter should contain a transform encapsulated in an appropriate specifier (example 6). Available specifiers are:
(program-transform 'number transform)
(program-transform 'channel transform).
EXAMPLE 1: (fill-template
transform dense2 dense1
:whatever (controller-tranform 'value (transpose 12)))
EXAMPLE 2: (fill-template data-section
ds1 200 50 (random-value 1.0 2)
(random-value c2 c4) mf 1)
EXAMPLE 3: (fill-template controller-data-object
cont1 50 300 1
(random-value 0 60)
7 1)
EXAMPLE 4: (fill-template parallel-section p3 cont1 ds1)
EXAMPLE 5: (fill-template transform tran1 p3
:pitch (transpose 12)
:whatever (controller-transform
'value (transpose 60)))
EXAMPLE 6: (fill-template transform data3 data2
:whatever (program-transform
'number (compress 25 16)))
midi output using a capybara/pacarana
Midi output can be directed to a Capybara or Pacarana Sound Computation Engine via its firewire interface. Pitch, velocity, and controller data can be floating-point numbers in that case. Integer values may also be used. Program changes can be sent as well.
To select the Capybara or Pacarana as output destination, use Midi Setup. If Capybara/Pacarana does not appear in the output menu, make sure that the firewire interface is on and connected. The button Hunt Capybaras/Pacaranas can be used to take (another) look for the interface.
To use Midi output via a Capybara/Pacarana, Kyma must be started and an appropriate sound loaded in the Capybara. Appropriate means in this context, any sound which responds to incoming Midi data by using expressions such as !Pitch, !KeyDown, etc. Polyphony requires using the MidiVoice object or specifying polyphony on a timeline. Controller data can currently only be sent to !cc01, !cc02, etc. Midi controller 1 in the AC Toolbox will be sent to !cc01 in Kyma.
The AC Toolbox currently is limited to dealing with the first 100 voices on a Capybara or Pacarana.
It is the responsibility of the user to ensure that the Capybara or Pacarana can respond to the data sent by the AC Toolbox. In particular, the user should check the Midi channel for incoming data.
midi program change
Midi program changes can be realized through a MIDI-PROGRAM-OBJECT. Each object has a name, one or more program change messages (program and channel) and relative times at which they should occur.
The most simple of the objects can be created by selecting Program Change in the MIDI OBJECT menu. One program change and one channel number may be entered. The resulting object can be used in a sequential section to make a program change between sections.
A Program-Data-Object is specified similarly to a data section. Rhythm is a multiple of a clock unit in centiseconds. A program change and channel are selected at points corresponding to each rhythmic value.
Using example 1, an object with 10 events will be created. Each event occurs contains a program change command. An events occurs every 200 milliseconds (clock unit 200 * rhythm 1).
If a data section called section1 existed and you wanted a program change for every note of that section, first a program-data-object could be defined and then joined with the section in a parallel section. The rhythm values of section1 could be extracted and used as input for the program-data-object (examples 2-4).
A Program-Density-Object is specified similarly to a density section. A length of time is specified in sections. A number of attack points are calculated within that time. For each point, a program change and channel are specified (example 5).
If a density section called dense-section1 existed and you wanted a program change for every note in that section, a program-density-object could be defined and then joined with the section in a parallel section. The attack points of section2 can be extracted with (extract 'attack section2) which returns a list of attack points expressed as a percentage value between 0 and 100 (examples 6-8).
Program changes can also be realized as a stream. Make and play a PROGRAM STREAM to produce program changes in real-time.
EXAMPLE 1: (fill-template program-data-object data1 200 10 1
(random-value 1 32) 1)
EXAMPLE 2: (fill-template data-section section1 100 20
(random-value 1 3)
(random-value c2 c4) mf 1)
EXAMPLE 3: (fill-template program-data-object data2
(get-rhythmic-unit section1)
(get-length section1)
(extract 'rhythm section1)
(random-value 1 32) 1)
EXAMPLE 4: (fill-template parallel-section p1 data2 section1)
EXAMPLE 5: (fill-template program-density-object program1 30 10
(random-value 0.0 100)
(random-value 1 32) 1)
EXAMPLE 6: (fill-template
density-section dense-section1 30 20
(random-value 0.0 100) 50 (random-value c2 c4) mf 1)
EXAMPLE 7: (fill-template program-density-object program2
(get-object-duration dense-section1
:seconds t)
20 (extract 'attack dense-section1)
(random-value 1 32) 1)
EXAMPLE 8: (fill-template parallel-section
p2 dense-section1 program2)
midi setup
The AC Toolbox uses CoreMidi for Midi input/output. It is also possible to use QuickTime Musical Instruments or a Capybara or Pacarana Sound Computation Engine for output. When launched, the Toolbox tries to connect to the most recent Midi setup. If this is not possible, for instance if the devices previously used are not available, the Toolbox will connect to the first thing it finds.
A user can choose from the available input/output possibilies using the menu item MIDI SETUP. The resulting dialog box allows devices to be chosen. Only one input and one output can be specified for use with the AC Toolbox. The choices are put into effect when the user hits the ACCEPT button.
QuickTime and Capybara/Pacarana output accepts floating-point values for pitch. Output to all other destinations will be rounded to integer values.
When the generator External-value is used, an external Midi controller should be attached to an available input port or selected as an input if it appears in the pop-up menu for MIDI SETUP.
If an object is played after the external or virtual Midi connections have been changed, the Toolbox will try and adjust the Midi settings. It may however be necessary to adjust the settings in the the MIDI SETUP dialog. If the dialog is still open, hitting the RESCAN button will update the input and output menus.
Capybara/Pacarana output is only possible via a firewire interface for a Capybara or Pacarana. If a Capybara/Pacarana has previously been selected for output in the AC Toolbox, the program will initialize it on startup if the firewire interface is available. Otherwise, select the button Hunt Capybaras/Pacaranas to look for one. Make sure the interface is on before requesting it.
(midi->hz note-number &key base)
Returns a closure. When applied, a Midi note-number is converted to a frequency value in Hz (example 1).
NOTE-NUMBER may be a constant, list, generator, etc. (examples 2-4).
Keyword BASE is a reference frequency for A4 (or A3, depending on the preference chosen). It defaults to 440.0 Hz (example 5).
This generator could be useful in preparing Csound score files.
EXAMPLE 1: (print-result (make (midi->hz a4)))
EXAMPLE 2: (for-example (midi->hz 60))
EXAMPLE 3: (for-example (midi->hz (major 60)))
EXAMPLE 4: (for-example (midi->hz '(c4 a4 c5)))
EXAMPLE 5: (for-example (midi->hz 60 :base 415))
(midi->notename input &key float)
Returns a closure. When applied, a Midi note number is converted to its alphanumeric representation.
E.g. Midi notenumber 60 is c4. (example 1). The choice for C3 for Midi notenumber 60 (middle C) can be made in the Preferences dialog.
INPUT may be a constant, list, stockpile, generator, etc. (example 2)
When keyword FLOAT is bound to t, the fractional part of a note is printed in parentheses. This is useful if the Midi value being converted is a floating point number and insight into a possible translation to microtones is desired (examples 3-4).
EXAMPLE 1: (print-result (make (midi->notename 60)))
EXAMPLE 2: (for-example (midi->notename (random-value 40 80)))
EXAMPLE 3: (for-example (midi->notename (random-value 40.0 80)))
EXAMPLE 4: (for-example (midi->notename
(random-value 40.0 80) :float t))
(midi-articulation &optional ms)
A tool to either report or adjust the current Midi articulation time. This is the time subtracted from the duration of all notes to increase the time between a note off command and the next note on command.
MS is the time in milliseconds.
To report the current value, see example 1.
Occasionally, a Midi program may require an additional time between notes in order to repeat notes 'properly'. QuickTime Musical Instruments (in some versions) is such a program.
Example 2 will decrease all note durations by 1 millisecond, causing a gap between notes of 1 millisecond. This gap should be enough to allow notes to repeat properly if there had been such a problem.
Changes made with this tool are remembered in the preference file. To set the value to zero, use example 3.
EXAMPLE 1: (print-result (midi-articulation))
EXAMPLE 2: (midi-articulation 1)
EXAMPLE 3: (midi-articulation 0)
midi: repetition problem
Some versions of QuickTime Musical Instruments and perhaps other programs may require additional time between notes in order to repeat correctly. The tool MIDI-ARTICULATION can correct this problem (example 1).
This will subtract one millisecond from each duration when a section is played.
EXAMPLE 1: (print-result (midi-articulation 1))
(mingle stockpile1 stockpile2 ...)
or
(mingle number1 stockpile1 number2 stockpile2 ...)
Returns a list made from interleaving 2 or more stockpiles, lists, sections, etc. If 2 stockpiles are mingled, the resulting list would contain element1 from stockpile1, element1 from stockpile2, element2 from stockpile1, element2 from stockpile2, etc. (example 1).
If the stockpiles are not the same length, the process continues after one stockpile is empty with the elements of the remaining stockpile(s) (example 2).
An unlimited number of stockpiles can be mingled (example 3).
The simplest form of using mingle just specifies a number of stockpiles and one value is taken from each in turn. It is possible to take more values from each stockpile each time. To do that, the second syntax description in the header should be used. For each stockpile, a number indicating the number of elements to take from the stockpile should be specified. If this syntax is used, all stockpiles must have a number specifying how many elements to take (example 4).
The numbers can change over time using a generator (but not a list or stockpile since they would be mingled) (example 5).
It is also possible to mingle the notes in two or more sections. If SECTION1 and SECTION2 exist, they could be mingled in example 6.
EXAMPLE 1: (print-result (mingle '(1 2 3) '(a b c)))
EXAMPLE 2: (print-result (mingle '(1 2 3) '(a b c d e)))
EXAMPLE 3: (print-result
(mingle '(1 2 3) '(10 20 30 40)
'(100 200 300 400 500) '(a b c d)))
EXAMPLE 4: (print-result
(mingle 1 '(1 2 3 4 5)
2 '(100 101 102 103 104 105 106 107 108)))
EXAMPLE 5: (print-result
(mingle (random-value 1 2) '(1 2 3 4 5)
(random-value 2 3)
'(100 101 102 103 104 105 106 107 108)))
EXAMPLE 6: (fill-template note-section
section-m 100 100
(mingle section1 section2) 1)
(mirror center)
Returns a closure. When applied, the value being transformed is mirrored around CENTER. If CENTER is 60, and the value is 55, the result is 65. If the value is 65, the result is 55 (example 1).
CENTER may vary over time using a generator, etc. (example 2).
EXAMPLE 1: (show-transformation (mirror 60)
'(60 62 64 65 59 56 55))
EXAMPLE 2: (show-transformation
(mirror (line-segment 7 60 70
:conversion #'round))
'(60 62 64 65 59 56 55))
(mm metronome)
Converts a metronome indication into a value in milliseconds which is appropriate to use for a clock unit in a section specification (example 1).
EXAMPLE 1: (print-result (mm 120))
(more-than &rest constraints)
Returns a function appropriate for use with WITHOUT. It limits the number of times certain values can be used.
The constraints are the number of times a value can be used, followed by the value which should be constrained. When that number of a certain value has been chosen, WITHOUT will not allow any more of that value to pass.
In example 1, no more than one 3 will be allowed. In example 2, no more than two 60s and two 67s will be allowed. Note that any number of constraints can be specified as long as they are in the form: number value number value ...
It is possible that less than the allowed number of a certain value is chosen (example 3).
At the end of the constraints, it is possible to use the keyword :pitch-class followed by a non-nil value. It that case, the pitch class of values will be compared to the pitch class of the constrained values. In example 4, no more than two Cs will be allowed. Note that c2 is 36, c3 is 48 and c4 is 60.
This tool is related to NO-MORE-THAN which can be used independently to produce a list (example 5).
EXAMPLE 1: (for-example
(without (more-than 1 3) (rv 1 3)))
EXAMPLE 2: (make-histogram
(without (more-than 2 60 2 67) (rv 60 67)))
EXAMPLE 3: (for-example
(without (more-than 100 1) (rv 1 100)))
EXAMPLE 4: (for-example
(without (more-than 2 c4 :pitch-class t)
(rc '(c2 c3 c4 g4 a4 b4))))
EXAMPLE 5: (for-example
(no-more-than '(2 60 2 67) (rv 60 67) :n 20))
(morph thing1 thing2 index &key round)
Returns a closure. When applied, the next value from THING1 and the next value from THING2 are morphed (interpolated). If INDEX is 0, the value from THING1 is returned (example 1). If the INDEX is 1, the value from THING2 is returned (example 2). Otherwise a value between the two values is returned proportional to the value of INDEX (example 3).The value returned will always be between the two source values.
THING1, THING2, and INDEX can be a list, stockpile, generator, constant, etc. (examples 4-6).
ROUND defaults to nil, meaning the value is not rounded (or quantized). If ROUND is t, the value is rounded to an integer value (examples 7-8). If ROUND is a number, that number is used to quantize the result (example 9).
This generator is a simpler approach to morphing than the generator MUTATE.
EXAMPLE 1: (for-example (morph '(1 10 20) '(10 20 50) 0))
EXAMPLE 2: (for-example (morph '(1 10 20) '(10 20 50) 1))
EXAMPLE 3: (for-example (morph '(1 10 20) '(10 20 50) 0.25))
EXAMPLE 4: (for-example (morph 10 0 .25))
EXAMPLE 5: (plot (morph (convert sine-shape 100 1 100)
(convert expo-shape 100 1 100)
0.60))
EXAMPLE 6: (plot (morph (line 100 1 100)
(convert sine-shape 100 1 100)
(rc '(0 0.5 1)))
:plot nil)
EXAMPLE 7: (for-example (morph '(1 10) '(4 19) 0.5 :round t))
EXAMPLE 8: (fill-template data-section ds1 100 100 1
(morph (line 100 40 80) (convert sine-shape 100 40 80)
(rc '(0 0.5 1)) :round t)
f 1)
EXAMPLE 9: (for-example (morph '(1 10) '(4 19) 0.5 :round 0.5))
(ms number generator &optional predicate)
This tool is a shortcut for MAKE&SORT.
It is intended for use in Csound score objects and OSC scores. The START parameter can use this tool to generate a number of start values for events and sort the start times in ascending order (the default situation) (examples 1-1). This can be important if objects such as shapes, masks or stockpiles should be presented in the correct order.
See the documentation for MAKE&SORT for more information and examples.
EXAMPLE 1: (for-example (random-value 1 50))
EXAMPLE 2: (for-example (ms 20 (random-value 1 50)))
(multiple-bandwidths low high ...)
Returns a list containing all integer values between and including LOW and HIGH. There can be several LOW/HIGH pairs and the list will include all integers between them (examples 1-2).
This tool can be used in conjunction with generators with the suffix choice (examples 3-4).
EXAMPLE 1: (for-example (multiple-bandwidths 1 10 20 25))
EXAMPLE 2: (for-example (multiple-bandwidths c1 f#1 d3 a3 g#4 c5))
EXAMPLE 3: (for-example
(random-choice (multiple-bandwidths 20 25 38 43 74 77)))
EXAMPLE 4: (for-example
(beta-choice (multiple-bandwidths 20 25 38 43 74 77).3 .3))
musicxml
MusicXML is an interchange format which can be read by various music notation programs including Sibelius and Finale. Information about MusicXML can be found via example 1.
The AC Toolbox can write data in a format readable by FOMUS, a music notation formatting tool. FOMUS, in turn, can produce a MusicXML file which can be read by Sibelius, etc.
A notation program may not realize all features of MusicXML.
EXAMPLE 1: (open-url "http://www.recordare.com/xml.html")
(mutate source target index mutation-type
&key clumping start offset
override low high)
Returns a closure. When applied one value of the mutant is returned.
MUTATE is based on the morphological mutation functions developed by Larry Polansky and described in the ICMC Proceedings of 1991 and 1992 and in the Journal of New Music Research 25(4). A mutation function creates a transformation (cross-fade) between a source object and a target object.
MUTATE allows the transformation of a source object (list, stockpile, or shape) into a target object (list, stockpile, or shape) of the same length. The source can 'cross-fade' into the target in different ways and to different degrees. The degree of the mutation is expressed with an INDEX value between 0-1. 0 is the minimum mutation. 1 is the maximum mutation.
Different types of mutation functions have been defined.
Contour mutations transform the source into the target on the basis of the interval direction (or sign).
Magnitude mutations use the size of the interval (the magnitude), either signed or unsigned.
Five types of mutations are available in the AC Toolbox. They can be indicated by the numbers 1 - 5, by the abbreviations used by Polansky, or by a nickname.
Types of mutations
Number, Polansky, Nickname
1, LCM, contour
2, IUIM, some-source
3, ISIM, some-target
4, UUIM, all-source
5, USIM, all-target
Type 1, Linear contour mutation (LCM), uses the sign of the target and the interval of the source if an interval is to be mutated. The number of intervals mutated is determined by the index (examples 1-4).
Source: 72 60
Target: 67 68
Mutation: 72 84
Where M is the mutant, T the target, and S the source:
Mutated intervals: M(i) = M(j) + T(sign) * S(mag)
Non-mutated intervals: M(i) = M(j) + S(sign) * S(mag)
Type 2, Irregular Unsigned Interval Magnitude Mutation (IUIM),
uses the sign of the source and the interval of the target (examples 5-6).
Source: 72 60
Target: 67 68
Mutation: 72 71
Mutated intervals: M(i) = M(j) + S(sign) * T(mag)
Non-mutated intervals as above.
Type 3, Irregular Signed Interval Magnitude Mutation (ISIM),
uses both the sign and the interval of the target (examples 7-8).
Source: 72 60
Target: 67 68
Mutation: 72 73
Mutated intervals: M(i) = M(j) + T(sign) * T(mag)
Non-mutated intervals as above.
Type 4, Uniform Unsigned Interval Magnitude Mutation (UUIM),
mutates all interval magnitudes of the source by a percentage of the difference of the source interval magnitudes and the target interval magnitudes. The percentage is determined by the index. In this mutation, the absolute value of the difference is used. In Type 5, the actual value of the difference is used (examples 9-10).
Source: 72 60
Target: 67 68
Mutation: 77 54
Note that the first value is also mutated. The initial previous value for the source and for the target is 0.
Mutation: M(i) = M(j) + S(sign)
* (S(mag) + index * |T(mag) - S(mag)|)
Type 5 Uniform Signed Interval Magnitude Mutation (USIM),
mutates all interval magnitudes of the source by a percentage of the difference of the source interval magnitudes and the target interval magnitudes. The percentage is determined by the index. This is a simple crossfade (example 11-12).
Source: 72 60
Target: 67 68
Mutation: 67 68
The initial previous value for the source and for the target is 0.
Mutation: M(i) = M(j) + Sint + index * (Tint - Sint)
where Sint = S(sign) * S(mag)
and Ting = T(sign) * T(mag)
The degree of the mutation is expressed with INDEX. 0 is no mutation. 1 is the maximum mutation. The effect of changing the index can be seen in examples 13-15.
INDEX can be a constant value, a list, a stockpile, or a closure. If INDEX is not a constant, its value will change for each mutation.
The mutations which are made may be evenly spread throughout the mutation or they may be 'clumped' together. The CLUMPING factor (0-1) together with the index controls the 'spread' of the mutations. With an index of 0.5 and a clumping factor of 1, the mutations would be maximally clumped (example 16).
The default clumping value is 0. Clumping can be a constant value, a list, a stockpile, or a closure. If clumping is not a constant, its value will change for each mutation.
START controls the place in the mutation where clumping begins. 0 is the beginning of the mutation and 1 is the end of the mutation (example 17).
The default value for start is 0.
OFFSET is the initial value in the mutation. By default it is 0 and can probably be left at this value.
OVERRIDE can be t or nil. By default it is nil. If it is t, a solution is used to the theoretical problem that an interval or a sign would be 0. If it is nil, this imperfection is not corrected. (See Polansky (1992) for a discussion.)
A mutation could result in very large or very small values. If the mutation is being mapped into MIDI note numbers for example, a limit on the minimum and maximum value should be placed. By default the smallest possible result of this function is 0 and the highest is 127. These values can be changed with the keywords :LOW and :HIGH. Values below or above these values will be clipped (example 18).
Mutations can be combined. When a type 1 mutation is performed, followed by a type 2 mutation, the target is reached when the index is 1. See the help for COMBINE-MUTATION for more information.
This generator is based on code contributed by Maarten van Walstijn.
EXAMPLE 1: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 1)))
EXAMPLE 2: (plot '(72 60 63 65 66 67 70 72)
:min 50 :max 100 :title "Source" :replace nil)
EXAMPLE 3: (plot
'(67 68 67 65 63 70 58 58)
:min 50 :max 100 :title "Target" :replace nil)
EXAMPLE 4: (plot
(produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1 1))
:min 50 :max 100 :title "Type 1" :replace nil)
EXAMPLE 5: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 'some-source)))
EXAMPLE 6: (plot
(produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1 2))
:min 50 :max 100 :title "Type 2" :replace nil)
EXAMPLE 7: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 'ISIM)))
EXAMPLE 8: (plot
(produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1 3))
:min 50 :max 100 :title "Type 3" :replace nil)
EXAMPLE 9: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 4)))
EXAMPLE 10: (plot
(produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1 4))
:min 50 :max 100 :title "Type 4" :replace nil)
EXAMPLE 11: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 5)))
EXAMPLE 12: (plot
(produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1 5))
:min 50 :max 100 :title "Type 5" :replace nil)
EXAMPLE 13: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0 1))
:recycle nil)
EXAMPLE 14: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 1))
:recycle nil)
EXAMPLE 15: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
1 1))
:recycle nil)
EXAMPLE 16: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 1 :clumping 1)))
EXAMPLE 17: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 1 :clumping 0.5 :start 0.5)))
EXAMPLE 18: (print-result (produce 8
(mutate '(72 60 63 65 66 67 70 72)
'(67 68 67 65 63 70 58 58)
0.5 3 :low 65 :high 80)))
(no-more-than constraints generator &key (n 100) pitch-class (stop 500))
Returns a list of N values produced by applying GENERATOR. CONSTRAINTS should be specified to limit the occurence of certain values.
If CONTRAINTS is the list '(1 3 2 1), there will be no more than 1 occurence of the value 3 and 2 occurences of value 1 (examples 1-2). Depending on the values produced by GENERATOR, there could be fewer of the constrained values.
CONSTRAINTS can be a list or stockpile.
GENERATOR can be a generator, list, or stockpile.
N has the default value of 100. It can be set to any other integer (example 3).
There can be any number of constraints as long as they are expressed as number value number value ... (example 4).
CONSTRAINTS may contain symbols such as c4 for the values (example 5).
Values which are not constrained will occur until a total of N values have been produced (example 6). In this example, after one 3 and two 1s have been chosen, all the remaining values with be 2.
If N values cannot be produced using the given constraints, the function will stop after STOP attempts (example 7).
When N is bound to nil, the function will stop as soon as all constraints have been met (example 8).
When PITCH-CLASS is bound to t, the pitch class of the value is compared to the pitch class of the constraint (example 9). In this example, no more than two Cs will occur, regardless of their octave.
If behavior similar to NO-MORE-THAN is wanted as a generator instead of in the form of a tool which produces a list, see MORE-THAN which can be used with the generator WITHOUT (example 10).
EXAMPLE 1: (for-example
(no-more-than '(1 3 2 1) (rv 1 3)))
EXAMPLE 2: (make-histogram
(no-more-than '(1 3 2 1) (rv 1 10)))
EXAMPLE 3: (for-example
(no-more-than '(2 60) (rv 60 72)
:n 20))
EXAMPLE 4: (make-histogram
(no-more-than '(5 60 3 64 7 67) (rv 60 72))
:print t)
EXAMPLE 5: (for-example
(no-more-than '(2 c4 3 g4) (rc '(c4 e3 g4 a4 b4))
:n 20))
EXAMPLE 6: (for-example
(no-more-than '(1 3 2 1) (rv 1 3) :n 20))
EXAMPLE 7: (for-example
(no-more-than '(1 60) (rv 60 60)))
EXAMPLE 8: (for-example
(no-more-than '(2 60 1 64 1 67) (rv 60 67)
:n nil))
EXAMPLE 9: (for-example
(no-more-than '(2 c4) (rc '(c1 c3 g3 a3 b3))
:n nil :pitch-class t))
EXAMPLE 10: (for-example
(without (more-than 1 3 2 1) (rv 1 3)))
(noice-choice n sequence gamma)
Returns a closure. When applied, one element of the sequence is returned. The choice of element is made according to a fractional noise distribution.The type of fractional noise is determined by GAMMA which can range from 0 to -4. 0 is white, -1 is 1/f (or pink), -2 is brownian, and anyvalue < -2 is black (examples 1-5).
N is the (estimated) total number of values to generated with this generator.
GAMMA can vary over time.
EXAMPLE 1: (for-example (noise-choice 20 '(a b c d e f g h i) 0))
EXAMPLE 2: (for-example (noise-choice 20 '(a b c d e f g h i) -.5))
EXAMPLE 3: (for-example (noise-choice 20 '(a b c d e f g h i) -1))
EXAMPLE 4: (for-example (noise-choice 20 '(a b c d e f g h i) -2))
EXAMPLE 5: (for-example (noise-choice 20 '(a b c d e f g h i) -4))
(noise-value n a z gamma)
Returns a closure. When applied, one number between A and Z is returned according to a fractional-noise distribution. The type of fractional noise is determined by GAMMA which can range from 0 to -4.
0 is white, -1 is 1/f (or pink), -2 is brownian, and any value < -2 is black.
The type of the result is determined by the type of A and Z. N is the total number of values to be generated with this generator. A, Z, and GAMMA may vary over time.
100 values of various types of noise (examples 1-6):
Example 1 is white noise (gamma 0).
Example 2 has -.5 for gamma.
Example 3 is 1/f noise (gamma -1).
Example 4 has -1.5 for gamma.
Example 5 is brownian noise (gamma -2)
Example 6 is black noise (gamma -3).
Example 1: (plot (noise-value 100 1 100 0)
:title "0" :min 1 :max 100 :replace nil)
Example 2: (plot (noise-value 100 1 100 -.5)
:title "-0.5" :min 1 :max 100 :replace nil)
Example 3: (plot (noise-value 100 1 100 -1)
:title "-1" :min 1 :max 100 :replace nil)
Example 4: (plot (noise-value 100 1 100 -1.5)
:title "-1.5" :min 1 :max 100 :replace nil)
Example 5: (plot (noise-value 100 1 100 -2)
:title "-2.0" :min 1 :max 100 :replace nil)
Example 6: (plot (noise-value 100 1 100 -3)
:title "-3.0" :min 1 :max 100 :replace nil)
notation for a score
The AC Toolbox can convert section data to data appropriate for FOMUS, a music notation formatting tool. FOMUS in turn can produce data suitable for the LilyPond notation program or for the interchange format MusicXML which can be read by Sibelius, Finale, and other programs.
In the best case, the result can be considered a rough image of some note data that may be useful for informing compositional decisions.
FOMUS is intended to rationalize pitch and rhythm data to achieve a result more useful than importing Midi files into a notation program.
Various options can be entered via the dialog created by 'File>Write FOMUS File'. A discussion of their use can be found in the help (found under the ? button) in the previously-mentioned dialog. Further information can be found in the FOMUS documentation.
The user should install FOMUS (example 1) and a suitable notation program such as LilyPond (example 2) or a program that can read MusicXML. Additional information about MusicXML can be found via example 3.
Note that not all programs respond with equal sensitivity to the commands of MusicXML. Various features may not be realized.
LilyPond (in connection with FOMUS) does respond to data for quartertones.
The FOMUS installer puts FOMUS in /usr/local/bin. This is where the AC Toolbox assumes it is.
LilyPond (if used) should be in the Applications folder because that is where FOMUS expects to find it. It may be necessary to double-click LilyPond the first time it is used before trying to use it with FOMUS.
EXAMPLE 1: (open-url "http://fomus.sourceforge.net/")
EXAMPLE 2: (open-url "http://lilypond.org")
EXAMPLE 3: (open-url "http://www.recordare.com/xml.html")
note section
A section where notes are expressed as a combination of the parameters rhythm, pitch, velocity, and channel. Notes can be made with note structures (a-note, in-sequence, etc.) or with generators which can deal with notes, e.g. chaotic-notes.
note structure
A note structure is a note, a rest, a delay, or some combination of these structures. Note structures allow the specification of a known group of pitches, chords, and rests.
(note-pass-filter)
Produces a filter which will filter out anything that is not a note, e.g. controller values or program changes, from a section.
This filter should be used with the method FILTER.
Choose OTHER as the filter type then use (note-pass-filter) to produce the filter. The parameter should be WHATEVER. If the start times of the notes are not to be changed, the check box LEAVE GAPS should be checked.
If Section1 exists, example 1 will filter out everything but note information.
EXAMPLE 1: (fill-template filter section1f section1
(other (note-pass-filter))
'whatever t)
objects: community
A community is a group of sections joined in name only. A community can provide a mechanism for manipulating sections according some grouping.
The idea of a community is that all members act together while retaining their individual identities.
A community is an useful way to make a transformation involving several sections. Or to produce a group of sections which are variants of one input specification.
objects: controller
A controller is used to control parameter values on a larger scale. It maintains state, outside the scope of an object definition. A controller remembers what it has done and the next time it will provide the next value.
A controller can be used as an input in an edit box in another object. Each time that object is made (or varied), the next value from the controller will be produced.
A controller could be used to determine how many values each variant of a generated sequential section should have. A controller can have a list of values or a generator or a function as input. Each time the controller is used, the next value from the list or generator will be used.
Imagine that 10 sections will be created. The number of values per section is determined by a controller. If the controller is a list '(10 20 30), then the first section created will have 10 values, the second section 20 values, the third section 30 values, the fourth section 10 values, and so on. If a controller is not used and a list with '(10 20 30) is entered directly into the NUMBER edit box, each time the object is made, the first value (10) will be used.
objects: csound objects
Csound objects hold information that can be used to generate a score file for Csound. The object does not contain the score file but merely the information that can be used to generate one.
Csound objects may be combined in sequence or in parallel.
When combined in sequence, each Csound object in the sequence is applied to produce part of the data for a score file. Each time an object is applied, it produces new data (unless it only contains deterministic input). The data from one object comes after another in time.
When combined in parallel, each Csound object starts at the same time (or later if an offset is provided).
When Csound objects are combined, the start time for the data may be adjusted to correspond with the sequential or parallel nature of the combination. In these cases, the calculation times for any function generation statements (f statements) included in the header are not changed.
objects: mask
A mask is represented by two lines. It is a field which changes over time. Values can be calculated to be within a mask. Calculating values within a mask allows parameter values to change in time. CONVERT is a tool that can be used with masks to convert them to some useable parameter values.
objects: midi objects
Midi objects allow other Midi commands (MIDI controller values and program changes) to be created. These objects can be played or used to create a Midi file. They also can be mixed with other midi objects or sections in a parallel section.
A controller density object allows a time to be filled with Midi controller values. A controller data object produces Midi controller values in a fashion similar to a data section. A controller value object sets a Midi controller to a fixed value. A multi Midi controller object allows several controllers to be described in one object.
Program density objects, program data object, and program change objects produce Midi program change commands.
objects: note structure
A note structure is a note, a rest, a delay, or some combination of these structures. Note structures can be combined in sequence or in parallel. A note structure could also contain a section. Note structures can be used in defining a structured section or a note section. Note structures allow the specification of a known series of pitches, chords, and rests.
A note is made with (a-note rhythm pitch velocity channel) (examples 1-2).
RHYTHM values are multiples of a clock unit that is specified when a section is made.
PITCH can be MIDI note numbers or a known symbol, such as C4.
If PITCH is a list, a chord is produced.
VELOCITY is a MIDI value (0-127) or a known symbol, such as MF.
CHANNEL is specified between 1-16.
A rest is made with (a-rest rhythm).
Rhythm values are multiples of a clock unit that is specified when a section is made. When used within another structure, this object represents a rest of a certain length (example 3).
A delay is made with (a-delay time-in-milliseconds).
The TIME-IN-MILLISECONDS represents an actual amount of time for a rest and is not a multiple of a clock time.
Example 4 would wait 1 second in a note structure.
To join note structures in sequence:
(in-sequence structure1 structure2 ...)
The note structures included in the sequence are interpreted to occur one after another (in sequence). An indefinite number of structures can be included in sequence (example 5) .
To join note structures in parallel (at the same time):
(in-parallel structure1 structure2 ...)
The note structures included in parallel are interpreted to occur at the same time (example 6).
Note that both IN-SEQUENCE and IN-PARALLEL accept sections as input. Several sections could occur in parallel as follows: (in-parallel section1 section2 section3)
EXAMPLE 1: (print-result (a-note 1 c4 mf 1))
EXAMPLE 2: (print-result (a-note 1 60 64 1))
EXAMPLE 3: (print-result (a-rest 2))
EXAMPLE 4: (print-result (a-delay 100))
EXAMPLE 5: (print-result (in-sequence (a-note 1 60 mf 1)
(a-rest 3)
(a-note 1 67 mf 1)))
EXAMPLE 6: (print-result (in-parallel (a-note 2 c4 mf 1)
(a-note 1 c#4 f 2)))
objects: osc scores
OSC score objects hold information that can be used to generate a binary OSC file. The object does not contain the score file but merely the information that can be used to generate one.
OSC scores may be combined in sequence or in parallel.
When combined in sequence, each OSC object in the sequence is applied to produce part of the data for an OSC file. Each time an object is applied, it produces new data (unless it only contains deterministic input). The data from one object comes after another in time.
When combined in parallel, each OSC score starts at the same time (or later if an offset is provided).
An OSC Score Bunch object contains one or more bundles (of OSC messages). This object may be convenient if other OSC score objects need to include additional bundle information (such as a message for allocating and filling a buffer).
The tool INSIDE-OSC can be used to update parameters during one score event.
objects: scheme of variations
A scheme of variations contains the names of objects that are to be made in a certain order. When the scheme is applied, those objects are made in that order. If an object is made as part of a scheme, the previous output of that object is lost.
A scheme of variations is useful when you want to specify dependencies of objects upon each other. E.g. if a shape is changed, the sections using that shape should also be redefined.
A scheme of variations is also useful when you want to work in a top-down fashion. First, the specifications for all objects will be made. The specifications can be made in an order that is convenient and logical to the user without worrying if the objects that are needed have already been defined or not. Finally, all object names should be included in a scheme. Later the objects will be made in the order specified in the scheme of variations.
objects: section
An important activity when using the Toolbox to create note information is the definition of sections. A section is a general term referring to part or all of a musical composition involving note data. A section can be listened to, exported as a MIDI file, imported from a MIDI file, printed as a text score, plotted, examined via histograms, combined with other sections (in sequence, in parallel, or starting at certain times). A section can be transformed in many ways.
A section contains a list of notes represented with MIDI values, their durations expressed in milliseconds, and their start time relative to the beginning of a section.
A section can contain one or more notes. In this way it can fulfill many different roles: note, phrase, section, voice, movement, composition, etc.
Different ways of defining sections have been included.
In a DATA SECTION, input for each of the parameters (rhythm, pitch, velocity, and channel) is separate.
In a NOTE SECTION, notes are expressed as a combination of those four parameters.
In a STRUCTURED SECTION, an object called a note structure must be entered.
In a DENSITY SECTION, time is the paramount parameter. Time is filled with either a function or a shape.
Sections can be combined in sequence (sequential section), in parallel (parallel section), or by specifying start times (timed section). A parallel section can be generated by varying an existing section several times and combining those outputs in parallel (generate parallel section). A sequential section can be generated in a similar manner (generate sequential section).
Examples of appropriate input for each of these types of sections can be found via the menu item 'Help>Dialog Examples'.
objects: shape
A shape is an abstraction reflecting some motion over time. A shape can be drawn with a mouse, expressed as a series of evenly spaced values, or created using a generator.
Shapes can be used to create values for various input parameters. Shapes can be used to determine pitch in a data section. Or to express the tempo changes in a transformation of a section, etc. CONVERT is a tool that can be used with shapes to convert them to some useable parameter values.
Some default shapes have been included in the environment. They can be seen Objects dialog (Tools>Show Objects).
objects: stockpile
A stockpile is a collection of values that are available to be used. A user may wish to define various stockpiles of source material and them make choices from these stockpiles using generators. A stockpile is the standard input to a generator ending with -choice, e.g. random-choice.
Stockpiles can be specified value for value, can be created using a generator, or they can be constructed with some other available tool. A combination of existing stockpiles can also be generated.
objects: stream
Streams can go on forever. Like water from a faucet, a stream continues until it is turned off. Several streams can be played at the same time as a parallel stream. Data streams and Note streams produce note on and note off commands. Controller streams produce Midi controller values. Multi-controller streams can produce Midi controllers values for up to five Midi controllers. Program streams produce Midi program change commands.
Streams can be combined in parallel by making a parallel stream and specifying the streams to combine. A parallel stream can also be generated by cloning an existing stream, such as a data stream, a number of times with the dialog Generate Parallel Stream.
Streams can be controlled externally by a Midi controller. If a stream uses the generator EXTERNAL-VALUE it will read and scale values from a Midi input device.
Streams can also receive values from the Test Value dialog. If a stream uses the generator TEST-VALUE, it will read values from boxes in the Test Value dialog.
Streams can be started and stopped with the play dialog or in the show objects dialogs for streams or all objects.
(on-the-fly object1 operator1 object2 &rest expressions)
Returns a closure. When applied, OPERATOR1 (e.g. +) is applied to one result from OBJECT1 and one from OBJECT2. The objects may be constants, lists, stockpiles, or generators as is customary in the AC Toolbox.
The functionality is similar to the generator COMBINE except that infix notation is used and the operator does not require a function quote (#'). Also, more than one operation can be done in series. Infix notation has the operator between the 2 operands. In Lisp, normally you have the function first and then the data to which it is applied (examples 1-4).
Since ON-THE-FLY is a generator, it produces one value each time it is applied. In the example with the stockpile, each time the generator is applied, the next value from the stockpile is read and 100 is added to it. In the example with the list, each time the generator is applied, the next value from the list is read and added to a new random number produced by the generator rv.
Several operators can be used. They will be evaluated from left to right, as is the case with SuperCollider and unlike the normal custom of mathematics (example 5).
Semitone frequency values between A 440 Hz and an octave higher could be produced (example 6). (from 0 1 :step 1/12) produces a list of values from 0 to 1 at a distance of 1/12. expt in this example raises 2 to each power from the list produced by FROM. That result is multiplied by 440. Each time the generator is applied, the next value from FROM is returned and used in this expression.
ON-THE-FLY expressions can be nested. The preceding formula for frequencies could be rewritten as in example 7.
To manipulate other objects such as shapes, they should first be converted to lists. Example 8 multiplies a sine shape by a random value.
Examples-9-10 can be used to generate a shape object.
Pitch deviation could be generated with on-the-fly (examples 11-12).
Alternatives to using ON-THE-FLY are APPLY-FUNCTION, and COMBINE.
A tool which is similar is CAL. It wil produce a fixed number of results. ON-THE-FLY will produce a new result each time it is applied (examples 13-14).
OTF is a shortcut for ON-THE-FLY (example 15).
EXAMPLE 1: (for-example (on-the-fly 2 * 2))
EXAMPLE 2: (fill-template construct-stockpile
stock (from 1 10))
EXAMPLE 3: (for-example (on-the-fly stock + 100))
EXAMPLE 4: (for-example (on-the-fly '(10 20 30) + (rv -1.0 1.0)))
EXAMPLE 5: (for-example (on-the-fly 3 + 2 * 2))
EXAMPLE 6: (for-example
(on-the-fly 2 expt (from 0 1 :step 1/12) * 440)
:number 13)
EXAMPLE 7: (for-example
(on-the-fly 440 * (on-the-fly 2 expt (from 0 1 :step 1/12)))
:number 13)
EXAMPLE 8: (plot
(on-the-fly (convert sine-shape 100 0.0 1) * (rv -1.0 1)))
EXAMPLE 9: (fill-template generate-shape mul-shape 100
(on-the-fly (convert sine-shape 100 0.0 1) * (rv -1.0 1)))
EXAMPLE 10: (plot mul-shape)
EXAMPLE 11: (fill-template data-section ds1
100 100 1 (on-the-fly 60 + (rv -5.0 5.0)) mf 1)
EXAMPLE 12: (fill-template data-section ds2 100 100 1
(on-the-fly (convert expo-shape 100 48 72)
+ (rv -5.0 5.0)) mf 1)
EXAMPLE 13: (for-example (cal '(10 20 30) + (rv -1.0 1)))
EXAMPLE 14: (for-example (on-the-fly '(10 20 30) + (rv -1.0 1)))
EXAMPLE 15: (for-example (otf '(10 20 30) + (rv -1.0 1)))
(open-url string)
OPEN-URL will open an url supplied as a string in a browser window.
Example 1 makes an internet connection and opens (if possible) the browser page from the AC Toolbox. If the tool does not open the browser, try opening the browser 'by hand' before evaluating the expression.
EXAMPLE 1: (open-url "http://www.koncon.nl/ACToolbox")
osc
OSC (OpenSound Control) is a protocol for communicating among computers, synthesizers, etc. which was developed at CNMAT, Berkeley. Among its uses is the network control of audio programs.
For more information, see example 1.
EXAMPLE 1: (open-url "http://www.cnmat.berkeley.edu/OpenSoundControl/")
osc files: filtering
Binary OSC files can be filtered using the dialog produced by 'Methods>Filter>OSC File'. The result of the filtering operation is a new file. The original file is not changed.
Select an OSC file by clicking on the 'Select' button.
It is possible to filter up to four parameters in the file using this dialog. If a parameter is to be filtered, enter the argument name as it occurs in the Synthdef. Arguments names are case sensitive. Select a filter type for that argument using the corresponding popup menu. Parameters, such as a threshold value for a low-pass filter must be specified. To do this, click the button 'Set Parameters' and fill in the appropriate value(s).
If the filter type is 'None', the corresponding argument will not be filtered.
When a file is filtered, OSC bundles are examined. If a bundle is allowed to pass, it is copied to a new file. If the bundle is filtered away, it is not copied.
If a low-pass filter with a parameter of 500 is being applied to argument 'freq', any bundle containing a 'freq' value <= 500 will be allowed to pass. Otherwise the entire bundle is ignored.
If more than one filter have been specified, a choice must be made on how to combine the results of the filters to determine if a bundle should be copied or not. If 'Or' is selected, a bundle is copied if one ore more of the filters would allow it to be copied. If 'And' is selected, it is copied only if all of the filters would allow it to be copied.
Combining filters with 'And' can be useful when filtering different arguments, e.g. when selecting only those bundles where 'dur' is below a certain value and 'freq' is above another value.
Only one filter may be used per argument. Filters can however be combined in a lambda expression as a parameter for the 'Other' filter. To apply first a low-pass filter and then a high-pass filter, the following expression could be used in Other filter:
#'(lambda (x) (and (funcall (high-pass 900) x) (funcall (low-pass 1000) x)))
More information about writing Lisp expressions to use for a filter of type 'Other' can be found in Help>Lisp>Your Own.
When the filtered file is made, it will be rendered or not according to the various options in the OSC File Options dialog.
OSC files that were made using INSIDE-OSC for one or more the parameters cannot be filtered.
osc files: transforming
Binary OSC files can be transformed using the dialog produced by Methods>Transform>OSC File. The result of the transformation is a new file. The original file is not changed.
Select an OSC file of either type clicking on the 'Select' button.
It is possible to transform up to four parameters in the file using this dialog. If a parameter is to be transformed, enter the argument name as it occurs in the Synthdef. In the corresponding edit box, fill in a transformer expression such as (transpose 500) which would add 500 to the value of the corresponding arg. Available transformers can be found in the Annotated Index (Help>Annotated Index).
Argument names are case sensitive.
A transformer is applied to the specified argument of every bundle in the OSC file. Other arguments are not changed.
Only one transforer can be applied to an argument. COMPOSE can be used to combine transformers. To add 1000 and then a random deviation of 10% to a value, the following could be entered as a transformer:
(compose (random-deviation 10) (transpose 1000))
When the transformed file is made, it will be rendered or not according to the various options in the OSC File Options dialog.
osc score
An OSC score object contains the specification to generate a binary OSC file which can be rendered to an audio file.
osc score bunch
One or more bundles of OSC messages. Bundles are expressed with the bundle tool. A score bunch can be used together other OSC score objects.
(osc-frame time-in-seconds)
Returns a closure. When applied, a time value in seconds is converted to a frame number for use in reading buffers in OSC messages.
The time value is multipled by the current sampling rate which is used for rendering the binary OSC files to audio.
In a synthdef, ugens such as PlayBuf have an argument for the frame position to start playback. OSC-FRAME can be used to calculate this position.
TIME-IN-SECONDS can change over time (examples 1-2).
EXAMPLE 1: (for-example (osc-frame 0.5))
EXAMPLE 2: (for-example (osc-frame (random-value 1.0 10))
:number-per-line 1)
osc: parallel objects
OSC score objects can be combined in parallel in 2 ways. The groups of objects can be specified by name or the group can be generated using a generator etc. to determine the order of the available scores. In both cases, each time another score object is applied, it is generated anew.
Specify Objects and their Offset
To specify a group of score objects to be joined in parallel, use the OSC Scores>Parallel scores' menu item. In the space for score objects, the names of score objects can be entered (example 1).
As many objects as desired can be entered. The objects can be OSC score objects, sequential OSC score objects, parallel OSC score objects and/or OSC Score bunches.
The start of an object can be delayed by a time specified as a number (in seconds). If no offset is desired, no number need be entered. The time offset is not the time between objects (as is the case with a sequential score) but the time since the beginning of the parallel score object (example 2).
In example 2, osc1 and osc2 will start at the same time. The second instance of osc1 will start 3 seconds later. Note that the two applications of osc1 may result in different events (depending on the way that osc1 was specified). If score1 contains generators with random aspects, the files will probably be different.
Generate Objects and their Offset
To generate a group of score objects to occur in parallel, use the menu item Osc Scores>Generate parallel scores.
The number of score objects to be generated, something to produce an offset value (from the beginning of the parallel object), and a generator etc. to choose the group of score objects should be entered (example 3).
The offset value can be a constant, list, generator, etc. If the offset is 0, all scores will start at the same time. In any case, the first score always starts at time 0. The offset is applied to the start time of the remaining scores.
The scores can be chosen with a generator as in the above example. A list could be given in which case the scores occur in the same order as they occur in the list (example 4).
The name of a single score could be used (example 5).
EXAMPLE 1: (fill-template create-parallel-osc-score-object
osc-par1 osc1 osc2)
EXAMPLE 2: (fill-template create-parallel-osc-score-object osc-par2
osc1 osc2 3 osc1)
EXAMPLE 3: (fill-template generate-parallel-osc-score-object
gen-osc-par1 3
(random-value 0.0 2)
(random-choice '(osc1 osc2)))
EXAMPLE 4: (fill-template generate-parallel-osc-score-object
gen-osc-par2 3
(random-value 0.0 2)
'(osc1 osc2))
EXAMPLE 5: (fill-template generate-parallel-osc-score-object
gen-osc-par3 3
(random-value 0.0 5)
osc1)
osc: score objects
An OSC score object can be used to specify an algorithm to generate a binary OSC file. When an object is specified, the algorithm is saved but no file is generated. When an object is applied, the specification is saved and a binary OSC file is generated. This file can be rendered to an audio file within the AC Toolbox which in turn will use SuperCollider Server (scscynth) to do this. To render a binary OSC file, SuperCollider must be installed.
OSC score objects can be joined in sequence or in parallel which means that when applied, several objects will be generated and the values saved as part of one file.
Sequential OSC objects are described in the help for OSC: Sequential Objects.
Parallel OSC objects are described in the help for OSC: Parallel Objects.
The remainder of this text describes the use of the dialog box for an OSC score object.
An OSC score will generate a binary file containing bundles of OSC messages. Each bundle includes a time indication when the message should be sent. Messages typically will assign one or more arguments used in a SuperCollider synthdef some value at the specified time. Synthdefs used in conjunction with the AC Toolbox are assumed to have a duration parameter and are expected to turn themselves off after that amount of time.
Include
An OSC file might need to send other bundles in additional to those that are generated. These bundles could do things such as allocate and read buffers. Such bundles can be specified in Include. A bundle specification looks like this:
(bundle 0 (message "/b_allocRead" 0 "sounds/a11wlk01-44_1.aiff"))
One or more bundles may occur in Include. Instead of specifying bundles, the name of an OSC score bunch object containing one or more bundles can be entered in Include. Note that these two forms cannot be mixed. Either bundles are enter as shown above OR the name of a OSC score bunch is entered. An OSC score bunch can be made with menu item Define>OSC Scores>Bunch of Bundles.
If no additional bundles are needed, Include may be left blank.
Synthdef
Synthdef is the name of an available SuperCollider synthdef. The synthdef is compiled in the SuperCollider language and written to the default synthdefs folder. Once the synthdef has been compiled, it remains available for subsequent use.
The following synthdef is used in these examples. It should be compiled in the SuperCollider language application.
(
SynthDef("sine1",{ arg freq = 440, amp = 0.2, dur = 1.0, attack = 0.25, decay = 0.25;
var ss = 1 - attack - decay;
Out.ar(0,
SinOsc.ar(freq, 0,amp)
* EnvGen.kr(Env.linen(attack,ss, decay,1), timeScale: dur, doneAction: 2)
)
}).writeDefFile;
)
The source code for the synthdef sine1 can be found in test osc synthdefs.rtf in Support/FileExamples.
Layers
In the OSC file, one or more layers can be produced. Layers are parallel combinations of outputs. The parameter LAYERS may be a constant, list, generator, etc.
Number
Number is the number of events in a layer. It may be a constant, list, generator, etc.
Start
If start is a constant number, the first start-time in the file will be this value. Subsequent values for the start-time of events will be the previous value plus the previous duration. If start is a generator, list, etc., the values for all of the actual start-times will be produced with it. Start-times are expressed in seconds.
Duration
Duration is the length of each event and is expressed in seconds.
The argument name for duration should be the name used in the synthdef. Each synthdef used in combination with an OSC score object should have a duration parameter. The name of the parameter does not matter, but it should be able to turn off the synthdef. One way to do this is with doneAction: 2 in an envelope specification.
The argument value may be a constant, list, generator, etc.
Example
In example 1, a score object will be made using synthdef sine1 with only three arguments specified: dur, freq, and amp. The arguments names are the names used in the synthdef. A duration must be specified. If other arguments are not specified, the default values in the synthdef will be used. The duration argument needs to specified in the fields labeled Duration. The order of the other arguments does not matter.
When the specify button is used, the information in this dialog is saved as an object. When the apply button is used, the information is saved and a binary OSC file with 50 events is produced. By default, this binary file will also be rendered to an audio file. Various options concerning the audio header, sample format, etc. of the audio file can be set using OSC File Options (Other>OSC File Options).
Rests
Negative durations produce rests. The values produced for the other arguments are lost (if there is a rest). This produces 'gaps' in the file as if holes had been shot in it. The file will only contain the events which are not rests (example 2).
Until-Time
UNTIL-TIME can be used to determine the number of values to be calculated. UNTIL-TIME indicates that events should be generated until a certain length of time in seconds has been reached. It can only be used if START is a constant value.
When the score file from example 3 is made, events will be generated until 10 seconds have been filled. The last event is not truncated to fit within the 10 seconds but is allowed its full duration. This could mean that the total length of the score is longer than 10 seconds.
The use of UNTIL-TIME assumes that duration is expressed in seconds.
In example 3, FROM-NUMBER was used to convert line-shape for P4. (from-number) returns the number of events calculated to fill 10 seconds.
Using a Generator for Start
In example 4, the start-times of the events are randomly chosen between 0.0 and 20 seconds. Note that the events are no longer in chronological order. If that is important, for instance because a mask or shape is being used in another parameter, the start-times should be sorted using make&sort. An example using make&sort is given later.
Using a Shape to Determine the Density
DENSITY-OF-START-TIMES makes a list of start times by mapping a shape to represent density varying between a minimum and maximum value.
In example 5, LINE-SHAPE represents a linearly increasing density that is mapped between 1 event per second to 10 events per second in the course of 10 seconds.
The NUMBER parameter is related to the number of events generated by the DENSITY-OF-START-TIMES expression by using (from-start-times) as input.
Several Layers
In example 6, generators are made again for each layer. This means that they forget their history and start at the beginning (though not necessarily with the same results). In this example, freq uses the WALK generator. The walk for each layer will start at 440 Hz. SCALE-BY-LAYERS scales the maximum amplitude value per layer according to the number of layers.
Shapes or Masks
If one of the parameters is to be derived from a shape or a mask, it is important that the start-times be in ascending order. If a constant value is used for start-time, there is no problem. If a generator is used for start-time, it is possible that the order of the shape or mask is destroyed after the events are sorted. To prevent this, you should sort the start-times using the tool MAKE&SORT.
In examples 7-8, twenty values made by the generator RANDOM-VALUE are sorted and returned in a list.
Extra
The dialog for extra may contain names and values for additional arguments. Data for an unlimited number of parameters can be included in this dialog. Data should be in the form: name value. NAME should be the argument name. VALUE may be a generator, list, constant, etc. (example 9)
Synthdef sine1, as defined above, recognizes the parameters attack and decay. Those arguments will be used. Sine1 does not recognize the parameters niks, nada, etc. These are just used to show how 'real' parameters could be specified if needed.
Relating Parameters
Amplitude can be derived from frequency by using a lookup table. Frequency values are entered in the table with the desired amplitude for that frequency. Generator LOOKUP will use a frequency value as input and return the amplitude value related to the nearest frequency.
Example 10 defines a frequency stockpile.
Example 11 defines an amplitude lookup table.
The chosen frequencies can be seen with example 12.
Some related amplitude values can be seen with example 13.
An OSC score object can be made using both (example 14).
Per Layer
This box can be used to indicate which (if any) objects that have already been defined should be remade before each layer is calculated. When an object is remade, the input specification is used to make a new output which replaces the previous output of that object.
For example, the frequency stockpile made in the previous example could be
remade for each layer. Each layer would have a new choice of frequency values
but each layer could relate its frequencies to the amplitude table (example 15).
Several objects can be remade per layer. If only 1 layer is specified, the objects are remade before the first layer is calculated.
Per Score
This box can be used to indicate which (if any) objects that have already been defined should be remade before each score object is calculated. When an object is remade, the input specification is used to make a new output which replaces the previous output of that object.
When an object is remade per score, this would allow all layers to use the same object but each time the score is applied, a new object would be made for use in all layers.
Overlapping Start Times
The generator OVERLAP can be used to guarantee that start times for adjacent events will overlap. The amount of overlap can be a time value in seconds (example 16).
The amount can also be expressed as a percentage of the previous duration (example 17).
Note the use of FROM-OVERLAP for the duration parameter when the generator OVERLAP is used.
updating parameters
A parameter value can be changed during an event by using INSIDE-OSC. This will generate new values and send them to the current event according to the times created by the rhythm parameter of INSIDE-OSC. Example 18 produces a frequency glissando using INSIDE-OSC. A new frequency value is sent to the current event every 0.01 seconds. The event has a duration between 1-10 seconds followed by a rest of between 1 and 1.5 seconds.
Miscellaneous
When an OSC score object generates a file, the name can be supplied by the user or the AC Toolbox can be asked to supply a name. In the latter case, the prefix entered in the OSC File Options dialog will be used for the file name, followed by consecutive, increasing numbers. The choice of which format to use and the available options can be specified in the dialog created by Other>OSC File Options.
Various choices regarding the rendering of the OSC binary file to an audio file can be specified in the OSC File Options dialog. These options include the type of audio header (aiff or wav), the sample format (including 16, 24, and 32-bit integers as well as 32-bit floating point numbers), the sample rate, etc.
SuperCollider produces text when a binary OSC file is rendered. If there is some mistake, such as a buffer file cannot be found, looking at this text can be useful. The text is printed in the Text Output window. On the other hand, if thousands of events are generated for the OSC file, printing the text indicated when each event started might be considered a waste of time. For these reasons, it is possible to turn printing on and off in the OSC File Options dialog.
EXAMPLE 1: (fill-template osc-score-object osc1
50 "sine1" nil nil nil 1 0
"dur" (random-value 0.05 0.1)
"freq" (series-value 900 1000)
"amp" 0.3)
EXAMPLE 2: (fill-template osc-score-object osc2
50 "sine1" nil nil nil 1 0
"dur" '(1 -1)
"freq" '(100 200 300 400 500)
"amp" 0.3)
EXAMPLE 3: (fill-template osc-score-object osc3 (until-time 10)
"sine1" nil nil nil 1 0
"dur" (random-value 0.1 0.2)
"amp" 0.3
"freq" (series-value 415 466))
EXAMPLE 4: (fill-template osc-score-object osc4
10 "sine1" nil nil nil 1
(random-value 0.0 20)
"dur" (random-value 0.5 1)
"amp" 0.3
"freq" (random-value 100 1000))
EXAMPLE 5: (fill-template osc-score-object osc5
(from-start-times) "sine1" nil 'nil 'nil 1
(density-of-start-times 10 line-shape 1 10)
"dur" (random-value 0.5 1) "amp" 0.1
"freq" (random-value 220 880))
EXAMPLE 6: (fill-template osc-score-object osc6
100 "sine1" nil nil nil 5 0
"dur" (random-value 0.1 0.2)
"amp" (scale-by-layers 0.5)
"freq" (walk 440 (random-value -10.0 10)
100.0 2000))
EXAMPLE 7: (for-example (make&sort 20 (random-value 0.0 10)))
EXAMPLE 8: (fill-template osc-score-object osc7
20 "sine1" nil nil nil 1
(make&sort 20 (random-value 0.0 10))
"dur" (random-value 1.0 2)
"amp" 0.2 "freq"
(convert line-shape 20 200.0 400))
EXAMPLE 9: (fill-template osc-score-object osc8
20 "sine1" NIL 'NIL 'NIL 1 0 "dur" 1 "amp" 0.5
"freq" (RANDOM-VALUE 400.0 800) "attack" 0.01
"decay" (RANDOM-VALUE 0.2 0.7)
"niks" 1 "nada" 0.2
"nothing" (RANDOM-VALUE 1.0 20000000)
"whatever" 10 "something" '(10 20))
EXAMPLE 10: (fill-template generate-stockpile freqs
100 (random-value 100.0 3000))
EXAMPLE 11: (fill-template construct-stockpile amp-table
(make-lookup-table 100 0.5 800 0.3 1200 0.1
2000 0.01))
EXAMPLE 12: (for-example freqs)
EXAMPLE 13: (for-example (lookup freqs amp-table :interpolate t))
EXAMPLE 14: (fill-template osc-score-object osc9
100 "sine1" nil nil nil 1 0
"dur" (random-value 0.1 0.2)
"freq" freqs
"amp" (lookup freqs amp-table :interpolate t))
EXAMPLE 15: (fill-template osc-score-object osc10
100 "sine1" nil '(freqs) nil 5 0
"dur" (random-value 0.1 0.2)
"freq" freqs
"amp" (scale-by-layers
(lookup freqs amp-table :interpolate t)))
EXAMPLE 16: (fill-template osc-score-object osc11
10 "sine1" NIL NIL NIL 1
(overlap 0 (random-value 0.5 1.5) 0.25)
"dur" (from-overlap) "amp" 0.4
"freq" (random-value 100.0 1000))
EXAMPLE 17: (fill-template osc-score-object osc12
10 "sine1" nil nil nil 1
(overlap 0 (random-value 0.5 1.5) 50 :percent t)
"dur" (from-overlap) "amp" 0.2
"freq" (random-value 100.0 1000))
EXAMPLE 18: (fill-template osc-score-object osc13
10 "sine1" nil nil nil 1 0
"dur" (take 1 (rv 1.0 10) 1 (rv -1 -1.5))
"freq" (inside-osc 0.01
(generate-line 400
(rv 100 1000)
(rv 50 3000) :exponential t))
"amp" 0.1)
osc: sequential objects
OSC score objects can be combined in sequence in 2 ways. The sequence of objects can be specified by name or the sequence can be generated using a generator etc. which will choose from among available scores. In both cases, each time another score object is applied, it is generated anew.
Specify a Sequence of Objects
To specify a sequence of score objects, use the OSC Scores>Sequential scores menu item. In the space for score objects, the names of score objects can be entered (example 1).
As many objects as desired can be entered. The objects can be OSC score objects, sequential OSC score objects, parallel OSC score objects and/or OSC Score bunches.
A time delay between objects can be specified as a number (in seconds). If no delay is desired, no number need be entered (example 2).
In example 2, a gap of 3 seconds will occur between the end of osc2 and the beginning of osc1. Note that the two applications of osc1 may result in different events (depending on the way that osc1 was specified). If osc1 contains generators with random aspects, the files will probably be different.
If an OSC score bunch object is used, it should come before any other score object which may need the results of the message it sends.
Generate a Sequence of Objects
To generate a sequence of score objects, use the menu item OSC Scores>Generate Sequential Scores.
The number of scores to be generated, something to produce an offset value (between the scores), and a generator etc. to choose the sequence of scores should be entered (example 3).
The offset value can be a constant, list, generator, etc. If the offset is 0, there will be no time gap between the end of one score and the beginning of another.
The scores can be chosen with a generator as in the above example. A list could be given in which case the scores occur in the same order as they occur in the list (example 4).
The name of a single score could be used (example 5).
Note that the times indicated in any bundles in the Include box, will be adjusted to correspond to the beginning of the score in which they occur.
EXAMPLE 1: (fill-template create-sequential-osc-score-object
osc-seq1 osc1 osc2)
EXAMPLE 2: (fill-template create-sequential-osc-score-object
osc-seq2 osc1 osc2 3 osc1)
EXAMPLE 3: (fill-template generate-sequential-osc-score-object
gen-osc-seq1 5
(random-value 1.0 2)
(random-choice '(osc1 osc2)))
EXAMPLE 4: (fill-template generate-sequential-osc-score-object
gen-osc-seq2 5
(random-value 1.0 2)
'(osc1 osc2))
EXAMPLE 5: (fill-template generate-sequential-osc-score-object
gen-osc-seq3 5
(random-value 1.0 3)
osc1)
(otf object1 operator1 object2 &rest expressions)
OTF is a shortcut for ON-THE-FLY (example 1).
See the help for generator ON-THE-FLY for more information.
EXAMPLE 1: (for-example (otf '(10 20 30) + (rv -1.0 1)))
(overlap start-time duration amount &key percent)
Returns a closure. When applied, a start time and duration are calculated for a CSound or OSC file.. The start time for the next event in the score file will overlap the previous one by AMOUNT. The time unit for START-TIME, DURATION and AMOUNT is seconds (example 1).
The resulting Csound score could be rendered with test csound.orc in Support/FileExamples.
In the score file made by example 1, each event begins 0.25 seconds before the previous one is finished. Note that overlap is used for the START parameter.
Since DURATION is typically not a constant value, FROM-OVERLAP can be used to fill in the generated durations for the Csound score dialog parameter DURATION (example 2).
A similar output could be realized as an OSC score object (example 3).
The source code for the synthdef sine1 can be found in test osc synthdefs.rtf in Support/FileExamples.
If START-TIME is a generator, it is applied once to calculate the initial start time (example 4).
DURATION and AMOUNT can be a constant value, generator, stockpile, etc.
If the keyword PERCENT is bound to t, AMOUNT is considered to be a percentage in the range 0-100. That percentage of the previous duration will determine where the next event will be begin (examples 5-6).
The value for AMOUNT can also be negative which means there will not be an overlap, but rather a gap (example 7).
OVERLAP is intended to produce granular textures with a guarantee that grains will overlap (unless a negative AMOUNT is used, in which case the guarantee is that grains will not overlap).
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1
(overlap 0 1 0.25)
1 30000 (random-value 100.0 1000))
EXAMPLE 2: (fill-template csound-score-object score2
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1
(overlap 0 (random-value 0.5 1.5) 0.25)
(from-overlap) 30000 (random-value 100.0 1000))
EXAMPLE 3: (fill-template osc-score-object osc-score2 10 "sine1" NIL NIL NIL 1
(overlap 0 (random-value 0.5 1.5) 0.25)
"dur" (from-overlap) "amp" 0.5
"freq" (random-value 100.0 1000))
EXAMPLE 4: (fill-template csound-score-object score3
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 2 10 1
(overlap (random-value 0.0 2)
(random-value 0.5 1.5) 0.25)
(from-overlap) 16000 (random-value 100.0 1000))
EXAMPLE 5: (fill-template csound-score-object score4
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1
(overlap 0 (random-value .5 1.5) 50 :percent t)
(from-overlap) 16000 (random-value 100.0 1000))
EXAMPLE 6: (fill-template osc-score-object osc-score3
10 "sine1" nil nil nil 1
(overlap 0 (random-value 0.5 1.5) 50 :percent t)
"dur" (from-overlap) "amp" 0.2
"freq" (random-value 100.0 1000))
EXAMPLE 7: (fill-template csound-score-object score5
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 10 1
(overlap 0 (random-value .5 1.5)
(random-value -1.0 -0.5))
(from-overlap) 16000 (random-value 100.0 1000))
(par parameter)
Returns a closure which can be used when defining a Csound score object. This is the only possible use of this generator. When the closure is applied, the current value for a parameter of a Csound score is returned.
Parameters in Csound scores are basically generated in order, p1,p2,p3 .... PAR can only access a lower-numbered parameter (i.e. one which has already been generated). The creation order of p2 (start time) and p3 (duration) has various dependencies to accomodate constructions such as until-time. Accessing p2 and p3 in those fields might not lead to the desired results.
PARAMETER can be the number of the Csound p-field: 1,2,3,4,5,6,... or the symbols number, instrument, start, duration. Number returns the number of events in this layer of the score. Instrument returns the instrument number. Start returns the start time. Duration returns the duration value. 4 would return the value of p4.
In general, any parameter can access a lower-numbered parameter. In any case, any parameter > 3 can always do that. P5 for instance can access number, instrument, start, duration, and p4.
To have frequency dependent on duration (the longer the duration, the lower the frequency), this expression could be used for the frequency parameter:
(on-the-fly 100.0 / (par 'duration))
The value 100.0 is divided by the value for duration (in p3). If duration is .1, frequency is 1000. If duration is .5, frequency is 200.
Assuming an instrument (such as instrument 2 in test csound.orc in the Support/FileExamples folder) where p4 is for frequency and p5 for amp, PAR could be used as in example 1.
Again assuming frequency as p4 and amp as p5, amp is dependent on frequency in example 2.
For each amplitude value, the frequency value in p4 is read and compared to some boundaries. If p4 > 700, the generator (rv 500 1000) is chosen which produces rather small amplitudes. Otherwise, p4 is compared to 400. If larger, (rv 1000 2000) is used, producing larger amplitudes. In all remaining cases, p4 is <= 400 and (rv 10000 15000) is used for amplitude.
PAR is a generator and can only be used when a generator is appropriate in a Csound score object.
EXAMPLE 1: (fill-template csound-score-object score1
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 50 2 0 (random-value 0.1 0.5)
(on-the-fly 100.0 / (par 'duration)) 10000)
EXAMPLE 2: (fill-template csound-score-object score2
"f1 0 8192 10 1
f2 0 8192 20 2 1"
nil nil 1 50 2 0
(rv 0.1 0.2) (rv 200.0 1000)
(act-if (par 4) > 700
(rv 500 1000)
else > 400 (rv 1000 2000)
else (rv 10000 15000)))
parallel section
A section made by combining two ore more sections, communities, or midi objects in parallel. Combining sections in parallel means that the notes of the sections will be layered and heard at the same time. Combining a community in parallel means that the members of the community will be combined in parallel. If a community consists of 5 sections, those 5 sections will be heard at the same time.
A time offset expressed in seconds can be entered between the objects. The following object will delay starting that amount of time. This offset has no effect on other objects.
(pass-stockpile-filter stockpile)
This tool will produce a filter which selects a value if it is found in the stockpile. It should be used with the FILTER method or with FILTER-STOCKPILE.
To use with the FILTER method: choose OTHER as the filter type.
STOCKPILE may be a list or a stockpile object.
If SECTION1 exists, it can be filtered with example 1. Only notes which have a pitch of 60 or 64 or 67 will be passed. Everything else will be filtered out.
Example 2 uses the tool with FILTER-STOCKPILE.
EXAMPLE 1: (fill-template filter section1f section1
(other (pass-stockpile-filter '(60 64 67))) 'pitch t)
EXAMPLE 2: (print-result
(filter-stockpile '(1 2 3 4 5 6 7 8 9 10)
(pass-stockpile-filter '(2 4 6 8))))
(peaks? stockpile)
If STOCKPILE contains data returned by READ-SPECTRUM-FILE, the number of spectral peaks is printed in the Text Output window and also returned as a numerical value.
Example 1 will create a stockpile. Select the sample file 'test spear bassoon.txt' from Support/FileExamples.
Example 2 prints and returns the number of peaks. The purpose of this tool is to remind the user about the number of peaks if it is forgotten for some reason.
To recall the number of tracks in data returned by READ-TRACKS-FILE, use tool TRACKS?.
EXAMPLE 1: (fill-template construct-stockpile spectrum1
(read-spectrum-file))
EXAMPLE 2: (print-result (peaks? spectrum1))
(pendulum x y omega damp bigomega bigA giant &key eye xy (stepsize 0.01) first)
Returns a closure. When applied returns the next value of a dynamical system, described by the following formula:
x'=y
y'=-omega^2sinx-cy+Acos(Bigomega*t)
The default output variable is X. By using the keyword EYE the variable Y is returned. Both variables will be returned in a list by using the keyword XY.
X and Y set the initial values for place and velocity. OMEGA is the frequency of the non-driven pendulum, while DAMP is its damping. BIGOMEGA and BIGA are the values of the frequency and amplitude of the driving force.
The parameter GIANT determines after how many iterations the value is returned. This can be useful for filling a list with a small number of values describing the behaviour of the system over a longer period.
By setting the values for BIGOMEGA and BIGA to zero,the system behaves like a free oscillating (damped) pendulum (example 1).
A driven pendulum starts off with a transient after which it reaches a steady state oscillation (example 2).
Sometimes the steady state part of the oscillation is reached after a long chaotic transient (example 3).
Sometimes the steady state will never be reached (example 4).
It is not easy to predict the maximum and minimum of the output values. To map the output of this function to useful values, use CONVERT (example 5).
The initial values for X and Y are not returned. If the initial values should be returned as the first result of the generator, keyword FIRST should be bound to t (examples 6-7).
This generator was contributed by Gijs de Bruin.
EXAMPLE 1: (plot (pendulum 1.0 1.0 2.5 0.9 0.0 0.0 10))
EXAMPLE 2: (plot (pendulum 1.0 1.0 2.5 0.5 1.4 3.8 10)
:number 300)
EXAMPLE 3: (plot (pendulum 1.0 1.0 2.5 0.5 1.99 3.8 10)
:number 350)
EXAMPLE 4: (plot (pendulum 1.0 1.0 2.5 0.5 1.8 3.8 10)
:number 500)
EXAMPLE 5: (for-example
(convert (pendulum 1.0 1.0 2.5 0.5 1.8 3.8 10) 100 c2 c5))
EXAMPLE 6: (for-example (pendulum 1.0 1.0 2.5 0.9 0.0 0.0 10))
EXAMPLE 7: (for-example
(pendulum 1.0 1.0 2.5 0.9 0.0 0.0 10 :first t))
(pentatonic start)
Returns a closure. When applied, a note number corresponding to the next value in a pentatonic scale is generated. The first value in the series is START. The series could continue indefinitely (examples 1-2).
EXAMPLE 1: (for-example (pentatonic 60) :number 8)
EXAMPLE 2: (for-example (pentatonic 55) :number 8)
(phrase-groupings section parameter new-value-generator &key other)
Determines phrase groupings according to Tenney's theory of Temporal Gestalt Perception of Music (Journal of Music Theory 24,2). In short, this theory states that a new group begins when an interval (of some parameter) is larger than the interval preceding it and the interval following it.
Every time a new group begins, NEW-VALUE-GENERATOR (a generator or a list) should provide a value which will be added to the current value in the section being transformed. If the parameter being transformed is ATTACKS and the parameter being grouped is PITCH, the result would be a rest before each new group begins. Example 1 defines a section which is transformed in example 2.
A rest of between 100 and 300 milliseconds will be added before each group boundary. The boundaries are determined by pitch. If pitch contains chords (i.e. a list of pitches to begin at one time point), the average values of the pitches in a chord is used as the pitch of the chord. (This is not part of Tenney's theory).
PITCH, DURATION, ATTACKS, and VELOCITY are the parameter that can be used with PHRASE-GROUPINGS to determine the phrase boundaries. If a parameter other than attacks is being transformed with this transformer, the key word :OTHER should be true:
(phrase-groupings s1 'pitch 20 :other t)
This transformer currently only works with sections.
EXAMPLE 1: (fill-template data-section s1 100 100 1 (rv 40 80) f 1)
EXAMPLE 2: (fill-template transform s1t s1
:attacks (phrase-groupings
s1
'pitch (random-value 100 300)))
(pick-editor-font)
This tool allows setting the font of the Lisp editor to a fixed width font. It must be set to a fixed width font (example 1).The choice is not remembered between sessions.
The intended use of this tool is to increase the size of the Lisp editor font for making presentations. Otherwise the only choices are in the preferences for font and dialog size.
EXAMPLE 1: (pick-editor-font)
(piecewise number a b number2 c number3 d ...)
Returns a closure. When applied, the next value is returned. Linear sequences of numbers are produced: NUMBER values are evenly spaced between A and B (example 1).
If one of the numbers in a pair of low and high values is a real number, the resulting numbers will be reals (example 2).
A function indicating how the numbers should be converted to integers can be included as the last argument (example 3).
To ensure that the numbers are floats instead of rationals, the function FLOAT can be included as the final (conversion) argument (examples 4-5).
Additional line segments can be specified by including NUMBER2 and C (example 6). This produces 11 steps from 1 to 11 and 10 back to 1.
Any number of additional segments can be specified (examples 7-8).
EXAMPLE 1: (for-example (piecewise 20 1 10))
EXAMPLE 2: (for-example (piecewise 20 1.0 10))
EXAMPLE 3: (for-example (piecewise 20 1 10 #'round))
EXAMPLE 4: (for-example (piecewise 20 1 10))
EXAMPLE 5: (for-example (piecewise 20 1 10 #'float))
EXAMPLE 6: (for-example (piecewise 11 1 11 10 1) :number 21)
EXAMPLE 7: (for-example (piecewise 10 1 10 5 20 5 1))
EXAMPLE 8: (for-example (piecewise 10 1 5 5 20 5 1 #'round))
pitch
Pitch is expressed as midi note numbers (0-127). Pitch may be also be represented as a lettername with an octave: c4 is Midi note number 60. c#4 is 61. df4 is also 61. Via the 'Preferences' dialog, it is possible to assign Midi note number 60 to the symbol c3. All other input symbols for pitch are then adjusted accordingly.
QuickTime and Capybara/Pacarana Midi output can play floating-point numbers (microtones). 60.5 is a quarter-tone higher than 60. Any value after a decimal point may be specified in the AC Toolbox for pitch. Capybara/Pacarana output has a higher fractional resolution than does QuickTime.
Midi output sent to other destinations will be rounded to integers. Pitch data in Midi files is also limited to integer representations.
In a data section, if a single value is a list, it is considered to be a chord:
'((60 64 67) (62 67 69)) represents 2 chords.
(pitch-and-octave pitch octave)
Returns a closure. When applied, a MIDI note number is produced. PITCH can be in any range, but it is reduced to 0 - 11 as the representation of the pitch class. 0 is C, 1 is C#, etc.
OCTAVE is related to the choice made in the Preferences for C3 or C4. If middle C is represented as C4 (the default situation), then a value of 4 will produce the octave starting with middle C. If middle C is represented as C3, then a value of 3 will produce the octave starting with middle C. In the first case (using C4), OCTAVE can have values from -1 to 9. In the second case (using C3), OCTAVE can vary from -2 to 8.
PITCH and OCTAVE can be constants, lists, stockpiles, or generators (examples 1-4).
EXAMPLE 1: (for-example
(make (pitch-and-octave 0 4)))
EXAMPLE 2: (for-example
(pitch-and-octave '(0 1 2 3) (random-value 0 4)))
EXAMPLE 3: (for-example
(pitch-and-octave (major 60) (random-value 0 4)))
EXAMPLE 4: (for-example
(midi->notename
(pitch-and-octave (major 60) '(3 4 5))))
(pitch-class-filter pitch-classes)
Will produce a filter that will select a value if its pitch class is found in PITCH-CLASSES. PITCH-CLASSES should be a list or stockpile. It can be used with the FILTER method or with FILTER-STOCKPILE.
With the FILTER method, choose OTHER as the filter-type.
If SECTION1 exists, it can be filtered with example 1. In that example, only pitches in the specified pitch classes (0 4 7) or c, e, g will be passed through.
Example 2 shows the use of this filter with FILTER-STOCKPILE.
EXAMPLE 1: (fill-template filter section1f section1
(other (pitch-class-filter '(0 4 7))) 'pitch t)
EXAMPLE 2: (print-result (stockpile->notename
(filter-stockpile '(c3 c#3 d3 c4 f4 c5)
(pitch-class-filter '(0)))))
(pitch-interval-filter &key intervals (next t))
Produces a filter which will filter out undesired pitch intervals in a section. The intervals can occur in parallel or in sequence.
With the dialog for the FILTER method, choose OTHER as the filter type. Choose WHATEVER as the parameter. If the start times of the notes are not to be changed, the check box LEAVE GAPS should be checked. The keyword INTERVALS can be bound to a constant value (if only one interval is to be filtered) or to a list of values.
Example 1 creates data section ds1. Example 2 shows the text representation of this data section. Example 3 filters pitch repetitions from section ds1. Example 4 shows the text representation. In the pitch column, note that the repetition of note number 62 is missing.
In example 5, ds1 is filtered to removed all unisons and major seconds. Intervals is bound to '(0 2) (examples 5-6).
If keyword NEXT is bound to nil, only intervals occurring at the same time are filtered. Intervals in sequence are not filtered. To demonstrate this, the sections in examples 7-8 can be made. These sections should contain some 'forbidden' intervals that happen both in parallel and in sequence. Example 9 will filter the intervals 0 and 2. Examples 10-11 show the text representations of the unfiltered and the filtered section. The default value for NEXT is t which means that both parallel and sequential intervals are filtered. This is the case in example 9.
In example 12, the keyword NEXT is bound to NIL. This will only filter 'forbidden' intervals that have the same start time but not the intervals that happen in sequence. Example 13 shows the text representation.
The PITCH-INTERVAL-FILTER does not filter pitches which have been entered as lists (chords), either by the user or by the generator MAKE-CHORD. In MAKE-CHORD, it is possible to block intervals when constructing a chord. It is also possible to prevent successive chords from sharing pitches.
PITCH-INTERVAL-FILTER does not work in combination with FILTER-STOCKPILE since start time values are needed.
EXAMPLE 1: (fill-template data-section ds1 100 10 1
'(60 62 62 64 67 69 67 63) mf 1)
EXAMPLE 2: (show-text ds1)
EXAMPLE 3: (fill-template filter ds1f ds1
(other (pitch-interval-filter :intervals 0)) 'whatever t)
EXAMPLE 4: (show-text ds1f)
EXAMPLE 5: (fill-template filter ds1f2 ds1
(other (pitch-interval-filter :intervals '(0 2)))
'whatever t)
EXAMPLE 6: (show-text ds1f2)
EXAMPLE 7: (fill-template data-section ds2 100 50 1
(rc '(60 62 63 64 67 69)) mf 1)
EXAMPLE 8: (fill-template new-generate-parallel-section
ds2-p 4 0 ds2 nil nil nil nil)
EXAMPLE 9: (fill-template filter ds2-pf ds2-p
(other (pitch-interval-filter :intervals '(0 2)))
'whatever t)
EXAMPLE 10: (show-text ds2-p)
EXAMPLE 11: (show-text ds2-pf)
EXAMPLE 12: (fill-template filter ds2-pf2 ds2-p
(other (pitch-interval-filter :next nil :intervals '(0 2)))
'whatever t)
EXAMPLE 13: (show-text ds2-pf2)
(pitch-repetition-filter)
Produces a filter which will filter out repeated pitches from a section. It filters pitches which occur at the same time and pitches which occur in succession.
With the dialog for the FILTER method, choose OTHER as the filter type. Choose WHATEVER as the parameter. If the start times of the notes are not to be changed, the check box LEAVE GAPS should be checked (examples 1-2).
The repetitions of pitches which probably occurred in ds1 are filtered away in ds1f. This results in fewer notes.
Example 3 creates some layers to filter.
Example 4 filters out pitch repetitions.
Examples 5-6 show the difference in the two text versions.
The PITCH-REPETITION-FILTER does not filter pitches which have been entered as lists, either by the user or by the generator MAKE-CHORD. Repetitions within a chord can in that case be removed with the transformer REMOVE-DOUBLES. In MAKE-CHORD, it is possible to block unisons when constructing a chord. It is also possible to prevent successive chords from sharing pitches.
For a filter that allows removing other pitch intervals, see PITCH-INTERVAL-FILTER. PITCH-INTERVAL-FILTER can also be limited to only remove undesired values that occur at the same time but not in sequence.
PITCH-REPETITION-FILTER does not work in combination with FILTER-STOCKPILE since start time values are needed. A stockpile can be filtered with REPETITION-FILTER.
EXAMPLE 1: (fill-template data-section ds1 100 100 1
(rv 60 67) mf 1)
EXAMPLE 2: (fill-template filter ds1f ds1
(other (pitch-repetition-filter))
'whatever t)
EXAMPLE 3: (fill-template new-generate-parallel-section
ds1-p 4 0 ds1 nil nil nil nil)
EXAMPLE 4: (fill-template filter ds1-pf ds1-p
(other (pitch-repetition-filter))
'whatever t)
EXAMPLE 5: (show-text ds1-p)
EXAMPLE 6: (show-text ds1-pf)
(pitch-track data track &key filter)
Returns a list of pitches read from one or more tracks of data produced with READ-TRACKS-FILE.
TRACK can be a constant, a list, or a stockpile with track numbers.
READ-TRACKS-FILE can read track data made by SPEAR or the Csound Hetro utility.
For example 1, select file 'test spear voice.txt' in Support/FileExamples. Example 2 plots one track of pitches. Example 3 plots all of the pitches. Example 4 produces a stockpile of pitches which is used in the sections made with examples 5-6.
Pitch repetitions can be filtered by binding FILTER to t (examples 7-9).
EXAMPLE 1: (fill-template construct-stockpile voice1
(read-tracks-file :round 0.5))
EXAMPLE 2: (plot (pitch-track voice1 4))
EXAMPLE 3: (plot (pitch-track voice1 (from 1 30)))
EXAMPLE 4: (fill-template construct-stockpile track-data1
(pitch-track voice1 4))
EXAMPLE 5: (fill-template data-section track-melody1
100 (get-length track-data1) 1
track-data1 mf 1)
EXAMPLE 6: (fill-template data-section track-melody2
100 100 1
(random-choice track-data1) mf 1)
EXAMPLE 7: (fill-template construct-stockpile track-data2
(pitch-track voice1 '(4 7 10) :filter t))
EXAMPLE 8: (fill-template data-section track-melody3
100 (get-length track-data2) 1
track-data2 mf 1)
EXAMPLE 9: (fill-template data-section track-melody4
100 100 1
(random-choice track-data2) mf 1)
play
To play a section, community, or Midi object, select it in the Objects dialog and then choose play. The Objects dialog can be opened with 'Tools>Show Objects'. The menu item 'Tools>Play' will play the selected item in the Objects dialog if the dialog is opened and the selected object can be played. If playing is not as consistent as desired, make sure that the preference for Scheduler Overdrive is selected.
(plot whatever &key title min max number plot replace 2d)
A visual representation is made of the object WHATEVER.
WHATEVER can be a list, shape, mask, stockpile, section, lexical closure, etc (examples 1-2).
If WHATEVER is a generator, the representation is of the result of applying the closure a number of times. By default this is 100. That number can be changed with the key word NUMBER which is only available for use with a generator. For all other objects it is ignored (example 3-4).
If WHATEVER is a generator or a list, the keyword PLOT can be used display values as points or a line. If PLOT is t, points will be plotted. If PLOT is nil, a line will be drawn between the points (example 5).
TITLE should be a string (example 6).
Normally, the drawing or representation is scaled by determining what the actual minimum and maximum value in the group of numbers to be displayed. This can be overridden with the keywords MIN and MAX if you want to refer to some other range (examples 7-8). If the actual minimum or maximum is outside the values expressed by MIN or MAX, the actual boundary will be used.
If the elements of the list to be displayed are lists with two values, the elements will be treated as x,y pairs and plotted as such (example 9).
If the generator produces lists with two elements, the lists will be treated as x,y pairs and plotted as such (example 10).
If the elements of a list to be displayed or the results of applying a lexical closure are lists with 3 elements, thoses elements will be treated as x,y,z combinations and x,z will be plotted (example 11).
Keyword REPLACE controls whether the previous plot window should be removed after the new one has been made (example 12).
The keyword 2D controls the way that data which is also a list is displayed. Lists of 2 or 3 values in lists or stockpiles can be considered x,y or x.y.z data but also as a chord. This ambiguity can be resolved by binding a value to 2D. The default is t meaning that values will be considered as x,y data (examples 13-17).
EXAMPLE 1: (plot '(1 100 50 75))
EXAMPLE 2: (plot sine-shape)
EXAMPLE 3: (plot (random-value 1 100))
EXAMPLE 4: (plot (random-value 1 100) :number 500)
EXAMPLE 5: (plot (random-value 1 100) :plot nil)
EXAMPLE 6: (plot sine-shape :title "A Sine")
EXAMPLE 7: (plot (random-value 1 50))
EXAMPLE 8: (plot (random-value 1 50) :min 1 :max 100)
EXAMPLE 9: (plot '((0 0) (50 20) (100 50) (40 25)))
EXAMPLE 10: (plot (henon 0 0 1.4 0.3 1 :xy t))
EXAMPLE 11: (plot (lorenz 0.1 0.1 0.1 10 28 3/8 1 :xyz t))
EXAMPLE 12: (plot (rv 1 100) :replace nil)
EXAMPLE 13: (fill-template generate-stockpile henon-stock
10 (henon 0.0 0.0 1.4 .3 1 :xy t))
EXAMPLE 14: (plot henon-stock)
EXAMPLE 15: (fill-template generate-stockpile chords
10 (make-chord (rv 40 80) 2))
EXAMPLE 16: (plot chords)
EXAMPLE 17: (plot chords :2d nil)
plotting
When possible, objects can be plotted by selecting the object name in the OBJECTS dialog and then selecting Plot.
Individual parameters of a section or community can be plotted with the 'Plot' menu item (available parameters are 'Pitch', 'Rhythm', or 'Velocity').
One parameter of a Csound score file can be plotted over time using the dialog created by Tools>Plot>Csound File.
One argument of an OSC file can be plotted over time using the dialog creaed by Tools>Plot>OSC File.
The output of a number of applications of a generator can be plotted using Tools>Plot>Other. The number of applications can be set in the options for that dialog. The choice between plotting dots or drawing lines can also be made in the options.
A list can also be plotted with Tools>Plot>Other
A multi controller midi object is plotted with different colors for each controller. The controllers are plotted according to their order in the object. The order of the colors are: the default plotting color, blue, orange, red, slategrey, pink.
(plus-min value probability)
Returns a closure. VALUE is assumed to be something which could produce a positive value. PROBABILITY is something that could produce a probability value in the range of 0-1. (O is never, 1 is always).
Both VALUE and PROBABILITY can change over time. They can be e.g. a constant, a list, a stockpile, a generator, etc (examples 1-2).
When a value is produced, it may be made a negative number according to the specified probability. Rests in the AC Toolbox are specified as negative numbers. This generator can produce rests or rhythmic values according to the specified probability.
EXAMPLE 1: (for-example (plus-min '(1 2 3 4 5) 0.5))
EXAMPLE 2: (for-example (plus-min (random-value 1 10) 0.3))
(positive-negative value &key pos neg)
Returns a closure. When applied, one value is produced using VALUE which may vary over time. The next value will normally be the negative version of that same value. Then the next value from VALUE is produced. And the next negative version. Etc.
VALUE may be a constant, list, generator, etc.
In examples 1-4, one positive value is followed by one negative value. Using the keywords POS and NEG these numbers can be changed.
If POS is bound to 2, the positive value will occur two times before the negative value occurs (example 5).
If NEG is bound to 3, the negative value will occur three times (example 6).
It is possible to bind values to POS and NEG in the same expression (example 7).
VALUE, POS, and NEG may vary over time (example 8).
EXAMPLE 1: (for-example (positive-negative 1))
EXAMPLE 2: (for-example (positive-negative '(1 2 3 4)))
EXAMPLE 3: (for-example (positive-negative (random-choice '(1 3 4))))
EXAMPLE 4: (for-example
(add-to 60
(positive-negative '(1 2 3 4 5 6 7 8 9 10 11))))
EXAMPLE 5: (for-example (positive-negative '(1 2 3) :pos 2))
EXAMPLE 6: (for-example (positive-negative '(1 2 3) :neg 3))
EXAMPLE 7: (for-example (positive-negative '(1 2 3) :pos 4 :neg 2))
EXAMPLE 8: (for-example (positive-negative (random-value 1 10)
:pos (random-value 1 3)))
(predicate function &rest values)
Predicate produces a function appropriate for use with WITHOUT or FILTER-STOCKPILE. The first argument should be a function. Zero, one, or two additional arguments are accepted.
If one additional argument is used, the generated value is compared to it.
The predicate in example 1 excludes values less than 60.
If two additional arguments are used, the generated value is used between the two arguments when the predicate is made.
The predicate in example 2 does not allow values between (and including) 60 and 70.
If no additional arguments are used, the function is applied to the generated value (example 3).
The above predicate would not allow even values.
Predicate can also be used with FILTER-STOCKPILE to produce a function to filter a stockpile or list (example 4).
In earlier versions of the AC Toolbox, the function argument in predicate had to be preceded by a function quote: #'. This is no longer necessary though it may be used (example 5).
Predicate is the name that is used to describe Lisp functions that test for some condition and indicate if the condition is true or false.
EXAMPLE 1: (for-example
(without (predicate < 60)
(random-value 40 80)))
EXAMPLE 2: (for-example
(without (predicate <= 60 70)
(random-value 40 80)))
EXAMPLE 3: (for-example
(without (predicate evenp)
(random-value 40 80)))
EXAMPLE 4: (print-result
(filter-stockpile (from 1 10) (predicate < 5)))
EXAMPLE 5: (for-example
(without (predicate #'< 60)
(random-value 40 80)))
preferences
Several preferences which affect the program can be specified using the dialog made with the menu item AC Toolbox > Preferences. If the preference concerns a window, it will not change the current windows but will only effect new ones.
PEN COLOR
The color of the pen for drawing shapes and masks, as well as for plotting various values can be chosen using one of the available Apple color selection tools.
FONT AND DIALOG SIZE
Three sizes are available for fonts and dialogs. If Big is chosen, most dialogs will be bigger and use larger fonts. This is convenient when using a projector. Small will make most dialogs and fonts smaller. Normal is the standard setting.
EXTERNAL VALUE
The generator external-value can refer to either Midi controller numbers or Midi channels as the first argument to the generator.
EXAMPLES: CLOSE PREVIOUS WINDOW WITH TOOL
The tools plot, make-histogram, and for-example are often used in examples in the help for generators, tools, and transformers. These tools could always close the previous window made by the tool each time a new one is made. This reduces screen clutter. This setting only applies to the tools. It does not affect the settings in the options for various dialogs.
WHEN OPENING OBJECT DIALOGS
Each time an object dialog is opened, the previous dialog can be closed or left unchanged. Closing the previous dialog reduces screen clutter.
SAVE ENVIRONMENT WITH
The AC Toolbox can read environment files written in older formats. Previous versions of the Toolbox (before 4.4) cannot read environments in the current (new) format. If data is to be shared between various versions of the Toolbox, environment files should be saved in the old format. The old format will not save object dialog size and position information.
WINDOW STYLE
Dialogs can either use a textured background or the standard style. This only effects new dialogs.
DATE FORMAT
When environment or example files are saved, a name reflecting the current date may be suggested. A choice can be made among the two possible data formats.
TRANSPARENCY
The transparency of new windows can be changed. Moving the slider to the left reduces transparency.
MIDDLE C (60)
Middle C is Midi note number 60. Many people and programs call this pitch C4. Some call it C3. Adjusting the preference causes the value of all pitch symbols, such as c3, c#3, etc. to be adjusted.
CLEAR-PREFERENCE-FILE
A tool called clear-preference-file can be used to delete the preference file which stores the settings of the preferences mentioned in the Preferences dialog as while information about the size and position of many dialogs. Using this tool will also cause the AC Toolbox to not to save the current values to a file the first time the program is closed after this tool has been used. On subsequent use, the preferences will be saved.
The clear-preference-file can be evaluated using the example found in the help for the tool.
(prime-number &optional n)
Returns a closure. When applied, it will generate the next prime number (example 1). If the optional parameter N is specified, the first result will be the next prime number higher than N (example 2). Otherwise the series starts with 2 as the first prime number.
EXAMPLE 1: (for-example (prime-number))
EXAMPLE 2: (for-example (prime-number 20))
(print-phrase-groupings section parameter to-produce-value)
Returns a closure that can be used with the TEXT-SCORE dialog. A section is studied for phrase groupings according to Tenney's theory (see the help for the transformer PHRASE-GROUPINGS for more information). The parameters that can be analyzed are PITCH, DURATION, ATTACKS, and VELOCITY. TO-PRODUCE-VALUE should be a closure, a list, or a symbol.
The primary use for this tool is to produce a closure for the additional parameter for printing a score. The following form could be entered in the box for EXTRA PARAMETER EXPRESSION (OPTIONAL) if section S1 is being printed:
(print-phrase-groupings s1 'pitch 'group)
The symbol GROUP will be printed on each line where a pitch group begins.
(print-result expression)
This tool is used in help windows. EXPRESSION will be evaluated and the result is printed to a window (example 1).
EXAMPLE 1: (print-result (get-input sine-shape))
(produce n object)
Returns a list of N values derived from OBJECT. If object is a generator, it is applied N times (example 1).
If OBJECT is a list or stockpile, the first N values are taken from the the object (example 2). If the object contains fewer than N values, PRODUCE loops through the available values (example 3).
If N is a generator, stockpile, etc., one value is taken from it to determine n.
EXAMPLE 1: (print-result (produce 10 (rv 1 100)))
EXAMPLE 2: (print-result (produce 2 '(1 2 3 4 5)))
EXAMPLE 3: (print-result (produce 20 '(1 2 3 4 5)))
(produce-pulse produce-indispensability produce-level
&optional max-indispensability-level low-value high-value)
Returns a closure. When applied, the next value reflecting an interpretation of a pulse value is produced.
The standard interpretation is for rhythmic values; 1 or -1 is produced depending if the pulse-value is positive or negative (examples 1-2). If the optional parameters are included, the interpretation is for velocity (or some other parameter). Negative pulse values are 0 and positive values are mapped between LOW-VALUE and HIGH-VALUE (examples 3-4).
The pulse value is determined by how indispensable it is and what the level of thinning is. Both of these concepts come from Clarence Barlow in CMJ 11,1.
If a meter is described as 3*2, it is for example 3/4: 3 divisions of 2. The first pulse is the most important and has the value 5. The least important pulse would have the value 0. Clarence's indispensabilities for 3/4 are '(5 0 3 1 4 2). 6/8 is '(5 0 2 4 1 3).
If the thinning level is 2, all pulses with a indispensability less than 2 are turned into rests, i.e. a negative value (-1). All pulses with an indispensability that is 2 or higher are 1. If the thinning level is a function or a list, the next value is chosen at the beginning of each indispensability list.
The first two parameters to this generator function can be a constant, a list, or a generator. The optional parameters should be constants.
Also see the tool PULSE-HIERARCHY which can be used to generate a list of indispensability values given some metric division.
EXAMPLE 1: (for-example (produce-pulse '(5 0 2 4 1 3) 2)
:number 12 :number-per-line 6)
EXAMPLE 2: (for-example (produce-pulse '(5 0 2 4 1 3)
(random-value 1 5))
:number 24 :number-per-line 6)
EXAMPLE 3: (for-example (produce-pulse '(5 0 2 4 1 3) 2 5 50 90)
:number 12 :number-per-line 6)
EXAMPLE 4: (for-example (produce-pulse '(5 0 2 4 1 3)
(random-value 1 5) 5 50 90)
:number 24 :number-per-line 6)
(program-filter parameter filter)
Since the filter template has no button for filtering MIDI program changes that may be in a midi-controller-object or a midi-section, a filter definition will have to be produced if you want to filter MIDI program changes.
Choose OTHER as the filter type then use PROGRAM-FILTER to produce an appropriate filter definition.
PARAMETER can be:
NUMBER
CHANNEL
FILTER can be a Lisp expression reflecting the available filter types:
(low-pass threshold)
(high-pass threshold)
(band-pass low high)
(band-reject low high)
(bank low1 high1 low2 high2 ...)
(shot-gun percentage)
If Midi program object PROG1 exists, it can be filtered with example 1.
Click on SET PARAMETERS to see the filter definition. A low-pass filter for midi program changes will be produced.
EXAMPLE 1: (fill-template filter prog2 prog1
(other (program-filter 'number (low-pass 10)))
'whatever nil)
(program-transform parameter transformer)
This transformer builds another transformer which can be used with the WHATEVER parameter (and only with the WHATEVER parameter) to transform MIDI program change commands. MIDI program change commands are only found in midi-program-objects or midi-sections.
PROGRAM-TRANSFORM 'encapsulates' the other transformer and makes it suitable for use with MIDI program change commands.
The available values for PARAMETER are:
number
channel
NUMBER would transform the MIDI program number.
CHANNEL transforms the MIDI channel assignment for the MIDI
program commands.
The parameter values should be quoted.
TRANSFORMER can be any available transformer such as TRANSPOSE.
If object midi1 exists, it can be transformed with example 1.
EXAMPLE 1: (fill-template transform midi2 midi1
:whatever (program-transform 'number (transpose 12)))
(pulse-hierarchy &rest divisions)
Returns a list of indispensabilities for the pulses of some metric division. Any number of divisions can be specified.
At the level of sixteenth notes
3/4 is 3 * 2 * 2 and should be entered as (pulse-hierarchy 3 2 2)
6/8 is (pulse-hierarchy 2 3 2)
12/16 is (pulse-hierarchy 2 2 3)
This implementation differs with Clarence Barlow's formula in that his way is completely deterministic. This algorithm only assumes that the first pulse is the most indispensable and the remaining pulses at the same level in the hierarchy receive a random value chosen from among the available possibilities (examples 1-2).
See Clarence's article in CMJ 11(1) and the help for the generator PRODUCE-PULSE.
This tool can be used in combination with PRODUCE-PULSE and with INTERPRET-PULSE.
EXAMPLE 1: (print-result (pulse-hierarchy 3 2 2))
EXAMPLE 2: (print-result (pulse-hierarchy 2 3 2))
(pulse-interpolation list1 list2 rate)
Returns a list reflecting the interpolation between list1 and list2. Both lists are indispensability lists (see generator PRODUCE-PULSE for a discussion of indispensability). RATE is the number of times that a list is used before one value is changed.
Thinned values are represented as negative numbers. Other indispensabilities are positive.
To obtain useful results, the input lists should be thinned, otherwise the result will contain no rests and the interpolation is a bit too straightforward. THIN is a tool to thin indispensability lists (see its help).
Example 1 interpolates from a 3/4 measure (5 -1 3 -1 4 -1) to a 6/8 measure (5 -1 2 4 -1 3).
The result of PULSE-INTERPOLATION should be interpreted with INTERPRET-PULSE.
EXAMPLE 1: (for-example
(pulse-interpolation (thin '(5 0 3 1 4 2) 3)
(thin '(5 0 2 4 1 3) 2)
2)
:number-per-line 6)
(quantize unit)
Returns a closure which can be used as a transformer. The value being transformed is rounded off to the nearest multiple of UNIT (example 1).
If this transformer is used with the tempo parameter, both attack and duration values will be changed. If it is only used with duration, the attack times are not changed.
When used for tempo, attack, or duration values, the unit should be expressed in miliseconds.
UNIT may vary over time using a generator, etc.
EXAMPLE 1: (show-transformation (quantize 2)
'(0 1 2 3 4 5 6 7 8 9 10))
quicktime musical instruments
When QuickTime is selected for Midi output in the Midi Setup dialog, fractional pitch values can be played. 60.5 is a quarter tone higher than Midi note number 60.
Different General Midi instruments can be assigned to different Midi channels via the menu item Other>General Midi.
Some versions of QuickTime may require additional time between notes in order to repeat correctly. The tool MIDI-ARTICULATION can correct this problem.
Example 1 subtracts one millisecond from each duration when a section is played.
EXAMPLE 1: (print-result (midi-articulation 1))
(ramp begin end increment &key conversion (wrap t))
Steps from begin to end in steps of increment (example 1). The output wraps around to BEGIN when END has been reached. (I.e. Increment is added to begin) (example 2).
To restart with begin, set keyword wrap to nil (example 3).
Output is a real number if one or more of the arguments is a real number (example 4).
If integer output is desired in such a case, the name of a conversion function should be given to the keyword (example 5).
EXAMPLE 1: (for-example (ramp 1 20 1))
EXAMPLE 2: (for-example (ramp 1 5 1))
EXAMPLE 3: (for-example (ramp 1 5 1 :wrap nil))
EXAMPLE 4: (for-example (ramp 1 10 1.5))
EXAMPLE 5: (for-example (ramp 1 10 1.5 :conversion #'round))
(random-choice sequence)
Returns a closure. When applied, it will randomly choose one of the elements of the sequence or stockpile. Ideally, it will produce a uniform random distribution (example 1).
RANDOM-CHOICE may be abbreviated to RC (example 2).
EXAMPLE 1: (for-example (random-choice '(a b c d)))
EXAMPLE 2: (for-example (rc '(60 64 67)))
(random-deviation percentage)
Returns a closure. PERCENTAGE is the total percentage of deviation. If for example it is 10, that means that deviation is possible from 5% under the value to 5% above the value (example 1).
To force the result of the transformation to be an integer, use force-int (example 2).
PERCENTAGE may vary over time using a generator, etc. (example 3).
EXAMPLE 1: (show-transformation (random-deviation 10)
'(60 60 60 60))
EXAMPLE 2: (show-transformation (force-int (random-deviation 10))
'(60 60 60 60))
EXAMPLE 3: (show-transformation
(random-deviation (line-segment 10 10 50))
'(60 60 60 60 60 60 60 60 60 60))
(random-intervals low high &rest intervals)
Returns a closure. When applied, for the first time, a random value between LOW and HIGH is produced. Every subsequent value is randomly chosen from among the available intervals. The chosen interval is either added to or subtracted from the previous value.
The series of numbers produced by this generator will always be within the boundaries specified by LOW and HIGH.
Any number of intervals can be specified. The intervals specified in example 1 are 1,3, and 4 which indicate a minor second, a minor third, and a major third when considered as pitch. Each value in the series of numbers will be up or down one of those intervals.
EXAMPLE 1: (for-example (random-intervals 48 72 1 3 4))
(random-value low high)
Returns a closure. When applied, it will produce a random value between LOW and HIGH. Integer values for LOW and HIGH produce an integer result (examples 1-2). Otherwise a real result is returned (example 3). LOW and HIGH can change over time (example 4).
RANDOM-VALUE may be abbreviated to RV (example 5).
EXAMPLE 1: (for-example (random-value 40 80))
EXAMPLE 2: (plot (random-value 1 100))
EXAMPLE 3: (for-example (random-value 0.0 1))
EXAMPLE 4: (plot (random-value (line-segment 100 1 40)
(line-segment 100 10 90)))
EXAMPLE 5: (for-example (rv 40 80))
(ratio-choice value-sequence factor-sequence)
Returns a closure. When applied, an element of the VALUE-SEQUENCE is returned. The FACTOR-SEQUENCE is a list of integer weights specifying the relative frequency of occurance for the corresponding element in the VALUE-SEQUENCE. The first element in the FACTOR-SEQUENCE is the weight for the first element in the VALUE-SEQUENCE, etc. (example 1)
To vary weights over time, use generator CHANGING-WEIGHTS.
EXAMPLE 1: (for-example (ratio-choice '(a b c d) '(5 1 3 1)))
(ratio-value a z factor-sequence)
Returns a closure, When applied, it returns an integer between A and Z. FACTOR-SEQUENCE should contain an integer weight for each value between and including A and Z. That weight indicates the relative frequency of occurance of the corresponding number (examples 1-2).
To vary weights over time, use generator CHANGING-WEIGHTS.
EXAMPLE 1: (for-example (ratio-value 1 4 '(1 5 1 3)))
EXAMPLE 2: (make-histogram (ratio-value 1 4 '(1 5 1 3))
:number 10)
(rc stockpile)
RC is a shortcut (abbreviation) for RANDOM-CHOICE (example 1).
See the help for RANDOM-CHOICE for more information.
EXAMPLE 1: (for-example (rc '(c4 e4 g4 b4)))
(read-from stockpile index-values &optional number generator)
Returns a closure. When applied, a value from STOCKPILE is returned. The values are produced in the order determined by INDEX-VALUES. Positions are numbered starting with 1. INDEX-VALUES may be a list or stockpile of index values, a generator, a shape, or a mask.
STOCKPILE can be a list, vector, stockpile, section or any other toolbox object for which a get-stockpile method has been defined.
If INDEX-VALUES is a list or stockpile, the values should be valid indices (from 1 to the length of the stockpile or list) (example 1).
If it is a generator, the generator should also produce valid indices (example 2).
If a shape or mask is used, the index value will be considered to be the percentage from the beginning of the stockpile. This means that the stockpile is spread on the Y axis of the shape or mask. NUMBER is the length of the cycle for one application of a shape or a mask (example 3).
If MASK1 has been defined (example 4):
A mask is the only object which uses the optional generator parameter. By default, a mask chooses between its boundaries using (random-value 0.0 100.0) where 0 and 100 are percentages of the distance between boundaries. The generator parameter could use a different generator producing values in the same range, e.g.
(beta-value 0.0 100.0 .2 .2)
If MASK1 has been defined (example 5):
To determine the length of an object, GET-LENGTH can be used. If Stockpile STOCK1 has been defined, (get-length stock1) will return the number of elements it has. This number is also the maximum index value.
EXAMPLE 1: (for-example (read-from '(a b c) '(2 1 3 3 1 2 1 1 1 1)))
EXAMPLE 2: (for-example (read-from '(a b c d e f g)
(random-value 1 7)))
EXAMPLE 3: (for-example (read-from '(a b c d e f g) sine-shape 20))
EXAMPLE 4: (for-example
(read-from (from 40 80) mask1 100) :number 100)
EXAMPLE 5: (for-example
(read-from (from 40 80) mask1 100
(beta-value 0.0 100 .2 .2)) :number 100)
(read-permutation permutation &key random)
Returns a closure. When applied, one element from a permutation of a group of elements is returned. Each time the generator is applied, the next element from that permutation is returned. This continues until all elements of all permutations have been returned.
PERMUTATION is a list or stockpile made using the tool MAKE-PERMUTATION. See the help for that tool for more information (example 1).
Permutations all always made in a fixed order. A different order can be achieved by entering the elements in a different order (example 2).
Instead of returning each permutation of the elements in the PERMUTATION in their fixed order, a random order can be selected by binding the keyword RANDOM to t (example 3).
Note that MAKE-PERMUTATION works best with eight or less elements to permute.
EXAMPLE 1: (for-example (read-permutation
(make-permutation '(1 2 3)))
:number 18 :number-per-line 3)
EXAMPLE 2: (for-example (read-permutation
(make-permutation '(3 1 2)))
:number 18 :number-per-line 3)
EXAMPLE 3: (for-example (read-permutation
(make-permutation '(1 2 3)) :random t)
:number 18 :number-per-line 3)
read-sound-file
has been renamed LOAD-SOUND-FILE.
(read-spectrum-file &key type round base unique peaks)
This tool reads a file that can be used as a static spectrum for deriving pitch material, etc. The file should be either a tracks file (produced by SPEAR or the Csound utility Hetro) or a text with spectral data (produced by Audacity or Amadeus).
The default is to read a SPEAR file. SPEAR is an analysis/resynthesis program using tracks of partials. The data should be exported from SPEAR using the 'text - partials' format. Example 1 reads a SPEAR file, constructs a spectrum with one pitch per track, and stores the data in a stockpile. Select the sample file 'test spear bassoon.txt' in Support/FileExamples. Example 2 plots the spectrum expressed as amplitude over pitch.
A spectrum read with this tool can be used in the following AC Toolbox tools:
spectrum->pitch
spectrum->amp
spectrum->freq
spectrum->structure
spectrum->window
and with the generator: spectrum->chord
Example 3 prints data derived from the spectrum to a window. Peaks are sorted according to amplitude.
If ROUND is nil, the values for pitch are not rounded. If it is bound to 1, semitones are returned; 0.5 returns quarter-tones, etc. The default value is nil. Example 4 shows the spectrum rounded to quarter-tones.
BASE is by default bound to 440.0. It is the value for a4 and used in the conversion process from frequency to note numbers (example 5).
Spectral data may contain pitch duplications (e.g. as a result of a rounding operation). To eliminate these duplicates, bind UNIQUE to t. Select file 'test spear voice.txt' (examples 6-7). Note the difference between the number of tracks and the number of unique pitch values.
Hetro is a Csound utility that decomposes a soundfile into amplitude and frequency tracks. If Csound5 has been installed, Hetro can be called from within the AC Toolbox. In the Csound File Options dialog, press the button for Analysis Programs. Choose the pop-up menu for hetro.
To read Hetro files with READ-SPECTRUM-FILE, the analysis file must be made specifically for the platform being used (either Intel or PPC). Example 8 will read in a Hetro file. Select either 'test hetro (intel).het' or 'test hetro (ppc).het' depending on the platform being used.
Spectra can also be read from text files produced by Audacity or Amadeus. In general, spectral data read from SPEAR files will produce pitch data more similar to the analyzed file.
In Audacity a spectral text file can be created by exporting a spectral plot. To read an Audacity file, TYPE should be bound to audacity. 'test audacity bassoon.txt' is a sample Audacity file in the folder Support/File Examples. Select this file with example 9.
In Amadeus, the spectrum can be saved as a text file (not importable). To read an Amadeus spectrum file, TYPE should be bound to amadeus.
Spectrum files produced with Audacity or Amadeus have a large number of frequency-amplitude pairs. For an Audacity or Amadeus file, the default is to return the 10 peaks with the largest amplitude values. Another number of peaks can be specified with the keyword PEAKS (example 10). This number may be larger than 10. The default value for PEAKS is nil for SPEAR or Hetro files. This will return all peaks. For these files, a smaller number of peaks can be specified but not a larger one.
EXAMPLE 1: (fill-template construct-stockpile spectrum1
(read-spectrum-file))
EXAMPLE 2: (plot spectrum1)
EXAMPLE 3: (spectrum->window spectrum1)
EXAMPLE 4: (spectrum->window (read-spectrum-file :round 0.5))
EXAMPLE 5: (spectrum->window (read-spectrum-file :round 0.5 :base 415))
EXAMPLE 6: (read-spectrum-file :round 1)
EXAMPLE 7: (read-spectrum-file :round 1 :unique t)
EXAMPLE 8: (plot (read-spectrum-file :type 'hetro))
EXAMPLE 9: (spectrum->window (read-spectrum-file :type 'audacity))
EXAMPLE 10: (spectrum->window
(read-spectrum-file :type 'audacity :peaks 20))
(read-text-file)
Returns a list of values read in from a text file. The file is chosen with the customary dialog box (example 1).
EXAMPLE 1: (for-example (read-text-file))
(read-tracks-file &key type round filter base average)
Reads a sound analysis file containing tracks and converts the data to a format that can be used with the tool MAP-TRACKS to produce notes.
The sound analysis file can either be a partials text file exported from SPEAR or a hetrodyne filter analysis prepared by the Csound utility Hetro.
TYPE refers to the type of the analysis file. Allowed types are SPEAR and Hetro. The default for type is SPEAR.
READ-TRACKS-FILE is typically either used directly as an input for MAP-TRACKS or it is used to construct a stockpile so that the analysis data can be used several times without reloading the analysis file. Example file 'test spear voice.txt', available in Support/FileExamples, can be loaded to test this tool (examples 1-2).
The number of available tracks is printed in the Text Output window when the file is read.
The track data can be performed with MAP-TRACKS (example 3). See the help for that tool for more information on what can be done with it.
The pitch values from the track data can be rounded by binding the unit to keyword ROUND. 1 rounds to semitones, 0.5 to quarter-tones, nil does not round. nil is the default value (example 4).
FILTER will filter out pitch repetitions in a track. This happens after the values have been rounded. (example 5).
AVERAGE can be bound to a time unit in milliseconds. Pitch data in a track will be averaged across that time unit. The next averaged value is assigned the first start time within the unit (example 6). This reduces the amount of data produced. The data can be further reduced by filtering it in MAP-TRACKS (example 7). Filtering in MAP-TRACKS rather than in READ-TRACKS-FILE is advantageous when averaging because it will also filter duplicate pitches in chords.
BASE is used for converting frequency data to pitches (Midi note numbers). By default it is 440 for a4. To change this value, bind BASE to a different frequency (example 8).
SPEAR (Sinusoidal Partial Editing Analysis and Resynthesis) is a standalone application for analyzing a soundfile into individual sinusoidal tracks (partials). It offers various opportunities to edit this data. The data should be exported from SPEAR using the 'Text - Partials' format. The AC Toolbox can read this exported text file. The Toolbox does not read the standard sdif format used by SPEAR (example 9).
Track data can also be read from a Hetro analysis file. A different Hetro file is available in Support/FileExamples for each platform. It is called 'test hetro (ppc).het' or 'test hetro (intel).het' (examples 10-11).
Hetro decomposes a soundfile into several sinusoids and outputs a description of the sound in the form of a number of amplitude and frequency tracks. If a harmonic stored by Hetro has an amplitude of 0, it is ignored by READ-TRACKS-FILE. This means that there may be fewer tracks in the file than were specified in Hetro.
READ-TRACKS-FILE assumes that the Hetro analysis was made specifically for the platform (Intel or PPC) that the Toolbox is currently using. Analyzes made on a PPC machine or using Rosetta should not be used with the AC Toolbox on an Intel processor.
If Csound5 has been installed, Hetro can be called from within the Toolbox. In the Csound File Options dialog, press the button for Analysis Programs. In the resulting dialog, choose the pop-up menu item for hetro.
To retrieve the pitch data from one track, see tool PITCH-TRACK.
To treat the track data as a cumulative spectrum with one peak per track, see READ-SPECTRUM-FILE.
EXAMPLE 1: (fill-template construct-stockpile
voice1 (read-tracks-file))
EXAMPLE 2: (plot voice1)
EXAMPLE 3: (fill-template structured-section
section1 1 (map-tracks voice1 (from 1 30) 1))
EXAMPLE 4: (fill-template structured-section
section2 1 (map-tracks (read-tracks-file :round 1)
(from 1 30) 1))
EXAMPLE 5: (fill-template structured-section
section3 1 (map-tracks (read-tracks-file :round 1 :filter t)
(from 1 30) 1))
EXAMPLE 6: (fill-template structured-section
section4 1 (map-tracks (read-tracks-file :round 1 :average 1000)
(from 1 30) 1
:min-vel 30 :max-vel 60))
EXAMPLE 7: (fill-template structured-section
section5 1 (map-tracks (read-tracks-file :round 1 :average 1000)
(from 1 30) 1
:filter t
:min-vel 30 :max-vel 60))
EXAMPLE 8: (fill-template structured-section
section6 1 (map-tracks (read-tracks-file :base 415)
(from 1 30) 1))
EXAMPLE 9: (open-url "http://www.klingbeil.com/spear")
EXAMPLE 10: (fill-template structured-section
section7 1 (map-tracks (read-tracks-file :type 'hetro)
(from 1 10) 1))
EXAMPLE 11 (fill-template structured-section
section8 1 (map-tracks
(read-tracks-file :type 'hetro :round 1
:average 1000)
(from 1 10) 1
:filter t
:min-vel 60 :max-vel 80))
(rearrange stockpile index-rule)
Returns a closure. When applied, a value taken from the stockpile is returned. The order for choosing from the stockpile is determined by the INDEX-RULE. INDEX-RULE can be a list, generator, etc. It should provide an index for reading from the stockpile (the first value in the stockpile has the index 1).
After a number of values that is equal to the length of the stockpile have been returned, the stockpile is replaced with a new stockpile consisting of the previous series of values from the stockpile. The INDEX-RULE is then applied to this new stockpile.
In this way, values from the stockpile can be rotated or rearranged in various ways according to the INDEX-RULE (examples 1-2).
INDEX-RULE can vary over time (example 3).
EXAMPLE 1: (for-example
(rearrange '(a b c d e) '(2 3 4 5 1)))
EXAMPLE 2: (for-example
(rearrange '(a b c d e) '(3 1 4 5 2)))
EXAMPLE 3: (for-example
(rearrange '(a b c d e) (series-value 1 5)))
(rearrange-stockpile stockpile type &optional a b)
Returns a list made by rearranging STOCKPILE according to one of the available types. STOCKPILE should be a list or stockpile. TYPE should one of the following:
shuffle
swap
rotate-left
rotate-right
adjacent
order
A and B are optional parameters that may be needed for certain types of rearrangements.
SHUFFLE rearranges the stockpile in a random order (example 1).
SWAP exchanges values at two locations in a stockpile. Locations are numbered starting with 1. A and B receive the numbers of the locations to be swapped (examples 2-3).
ROTATE-LEFT moves each element in the stockpile one place to the left. The first element in the stockpile moves to the last position. A is the number of rotations (examples 4-5).
ROTATE-RIGHT moves each element in the stockpile one place to the right. The last element in the stockpile moves to the first position. A is the number of rotations (examples 6-7).
ADJACENT swaps the element at location A with the element one place to the right (one location higher) (examples 8-9).
ORDER rearranges the stockpile in the order specified by A. A may be a list, stockpile, generator, etc. with values for locations in the stockpile (examples 10-11).
A and B may be constant values, a generator, etc. If no value is specified for A, it will have the value 1. If no value is specified for B, it will have the value 2.
EXAMPLE 1: (print-result
(rearrange-stockpile '(a b c d e) 'shuffle))
EXAMPLE 2: (print-result
(rearrange-stockpile '(a b c d e) 'swap 1 3))
EXAMPLE 3: (print-result
(rearrange-stockpile '(a b c d e) 'swap 2 5))
EXAMPLE 4: (print-result
(rearrange-stockpile '(a b c d e) 'rotate-left))
EXAMPLE 5: (print-result
(rearrange-stockpile '(a b c d e) 'rotate-left 2))
EXAMPLE 6: (print-result
(rearrange-stockpile '(a b c d e) 'rotate-right))
EXAMPLE 7: (print-result
(rearrange-stockpile '(a b c d e) 'rotate-right 2))
EXAMPLE 8: (print-result
(rearrange-stockpile '(a b c d e) 'adjacent 2))
EXAMPLE 9: (print-result
(rearrange-stockpile '(a b c d e) 'adjacent
(random-value 1 4)))
EXAMPLE 10: (print-result
(rearrange-stockpile '(a b c d e)
'order '(4 2 3 5 1)))
EXAMPLE 11: (print-result
(rearrange-stockpile '(a b c d e)
'order (series-value 1 5)))
(reject-pitch-class-filter pitch-classes)
Will produce a filter that will reject a value if its pitch class is found in PITCH-CLASSES. PITCH-CLASSES should be a list or stockpile. It can be used with the FILTER method or with FILTER-STOCKPILE.
With the FILTER method, choose OTHER as the filter-type.
If SECTION1 exists, it can be filtered with example 1. In that example, only pitches not in the specified pitch classes (0 4 7) or c, e, g will be passed through.
Example 2 shows the use of this tool with FILTER-STOCKPILE.
EXAMPLE 1: (fill-template filter section1f section1
(other (reject-pitch-class-filter '(0 4 7)))
'pitch t)
EXAMPLE 2: (print-result
(stockpile->notename
(filter-stockpile '(c3 c#3 d3 c4 f4 c5)
(reject-pitch-class-filter '(0)))))
(reject-stockpile-filter stockpile)
Will produce a filter which rejects a value if it is found in the stockpile. This filter should be used with the FILTER method or with FILTER-STOCKPILE.
To use with the FILTER method: choose OTHER as the filter type.
STOCKPILE may be a list or a stockpile object.
If SECTION1 exists, it can be filtered with example 1. In that case, notes which have a pitch of 60 or 64 or 67 will be filtered out.
Example 2 uses this tool with FILTER-STOCKPILE.
EXAMPLE 1: (fill-template filter section1f section1
(other (reject-stockpile-filter '(60 64 67)))
'pitch t)
EXAMPLE 2: (print-result
(filter-stockpile '(1 2 3 4 5 6 7 8 9 10)
(reject-stockpile-filter '(2 4 6 8))))
(remake&vary &rest objects)
Returns a closure. When applied, it remakes all but the last object used as an argument in the order indicated. The last argument is varied (but not remade). This is useful if, for example, a stockpile is generated, that stockpile is used in a section, and the section is varied to produce a community.
Stated another way, all objects but the last object are destructively modified. The last object is varied without changing the original object.
For example, if stock1, stock2, and section1 existed:
(remake&vary stock1 stock2 section1)
would redefine stock1 and stock2 and would vary section1 without changing its previous value.
Examples 1-3 produces objects which are used for the community (example 4).
Note that something similar to REMAKE&VARY could also be achieved by using
the dialog GENERATE SEQUENTIAL SECTION.
EXAMPLE 1: (fill-template generate-stockpile pitch1 30
(random-value c2 c5))
EXAMPLE 2: (fill-template generate-stockpile rhythm1 10
(random-value 1.0 2))
EXAMPLE 3: (fill-template data-section s1 100 30 rhythm1 pitch1 mf 1 0)
EXAMPLE 4: (fill-template generate-community com1 4
(remake&vary pitch1 rhythm1 s1))
(remove-doubles)
Returns a closure which is intended to be used in transforming chords. If a pitch value is a list, a new list is returned which contains no double values (example 1).
If the pitch value is not a list, it is returned without change.
To combine remove-doubles with another transformer, use compose (example 2).
In the above example, the values are first transposed, then the double values are removed.
EXAMPLE 1: (show-transformation (remove-doubles)
'(60 (60 64 60 60)))
EXAMPLE 2: (show-transformation
(compose (remove-doubles) (transpose 12))
'(60 (60 64 60 60)))
(remove-repetitions generator-or-object &key stop)
Returns a closure. When applied, a new value is derived from GENERATOR-OR-OBJECT. If that value is a repetition of the previously produced value, it is discarded and GENERATOR-OR-OBJECT is asked for a new value. Otherwise the value is returned (examples 1-2).
If GENERATOR-OR-OBJECT keeps producing the same value for STOP number of times in a row, the process is cancelled and an error message appears. The default value for STOP is 100, i.e. the generator will try 100 times to produce a new value before giving up (examples 3-4).
GENERATOR-OR-OBJECT will typically be a generator, a list, or a stockpile.
To remove repetitions from an object which already exists, see REPETITION-FILTER. To remove repetitions in a chord, see REMOVE-DOUBLES.
EXAMPLE 1: (for-example (remove-repetitions '(1 2 3 1 1 1 2 1 1 2)))
EXAMPLE 2: (for-example (remove-repetitions (random-value 1 3)))
EXAMPLE 3: (for-example (remove-repetitions (always 25)))
EXAMPLE 4: (for-example (remove-repetitions (always 25) :stop 20))
(remove-successive)
Returns a closure which is intended to be used in transforming chords. If a pitch value is a list, a new list is returned without the pitches that were in the previous chord (example 1).
If the pitch value is not a list, it is returned without change.
This transformer only works with chords that were explicitedly entered as lists or were created with make-chord. For other sections, use the PITCH-REPETITION-FILTER with the FILTER method.
To remove doubling within a chord entered as a list or made with make-chord, use transformer REMOVE-DOUBLES.
Remove-successive may result in the removal of all pitches from an event. Although this has no effect on the functionality of the Toolbox, it results in the number of events being higher than the number played, plotted, printed, etc. To clean-up the empty events (the ones with no pitch) from a section, use tool clean-up-blanks. This change is destructive and irreversible.
EXAMPLE 1: (show-transformation (remove-successive)
'(60 (60 64 67) (60 64 67) (60 64 69)))
(render-csd &optional open filename)
This tool can be used to render an existing unified Csound file (with extension csd). The file will be rendered using the options specified in the file and not those of the Csound File Options dialog.
In particular, this means that the various directories, audio header, sample format, as well as the choice of rendering to file or in realtime will be those that were included in the file.
A csd file includes an orchestra definition and that definition is what is used to render the file (example 1).
If the csd file renders to an audio file, that audio file will be opened for performance in the default program for files of that type (aif or wav). If this behavior is not desired, bind open to nil. The file will then be rendered but not opened (example 2).
To render existing csd files using the current Csound File Options, use tool REPLACE-CSD-OPTIONS.
RENDER-CSD is not needed when Csound score objects are applied and rendered. Instead, it could be useful to render a file at a later time.
FILENAME can be bound to a path for a csd file. RENDER-CSD will otherwise ask for a file name.
Csound files generated by the AC Toolbox can, in any case, be rendered using this tool. The assumption is that all csd files will contain a setting for the SFDIR directory within the file as is the case with files produced by the AC Toolbox.
EXAMPLE 1: (render-csd)
EXAMPLE 2: (render-csd nil)
(render-osc)
Renders an existing OSC file to audio using the options for sample rate, etc. that are specified in the OSC File Options dialog.
If the OSC file uses an audio input file, that file should be chosen in the OSC File Options dialog.
This tool is not needed when OSC Scores are applied and rendered. It could be useful to render an OSC file without specifying an OSC Score object if the sound file is no longer available. Another use would be to test an OSC file with different audio input files (example 1).
This tool can be used in a Listener window, among other places.
EXAMPLE 1: (render-osc)
rendering csound
If Csound5 has been installed in /usr/local/bin, Csound csd files can be rendered to audio signals or files by the AC Toolbox.
Installation instructions are in the help item for Installing Csound.
The options controlling the way a csd file is rendered can be found in the Csound File Options dialog. A summary of these options can be seen by clicking on the ? button in that dialog.
If the csd file is rendered to an audio file and the option Open Audio File After Rendering has been checked, the file will open in the default program for that file type. A different program can be requested in the Finder: select an audio file with the desired extension, do Command-I (or click on the More Info button). In the resulting dialog, specify a program (such as QuickTime Player) to open all files of this type.
If no sound can be heard after rendering a Csound file, check the directory specifications in the Csound File Options. If sample or analysis files are needed, the correct directory for such a file must be chosen.
If the directories are correct but still no sound is heard, there may be a syntax error in the Csound specification. Check that all necessary P fields are receiving values. Make sure any function definitions have been made in the header. The text printed in the Text Output window may be useful in tracking errors.
If files are rendered in realtime, they can be stopped with the Menu item Others>Kill or cmd-K.
If a file with the same name as one which is open in another program such as QuickTime Player is to be made, the open file should be closed before rendering the new one.
(repetition-filter)
Produces a filter which will filter out successive repetitions of a value. This filter is intended for use with the FILTER method or with FILTER-STOCKPILE.
To use with the FILTER method: choose OTHER as the filter type then use (repetition-filter) to produce the filter.
If SECTION1 exists, example 1 will filter pitch repetitions.
Example 2 demonstrates use with FILTER-STOCKPILE.
EXAMPLE 1: (fill-template filter section1f section1
(other (repetition-filter))
'pitch t)
EXAMPLE 2: (for-example
(filter-stockpile '(1 2 2 2 3 3 4 5 5)
(repetition-filter)))
repetitions: prevent or remove
There are different ways of preventing the generation of repetitions or removing them once they have occurred. The choice depends on the context and the amount of information available when generating a parameter, transforming a parameter, or filtering an object.
The following is an attempt to clarify some of the possibilities to prevent or remove repetitions. More information can be found in the help for the various generators, tools, and transformers.
PREVENTING REPETITIONS
remove-repetitions
This is a generator. The input is another generator or an object from which values can be derived. If the generator produces a repetition (a value that is the same as the preceding one), the value is discarded and the generator is asked for a new value. It is up to the user to make sure that the generator can actually produce non-repeating values (examples 1-2).
duplicates
This is a tool that is used together with the generator WITHOUT. Without produces values that are not excluded by a condition. DUPLICATES is such a condition. It disallows any value which has already occurred. It is not limited to the preceding value but any value in the current series (examples 3-4).
make-chord
This generator is to produce chords (pitches) which are represented as a list. Repetitions can be blocked in two different ways.
Within a chord, the interval 0 (unison) can be blocked. This means that the same pitch will not occur in a chord (example 5).
Repetition of pitches in successive chords (i.e. that a pitch in one chord occurred in the previous one) can be blocked by binding the key word allow-repeats to nil (examples 6-7).
block-interval
This generator is wrapped around another generator which produces values. One or more intervals can be blocked. If the interval 0 is blocked, the next value cannot be the same as the current one (example 8).
convert
When converting a mask to a list of numbers chosen within that mask, it is possible to block one or more intervals using the parameter INTERVAL-OR-LIST. The interval refers to successive values (examples 9-11).
REMOVING EXISTING REPETITIONS
remove-doubles
This is a transformer for use with the pitch parameter. If