SynthEvent¶

class maelzel.core.synthevent.SynthEvent(bps, instr, delay=0.0, chan=1, fade=0, gain=1.0, pitchinterpol='linear', fadeshape='cos', args=None, priority=1, position=-1, numchans=2, linkednext=False, whenfinished=None, properties=None, sustain=0.0, initfunc=None)[source]¶

Bases: object

Represents a standard event (a line of variable breakpoints)

A User never creates a SynthEvent: a SynthEvent is created by a Note or a Voice. They are used internally to generate a set of events to be played/recorded by the playback engine.

Attributes Summary

`args`	Any parameters passed to the instrument.
`automationSegments`	List of automation points
`automations`	A list of SynthAutomation.
`bps`	breakpoints, where each breakpoint is a list of [timeoffset, midi, amp, [...]]
`chan`	output channel
`delay`	time delay - The effective time of bp[n] will be delay + bp[n][0]
`dur`	Duration of this event, in seconds
`dynamicAttributes`	Attributes which can change within merged events
`end`	Absolute end time of this event, in seconds
`fade`	A tuple (fadein, fadeout)
`fadein`	fade in time
`fadeout`	fade out time
`fadeshape`	Shape of the fades
`fadeshapeToInt`	Map a fadeshape to an identifier used inside csound
`gain`	a gain to be applied to this event
`initfunc`	A function called when the event is being scheduled.
`instr`	Instrument preset used
`kws`
`linkednext`	Is this event linked to the next? A linked synthevent is a tied note or a note with a glissando followed by some continuation.
`numchans`	The number of signals produced by the event
`pitchinterpol`	Pitch interpolation
`pitchinterpolToInt`	Map an interpolation shape to an identifier used inside csound
`position`	Panning position (between 0-1)
`priority`	Schedule priority (priorities start with 1)
`properties`	User defined properties for an event
`start`
`staticAttributes`
`sustain`	Sustain time after the actual duration
`whenfinished`	A function to call when this event has finished

Methods Summary

`addAutomation`(automation)
`addAutomationsFromPlayArgs`(playargs, scorestruct)	rtype: `None`
`breakpointSize`()	Returns the number of breakpoints in this SynthEvent
`clone`(**kws)	rtype: `SynthEvent`
`copy`()	rtype: `SynthEvent`
`crop`(dur)	rtype: `None`
`cropEvents`(events[, skip, end])	Crop the events at the given time slice (staticmethod)
`cropped`(start, end)	Return a cropped version of this SynthEvent
`fromPlayArgs`(bps, playargs[, properties])	Construct a SynthEvent from breakpoints and playargs
`getInstr`()	rtype: `Instr`
`getPreset`()	rtype: `PresetDef`
`initialize`(renderer)	rtype: `None`
`mergeEvents`(events)	Static method to merge events which are linked (tied, gliss)
`paramValue`(param)
`plot`([axes, notenames])	Plot the trajectory of this synthevent
`plotEvents`(events[, axes, notenames])	Plot all given events within the same axes (static method)
`resolvedPosition`()	rtype: `float`
`set`(param, value[, delay])	rtype: `None`
`timeShifted`(offset)	A clone of this event, shifted in time by the given offset

Attributes Documentation

args: dict[str, float | str] | None¶: Any parameters passed to the instrument. Can be None

automationSegments: list[_AutomationSegment] | None¶

List of automation points

These are created when multiple events are merged into one. The dynamic parameters of the subsequent events are gathered as automation points.

automations: list[SynthAutomation] | None¶

A list of SynthAutomation.

This keeps track of any automation for this event, both automation lines and single set events. Add automation via .addAutomation

bps: list[list[float]]¶: breakpoints, where each breakpoint is a list of [timeoffset, midi, amp, […]]

chan: int¶: output channel

delay: float¶: time delay - The effective time of bp[n] will be delay + bp[n][0]

dur¶: Duration of this event, in seconds

dynamicAttributes = ('position', 'gain')¶: Attributes which can change within merged events

end¶: Absolute end time of this event, in seconds

fade¶: A tuple (fadein, fadeout)

fadein: float¶: fade in time

fadeout: float¶: fade out time

fadeshape: str¶: Shape of the fades

fadeshapeToInt = {'cos': 1, 'linear': 0, 'scurve': 2}¶: Map a fadeshape to an identifier used inside csound

gain: float¶: a gain to be applied to this event

initfunc¶: A function called when the event is being scheduled. It has the form (synthevent, renderer) -> None, where synthevent is the event being rendered and renderer is the renderer performing the render (either a maelzel.core.playback.RealtimeRenderer or a maelzel.core.playback.OfflineRenderer). It can be used to initialize any resources needed by the event (load/make tables, add includes, global code, etc)

instr: str¶: Instrument preset used

kws¶

linkednext: bool¶: Is this event linked to the next? A linked synthevent is a tied note or a note with a glissando followed by some continuation. In any case, the last breakpoint of this synthevent and the first breakpoint of the following event should be equal for a two events to be linked. NB: since we are dealing with floats, code should always check that the numbers are near instead of using ==

numchans: int¶: The number of signals produced by the event

pitchinterpol: str¶: Pitch interpolation

pitchinterpolToInt = {'cos': 1, 'freqcos': 3, 'freqlinear': 2, 'linear': 0}¶: Map an interpolation shape to an identifier used inside csound

position: float¶: Panning position (between 0-1)

priority: int¶: Schedule priority (priorities start with 1)

properties: dict[str, Any] | None¶: User defined properties for an event

start¶

staticAttributes = ('chan', 'priority', 'numchans')¶

sustain: float¶: Sustain time after the actual duration

whenfinished: Optional[Callable]¶: A function to call when this event has finished

Methods Documentation

addAutomation(automation)[source]¶

addAutomationsFromPlayArgs(playargs, scorestruct)[source]¶

Return type:: None

breakpointSize()[source]¶

Returns the number of breakpoints in this SynthEvent

Return type:: int

clone(**kws)[source]¶

Return type:: SynthEvent

copy()[source]¶

Return type:: SynthEvent

crop(dur)[source]¶

Return type:: None

static cropEvents(events, skip=0.0, end=inf)[source]¶

Crop the events at the given time slice (staticmethod)

Removes any event / part of an event outside the time slice start:end

Parameters:

events (list[SynthEvent]) – the events to crop
skip – start of the time slice (None will only crop at the end)
end – end of the time slice (None will only crop at the beginning)

Return type:

list[SynthEvent]

Returns:

the cropped events

cropped(start, end)[source]¶

Return a cropped version of this SynthEvent

Return type:: SynthEvent

classmethod fromPlayArgs(bps, playargs, properties=None, **kws)[source]¶

Construct a SynthEvent from breakpoints and playargs

Note

This method does not transfer any automations from the playargs to the created SynthEvent. Automations can be transferred via SynthEvent.addAutomationsFromPlayArgs()

Parameters:

bps (list[list[float]]) – the breakpoints
playargs (PlayArgs) – playargs
properties (Optional[dict[str, Any]]) – any properties passed to the constructor
kws – any keyword accepted by SynthEvent

Return type:

SynthEvent

Returns:

a new SynthEvent

getInstr()[source]¶

Return type:: Instr

getPreset()[source]¶

Return type:: PresetDef

initialize(renderer)[source]¶

Return type:: None

static mergeEvents(events)[source]¶

Static method to merge events which are linked (tied, gliss)

Parameters:: events (Sequence[SynthEvent]) – the events to merge
Return type:: SynthEvent
Returns:: the merged event

paramValue(param)[source]¶

plot(axes=None, notenames=False)[source]¶

Plot the trajectory of this synthevent

Parameters:

axes (Optional[Axes]) – a matplotlib.pyplot.Axes, will be used if given
notenames – if True, use notenames for the y axes

Return type:

Axes

Returns:

the axes used

static plotEvents(events, axes=None, notenames=False)[source]¶

Plot all given events within the same axes (static method)

Parameters:

events (list[SynthEvent]) – the events to plot
axes (Optional[Axes]) – the matplotlib Axes to use, if given
notenames – if True, use notenames for the y axes

Return type:

Axes

Returns:

the axes used

Example

>>> from maelzel.core import *
>>> from maelzel.core import synthevent
>>> chord = Chord("4E 4G# 4B", 2, gliss="4Eb 4F 4G")
>>> synthevent.plotEvents(chord.events(), notenames=True)

resolvedPosition()[source]¶

Return type:: float

set(param, value, delay=0.0)[source]¶

Return type:: None

timeShifted(offset)[source]¶

A clone of this event, shifted in time by the given offset

Return type:: SynthEvent