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)

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)
automate(param, pairs[, interpolation, ...])
breakpointSize()	Returns the number of breakpoints in this SynthEvent
clone(**kws)
copy()
crop(start, end)	Crop this event in place
cropEvents(events[, start, end])	Crop the events at the given time slice (staticmethod)
cropped(start, end)	Return a cropped version of this SynthEvent
dumpEvents(events)
fromPlayArgs(bps, playargs[, properties])	Construct a SynthEvent from breakpoints and playargs
getInstr()
getPreset()
initialize(renderer)
mergeEvents(events)	Static method to merge events which are linked (tied, gliss)
paramValue(param)
plot([axes, notenames, linewidth])	Plot the trajectory of this synthevent
plotEvents(events[, axes, notenames, linewidth])	Plot all given events within the same axes (static method)
resolvedPosition()
set(param, value[, delay])
shiftInPlace(offset[, crop])	Shift the times of this event, in place
shifted(offset[, crop])	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[tuple[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)

addAutomationsFromPlayArgs(playargs, scorestruct)

Return type:

None

automate(param, pairs, interpolation='linear', delay=0.0, overtake=False)

Return type:

None

breakpointSize()

Returns the number of breakpoints in this SynthEvent

Return type:

int

clone(**kws)

Return type:

SynthEvent

copy()

Return type:

SynthEvent

crop(start, end)

Crop this event in place

Parameters:

• start (float) – start time, in seconds

• end (float) – end time, in seconds

Return type:

None

static cropEvents(events, start=0.0, end=inf)

Crop the events at the given time slice (staticmethod)

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

Parameters:

• events (list[SynthEvent]) – the events to crop

• start – 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)

Return a cropped version of this SynthEvent

Return type:

SynthEvent

static dumpEvents(events)

classmethod fromPlayArgs(bps, playargs, properties=None, **kws)

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[tuple[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()

Return type:

Instr

getPreset()

Return type:

PresetDef

initialize(renderer)

Return type:

None

static mergeEvents(events)

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)

plot(axes=None, notenames=False, linewidth=1.0)

Plot the trajectory of this synthevent

Parameters:

• axes (Axes | None) – a matplotlib.pyplot.Axes, will be used if given

• notenames – if True, use notenames for the y axes

• linewidth – linewidth used for plotting

Return type:

Axes

Returns:

the axes used

static plotEvents(events, axes=None, notenames=False, linewidth=1.0)

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

Parameters:

• events (list[SynthEvent]) – the events to plot

• axes (Axes | None) – the matplotlib Axes to use, if given

• notenames – if True, use notenames for the y axes

• linewidth – width to use between breakpoints

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.synthEvents(), notenames=True)

resolvedPosition()

Return type:

float

set(param, value, delay=0.0)

Return type:

None

shiftInPlace(offset, crop=True)

Shift the times of this event, in place

Parameters:

• offset (float) – the offset to add

• crop – allow cropping if the given offset results in negative delay

Return type:

None

shifted(offset, crop=True)

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

Parameters:

• offset (float) – the offset to add

• crop – allow cropping if the given offset results in negative delay

Return type:

SynthEvent

Returns:

the resulting event