Synth

Synth#

A Synth is a wrapper for a unique event scheduled via a Session.

Note

A user does not normally create a Synth: a Synth is created when an Instr is scheduled in a Session via sched()

The lifetime of the underlying csound event is not bound to the Synth object. In order to stop a synth its stop() method must be called explicitely

Examples#

Automate a synth#

from csoundengine import *
from pitchtools import ntom
session = Engine().session()
session.defInstr('vco', r'''
    |kamp=0.1, kmidi=60, ktransp=0|
    asig vco2 kamp, mtof:k(kmidi+ktransp)
    asig *= linsegr:a(0, 0.1, 1, 0.1, 0)
    outch 1, asig
''')
notes = ['4C', '4D', '4E']
synths = [session.sched('vco', kamp=0.2, kmidi=ntom(n)) for n in notes]
# synths is a list of Synth
# automate ktransp in synth 1 to produce 10 second gliss of 1 semitone downwards
synths[1].automate('ktransp', [0, 0, 10, -1])

Autogenerate a ui to explore a synth#

# Inside jupyter
from csoundengine import *
s = Engine().session()
s.defInstr('vco', r'''
  |kmidinote, kampdb=-12, kcutoff=3000, kres=0.9|
  kfreq = mtof:k(kmidinote)
  asig = vco2:a(ampdb(kampdb), kfreq)
  asig = moogladder2(asig, kcutoff, kres)
  asig *= linsegr:a(0, 0.1, 1, 0.1, 0)
  outs asig, asig
''')
synth = s.sched('vco', kmidinote=67)
# Specify the ranges for some sliders. All named parameters
# are assigned a widget
synth.ui(kampdb=(-48, 0), kres=(0, 1))

Generated ui when working in the terminal:

Generated ui inside jupyter:

SynthGroup#

A SynthGroup is used to control multiple synths. Such multiple synths can be groups of similar synths (as in additive synthesis), or processing chains which work as an unity

A SynthGroup behaves very similar to a synth but its effects encompass all the synths within it. For example, calling its stop() method will stop all the synths in the group. Calling set() will modify dynamic parameters for all the synths in the group which declare such a parameter

Classes:

`Synth`(session, p1, instr, start[, dur, ...])	A Synth represents a live csound event
`SynthGroup`(synths[, autostop])	A SynthGroup is used to control multiple synths

class csoundengine.synth.Synth(session, p1, instr, start, dur=-1, args=None, autostop=False, priority=1, controls=None, controlsSlot=-1, uniqueId=0)[source]#

A Synth represents a live csound event

A user never creates a Synth directly, it is created by a Session when Session.sched is called

Parameters:

session (Session) – the Session this synth belongs to
p1 (float) – the p1 assigned
instr (Instr) – the Instr of this synth
start (float) – start time (absolute)
dur (float) – duration of the synth (-1 if no end)
args (list[float | str] | None) – the pfields used to create the actual event, starting with p5 (p4 is reserved for the controlsSlot
autostop – if True, the underlying csound event is stopped when this object is deallocated
priority (int) – the priority at which this event was scheduled
controls (dict[str, float] | None) – the dynamic controls used to schedule this synth
controlsSlot (int) – the control slot assigned to this synth, if the instrument defines named controls
uniqueId – an integer identifying this synth, if applicable

Example

from csoundengine import *
from pitchtools import n2m
session = Engine().session()
session.defInstr('vco', r'''
    |kamp=0.1, kmidi=60, ktransp=0|
    asig vco2 kamp, mtof:k(kmidi+ktransp)
    asig *= linsegr:a(0, 0.1, 1, 0.1, 0)
    outch 1, asig
''')
notes = ['4C', '4E', '4G']
synths = [session.sched('vco', kamp=0.2, kmidi=n2m(n)) for n in notes]
# synths is a list of Synth
# automate ktransp in synth 1 to produce 10 second gliss of 1 semitone downwards
synths[1].automate('ktransp', [0, 0, 10, -1])

Attributes:

`p1`	Event id for this synth
`args`	Args used for this event (p4, p5, ...)
`controls`	The dynamic controls used to schedule this event
`controlsSlot`	The slot/token assigned for dynamic controls
`dur`	Duration of the event (p3).
`end`	End of this event (can be inf if the duration is given as negative)
`instr`	The Instr corresponding to this Event, if applicable
`instrname`	The instrument template this event was created from, if applicable
`parent`	The Renderer to which this event belongs (can be None)
`priority`	The priority of this event, if applicable
`start`	Start time of the event (p2)
`uniqueId`	A unique id of this event, as integer

Methods:

`wait`([pollinterval, sleepfunc])	Wait until this synth has stopped
`aliases`()	The parameter aliases of this synth, or an empty dict if no aliases defined
`controlNames`([aliases, aliased])	The names of all controls
`ui`(**specs)	Modify dynamic (named) arguments through an interactive user-interface
`playStatus`()	Returns the playing status of this synth (playing, stopped or future)
`playing`()	Is this Synth playing
`finished`()	Has this synth ceased to play?
`dynamicParamNames`([aliases, aliased])	The set of all dynamic parameters accepted by this Synth
`pfieldNames`([aliases, aliased])	Returns a set of all named pfields
`paramValue`(param)	Get the value of a parameter
`automate`(param, pairs[, mode, delay, overtake])	Automate any named parameter of this Synth
`stop`([delay])	Stop this event
`paramNames`([aliases, aliased])	Set of all named parameters :rtype: `frozenset`[`str`]
`set`([param, value, delay])	Set a value of a named parameter
`show`()	If inside jupyter, display the html representation of self
`unaliasParam`(param[, default])	Returns the alias of param or default if no alias was found

p1: float#: Event id for this synth

wait(pollinterval=0.02, sleepfunc=<built-in function sleep>)[source]#

Wait until this synth has stopped

Parameters:

pollinterval (float) – polling interval in seconds
sleepfunc – the function to call when sleeping, defaults to time.sleep

Return type:

None

aliases()[source]#

The parameter aliases of this synth, or an empty dict if no aliases defined

Return type:: dict[str, str]

controlNames(aliases=True, aliased=False)[source]#

The names of all controls

Parameters:

aliases – if True, included control names aliases (if applicable)
aliased – if True, include the aliased names

Return type:

frozenset[str]

Returns:

the names of all controls. Returns an empty set if this event does not have any controls

ui(**specs)[source]#

Modify dynamic (named) arguments through an interactive user-interface

If run inside a jupyter notebook, this method will create embedded widgets to control the values of the dynamic pfields of an event. Dynamic pfields are those assigned to a k-variable or declared as |karg| (see below)

Parameters:: specs (tuple[float, float]) – map named arg to a tuple (minvalue, maxvalue), the keyword is the name of the parameter, the value is a tuple with the range
Return type:: None

Example

# Inside jupyter
from csoundengine import *
s = Engine().session()
s.defInstr('vco', r'''
  |kmidinote, kampdb=-12, kcutoff=3000, kres=0.9|
  kfreq = mtof:k(kmidinote)
  asig = vco2:a(ampdb(kampdb), kfreq)
  asig = moogladder2(asig, kcutoff, kres)
  asig *= linsegr:a(0, 0.1, 1, 0.1, 0)
  outs asig, asig
''')
synth = s.sched('vco', kmidinote=67)
# Specify the ranges for some sliders. All named parameters
# are assigned a widget
synth.ui(kampdb=(-48, 0), kres=(0, 1))

See also

Engine.eventui()

playStatus()[source]#

Returns the playing status of this synth (playing, stopped or future)

Return type:: str
Returns:: ‘playing’ if currently playing, ‘stopped’ if this synth has already stopped or ‘future’ if it has not started

playing()[source]#

Is this Synth playing

Return type:: bool

finished()[source]#

Has this synth ceased to play?

Return type:: bool

dynamicParamNames(aliases=True, aliased=False)[source]#

The set of all dynamic parameters accepted by this Synth

If the instrument used in this synth uses aliases, these are also included

Parameters:

aliases – if True, include aliases
aliased – include the original names of parameters which have an alias

Return type:

frozenset[str]

Returns:

a set of the dynamic (modifiable) parameters accepted by this synth

pfieldNames(aliases=True, aliased=False)[source]#

Returns a set of all named pfields

Parameters:

aliases – if True, included aliases for pfields (if applicable)
aliased – if True, include the aliased names. Otherwise if aliases are defined and included (aliases=True), the original names will be excluded

Return type:

frozenset[str]

Returns:

a set with the all pfield names.

paramValue(param)[source]#

Get the value of a parameter

Parameters:: param (str | int) – the parameter name or a pfield index
Return type:: float | str | None
Returns:: the value, or None if the parameter has no value

automate(param, pairs, mode='linear', delay=0.0, overtake=False)[source]#

Automate any named parameter of this Synth

Raises KeyError if the parameter is unknown

Parameters:

param (str) – the name of the parameter to automate
pairs (Union[Sequence[float], ndarray, tuple[ndarray, ndarray]]) – automation data as a flat array with the form [time0, value0, time1, value1, …] or a tuple of the form (times, values)
mode – one of ‘linear’, ‘cos’. Determines the curve between values
delay – when to start the automation
overtake – if True, do not use the first value in pairs but overtake the current value

Return type:

float

Returns:

the eventid of the automation event.

stop(delay=0.0)[source]#

Stop this event

When using this in offline mode, delay is an absolute time

Parameters:: delay – when to stop
Return type:: None

args#: Args used for this event (p4, p5, …)

controls: dict[str, float] | None#: The dynamic controls used to schedule this event

controlsSlot: int#: The slot/token assigned for dynamic controls

dur#: Duration of the event (p3). Can be negative to indicate an endless/tied event

property end: float#: End of this event (can be inf if the duration is given as negative)

property instr: Instr#

The Instr corresponding to this Event, if applicable

Raises ValueError if this event cannot access to the Instr instance (if it has no parent or its instrument name is invalid)

instrname: str#: The instrument template this event was created from, if applicable

paramNames(aliases=True, aliased=False)#: Set of all named parameters :rtype: frozenset[str]

See also

dynamicParams(), set(), automate()

parent: AbstractRenderer | None#: The Renderer to which this event belongs (can be None)

priority: int#: The priority of this event, if applicable

set(param='', value=0.0, delay=0.0, **kws)#

Set a value of a named parameter

Parameters:

param – the parameter name. Can also be an unnamed param, like ‘p5’
value (float) – the value to set
delay – when to set this parameter
kws – the key should be a named parameter, or p5, p6, etc., if setting a parameter by index. Bear in mind that only parameters assigned to a control variable will see any modification

Return type:

None

Example

>>> from csoundengine import *
>>> s = Engine().session()
>>> s.defInstr('osc', r'''
... |kfreq, kamp|
... outch 1, oscili:a(kamp, kfreq)
... ''')
>>> synth = s.sched('osc', kfreq=1000, kamp=0.5)
>>> synth.set(kfreq=440)
>>> # Parameters can be given as index also:
>>> synth.set(p5=440, delay=2.5)
>>> # Multiple parameters can be set at a time
>>> synth.set(kfreq=442, kamp=0.1)

show()#

If inside jupyter, display the html representation of self

Return type:: None

start#: Start time of the event (p2)

unaliasParam(param, default='')#

Returns the alias of param or default if no alias was found

Parameters:

param (str) – the parameter to unalias
default – the value to return if param has no alias

Return type:

str

Returns:

the original name or default if no alias was found

uniqueId: int#: A unique id of this event, as integer

class csoundengine.synth.SynthGroup(synths, autostop=False)[source]#

A SynthGroup is used to control multiple synths

Such multiple synths can be groups of similar synths, as in additive synthesis, or processing chains which work as an unity.

synths#

the list of synths in this group

Type:: list[AbstrSynth]

Example

>>> import csoundengine as ce
>>> session = ce.Engine().session()
>>> session.defInstr('oscil', r'''
... |kfreq, kamp=0.1, kcutoffratio=5, kresonance=0.9|
... a0 = vco2(kamp, kfreq)
... a0 = moogladder2(a0, kfreq * kcutoffratio, kresonance)
... outch 1, a0
... ''')
>>> synths = [session.sched('oscil', kfreq=freq)
...           for freq in range(200, 1000, 75)]
>>> group = ce.synth.SynthGroup(synths)
>>> group.set(kcutoffratio=3, delay=3)
>>> group.automate('kresonance', (1, 0.3, 10, 0.99))
>>> group.stop(delay=11)

Methods:

`extend`(synths)	Add the given synths to the synths in this group
`stop`([delay])	Stop this event
`dynamicParamNames`([aliases, aliased])	The set of all dynamic parameters accepted by this event
`pfieldNames`([aliases, aliased])	Returns a set of all named pfields
`automate`(param, pairs[, mode, delay, overtake])	Automate the given parameter for all the synths in this group
`ui`(**specs)	Modify dynamic (named) arguments through an interactive user-interface
`paramValue`(param)	Returns the parameter value for the given parameter
`controlNames`([aliases, aliased])	Returns a set of available table named parameters for this group
`paramNames`()	Set of all named parameters :rtype: `frozenset`[`str`]
`set`([param, value, delay])	Set a value of a named parameter
`show`()	If inside jupyter, display the html representation of self
`unaliasParam`(param[, default])	Returns the alias of param or default if no alias was found
`wait`([pollinterval, sleepfunc])	Wait until this synth has stopped

Attributes:

`dur`	Duration of the event (p3).
`end`	End of this event (can be inf if the duration is given as negative)
`start`	Start time of the event (p2)

extend(synths)[source]#

Add the given synths to the synths in this group

Return type:: None

stop(delay=0.0)[source]#

Stop this event

Return type:: None

dynamicParamNames(aliases=True, aliased=False)[source]#

The set of all dynamic parameters accepted by this event

Return type:: set[str]
Returns:: a set of the dynamic (modifiable) parameters accepted by this event

pfieldNames(aliases=True, aliased=False)[source]#

Returns a set of all named pfields

Parameters:

aliases – if True, included aliases for pfields (if applicable)
aliased – if True, include the aliased names. Otherwise if aliases are defined and included (aliases=True), the original names will be excluded

Return type:

frozenset[str]

Returns:

a set with the all pfield names.

automate(param, pairs, mode='linear', delay=0.0, overtake=False)[source]#

Automate the given parameter for all the synths in this group

If the parameter is not found in a given synth, the automation is skipped for the given synth. This is useful when a group includes synths using different instruments so an automation would only adress those synths which support a given parameter. Synths which have no time overlap with the automation are also skipped.

Raises KeyError if the param used is not supported by any synth in this group Supported parameters can be checked via SynthGroup.dynamicParams()

Parameters:

param (int | str) – the parameter to automate
pairs (Union[Sequence[float], ndarray, tuple[ndarray, ndarray]]) – a flat list of pairs (time0, value0, time1, value1, …)
mode – the iterpolation mode
delay – the delay to start the automation
overtake – if True, the first value is dropped and instead the current value of the given parameter is used. The same effect is achieved if the first value is given as ‘nan’, in this case also the current value of the synth is overtaken.

Return type:

list[float]

Returns:

a list of synthids. There will be one synthid per synth in this group. A synthid of 0 indicates that for that given synth no automation was scheduled, either because that synth does not support the given param or because the automation times have no intersection with the synth

ui(**specs)[source]#

Modify dynamic (named) arguments through an interactive user-interface

Parameters:: specs (tuple[float, float]) – map named arg to a tuple (minvalue, maxvalue), the keyword is the name of the parameter, the value is a tuple with the range
Return type:: None

Example

# Inside jupyter
from csoundengine import *
s = Engine().session()
s.defInstr('vco', r'''
  |kmidinote, kampdb=-12, kcutoff=3000, kres=0.9|
  kfreq = mtof:k(kmidinote)
  asig = vco2:a(ampdb(kampdb), kfreq)
  asig = moogladder2(asig, kcutoff, kres)
  asig *= linsegr:a(0, 0.1, 1, 0.1, 0)
  outs asig, asig
''')
synths = [
    s.sched('vco', kmidinote=67)
    s.sched('vco', kmidinote=69)
]
group = SynthGroup(synths)

# Specify the ranges for some sliders. All named parameters
# are assigned a widget
group.ui(kampdb=(-48, 0), kres=(0, 1))

Synth

Contents

Synth#

Examples#

Automate a synth#

Autogenerate a ui to explore a synth#

SynthGroup#