defPreset

maelzel.core.presetmanager.defPreset(name, code, init='', post='', includes=(), 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 (Sequence[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 (the csound variables ifadein and ifadeout will be set to the given fade times). No envelope code is generated if no output variables are defined (aout1, aout2, …)

  • 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. No output code is generated if the user does not define any output variables (aout1, aout2, …)

  • aliases (Optional[dict[str, str]]) – if given, a dict mapping alias to real parameter name. This mechanism allows 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)

To output sound to anything different than the hardware output use output=False and implement the output directly within the instr body

>>> defPreset('mysynth', r'''
... asig vco2 kamp, kfreq, 10
... asigL, asigR pan2 asig, kpos
... chnmix asigL, "left"
... chnmix asigR, "right"
... ''')
>>> session = getSession()
>>> session.defInstr('reverb', r'''
...     |kwet=0.8|
...     aleft = chnget:a("left")
...     aright = chnget:a("right")
...     awetL, awetR reverbsc aleft, aright, 0.85, 12000, sr, 0.5, 1
...     outch 1, awetL * kwet + aleft * (1 - kwet), 2, awetR * kwet + aright * (1 - kwet)
...     chnclear "left", "right"
... ''')
>>> reverb = session.sched('reverb', priority=2)
>>> synth = Note("4C", dur=1).play(instr='mysynth')

See also