This module defines the object model of Volume, covering all representation of amplitude, volume, velocity, and related parameters.
realizeVolume(srcStream, setAbsoluteVelocity=False, useDynamicContext=True, useVelocity=True, useArticulations=True)¶
Given a Stream with one level of dynamics (e.g., a Part, or two Staffs that share Dynamics), 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.
Volume(client=None, velocity=None, velocityScalar=None, velocityIsRelative=True)¶
The Volume object lives on NotRest objects and subclasses. It is not a Music21Object subclass.
>>> v = volume.Volume(velocity=90)
Volume read-only properties
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.
>>> v = volume.Volume(velocity=128) >>> v.cachedRealized 1.0
Convenience property for testing.
>>> v = volume.Volume(velocity=128) >>> v.cachedRealizedStr '1.0'
Volume read/write properties
Get or set the client, which must be a note.NotRest subclass. The client is wrapped in a weak reference.
Get or set the velocity value, a numerical value between 0 and 127 and available setting amplitude on each Note or Pitch in chord.
>>> n = note.Note() >>> n.volume.velocity = 20 >>> n.volume.client == 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.
>>> n = note.Note() >>> n.volume.velocityScalar = .5 >>> n.volume.velocity 64
>>> n.volume.velocity = 127 >>> n.volume.velocityScalar 1.0
Return the dynamic context of this Volume, based on the position of the NotRest client 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 Dynamic object that will be used instead of a context search.
If useArticulations is True and client is not None, any articulations found on that client 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 client.
The velocityIsRelative tag determines if the velocity value includes contextual values, such as dynamics and and accents, or not.
>>> 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 dynamics
>>> 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.
>>> v = volume.Volume(velocity=64) >>> v.getRealizedStr() '0.5'
Given another Volume object, gather all attributes except client. Values are always copied, not passed by reference.
>>> n1 = note.Note() >>> v1 = volume.Volume() >>> v1.velocity = 111 >>> v1.client = n1
>>> v2 = volume.Volume() >>> v2.mergeAttributes(v1) >>> v2.client == None True >>> v2.velocity 111