3jd UdZddlmZddlmZmZddlZddlZddl m Z ddl m Z ddl m Z ddl m Z dd l mZejrdd l mZe j"d Zd ZGd de j(ZGdde j,ZGddeZGddeZGddeZGddeZGddeZGddeZGddeZGdd eZGd!d"eZ Gd#d$eZ!Gd%d&eZ"Gd'd(eZ#Gd)d*e#Z$Gd+d,e#Z%Gd-d.e#Z&Gd/d0e#Z'Gd1d2e#Z(Gd3d4eZ)Gd5d6e)Z*Gd7d8e)Z+Gd9d:e)Z,Gd;de)Z.deee"ddgde$e%e&e'e(gddde*e+e.gdddddegd?Z/d@e0dA<dGdHdBZ1 dI dJdCZ2GdDdEejfZ4eee+gZ5e6dFk(rddl Z e jne4yy)Kz This module defines numerous subclasses of :class:`~music21.clef.Clef`, providing object representations for all commonly used clefs. Clef objects are often found within :class:`~music21.stream.Measure` objects. ) annotations)IterableSequenceN)base) exceptions21) environment)pitch)style)streamclef#c eZdZy) ClefExceptionN)__name__ __module__ __qualname__9/DATA/.local/lib/python3.12/site-packages/music21/clef.pyrr(srrceZdZUdZdZdddZded<ejZ dZ dfd Z d Z e dd Zejdd Ze dd Zddd ddZxZS)Clefa A Clef is a basic `music21` object for representing musical clefs (Treble, Bass, etc.) Some clefs only represent the graphical element of the clef, such as G clef, which is subclassed by TrebleClef() and FrenchViolinClef(). >>> tc = clef.TrebleClef() >>> tc >>> tc.sign 'G' >>> tc.line 2 Most clefs also have a "lowestLine" function which represents the :attr:`~music21.pitch.Pitch.diatonicNoteNum` of the note that would fall on the lowest line if the Clef were put on a five-line staff. (Where C4,C#4,C##4,C-4 etc. = 29, all types of D4 = 30, etc.) >>> tc.lowestLine 31 **Equality** Two Clefs are equal if their class is the same, their sign is the same, their line is the same and their octaveChange is the same. >>> c1 = clef.PercussionClef() >>> c2 = clef.NoClef() >>> c1 == c2 False >>> c3 = clef.TrebleClef() >>> c4 = clef.TrebleClef() >>> c3 == c4 True >>> c4.octaveChange = -1 >>> c3 == c4 False Note that these are not equal: >>> clef.TrebleClef() == clef.GClef(line=2) False )signline octaveChangea The sign of the clef, generally, 'C', 'G', 'F', 'percussion', 'none' or None. >>> alto = clef.AltoClef() >>> alto.sign 'C' >>> percussion = clef.PercussionClef() >>> percussion.sign 'percussion' Note the difference here: >>> clef.Clef().sign is None True >>> clef.NoClef().sign 'none' a The line, counting from the bottom up, that the clef resides on. >>> clef.AltoClef().line 3 >>> clef.TenorClef().line 4 May be None: >>> print(clef.NoClef().line) None )rrdict[str, str] _DOC_ATTRrc Nt|di|d|_d|_d|_y)Nrr)super__init__rr _octaveChangeselfkeywords __class__s rrz Clef.__init__s) $8$" " "#rcy)Nrr"s r _reprInternalzClef._reprInternalsrc|jS)z The number of octaves that the clef "transposes", generally 0. >>> tc = clef.TrebleClef() >>> tc.octaveChange 0 >>> clef.Treble8vbClef().octaveChange -1 r r's rrzClef.octaveChanges!!!rc||_yNr*)r"newValues rrzClef.octaveChanges %rc|jjjdd}|r|dj|ddzSy)as Returns the "name" of the clef, from the class name >>> tc = clef.TrebleClef() >>> tc.name 'treble' >>> tc = clef.Treble8vbClef() >>> tc.name 'treble8vb' >>> tc = clef.MezzoSopranoClef() >>> tc.name 'mezzoSoprano' OMIT_FROM_DOCS >>> clef.Clef().name '' rr&rN)r$rreplacelower)r" classNames rnamez Clef.namesD,NN++33FB? Q<%%')AB-7 7rTF firstLastOnlyextremePitchOnlyct|tjr|g}n|}|s td|r!t |d}t |d}||g}n|rt |dkDr |d|dg}n|}d}t|ttfr|j|jdz} nt} |D]} | j| z } || z }|dk\ry y ) a Return a string representing the stem direction for a single :class:`~music21.pitch.Pitch` object or a list/tuple/Stream of pitches. >>> P = pitch.Pitch >>> bc = clef.BassClef() >>> bc.getStemDirectionForPitches(P('C3')) 'up' For two pitches, the most extreme pitch determines the direction: >>> pitchList = [P('C3'), P('B3')] >>> bc.getStemDirectionForPitches(pitchList) 'down' If `firstLastOnly` is True (as by default) then only the first and last pitches are examined, as in a beam group. Here we have C3, B3, C3, so despite the B in bass clef being much farther from the center line than either of the Cs, it is stem up: >>> pitchList.append(P('C3')) >>> bc.getStemDirectionForPitches(pitchList) 'up' If `firstLastOnly` is False, then each of the pitches has a weight on the process >>> bc.getStemDirectionForPitches(pitchList, firstLastOnly=False) 'down' If extremePitchOnly is True, then whatever pitch is farthest from the center line determines the direction, regardless of order. (default False). >>> bc.getStemDirectionForPitches(pitchList, extremePitchOnly=True) 'down' >>> pitchList.insert(1, P('C2')) >>> bc.getStemDirectionForPitches(pitchList, extremePitchOnly=True) 'up' z:getStemDirectionForPitches cannot operate on an empty listc|jSr,diatonicNoteNumpps rz1Clef.getStemDirectionForPitches.. R5G5Gr)keyc|jSr,r9r;s rr=z1Clef.getStemDirectionForPitches..r>rr/rdownup) isinstancer Pitch ValueErrorminmaxlenPercussionClef PitchClef lowestLineTREBLE_MID_LINE_DNNr:) r"pitchesr5r6 pitchListpitchMinpitchMaxrelevantPitches differenceSummidLinepdistanceFromMidLines rgetStemDirectionForPitcheszClef.getStemDirectionForPitchess\ gu{{ + IIYZ Z 9*GHH9*GHH'2O s9~1(|Yr];O'O d^Y7 8T__=Xoo)G)G A"#"3"3g"=  0 0M! A rreturnNonerZintr-r])rZstr)rOz#pitch.Pitch | Sequence[pitch.Pitch]r5boolr6r`rZr_)rrr__doc__equalityAttributesr__annotations__r TextStyle _styleClassclassSortOrderrr(propertyrsetterr3rX __classcell__r$s@rrr-s,Z:$ ' !I~ D//KN$ " "&&>#!& N2N N  N NrrcteZdZUdZddiZded<d fd Zed fd Zejd dZxZ S) rLzD Superclass for all other clef subclasses that use pitches. rMz The diatonicNoteNumber of the lowest line of the clef. (Can be `None`) >>> clef.TrebleClef().lowestLine 31 rrc 2t|di|d|_y)Nr)rrrMr!s rrzPitchClef.__init__s $8$!rct|S)a The number of octaves that the clef "transposes", generally 0. >>> tc = clef.TrebleClef() >>> tc.octaveChange 0 >>> clef.Treble8vbClef().octaveChange -1 Changing octaveChange changes lowestLine (but not vice versa) >>> tc.lowestLine 31 >>> tc.octaveChange = 1 >>> tc.lowestLine 38 >>> tc.octaveChange = -1 >>> tc.lowestLine 24 )rr)r"r$s rrzPitchClef.octaveChange#s,w##rcz|j}||_|j|xj||z dzz c_yy)N)r rM)r"r-oldOctaveChanges rrzPitchClef.octaveChange;s<,,% ?? & OO? :a? ?O 'rrYr\r^) rrrrarrcrrgrrhrirjs@rrLrLsU !I~"$$.@@rrLc2eZdZUdZiZded<fdZxZS)rKa represents a Percussion clef. >>> pc = clef.PercussionClef() >>> pc.sign 'percussion' >>> pc.line is None True Percussion clefs should not, technically have a "lowestLine," but it is a common usage to assume that in pitch-centric contexts to use the pitch numbers from treble clef for percussion clefs. Thus: >>> pc.lowestLine == clef.TrebleClef().lowestLine True * Changed in v7.3: setting `octaveChange` no longer affects `lowestLine`. rrc @t|di|d|_d|_y)N percussionrmr)rrrrMr!s rrzPercussionClef.__init__Ys! $8$  %rrrrrarrcrrirjs@rrKrKCs&!#I~"&&rrKc2eZdZUdZiZded<fdZxZS)NoClefz represents the absence of a Clef. >>> nc = clef.NoClef() >>> nc.sign 'none' Note that the sign is the string 'none' not the None object >>> nc.sign is None False rrc 2t|di|d|_y)Nnonerrrrr!s rrzNoClef.__init__ns $8$ rrurjs@rrwrw_s !#I~"rrwc"eZdZdZfdZxZS) JianpuClefz Jianpu notation does not use a clef, but musicxml marks it with a specialized "jianpu" sign. >>> jc = clef.JianpuClef() >>> jc.sign 'jianpu' c 2t|di|d|_y)Njianpurrzr!s rrzJianpuClef.__init__}s $8$ rrrrrarrirjs@rr|r|ssrr|c@eZdZdZfdZddd ddZxZS)TabClefz[ represents a Tablature clef. >>> a = clef.TabClef() >>> a.sign 'TAB' c @t|di|d|_d|_y)NTABr)rrrrr!s rrzTabClef.__init__s! $8$  rTFr4cy)zE Overridden to simply return 'down' for guitar tabs. rCr)r"rPr5r6s rrXz"TabClef.getStemDirectionForPitchessr)rPz#pitch.Pitch | Iterable[pitch.Pitch]r5r`r6r`rZr_)rrrrarrXrirjs@rrrs@#!& 4     rrc"eZdZdZfdZxZS)GClefz A generic G Clef >>> a = clef.GClef() >>> a.sign 'G' If not defined, the lowestLine is set as a Treble Clef (E4 = 31) >>> a.lowestLine 31 c 2t|di|d|_y)NGrrzr!s rrzGClef.__init__ $8$ rrrjs@rrrs rrc"eZdZdZfdZxZS)FrenchViolinClefz A G Clef that appears in many old French Violin scores, appearing on the lowest line, and thus higher than a treble clef. >>> a = clef.FrenchViolinClef() >>> a.sign 'G' >>> a.line 1 c @t|di|d|_d|_y)Nr/!rrrrrMr!s rrzFrenchViolinClef.__init__! $8$ %rrrjs@rrr &&rrc"eZdZdZfdZxZS) TrebleClefz The most common clef of all, a treble clef. >>> a = clef.TrebleClef() >>> a.sign 'G' >>> a.line 2 >>> a.lowestLine 31 >>> note.Note('E4').pitch.diatonicNoteNum 31 c @t|di|d|_d|_y)Nrmrrr!s rrzTrebleClef.__init__rrrrjs@rrrs &&rrc"eZdZdZfdZxZS) Treble8vbClefz A vocal tenor treble clef. Also for guitars. >>> a = clef.Treble8vbClef() >>> a.sign 'G' >>> a.octaveChange -1 c @t|di|d|_d|_y)NrArrrrrMr!s rrzTreble8vbClef.__init__s" $8$%rrrjs@rrr&&rrc"eZdZdZfdZxZS) Treble8vaClefz A treble clef an octave up (such as for piccolos) >>> a = clef.Treble8vaClef() >>> a.sign 'G' >>> a.octaveChange 1 c @t|di|d|_d|_y)Nr/rrrr!s rrzTreble8vaClef.__init__s" $8$%rrrjs@rrrrrrc"eZdZdZfdZxZS) GSopranoClefz A G clef on the middle line, formerly occasionally used for soprano parts. >>> a = clef.GSopranoClef() >>> a.sign 'G' >>> a.line 3 c @t|di|d|_d|_y)Nrrr!s rrzGSopranoClef.__init__rrrrjs@rrr &&rrc"eZdZdZfdZxZS)CClefz] A generic C Clef, with no line set >>> a = clef.CClef() >>> a.sign 'C' c 2t|di|d|_y)NCrrzr!s rrzCClef.__init__rrrrjs@rrrrrc"eZdZdZfdZxZS) SopranoClefz A soprano clef, with C on the lowest line (found in Bach often) >>> a = clef.SopranoClef() >>> a.sign 'C' >>> a.line 1 c @t|di|d|_d|_y)Nr/rrrr!s rrzSopranoClef.__init__*rrrrjs@rrrrrrc"eZdZdZfdZxZS)MezzoSopranoClefz A C clef with C on the second line. Perhaps the rarest of the C clefs >>> a = clef.MezzoSopranoClef() >>> a.sign 'C' >>> a.line 2 c @t|di|d|_d|_y)Nrrrr!s rrzMezzoSopranoClef.__init__<rrrrjs@rrr0rrrc"eZdZdZfdZxZS)AltoClefzs A C AltoClef, common for violas. >>> a = clef.AltoClef() >>> a.sign 'C' >>> a.line 3 c @t|di|d|_d|_y)Nrrrr!s rrzAltoClef.__init__Mrrrrjs@rrrBrrrc"eZdZdZfdZxZS) TenorClefz A C Tenor Clef, often used in bassoon and cello parts and orchestral trombone parts. >>> a = clef.TenorClef() >>> a.sign 'C' >>> a.line 4 c @t|di|d|_d|_y)NrBrrr!s rrzTenorClef.__init__`rrrrjs@rrrSrrrc"eZdZdZfdZxZS) CBaritoneClefz A Baritone C clef (as opposed to an F Baritone Clef) >>> a = clef.CBaritoneClef() >>> a.sign 'C' >>> a.line 5 c @t|di|d|_d|_y)Nrrrr!s rrzCBaritoneClef.__init__qrrrrjs@rrrfrrrc"eZdZdZfdZxZS)FClefz] A generic F-Clef, like a Bass clef >>> a = clef.FClef() >>> a.sign 'F' c 2t|di|d|_y)NFrrzr!s rrzFClef.__init__rrrrjs@rrrxrrrc"eZdZdZfdZxZS) FBaritoneClefz an F Baritone Clef >>> a = clef.FBaritoneClef() >>> a.sign 'F' >>> a.line 3 >>> b = clef.CBaritoneClef() >>> a.lowestLine == b.lowestLine True >>> a.sign == b.sign False c @t|di|d|_d|_y)Nrrrrr!s rrzFBaritoneClef.__init__rrrrjs@rrrs &&rrc"eZdZdZfdZxZS)BassClefzR A standard Bass Clef >>> a = clef.BassClef() >>> a.sign 'F' c @t|di|d|_d|_y)NrBrrr!s rrzBassClef.__init__rrrrjs@rrr&&rrc"eZdZdZfdZxZS) Bass8vbClefz A bass clef configured to be an octave lower. >>> a = clef.Bass8vbClef() >>> a.sign 'F' >>> a.octaveChange -1 c Nt|di|d|_d|_d|_y)NrBrArrrrrrrMr!s rrzBass8vbClef.__init__s) $8$ %rrrjs@rrrs&&rrc"eZdZdZfdZxZS) Bass8vaClefzj A rarely used Bass Clef an octave higher. >>> a = clef.Bass8vaClef() >>> a.sign 'F' c Nt|di|d|_d|_d|_y)NrBr/rrrr!s rrzBass8vaClef.__init__s) $8$ %rrrjs@rrrs&&rrc"eZdZdZfdZxZS) SubBassClefz[ An F clef on the top line. >>> a = clef.SubBassClef() >>> a.sign 'F' c @t|di|d|_d|_y)Nrrrr!s rrzSubBassClef.__init__rrrrjs@rrrrrr)rrrrz"dict[str, list[type[Clef] | None]]CLASS_FROM_TYPEc|j}|jdvrt|jdk(r tS|jdk(r tS|jdk(r t S|jdk(r t St |dk(r"|djt|d}}nt |dk(r.|dj}|d k(rd}n|d k(rd }n|d k(rd }nd}nt |dkDrddl m }|j}t|D]V}d|vr||jk7r|dz|jk7r2t||}t|tsO|cStd|ztd|dk7rA|||f} | dk(r t!S| dk(r t#S| dk(r t%S| dk(r t'S|dus|durtd|d|dks|dkDrtd||t(vrt(|} t| t*sJ| |R|d k(r t-} n:|d k(r t/} n*|d k(r t1} n|dk(r t} n t3} || _nK| |} t6j8r| Jt;| t2sJ| } nt3} || _|| _|dk7r|| _| S)aM Returns a Clef object given a string like "G2" or "F4" etc. Does not refer to a violin/guitar string. >>> tc = clef.clefFromString('G2') >>> tc >>> nonStandard1 = clef.clefFromString('F1') >>> nonStandard1 >>> nonStandard1.line 1 >>> nonStandard2 = clef.clefFromString('D4') >>> nonStandard2 >>> nonStandard2.sign 'D' >>> nonStandard2.line 4 >>> tc8vb = clef.clefFromString('G2', -1) >>> tc8vb Three special clefs, Tab, Percussion, and None are also supported. >>> tabClef = clef.clefFromString('TAB') >>> tabClef Case does not matter. >>> tc8vb = clef.clefFromString('g2', -1) >>> tc8vb >>> percussionClef = clef.clefFromString('Percussion') >>> percussionClef >>> noClef = clef.clefFromString('None') >>> noClef Invalid line numbers raise an exception: >>> invalidClef = clef.clefFromString('F6') Traceback (most recent call last): music21.clef.ClefException: line number (second character) must be 1-5; do not use this function for clefs on special staves such as 'F6' Can find any clef in the module >>> clef.clefFromString('Treble') >>> clef.clefFromString('trebleclef') >>> clef.clefFromString('treble8vb') )tabrtryr~rrtryr~rrr/rrrBrrF)r rr zCould not find clef z)Entry has clef info but no clef specified)rrrA)rrr/)rrBrA)rrBr/z cannot read z$ as clef str, should be G2, F4, etc.rziline number (second character) must be 1-5; do not use this function for clefs on special staves such as r) stripr1rrKrwr|rJupperr]music21r dirgetattrrEtyperrrrrrlistrrrrLrt TYPE_CHECKING issubclassrr) clefString octaveShiftxnStrthisTypelineNummyselfxnLowerxobjTypeparams line_listclefObjClefTypes rclefFromStringrs|    E {{}?? ;;=E !9  [[]l *!# # [[]f $8O [[]h &<  5zQ$Qx~~/U1X7 Uq8>># s?G _G _GG Ua*++-VAQ!'')#&(8AGGI(Efa(G'4(y 2U:;;GHHaG[1 \ ! ? " { " ? " | #= { "= 5Gu,l5'1UVWW{gkLLQ9VW W?"#H- )T*** W  %3'S'S'U"!)#+"GL )H+++!(I666jG+  a* Nrcd}d}d}|r|jn|j}|j}|D]#}|jD]} |dz }||| z }%|dk(rd} n||z } | dkDr t S|r| dkDr t S|s| dkDr t S|r| dkDr t S| d kDr tStS) aL Returns the clef that is the best fit for notes and chords found in this Stream. >>> import random >>> a = stream.Stream() >>> for x in range(30): ... n = note.Note() ... n.pitch.midi = random.randint(70, 81) ... a.insert(n) >>> b = clef.bestClef(a) >>> b >>> b.line 2 >>> b.sign 'G' >>> c = stream.Stream() >>> for x in range(10): ... n = note.Note() ... n.pitch.midi = random.randint(45, 54) ... c.insert(n) >>> d = clef.bestClef(c) >>> d >>> d.line 4 >>> d.sign 'F' This does not automatically get a flat representation of the Stream. There are a lot more high notes in `a` (30) than low notes in `c` (10), but it will not matter here, because the pitches in `a` will not be found: >>> c.insert(0, a) >>> clef.bestClef(c) But with recursion, it will matter: >>> clef.bestClef(c, recurse=True) Notes around middle C can get Treble8vb if the setting is allowed: >>> clef.bestClef(stream.Stream([note.Note('D4')])) >>> clef.bestClef(stream.Stream([note.Note('D4')]), allowTreble8vb=True) Streams of extremely high notes or extremely low notes can get Treble8va or Bass8vb clefs: >>> clef.bestClef(stream.Stream([note.Note('D7')])) >>> clef.bestClef(stream.Stream([note.Note('C0')])) cr|j}|jdkDr|dz }|S|jdkr|dz }|S)Nrrrr9)pInnerheights r findHeightzbestClef..findHeightsI''  ! !B & aKF  # #b ( bLF rrr/g=@1  ) recurseiter notesAndRestsrOrrrrr) streamObjallowTreble8vbrr totalPitches totalHeightsIternotesnrV averageHeights rbestClefr~s~LK#*I    0@E   E A A L :a= (Kq #l2 r MB.|   2| MB.  z}rceZdZdZy)Testc2ddlm}||ty)Nr) testCopyAll)music21.test.commonTestr globals)r"r s rtestCopyAndDeepcopyzTest.testCopyAndDeepcopys7D')$rN)rrrr rrrrrs%rr__main__)r)rZr)FF)rz stream.StreamrZrL)8ra __future__rcollections.abcrrtypingrunittestrrrrr r rr Environment environLocalrNMusic21Exceptionr Music21ObjectrrLrKrwr|rrrrrrrrrrrrrrrrrrrrrcrrTestCaser _DOC_ORDERrmainTestrrrrs? #. ??'{&&v.  L11 \4  \H/@/@d&T&8T(  i:I&&u&&&&*&J&"&J&"&5&( I &%&$&u&$&u&"&&&&E&$ I &E&, &u &&%&$ &% & &% &"  *lD$ G  -xM R dM8[ A $dD' 2 51Vt"d(dR%8  %J )  zGTr