3jjUdZddlmZddlmZddlZddlZddlm Z ddlm Z ddlm Z ddl m Z dd lmZdd lmZdd lmZdd lmZej$d ZGdde j(ZGddej,e Z ddZGddej2ZgZded<edk(rddlZej<eyy)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 eZdZy)VolumeExceptionN)__name__ __module__ __qualname__;/DATA/.local/lib/python3.12/site-packages/music21/volume.pyrr$srrc$eZdZdZdZddddd ddZddZdZd Zd Z d dd Z d dd Z e d Z e dZe dZe ddZej"ddZe ddZej"ddZy)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)rvelocityvelocityScalarrc||_d|_|t||_n|t ||_d|_||_yN)rrintrfloatrrr)selfrrrrs r__init__zVolume.__init__KsG +/  MDM  '"'"7D #"4rcZtj||dh}|j|_|S)z7 Don't copy the client; set to current r)ignoreAttributes)rdefaultDeepcopyr)r"memonews r __deepcopy__zVolume.__deepcopy___s*$$T48*M[[  rc4dt|jdS)Nz realized=)roundrealizedr"s r _reprInternalzVolume._reprInternalgs52344rc8|jjdS)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)rgetContextByClassr.s rgetDynamicContextzVolume.getDynamicContextks{{,,Y77rcN|#|j|_|j|_yy)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+  #(#8#8D &+&>&>D # rcX|j|||||}tt|dS)z Return the realized as rounded and formatted string value. Useful for testing. >>> v = volume.Volume(velocity=64) >>> v.getRealizedStr() '0.5' )useDynamicContext useVelocityuseArticulations baseLevelclipr+) getRealizedstrr,)r"r8r9r:r;r<vals rgetRealizedStrzVolume.getRealizedStrs;"1B+60@)2$( * 5a=!!rc|}d}|r=|j,|js |j}n||jdzz}n|dz }|jr|duret|tjr|}n4|j |j }ntjddg|||jdzz}|durqt|tjr|g}n=tj|r|}n%|j |j j}ng}|D]} || jz }|r|dkDrd}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 r1rr3 environLocal printDebug volumeScalarr Articulationr isIterable volumeShiftr) r"r8r9r:r;r<r?dmamas rr=zVolume.getRealizedscT  ##/....C!5!5!;3!67C u,. 0J0JK*+B&&'78)B[[,22BBA1==(C Qwq # rc\|j|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 )rr=r.s rcachedRealizedzVolume.cachedRealized+s-    '#'#3#3#5D ###rc@tt|jdS)z Convenience property for testing. >>> v = volume.Volume(velocity=128) >>> v.cachedRealizedStr '1.0' r+)r>r,rPr.s rcachedRealizedStrzVolume.cachedRealizedStr<s5,,a011rc"|jSr)r=r.s rr-zVolume.realizedGs!!rcr|j}|y|dz}|dkDr d}t|S|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)rr,)r"vsvs rrzVolume.velocityKsN ! ! : H s7AQxUAQxrc|d|_ytj|std||dkrd|_y|dk\rd|_y|dz |_y)Nz2value provided for velocity must be a number, not rrDrUrCg_@)rrisNumr)r"values rrzVolume.velocitycsZ =#'D e$!$VW\V]"^_ _ aZ#&D c\#&D #(5=D rc$|j}|y|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"rWs rrzVolume.velocityScalarps:   9Hrc|d|_tj|stdd|z|dkr d}||_y|dkDr d}||_ytj r|Jt |}||_y)Nz4value provided for velocityScalar must be a number, znot rrDrBrC)rrrYrt TYPE_CHECKINGr!)r"rZscalars rrzVolume.velocityScalars =#'D ||E"!"X&*5'N#34 4 19F & QYF &(((5\F%r)rznote.NotRest | Noner int | Noner float | Nonerboolr)TTTg?T)r8zdynamics.Dynamic | boolr:Hbool | articulations.Articulation | Iterable[articulations.Articulation])r8zbool | dynamics.Dynamicr:rc)returnr`)rZzint | float | None)rdra)rrr__doc__ __slots__r#r)r/r3r6r@r=propertyrPrRr-rsetterrrrrrr)sO4I%)!%)#' 5"5 5 # 5 ! 5(5 8?*CG#'  !$ "*?"B "448  C0C  3 CL$$ 22"".__ 1 1  D&&rrc^g}i}|j}d}|jtjrd}n|durd}|r|j tjd|jtj} | D]3} |j | } | | j jz} | || | f<5t|j}|jd} |D]} t| dst| tjs+| j|}|rC|dur?d}t!| t#|D]$}||\} } | |cxkDr| k\sn|} |||}nn|}| j$j'|||}|sd| j$_|| j$_y)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 )r8r9r:N)flattengetElementsByClassr r1extendDuration elementOffsetduration quarterLengthlistkeyssorthasattrrEr NotRestgetOffsetBySiterangelenr r=rr) srcStreamsetAbsoluteVelocityr8r9r:bKeys boundariesflatSrcdynamicsAvailableelementsestartendlastRelevantKeyIndexeStartrLkr?s r realizeVolumers( EJ!G!!("2"23   $ %  x//>--h.>.>?A))!,E!**222C'(Js| $Z__&'   1h Jq$,,$?&&w/F!%6$%>3SZ@A!&qJE3V,u,01,'a1A'((&&3>8H'JC#.3+*-'5rcBeZdZdZdZdZdZdZdZdZ dZ d Z y ) Testcddl}ddlm}tjd}|j |}|j |j|~|j|j |jtjdy)Nrr zG#4r) gcmusic21r r Noter assertEqualrcollect)r"rr n1rWs r testBasiczTest.testBasicsc" YYu  MMM $ 2&   499U#34rcddlm}ddlm}|j}t j d}|j d|t j d}|j d|tjd}|j|}|j d ||j|jjd ||j|j|y) Nrstreamrmffr+grr1)rrr Streamr r1insertr rrrrr2r3)r"rr sd1d2rv1s rtestGetContextSearchAzTest.testGetContextSearchA s"" MMO   d # B   c " B YYs^ ]]"] % B 44Y?D --/4rcnddlm}|j}tjd}|j d|tjd}|j d|t jd}|j d||j|jj|y)Nrrrrr+rr) rrrr r1rr rrr r3)r"rrrrrs rtestGetContextSearchBzTest.testGetContextSearchBs" MMO   d # B   c " B YYs^ B 446;rc~ddl}ddlm}tj}|j }d|_||_|j|}|j|j d|j|j d|j|j||j|j|y)Nrro) copyrr r rrrrdeepcopyr)r"rr rrv1Copys r testDeepCopyAzTest.testDeepCopyA-s" YY[ ]]_  r" c* #. B' +rcddlm}|jd}|j|j dt j d}|j|j |dt j d }|j|j |d t j d }|j|j |d |jd }t j d }|j|j |dt j d }|j|j |dt j d}|j|j |dt j d}|j|j |dy)Nrr@r0.5p)r80.35pppz0.15fffz0.91rU1.0z0.3mpz0.9z0.7)rr rrr@r r1)r"r rrs rtestGetRealizedAzTest.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*@%Hrc4td}|j|jdtj}|j|j|dtj }|j|j|dy)Nrrr)r:z0.65z0.6)rrr@r StrongAccentAccent)r"ra1a2s rtestGetRealizedBzTest.testGetRealizedB\s} R  **,e4  ' ' ) **B*?H  ! ! # **B*?Grcddlm}ddlm}|j}|j t j dd|jDcgc]}|jj}}|j|dgdztgdD]-\}}|j|dztj|/|jDcgc]}|jj}}|j|dgdz|j||jDcgc]}|jj}}|j|gd |j}|j t j ddtgdD]-\}}|j|dztj|/|jDcgc]}|jj}}|j|gd |jDcgc]}|jj}}|j|dgdz|j|d |jDcgc]}|jj}}|j|gd ycc}wcc}wcc}wcc}wcc}wcc}w) Nrrrg30.71)pprrrrffrrr+)rrrr0.64r0.99r0.78rrr0.21rrrT)rz)-r?rQr~rcrrUrUrrr)rrr r repeatAppendr rnotesrRr enumeraterr r1rr)r"rr rnmatchids rtestRealizeVolumeAzTest.testRealizeVolumeAmsI"" MMO tyy+67WW=W++W= 2 .MNDAq HHQUH,,Q/ 0O67WW=W++W= 2 . Q56WW=W++W= !A B MMO tyy+MNDAq HHQUH,,Q/ 0O56WW=W++W= !1 2-.GG4Gq""G4  , QD9,-GG4Gq""G4 !; > >>5 5s$J"J'$J,J1J6.J;cddlm}ddlm}|jd}|jdz}gd}t |j D]\}}t |D]}\}} ||z} |j| dj|jj} | | j|z } | j| tj| |d d|dd z}|j djj D cgc]} | j"j$}} |j'|gd |j d jj D cgc]} | j"j$}} |j'|gd |j d jj D cgc]} | j"j$}} |j'|gdycc} wcc} wcc} w)Nr)corpusrzbwv66.6)rrrrrrrrF)mustBeginInSpanr+)%rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrB)*rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr))rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr)rrrparse highestTimerpartsgetElementsByOffsetrlMeasurefirstrvrr r1rkrr rRr)r"rrrdurUnitdynsrrjroTargetmoInsertrrs rtestRealizeVolumeBzTest.testRealizeVolumeBs"" LL #--1$<agg&DAq!$1g+))':?*,,>,>v~~,Nuuw"A$5$5a$88("2"21"56(8d2Ah&D' 67WWQZ5G5G5I5O5OP5O++5OP !Y Z67WWQZ5G5G5I5O5OP5O++5OP !` a67WWQZ5G5G5I5O5OP5O++5OP !K L/QQQs G9)G>Hc6ddlm}|j}|jt j ddt dddD]<}|j|jjtj>t dddD]<}|j|jjtj>|jDcgc]}|jj}}|j|gdycc}w)Nrrrrrr)0.96rr0.810.86rrrrrrrrrrr)rrrrr rrwrrappendrrr rRr)r"rrrrrs rtestRealizeVolumeCzTest.testRealizeVolumeCs" MMO tyy+q"aA GGAJ $ $ + +M,@,@,B C!q"aA GGAJ $ $ + +M,F,F,H I!67WW=W++W= !1 2>s"DN) rrrrrrrrrrrrrrrrrs4 55& < ,"I<H"3rs#$! 5&{&&x0  l33 |&W # #%7|&H ',$("#' K.^q28  q2l J zGTr