defPreset

maelzel.core.presetmanager.defPreset(name, code, init='', post='', includes=None, args=None, description='', envelope=True, output=True, aliases=None)

Define a new instrument preset.

The defined preset can be used as note.play(instr=’name’), where name is the name of the preset. A preset is created by defining the audio generating part as csound code. Each preset has access to the following variables:

  • kpitch: pitch of the event, as fractional midi

  • kamp: linear amplitude (0-1)

  • kfreq: frequency corresponding to kpitch

code should generate an audio output signal named aout1 for channel 1, aout2 for channel 2, etc.:

code = 'aout1 oscili a(kamp), kfreq'
Parameters:

  • name (str) – the name of the preset

  • code (str) – audio generating csound code

  • post – code to include after any other code. Needed when using turnoff, since calling turnoff in the middle of an instrument can cause undefined behaviour.

  • init – global code needed for all instances of this preset (usually a table definition, loading samples, etc). It will be run only once before any event with this preset is scheduled. Do not confuse this with the init phase of an instrument, which runs for every event.

  • includes (Optional[list[str]]) – files to include

  • args (Optional[dict[str, float]]) – a dict {parametername: value} passed to the instrument. Parameters can also be defined inline using the |iarg=<default>, karg=<default>| notation

  • description – an optional description of the preset. The description can include documentation for the parameters (see Example)

  • envelope – If True, apply an envelope as determined by the fadein/fadeout play arguments. If False, the user is responsible for applying any fadein/fadeout (csound variables: ifadein, ifadeout

  • output – if True, generate output routing (panning and output) for this preset. Otherwise, the user is responsible for applying panning (kpos) and routing the generated audio to any output channels (ichan), buses, etc.

  • aliases (Optional[dict[str, str]]) – if given, a dict mapping alias to real parameter name. This allow to use any name for a parameter, instead of a csound variable

Return type:

PresetDef

Returns:

a PresetDef

Example

Create a preset with dynamic parameters

>>> from maelzel.core import *
>>> presetManager.defPreset('mypreset', r'''
...     aout1 vco2 kamp, kfreq, 10
...     aout1 moogladder aout1, lag:k(kcutoff, 0.1), iq''',
...     args={'kcutoff': 4000, 'iq': 1},
...     description=r'''
...         A filtered saw-tooth
...         Args:
...             kcutoff: the cutoff frequency of the filter
...             iq: the filter resonance
...     ''')

Or simply:

>>> defPreset('mypreset', r'''
... |kcutoff=4000, kq=1|
... ; A filtered saw-tooth
... ; Args:
... ;   kcutoff: cutoff freq. of the filter
... ;   kq: filter resonance
... aout1 vco2 kamp, kfreq, 10
... aout1 moogladder aout1, lag:k(kcutoff, 0.1), kq
... ''', aliases={'cutoff': 'kcutoff')

Then, to use the Preset:

>>> synth = Note("4C", dur=60).play(instr='mypreset', args={'kcutoff': 1000})

The maelzel.core.mobj.MObj.play() method returns a SynthGroup, even if in this case a Note generates only one synth (for example a Chord generates one synth per note)

NB: Parameters can be modified while the synth is running :

>>> synth.set(kcutoff=2000)

See also