rhDj%SrSSKJr SSKJr SSKrSSKrSSKJ r SSKJ r SSKJ r SSK J r SS KJr SS KJr SS KJr SS KJr \R$"S 5r"SS\ R(5r"SS\R,\ 5rSSjr"SS\R25r/rS\S'\S:XaSSKr\R<"\5 gg)z This module defines the object model of Volume, covering all representation of amplitude, volume, velocity, and related parameters. ) annotations)IterableN) articulations) exceptions21)common)SlottedObjectMixin)dynamics) environment)prebase)notevolumec\rSrSrSrg)VolumeException%N)__name__ __module__ __qualname____firstlineno____static_attributes__rH/home/james-whalen/.local/lib/python3.13/site-packages/music21/volume.pyrr%srrcB\rSrSrSrSrSSSSS.SSjjrSSjrS rS r S r SSS jjr SSS jjr \ S5r\ S5r\ S5r\ SSj5r\R$SSj5r\ SSj5r\R$SSj5rSrg)Volume*aR The Volume object lives on NotRest objects and subclasses. It is not a Music21Object subclass. Generally, just assume that a Note has a volume object and don't worry about creating this class directly: >>> n = note.Note('C5') >>> v = n.volume >>> v.velocity = 20 >>> v.client is n True But if you want to create it yourself, you can specify the client, velocity, velocityScalar, and >>> v = volume.Volume(velocity=90) >>> v >>> v.velocity 90 * Changed in v9: all constructor attributes are keyword only. (client as first attribute was confusing) )client_velocityScalar_cachedRealizedvelocityIsRelativeNT)rvelocityvelocityScalarrcXlSUlUb[U5UlOUb[ U5UlSUlX@lgN)rrintr floatr!rr)selfrr r!rs r__init__Volume.__init__LsC +/  MDM  '"'"7D #"4rcT[R"XS1S9nURUlU$)z' Don't copy the client; set to current r)ignoreAttributes)rdefaultDeepcopyr)r&memonews r __deepcopy__Volume.__deepcopy__`s($$T8*M[[  rc4S[URS53$)Nz realized=)roundrealizedr&s r _reprInternalVolume._reprInternalhs52344rc8URRS5$)a  Return the dynamic context of this Volume, based on the position of the client of this object. >>> n = note.Note() >>> n.volume.velocityScalar = 0.9 >>> s = stream.Measure([dynamics.Dynamic('ff'), n]) >>> n.volume.getDynamicContext() Dynamic)rgetContextByClassr4s rgetDynamicContextVolume.getDynamicContextls{{,,Y77rcPUb#URUlURUlgg)a Given another Volume object, gather all attributes except client. Values are always copied, not passed by reference. >>> n1 = note.Note() >>> v1 = n1.volume >>> v1.velocity = 111 >>> v2 = volume.Volume() >>> v2.mergeAttributes(v1) >>> v2.client is None True >>> v2.velocity 111 N)rr)r&others rmergeAttributesVolume.mergeAttributeszs+  #(#8#8D &+&>&>D # rcRURUUUUUS9n[[US55$)z Return the realized as rounded and formatted string value. Useful for testing. >>> v = volume.Volume(velocity=64) >>> v.getRealizedStr() '0.5' )useDynamicContext useVelocityuseArticulations baseLevelclipr1) getRealizedstrr2)r&rArBrCrDrEvals rgetRealizedStrVolume.getRealizedStrs; 1B+60@)2$( * 5a=!!rcUnSnU(aBURb0UR(d URnOX`RS--nOUS- nUR(aUSLak[U[R5(aUnO5UR bUR 5nO[RSS/5 UbXgRS--nUSLa~[U[R5(aU/nOD[R"U5(aUnO&UR bUR RnO/nUHn XiR- nM U(aUS:aSnOUS :aS nX`lU$) aH 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 0.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 an iterable 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 accents, or not. >>> s = stream.Stream() >>> s.repeatAppend(note.Note('d3', quarterLength=0.5), 8) >>> s.insert([0, dynamics.Dynamic('p'), ... 1, dynamics.Dynamic('mp'), ... 2, dynamics.Dynamic('mf'), ... 3, dynamics.Dynamic('f')]) >>> s.notes[0].volume.getRealized() 0.496... >>> s.notes[1].volume.getRealized() 0.496... >>> s.notes[2].volume.getRealized() 0.63779... >>> s.notes[7].volume.getRealized() 0.99212... velocity, if set, will be scaled by dynamics: >>> s.notes[7].volume.velocity = 20 >>> s.notes[7].volume.getRealized() 0.22047... Unless we set the velocity to not be relative: >>> s.notes[7].volume.velocityIsRelative = False >>> s.notes[7].volume.getRealized() 0.1574803... Ng@g^?FzgetRealized():zEuseDynamicContext is True but no dynamic supplied or found in context?r)rr isinstancer r8rr: environLocal printDebug volumeScalarr Articulationr isIterable volumeShiftr) r&rArBrCrDrErHdmamas rrFVolume.getRealizedsdP  ##/....C!5!5!;3!67C u,. 0J0JKK*+B&&'788)B[[,22BBA==(C Qwq # rc^URcUR5UlUR$)aV 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 )rrFr4s rcachedRealizedVolume.cachedRealized)s-    '#'#3#3#5D ###rc@[[URS55$)zf Convenience property for testing. >>> v = volume.Volume(velocity=128) >>> v.cachedRealizedStr '1.0' r1)rGr2r[r4s rcachedRealizedStrVolume.cachedRealizedStr:s5,,a011rc"UR5$r#)rFr4s rr3Volume.realizedEs!!rcdURnUcgUS-nUS:aSnOUS:aSn[U5$)z 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 Nr)rr2)r&vsvs rr Volume.velocityIsA ! ! : H s7A UAQxrcUcSUlg[R"U5(d[SU35eUS::aSUlgUS:aSUlgUS- Ulg)Nz2value provided for velocity must be a number, not rrNrcrMg_@)rrisNumr)r&values rr rfas] =#'D e$$!$VW\V]"^_ _ aZ#&D c\#&D #(5=D rc&URnUcgU$)a 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 = 0.5 >>> n.volume.velocity 64 >>> n.volume.velocity = 127 >>> n.volume.velocityScalar 1.0 If velocity is not set, then this will return None >>> n = note.Note() >>> n.volume.velocityScalar is None True N)r)r&res rr!Volume.velocityScalarns:   9HrcUcSUl[R"U5(d[SSU3-5eUS:aSnO.US:aSnO%[R (aUce[ U5nX lg)Nz4value provided for velocityScalar must be a number, znot rrNrLrM)rrrhrt TYPE_CHECKINGr%)r&riscalars rr!rksx =#'D ||E""!"X&*5'N#34 4 19F QYF(((5\F%r)rrrr rr!)rznote.NotRest | Noner int | Noner! float | Nonerboolr#)TTTg?T)rAzdynamics.Dynamic | boolrCOt.Union[bool, articulations.Articulation, Iterable[articulations.Articulation]])rAzbool | dynamics.DynamicrCrs)returnrp)rizint | float | None)rtrq)rrrr__doc__ __slots__r'r.r5r:r>rIrFpropertyr[r^r3r setterr!rrrrrr*sN4I%)!%)#' 5"5 5 # 5 ! 5(5 8?*CG#'6:!$ "*?"*3"248  A0A AH$$ 22"".__ 1 1  D&&rrc/n0nUR5nSnUR[R5(aSnOUSLaSnU(aUR [RSS9 UR[R5n U H1n UR U 5n XR R-n XX4'M3 [UR55nUR5 Sn UHn [U S5(dM[U [R5(dM7U RU5nU(aFUSLaASn[!U [#U55H%nUUupXs=:aU :dMO MUn XeUn O OUnU R$R'UUUS9nU(dMSU R$lUU R$lM g)aA 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. If setAbsoluteVelocity is True, the realized values will overwrite all existing velocity values, and the Volume objects velocityIsRelative parameters will be set to False. FT)inPlacerr )rArBrCN)flattengetElementsByClassr r8extendDuration elementOffsetduration quarterLengthlistkeyssorthasattrrOr NotRestgetOffsetBySiterangelenr rFrr!) srcStreamsetAbsoluteVelocityrArBrCbKeys boundariesflatSrcdynamicsAvailableelementsestartendlastRelevantKeyIndexeStartrVkrHs r realizeVolumers( EJ!G!!("2"233   $ %  x//>--h.>.>?A))!,E**222C'(| $Z__&'   1h  Jq$,,$?$?&&w/F!%6$%>3SZ@A!&qJE,u,,01,'a1A'((&&3>8H'JC#".3+*-'5rcJ\rSrSrSrSrSrSrSrSr Sr S r S r S r g ) TesticSSKnSSKJn [R"S5nUR US9nUR URU5 AUR5 UR UR[R"S55 g)Nrr zG#4r) gcmusic21r r Noter assertEqualrcollect)r&rr n1res r testBasicTest.testBasicsc" YYu  MMM $ 2&   499U#34rcSSKJn SSKJn UR5n[R "S5nUR SU5 [R "S5nUR SU5 [R"S5nURUS9nUR S U5 URURRS 5U5 URUR5U5 g) Nrstreamrmffr1grr8)rrr Streamr r8insertr rrrrr9r:)r&rr sd1d2rv1s rtestGetContextSearchATest.testGetContextSearchAs"" MMO   d # B   c " B YYs^ ]]"] % B 44Y?D --/4rctSSKJn UR5n[R"S5nUR SU5 [R"S5nUR SU5 [ R"S5nUR SU5 URURR5U5 g)Nrrrrr1rr) rrrr r8rr rrr r:)r&rrrrrs rtestGetContextSearchBTest.testGetContextSearchBs" MMO   d # B   c " B YYs^ B 446;rc~SSKnSSKJn [R"5nUR 5nSUlX4lURU5nURUR S5 URUR S5 URURU5 URURU5 g)Nrro) copyrr r rrr rdeepcopyr)r&rr rrv1Copys r testDeepCopyATest.testDeepCopyA+s" YY[ ]]_  r" c* #. B' +rcrSSKJn URSS9nURUR 5S5 [ R "S5nURUR US9S5 [ R "S 5nURUR US9S 5 [ R "S 5nURUR US9S 5 URS S9n[ R "S 5nURUR US9S5 [ R "S 5nURUR US9S5 [ R "S5nURUR US9S5 [ R "S5nURUR US9S5 g)Nrr@r 0.5p)rA0.35pppz0.15fffz0.91rc1.0z0.3mpz0.9z0.7)rr rrrIr r8)r&r rrs rtestGetRealizedATest.testGetRealizedA<s" ]]B] ' **,e4   c " **R*@&I   e $ **R*@&I  e $ **R*@&I]]C] (   e $ **R*@%H   e $ **R*@%H   d # **R*@%H   c " **R*@%Hrc&[SS9nURUR5S5 [R"5nURURUS9S5 [R "5nURURUS9S5 g)Nrrr)rCz0.65z0.6)rrrIr StrongAccentAccent)r&ra1a2s rtestGetRealizedBTest.testGetRealizedBZs} R  **,e4  ' ' ) **B*?H  ! ! # **B*?GrcSSKJn SSKJn UR5nUR [ R "S5S5 URVs/sHoDRRPM nnURUS/S-5 [/SQ5H.upgURUS-[R"U55 M0 URVs/sHoDRRPM nnURUS/S-5 URU5 URVs/sHoDRRPM nnURU/S Q5 UR5nUR [ R "S5S5 [/SQ5H.upgURUS-[R"U55 M0 URVs/sHoDRRPM nnURU/S Q5 URVs/sHoDRRPM nnURUS/S-5 URUS S 9 URVs/sHoDRRPM nnURU/S Q5 gs snfs snfs snfs snfs snfs snf) Nrrrg30.71)pprrrrffrrr1)rrrr0.64r0.99r0.78rrr0.21rrrT)r)-r?rQr~rcrrcrcrrr)rrr r repeatAppendr rnotesr^r enumeraterr r8rr )r&rr rnmatchids rtestRealizeVolumeATest.testRealizeVolumeAks9"" MMO tyy+67WW=W++W= 2 .MNDA HHQUH,,Q/ 0O67WW=W++W= 2 . Q56WW=W++W= !A B MMO tyy+MNDA HHQUH,,Q/ 0O56WW=W++W= !1 2-.GG4Gq""G4  , QD9,-GG4Gq""G4 !; > >>5 5s$J1J6+J;#K&K;K cSSKJn SSKJn URS5nURS-n/SQn[ UR 5Hupg[ U5HyupX-n URU SS9RUR5R5n XRU5- n U RU [R"U 55 M{ US SUSS -nM UR SR5R V s/sHoR"R$PM nn UR'U/S Q5 UR S R5R V s/sHoR"R$PM nn UR'U/S Q5 UR S R5R V s/sHoR"R$PM nn UR'U/SQ5 gs sn fs sn fs sn f)Nr)corpusrzbwv66.6)rrrrrrrrF)mustBeginInSpanr1)%rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrL)*rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr))rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr)rrrparse highestTimerpartsgetElementsByOffsetr|Measurefirstrrr r8r{rr r^r)r&rrrdurUnitdynsrrjroTargetmoInsertrrs rtestRealizeVolumeBTest.testRealizeVolumeBs"" LL #--1$<agg&DA!$+))':?*,,>,>v~~,Nuuw"$5$5a$88("2"21"56(8d2Ah&D' 67WWQZ5G5G5I5O5OP5O++5OP !Y Z67WWQZ5G5G5I5O5OP5O++5OP !` a67WWQZ5G5G5I5O5OP5O++5OP !K L/QQQs G=)HHcHSSKJn UR5nUR[R "S5S5 [ SSS5H>nURURR[R"55 M@ [ SSS5H>nURURR[R"55 M@ URVs/sHoDRRPM nnURU/SQ5 gs snf)Nrrrrrr)0.96rr0.810.86rrrrrrrrrrr)rrrrr rrrrappendrrr r^r)r&rrrrrs rtestRealizeVolumeCTest.testRealizeVolumeCs" MMO tyy+q"aA GGAJ $ $ + +M,@,@,B C!q"aA GGAJ $ $ + +M,F,F,H I!67WW=W++W= !1 2>s)DrN)rrrrrrrrrrrrrrrrrrrs4 55& < ,"I<H"3rs#$! 5&&x0  l33 y&W # #%7y&B ',$("#' K.^q28  q2l J z Tr