jj~UdZddlmZddlmZddlZddlZddlm Z ddlm Z ddlm Z ddl m Z dd lmZdd lmZdd lmZdd lmZejd ZGdde jZGddeje Z ddZGddejZgZded<edkrddlZejedSdS)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)notevolumeceZdZdS)VolumeExceptionN)__name__ __module__ __qualname__/Users/tedpeters/Documents/Projects/Claude Projects/Misc Tools/notename-sheets/.venv/lib/python3.11/site-packages/music21/volume.pyrr$sDrrc"eZdZdZdZdddddd%dZd&dZdZdZdZ d'd(dZ d'd)dZ e dZ e dZe dZe d*dZejd+d"Ze d,d#Zejd+d$ZdS)-Volumea 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)rvelocityvelocityScalarrrnote.NotRest | Noner int | Noner float | Nonerboolc||_d|_|t||_n|t ||_d|_||_dSN)rrintrfloatrrr)selfrrrrs r__init__zVolume.__init__KsT +/  MMDMM  '"'"7"7D #"4rcNtj||dh}|j|_|S)z7 Don't copy the client; set to current r)ignoreAttributes)rdefaultDeepcopyr)r&memonews r __deepcopy__zVolume.__deepcopy___s+$T48*MMM[  rc2dt|jdS)Nz realized=)roundrealizedr&s r _reprInternalzVolume._reprInternalgs4522444rc6|jdS)aJ 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)rgetContextByClassr2s rgetDynamicContextzVolume.getDynamicContextks{,,Y777rc>||j|_|j|_dSdS)ay 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 rmergeAttributeszVolume.mergeAttributesys.  #(#8D &+&>D # # #  r?useDynamicContextdynamics.Dynamic | booluseArticulationsHbool | articulations.Articulation | Iterable[articulations.Articulation]cp||||||}tt|dS)z Return the realized as rounded and formatted string value. Useful for testing. >>> v = volume.Volume(velocity=64) >>> v.getRealizedStr() '0.5' )r< useVelocityr> baseLevelclipr/) getRealizedstrr0)r&r<rAr>rBrCvals rgetRealizedStrzVolume.getRealizedStrsE"1B+60@)2$( ** 5a==!!!rbool | dynamics.Dynamicc2|}d}|r)|j|js|j}n||jdzz}n|dz }|jr|durdt|tjr|}n8|j|}ntddg| ||j dzz}|durZt|tj r|g}n-tj |r|}n|j |jj }ng}|D] } || jz } |r|dkrd}n|d krd }||_|S) a 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 r5rr7 environLocal printDebug volumeScalarr Articulationr isIterable volumeShiftr) r&r<rAr>rBrCrFdmamas rrDzVolume.getRealizedsT   #/.=.CC!5!;3!67C u,,. 0JKK*+BB&'788)BB[,2BBB))A1=(CC  Qwwq # rcP|j||_|jS)a 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 )rrDr2s rcachedRealizedzVolume.cachedRealized+s*   '#'#3#3#5#5D ##rcFtt|jdS)z Convenience property for testing. >>> v = volume.Volume(velocity=128) >>> v.cachedRealizedStr '1.0' r/)rEr0rXr2s rcachedRealizedStrzVolume.cachedRealizedStr<s5,a00111rc*|Sr#)rDr2s rr1zVolume.realizedGs!!!rreturncb|j}|dS|dz}|dkrd}n|dkrd}t|S)a4 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)rr0)r&vsvs rrzVolume.velocityKsH ! :4 H s77AA UUAQxxrvalueint | float | Nonec| d|_dStj|std||dkr d|_dS|dkr d|_dS|dz |_dS)Nz2value provided for velocity must be a number, not rrLr^rKg_@)rrisNumr)r&ras rrzVolume.velocitycs =#'D e$$ 1!"^W\"^"^__ _ aZZ#&D c\\#&D #(5=D rc|j}|dS|S)a9 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&r`s rrzVolume.velocityScalarps:   94Hrc|d|_tj|stdd|z|dkrd}n(|dkrd}ntjr|Jt |}||_dS)Nz4value provided for velocityScalar must be a number, znot rrLrJrK)rrrdrt TYPE_CHECKINGr%)r&rascalars rrzVolume.velocityScalars =#'D |E"" 4!"X$25NN#344 4 199FF QYYFF )(((5\\F%r)rrrrrr rr!r#)TTTr;T)r<r=r>r?)r<rHr>r?)r\r)rarb)r\r )rrr__doc__ __slots__r'r-r3r7r:rGrDpropertyrXrZr1rsetterrrrrrr)s4I%)!%)#' 555555(555 8 8 8???*CG#'  !$ """""448  CCCCCL$$X$ 22X2""X"X._ 1 1 1_ 1   X D&&&&&&rrFTcg}i}|}d}|tjrd}n|durd}|r|tjd|tj} | D]-} || } | | jjz} | || | f<.t| }| d} |D]} t| drt| tjr| |}|rT|durPd}t!| t#|D]/}||\} } | |cxkr| krn|} |||}n0n|}| j|||}|rd| j_|| j_dS)am 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 )r<rAr>N)flattengetElementsByClassr r5extendDuration elementOffsetduration quarterLengthlistkeyssorthasattrrMr NotRestgetOffsetBySiterangelenr rDrr) srcStreamsetAbsoluteVelocityr<rAr>bKeys boundariesflatSrcdynamicsAvailableelementsestartendlastRelevantKeyIndexeStartrTkrFs r realizeVolumers-( EJ!!G!!("233&   $ $ %   x/>>>--h.>?? ) )A))!,,E!*22C'(Js| $ $Z__&&''  .. 1h   .Jq$,$?$? .&&w//F! '%6$%>%>3SZZ@@A!&qJE3V,,,,u,,,,,01,'a1 -'(&&3>8H'JJC# ..3+*-'5..rcDeZdZdZdZdZdZdZdZdZ dZ d Z d S) Testc(ddl}ddlm}tjd}||}||j|~|||jtjddS)Nrr zG#4r) gcmusic21r r Noter assertEqualrcollect)r&rr n1r`s r testBasiczTest.testBasics """""" Yu   MMM $ $ 2&&&   49U#3#344444rcddlm}ddlm}|}t jd}|d|t jd}|d|tjd}| |}|d || |j d || | |dS) Nrstreamrmffr/grr5)rrr Streamr r5insertr rrrrr6r7)r&rr sd1d2rv1s rtestGetContextSearchAzTest.testGetContextSearchA s"""""""""""" MMOO  d # # B  c " " B Ys^^ ]]"] % % B 44Y??DDD --//44444rcddlm}|}tjd}|d|tjd}|d|t jd}|d|||j |dS)Nrrrrr/rr) rrrr r5rr rrr r7)r&rrrrrs rtestGetContextSearchBzTest.testGetContextSearchBs"""""" MMOO  d # # B  c " " B Ys^^ B 4466;;;;;rcddl}ddlm}tj}|}d|_||_||}| |jd| |jd| |j|| |j|dS)Nrro) copyrr r rrrrdeepcopyr)r&rr rrv1Copys r testDeepCopyAzTest.testDeepCopyA-s """""" Y[[ ]]__  r"" c*** #... B''' +++++rcddlm}|d}||dt jd}|||dt jd }|||d t jd }|||d |d }t jd }|||dt jd }|||dt jd}|||dt jd}|||ddS)Nrr@r0.5p)r<0.35pppz0.15fffz0.91r^1.0z0.3mpz0.9z0.7)rr rrrGr r5)r&r rrs rtestGetRealizedAzTest.testGetRealizedA>s"""""" ]]B] ' ' **,,e444  c " " **R*@@&III  e $ $ **R*@@&III e $ $ **R*@@&III]]C] ( (  e $ $ **R*@@%HHH  e $ $ **R*@@%HHH  d # # **R*@@%HHH  c " " **R*@@%HHHHHrcjtd}||dtj}|||dtj}|||ddS)Nrrr)r>z0.65z0.6)rrrGr StrongAccentAccent)r&ra1a2s rtestGetRealizedBzTest.testGetRealizedB\s R  **,,e444  ' ) ) **B*??HHH  ! # # **B*??GGGGGrcfddlm}ddlm}|}|t jddd|jD}||dgdztgdD]0\}}| |d ztj |1d |jD}||dgdz| |d |jD}||gd |}|t jddtgdD]0\}}| |d ztj |1d |jD}||gd d|jD}||dgdz| |dd|jD}||gddS)Nrrrg3c&g|]}|jjSrr rZ.0ns r z+Test.testRealizeVolumeA..u===+===r0.71)pprrrrffrrr/c&g|]}|jjSrrrs rrz+Test.testRealizeVolumeA..|rrc&g|]}|jjSrrrs rrz+Test.testRealizeVolumeA..rr)rrrr0.64r0.99r0.78rrr0.21rrrc&g|]}|jjSrrrs rrz+Test.testRealizeVolumeA..rrc&g|]}|jjSrr rrs rrz+Test.testRealizeVolumeA..444q"444rT)rc&g|]}|jjSrrrs rrz+Test.testRealizeVolumeA..rr)-r?rQr~rcrr^r^rrr)rrr r repeatAppendr rnotesr enumeraterr r5r)r&rr rmatchids rtestRealizeVolumeAzTest.testRealizeVolumeAms"""""""""""" MMOO ty+++>=QW=== 2 ...MMMNN 1 1DAq HHQUH,Q// 0 0 0 0>=QW=== 2 ... Q==QW=== !A!A!A B B B MMOO ty+++MMMNN 1 1DAq HHQUH,Q// 0 0 0 0==QW=== !1!1!1 2 2 254AG444  ,,, QD99944AG444 !;!;!; < < < < .PPP+PPPr)%rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrc&g|]}|jjSrrrs rrz+Test.testRealizeVolumeB..rrrJ)*rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrc&g|]}|jjSrrrs rrz+Test.testRealizeVolumeB..rr))rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr)rrrparse highestTimerpartsgetElementsByOffsetrqMeasurefirstr{rr r5rprr)r&rrrdurUnitdynsrrjroTargetmoInsertrs rtestRealizeVolumeBzTest.testRealizeVolumeBs9"""""""""""" LL # #-1$<<<ag&& ' 'DAq!$ 7 71g+))':?*,,,>,>v~,N,Nuuww"A$5$5a$8$88("21"5"566668d2A2h&DD QPQWQZ5G5G5I5I5OPPP !Y!Y!Y Z Z ZQPQWQZ5G5G5I5I5OPPP !`!`!` a a aQPQWQZ5G5G5I5I5OPPP !K!K!K L L L L Lrcddlm}|}|t jddt dddD]8}|j|j tj 9t dddD]8}|j|j tj 9d|jD}| |gddS) Nrrrrrrc&g|]}|jjSrrrs rrz+Test.testRealizeVolumeC..rr)0.96rr0.810.86rrrrrrrrrrr) rrrrr rr|rrappendrrr)r&rrrrs rtestRealizeVolumeCzTest.testRealizeVolumeCs """""" MMOO ty+++q"a D DA GAJ $ + +M,@,B,B C C C Cq"a J JA GAJ $ + +M,F,H,H I I I I==QW=== !1!1!1 2 2 2 2 2rN) rrrrrrrrrrrrrrrrrs 5 5 5555& < < < ,,,"III<HHH"3<3<3rs#"""""$$$$$$!!!!!! 555555&{&x00      l3   |&|&|&|&|&W #%7|&|&|&H ',$("#' K.K.K.K.^q2q2q2q2q28 q2q2q2l  zNNNGTr