jd JUdZddlmZddlmZmZddlZddlZddl m Z ddl m Z ddl m Z ddl m Z dd l mZejrdd l mZe jd Zd ZGd de jZGdde jZGddeZGddeZGddeZGddeZGddeZGddeZGddeZGdd 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<dKdLdCZ1 dMdNdGZ2GdHdIej3Z4eee+gZ5e6dJkrddl Z e j7e4dSdS)Oz 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#ceZdZdS) ClefExceptionN)__name__ __module__ __qualname__/Users/tedpeters/Documents/Projects/Claude Projects/Misc Tools/notename-sheets/.venv/lib/python3.11/site-packages/music21/clef.pyrr(sDrrceZdZUdZdZdddZded<ejZ dZ dfd Z d Z e ddZejddZe ddZdddd dZxZS)!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_ATTRrreturnNonec dtjdi|d|_d|_d|_dS)Nrr)super__init__rr _octaveChangeselfkeywords __class__s rr!z Clef.__init__s<$$8$$$" " "#rcdS)Nrr$s r _reprInternalzClef._reprInternalsrrintc|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 !!rnewValuec||_dSNr-)r$r.s rrzClef.octaveChanges%rstrc|jjdd}|r%|d|ddzSdS)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.namesN,N+33FB??  Q<%%'')ABB-7 72rTF firstLastOnlyextremePitchOnlypitches#pitch.Pitch | Sequence[pitch.Pitch]r9boolr:ct|tjr|g}n|}|std|r)t |d}t |d}||g}n(|r$t |dkr|d|dg}n|}d}t|ttfr|j |j d z} nt} |D]} | j | z } || z }|dkrd Sd S) 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|jSr0diatonicNoteNumpps rz1Clef.getStemDirectionForPitches.. R5Gr)keyc|jSr0r@rBs rrDz1Clef.getStemDirectionForPitches..rErr3rNdownup) isinstancer Pitch ValueErrorminmaxlenPercussionClef PitchClef lowestLineTREBLE_MID_LINE_DNNrA) r$r;r9r: pitchListpitchMinpitchMaxrelevantPitches differenceSummidLinepdistanceFromMidLines rgetStemDirectionForPitcheszClef.getStemDirectionForPitchess'\ gu{ + +  III [YZZ Z  (9*G*GHHHH9*G*GHHHH'2OO  (s9~~11(|Yr];OO'O d^Y7 8 8 *T_=Xo)GG)G  1 1A"#"3g"=  0 0MM A  64rrrrr+r.r+)rr1)r;r<r9r=r:r=rr1)rrr__doc__equalityAttributesr__annotations__r TextStyle _styleClassclassSortOrderr!r*propertyrsetterr7r^ __classcell__r&s@rrr-s.,,Z:$ ' ! !I    D/KN$$$$$$ " " "X "&&&&X>#!& NNNNNNNNNNrrcveZdZUdZddiZded<d fd Zedfd Zej dd ZxZ S)rSzD Superclass for all other clef subclasses that use pitches. rTz The diatonicNoteNumber of the lowest line of the clef. (Can be `None`) >>> clef.TrebleClef().lowestLine 31 rrrrc Htjdi|d|_dS)Nr)r r!rTr#s rr!zPitchClef.__init__s+$$8$$$!rr+c*tjS)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 )r r)r$r&s rrzPitchClef.octaveChange#s,ww##rr.c`|j}||_|j|xj||z dzz c_dSdS)N)r"rT)r$r.oldOctaveChanges rrzPitchClef.octaveChange;s@,% ? & OO? :a? ?OOOO ' &rr_r`ra) rrrrbrrdr!rhrrirjrks@rrSrSs !I""""""$$$$$X$.@@@@@@@@rrSc2eZdZUdZiZded<fdZxZS)rRa 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 Vtjdi|d|_d|_dS)N percussionrnr)r r!rrTr#s rr!zPercussionClef.__init__Ys2$$8$$$  %rrrrrbrrdr!rjrks@rrRrRCsW&!#I""""&&&&&&&&&rrRc2eZdZUdZiZded<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 Htjdi|d|_dS)Nnonerr r!rr#s rr!zNoClef.__init__ns+$$8$$$ rrvrks@rrxrx_sW  !#I""""rrxc"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 Htjdi|d|_dS)Njianpurr{r#s rr!zJianpuClef.__init__}s+$$8$$$ rrrrrbr!rjrks@rr}r}ssBrr}c2eZdZdZfdZddddd ZxZS)TabClefz[ represents a Tablature clef. >>> a = clef.TabClef() >>> a.sign 'TAB' c Vtjdi|d|_d|_dS)NTABr)r r!rrr#s rr!zTabClef.__init__s2$$8$$$  rTFr8rV#pitch.Pitch | Iterable[pitch.Pitch]r9r=r:rr1cdS)zE Overridden to simply return 'down' for guitar tabs. rJr)r$rVr9r:s rr^z"TabClef.getStemDirectionForPitchess vr)rVrr9r=r:r=rr1)rrrrbr!r^rjrks@rrrsh#!&          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 Htjdi|d|_dS)NGrr{r#s rr!zGClef.__init__+$$8$$$ rrrks@rrrsB  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 Vtjdi|d|_d|_dS)Nr3!rr r!rrTr#s rr!zFrenchViolinClef.__init__2$$8$$$ %rrrks@rrrB  &&&&&&&&&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 Vtjdi|d|_d|_dS)Nrnrrr#s rr!zTrebleClef.__init__rrrrks@rrrsB  &&&&&&&&&rrc"eZdZdZfdZxZS) Treble8vbClefz A vocal tenor treble clef. Also for guitars. >>> a = clef.Treble8vbClef() >>> a.sign 'G' >>> a.octaveChange -1 c Vtjdi|d|_d|_dS)NrHrr r!rrTr#s rr!zTreble8vbClef.__init__s3$$8$$$%rrrks@rrrB&&&&&&&&&rrc"eZdZdZfdZxZS) Treble8vaClefz A treble clef an octave up (such as for piccolos) >>> a = clef.Treble8vaClef() >>> a.sign 'G' >>> a.octaveChange 1 c Vtjdi|d|_d|_dS)Nr3rrrr#s rr!zTreble8vaClef.__init__s3$$8$$$%rrrks@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 Vtjdi|d|_d|_dS)Nrrr#s rr!zGSopranoClef.__init__rrrrks@rrrB  &&&&&&&&&rrc"eZdZdZfdZxZS)CClefz] A generic C Clef, with no line set >>> a = clef.CClef() >>> a.sign 'C' c Htjdi|d|_dS)NCrr{r#s rr!zCClef.__init__rrrrks@rrrBrrc"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 Vtjdi|d|_d|_dS)Nr3rrrr#s rr!zSopranoClef.__init__*rrrrks@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 Vtjdi|d|_d|_dS)Nrrrr#s rr!zMezzoSopranoClef.__init__<rrrrks@rrr0rrrc"eZdZdZfdZxZS)AltoClefzs A C AltoClef, common for violas. >>> a = clef.AltoClef() >>> a.sign 'C' >>> a.line 3 c Vtjdi|d|_d|_dS)Nrrrr#s rr!zAltoClef.__init__Mrrrrks@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 Vtjdi|d|_d|_dS)NrIrrr#s rr!zTenorClef.__init__`rrrrks@rrrSrrrc"eZdZdZfdZxZS) CBaritoneClefz A Baritone C clef (as opposed to an F Baritone Clef) >>> a = clef.CBaritoneClef() >>> a.sign 'C' >>> a.line 5 c Vtjdi|d|_d|_dS)Nrrrr#s rr!zCBaritoneClef.__init__qrrrrks@rrrfrrrc"eZdZdZfdZxZS)FClefz] A generic F-Clef, like a Bass clef >>> a = clef.FClef() >>> a.sign 'F' c Htjdi|d|_dS)NFrr{r#s rr!zFClef.__init__rrrrks@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 Vtjdi|d|_d|_dS)Nrrrrr#s rr!zFBaritoneClef.__init__rrrrks@rrrsB  &&&&&&&&&rrc"eZdZdZfdZxZS)BassClefzR A standard Bass Clef >>> a = clef.BassClef() >>> a.sign 'F' c Vtjdi|d|_d|_dS)NrIrrr#s rr!zBassClef.__init__rrrrks@rrrB&&&&&&&&&rrc"eZdZdZfdZxZS) Bass8vbClefz A bass clef configured to be an octave lower. >>> a = clef.Bass8vbClef() >>> a.sign 'F' >>> a.octaveChange -1 c dtjdi|d|_d|_d|_dS)NrIrHrrr r!rrrTr#s rr!zBass8vbClef.__init__s:$$8$$$ %rrrks@rrrsB&&&&&&&&&rrc"eZdZdZfdZxZS) Bass8vaClefzj A rarely used Bass Clef an octave higher. >>> a = clef.Bass8vaClef() >>> a.sign 'F' c dtjdi|d|_d|_d|_dS)NrIr3rrrr#s rr!zBass8vaClef.__init__s:$$8$$$ %rrrks@rrrsB&&&&&&&&&rrc"eZdZdZfdZxZS) SubBassClefz[ An F clef on the top line. >>> a = clef.SubBassClef() >>> a.sign 'F' c Vtjdi|d|_d|_dS)Nrrrr#s rr!zSubBassClef.__init__rrrrks@rrrrrr)rrrrz"dict[str, list[type[Clef] | None]]CLASS_FROM_TYPErch|}|dvr|dkrtS|dkrtS|dkrt S|dkrt St |dkr1|dt|d}}nt |dkr8|d}|d krd}n|d krd }n|d krd }nd}nt |dkrddl m }|}t|D]l}d|vr||kr|dz|kr;t||}t|tr |cSmtd|ztd|dkrU|||f} | dkrt!S| dkrt#S| dkrt%S| dkrt'S|dus|durtd|d|dks|dkrtd||t(vrt(|} t| t*sJ| |j|d krt-} nM|d krt/} n8|d krt1} n#|dkrt} nt3} || _nV| |} t6jr| Jt;| t2sJ| } nt3} || _|| _|dkr|| _| 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') )tabrurzrrrurzrrrr3rrrIrrF)r rr zCould not find clef z)Entry has clef info but no clef specified)rrrH)rrr3)rrIrH)rrIr3z 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 Nr) stripr5rrRrxr}rQupperr+music21r dirgetattrrLtyperrrrrrlistrrrrSrt TYPE_CHECKING issubclassrr) clefString octaveShiftxnStrthisTypelineNummyselfxnLowerxobjTypeparams line_listclefObjClefTypes rclefFromStringrs|     E {{}}??? ;;==E ! !99  [[]]l * *!## # [[]]f $ $88O [[]]h & &<<  5zzQ$Qx~~//U1X7 Uq8>>## s??GG __GG __GGGG Ua******++--V ! !AQ!''))##&(8AGGII(E(Efa((G'4(( !wyy    !2U:;;;GHHHaG[1 \ ! ! ?? " { " " ?? " | # #== { " "== 5Gu,,V5VVVWWW{{gkkVLQVVWW W?""#H- )T***** W  %3''S''S''U""!))#++"GLL )H 7+++!(I66666hjjGG++  a* NrF streamObj stream.Streamcd}d}d}|r|n|}|j}|D]}|jD]} |dz }||| z } |dkrd} n||z } | dkrt S|r| dkrt S|s| dkrt S|r| dkrt S| d krtStS) 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')])) cV|j}|jdkr|dz }n|jdkr|dz }|S)Nrrrr@)pInnerheights r findHeightzbestClef..findHeights?'  !B & & aKFF  #b ( ( bLF rrr3g=@1  ) recurseiter notesAndRestsr;rrrrr) rallowTreble8vbrr totalPitches totalHeightsIternotesnr\ averageHeights rbestClefr~s6~LK#* @I      0@0@E  E )) ) )A A L ::a== (KK )q #l2 r  MB..||   2 2|| MB..   zz}}rceZdZdZdS)TestcBddlm}||tdS)Nr) testCopyAll)music21.test.commonTestr globals)r$r s rtestCopyAndDeepcopyzTest.testCopyAndDeepcopys0777777 D'))$$$$$rN)rrrrrrrr r s#%%%%%rr __main__)r)rr)FF)rrrrS)8rb __future__rcollections.abcrrtypingrunittestrrrrr r rr Environment environLocalrUMusic21Exceptionr Music21ObjectrrSrRrxr}rrrrrrrrrrrrrrrrrrrrrdrrTestCaser  _DOC_ORDERrmainTestrrrrs5 #"""""........ ?'{&v..      L1   \\\\\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 55VVVVVt"dddddR%%%%%8 %%%J )  zNNNGTr