This module defines the object model of Volume, covering all representation of amplitude, volume, velocity, and related parameters.
Given a Stream with one level of dynamics (e.g., a Part, or two Staffs that share Dyanmics), destructively modify it to set all realized volume levels. These values will be stored in the Volume object as cachedRealized values.
This is a top-down routine, as opposed to bottom-up values available with context searches on Volume. This thus offers a performance benefit.
This is always done in place; for the option of non-in place processing, see Stream.realizeVolume().
If setAbsoluteVelocity is True, the realized values will overwrite all existing velocity values, and the Volume objects velocityIsRelative parameters will be set to False.
The Volume object lives on NotRest objects and subclasses. It is not a Music21Object subclass.
>>> from music21 import * >>> v = volume.Volume()
Attributes without Documentation: velocityIsRelative
Return the cached realized value of this volume. This will be the last realized value or, if that value has not been set, a newly realized value. If the caller knows that the realized values have all been recently set, using this property will add significant performance boost.>>> from music21 import * >>> v = volume.Volume(velocity=128) >>> v.cachedRealized 1.0
Convenience property for testing.>>> from music21 import * >>> v = volume.Volume(velocity=128) >>> v.cachedRealizedStr '1.0'
Get or set the parent, which must be a note.NotRest subclass. The parent is wrapped in a weak reference.
Return the realized unit-interval scalar for this Volume
Get or set the velocity value, a numerical value between 0 and 127 and available setting amplitude on each Note or Pitch in chord.>>> from music21 import * >>> n = note.Note() >>> n.volume.velocity = 20 >>> n.volume.parent == n True >>> n.volume.velocity 20
Get or set the velocityScalar value, a numerical value between 0 and 1 and available setting amplitude on each Note or Pitch in chord. This value is mapped to the range 0 to 127 on output.
Note that this value is derived from the set velocity value. Floating point error seen here will not be found in the velocity value.
When setting this value, an integer-based velocity value will be derived and stored.>>> from music21 import * >>> n = note.Note() >>> n.volume.velocityScalar = .5 >>> n.volume.velocity 64 >>> n.volume.velocity = 127 >>> n.volume.velocityScalar 1.0
- getContextByClass(className, sortByCreationTime=False, getElementMethod='getElementAtOrBefore')¶
Simulate get context by class method as found on parent NotRest object.
Return the dynamic context of this Volume, based on the position of the NotRest parent of this object.
- getRealized(useDynamicContext=True, useVelocity=True, useArticulations=True, baseLevel=0.5, clip=True)¶
Get a realized unit-interval scalar for this Volume. This scalar is to be applied to the dynamic range of whatever output is available, whatever that may be.
The baseLevel value is a middle value between 0 and 1 that all scalars modify. This also becomes the default value for unspecified dynamics. When scalars (between 0 and 1) are used, their values are doubled, such that mid-values (around .5, which become 1) make no change.
This can optionally take into account dynamicContext, useVelocity, and useArticulation.
If useDynamicContext is True, a context search for a dynamic will be done, else dynamics are ignored. Alternatively, the useDynamicContext may supply a Dyanmic object that will be used instead of a context search.
If useArticulations is True and parent is not None, any articulations found on that parent will be used to adjust the volume. Alternatively, the useArticulations parameter may supply a list of articulations that will be used instead of that available on a parent.
The velocityIsRelative tag determines if the velocity value includes contextual values, such as dynamics and and accents, or not.>>> from music21 import * >>> s = stream.Stream() >>> s.repeatAppend(note.Note('d3', quarterLength=.5), 8) >>> s.insert([0, dynamics.Dynamic('p'), 1, dynamics.Dynamic('mp'), 2, dynamics.Dynamic('mf'), 3, dynamics.Dynamic('f')]) >>> s.notes.volume.getRealized() 0.496... >>> s.notes.volume.getRealized() 0.496... >>> s.notes.volume.getRealized() 0.63779... >>> s.notes.volume.getRealized() 0.99212...>>> # velocity, if set, will be scaled by dyanmics >>> s.notes.volume.velocity = 20 >>> s.notes.volume.getRealized() 0.22047... >>> # unless we set the velocity to not be relative >>> s.notes.volume.velocityIsRelative = False >>> s.notes.volume.getRealized() 0.1574803...
- getRealizedStr(useDynamicContext=True, useVelocity=True, useArticulations=True, baseLevel=0.5, clip=True)¶
Return the realized as rounded and formatted string value. Useful for testing.>>> from music21 import * >>> v = volume.Volume(velocity=64) >>> v.getRealizedStr() '0.5'
Given another Volume object, gather all attributes except parent. Values are always copied, not passed by reference.>>> from music21 import * >>> n1 = note.Note() >>> v1 = volume.Volume() >>> v1.velocity = 111 >>> v1.parent = n1 >>> v2 = volume.Volume() >>> v2.mergeAttributes(v1) >>> v2.parent == None True >>> v2.velocity 111