PlayArgs

class maelzel.core.synthevent.PlayArgs(db=None, automations=None)

Bases: object

Playback customizations for an event or a set of events

Each MObj has a playargs attribute, which is an instance of PlayArgs and allows each object to set playback attributes like the instrument used, fade, pan position, etc. Each attribute set is added to the PlayArgs.args dict.

PlayArgs cascade similarly to css. If a note sets a specific attribute, like ‘instr’ (the instrument used), then this value is used since it is the most specific. If the note leaves that unset but the note is contained within a Chain and this Chain sets the ‘instr’ key within its own playargs, then this value is used. If that chain is contained within a Score and the score itself has the ‘instr’ key set, then that value is used, etc. Fallback defaults are often defined in the configuration

Keys

• delay: when to schedule this synth. This time is added to the absolute offset of an object

• chan: the channel to output to. If the synth is multichannel this is the first of many

  adjacent channels (TODO: implement channel mappings or similar strategies for spatialization)

• gain: an overall gain of the synth

• fade: a fade value or a tuple (fadein, fadeout), in seconds

• instr: the instrument preset to use

• pitchinterpol: interpolation mode for pitch (‘linear’, ‘cos’, ‘freqlinear’, ‘freqcos’)

• fadeshape: shape of the fade curve (TODO)

• args: any args passed to the instr preset (a dict {‘pname’: value}

• priority: the priority of this synth. Priorities start with 1, low priorities are evaluated

  first. An instr with a higher priority is used to receive audio from an instr with a lower priority

• position: the horizontal placement inplace. 0=left, 1=right. For multichannel (> 2)

  presets this value is interpreted freely by the instrument, which does its own spatialization

• sustain: if positive the last breakpoint is extended by this duration. This is used mainly for

  sample based instruments (soundfont) to extend the playback. It can be used to implement one-shot sample playback

• transpose: add an extra transposition to all breakpoints

• glisstime: slide time to next event. This allows to add glissando lines for events even if their gliss attr is not set, or to generate legato lines

Attributes Summary

args
automations	A list of Automations
db	A dictionary holding the arguments explicitely specified
playkeys	Available keys for playback customization

Methods Summary

addAutomation(param, breakpoints[, ...])	rtype: None
clone(**kws)	Clone self with modifications
copy()	Returns a copy of self
fillWith(other)	Fill any unset value in self with the value in other inplace
get(key[, default])	Like dict.get()
items()	Like dict.items()
keys()	All possible keys for a PlayArgs instance
linkedNext()	rtype: bool
makeDefault(conf[, copy])	Create a PlayArgs with defaults from a CoreConfig
makeSynthAutomations(scorestruct, parentOffset)	rtype: list[SynthAutomation]
setArgs(**kws)	Set one or multiple values for the parameters passed to a preset
update(d)	rtype: None
updated(other[, automations])	A copy of self overwritten by other
values()	The values corresponding to all possible keys

Attributes Documentation

args

automations: list[Automation] | None

A list of Automations

db: dict[str, Any]

A dictionary holding the arguments explicitely specified

playkeys = {'args', 'chan', 'delay', 'end', 'fade', 'fadeshape', 'gain', 'glisstime', 'instr', 'linkednext', 'pitchinterpol', 'position', 'priority', 'skip', 'sustain', 'transpose'}

Available keys for playback customization

Methods Documentation

addAutomation(param, breakpoints, interpolation='linear', relative=True)

Return type:

None

clone(**kws)

Clone self with modifications

Parameters:

**kws – one of the possible playkeys

Return type:

PlayArgs

Returns:

the cloned PlayArgs

copy()

Returns a copy of self

Return type:

PlayArgs

fillWith(other)

Fill any unset value in self with the value in other inplace

Parameters:

other (PlayArgs) – another PlayArgs

Return type:

None

get(key, default=None)

Like dict.get()

items()

Like dict.items()

Return type:

dict[str, Any]

keys()

All possible keys for a PlayArgs instance

This is not the equivalent of the actual set keys (see playargs.args.keys())

Return type:

set[str]

linkedNext()

Return type:

bool

static makeDefault(conf, copy=True)

Create a PlayArgs with defaults from a CoreConfig

Parameters:

• conf (CoreConfig) – a CoreConfig

• copy – if T

Return type:

PlayArgs

Returns:

the created PlayArgs

makeSynthAutomations(scorestruct, parentOffset)

Return type:

list[SynthAutomation]

setArgs(**kws)

Set one or multiple values for the parameters passed to a preset

Parameters:

**kws (float | str) – any keyword parameter passed to an instrument preset. They are not checked

Return type:

None

update(d)

Return type:

None

updated(other, automations=True)

A copy of self overwritten by other

Parameters:

• other (PlayArgs) – the playargs to update self with

• automations – if True, include automations in the update

Return type:

PlayArgs

Returns:

a copy of self updated by other

values()

The values corresponding to all possible keys

Return type:

Iterable

This might contain unset values. For only the actually set

values, use playargs.args.values()