rhqe %SrSSKJr SSKJrJr SSKrSSKrSSK J r SSK J r SSK J r SSK J r SS K Jr \R(aSS K Jr \ R""S 5r"S S \ R&5r"SS\ R*5r"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r"SS\5r"S S!\5r"S"S#\5r "S$S%\5r!"S&S'\5r""S(S)\"5r#"S*S+\"5r$"S,S-\"5r%"S.S/\"5r&"S0S1\"5r'"S2S3\5r("S4S5\(5r)"S6S7\(5r*"S8S9\(5r+"S:S;\(5r,"S<S=\(5r-S\\\!SS/S\#\$\%\&\'/SSS\)\*\-/SSSSS\/S>.r.S?\/S@'SFSGSAjjr0SHSISBjjr1"SCSD\Rd5r3\\\*/r4\5SE:XaSSK r \ Rl"\35 gg)Jz 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)streamclefc\rSrSrSrg) ClefException'N)__name__ __module__ __qualname____firstlineno____static_attributes__rF/home/james-whalen/.local/lib/python3.13/site-packages/music21/clef.pyrr'srrc^\rSrSr%SrSrSSS.rS\S'\Rr S r SU4S jjr S r \SS j5r\R SS j5r\SSj5rSSS.SSjjrSrU=r$)Clef,a 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 P>[TU]"S0UD6 SUlSUlSUlg)Nrr)super__init__rr _octaveChangeselfkeywords __class__s rr" Clef.__init__s) $8$" " "#rcg)Nrr%s r _reprInternalClef._reprInternalsrcUR$)z The number of octaves that the clef "transposes", generally 0. >>> tc = clef.TrebleClef() >>> tc.octaveChange 0 >>> clef.Treble8vbClef().octaveChange -1 r#r+s rrClef.octaveChanges!!!rcXlgNr/)r%newValues rrr0s%rcURRRSS5nU(aUSR5USS-$g)a 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 rname Clef.namesD,NN++33FB? Q<%%')AB-7 7rTF firstLastOnlyextremePitchOnlyc[U[R5(aU/nOUnU(d [S5eU(a[ USS9n[ USS9nXV/nO#U(a[ U5S:a USUS/nOUnSn[U[[45(aURbURS-n OS n UHn U RU - n X- nM US:ag g ) 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 listcUR$r2diatonicNoteNumpps r1Clef.getStemDirectionForPitches.. R5G5Gr)keycUR$r2r@rBs rrDrErFrr5r#downup) isinstancer Pitch ValueErrorminmaxlenPercussionClef PitchClef lowestLinerA) r%pitchesr<r= pitchListpitchMinpitchMaxrelevantPitches differenceSummidLinepdistanceFromMidLines rgetStemDirectionForPitchesClef.getStemDirectionForPitchess\ gu{{ + + IIYZ Z 9*GHH9*GHH'2O s9~1(|Yr];O'O d^Y7 8 8T__=Xoo)GG A"#"3"3g"=   0M! A r)r#rrreturnNonercintr3rf)rcstr)rWz#pitch.Pitch | Sequence[pitch.Pitch]r<boolr=rircrh)rrrr__doc__equalityAttributesr__annotations__r TextStyle _styleClassclassSortOrderr"r,propertyrsetterr9r`r __classcell__r's@rrr,s,Z:$ ' !I~ D//KN$ " "&&>#!& N2N N  N NNrrc^\rSrSr%SrSS0rS\S'S U4Sjjr\S U4Sjj5r \ RS S j5r S r U=r $)rUiz< Superclass for all other clef subclasses that use pitches. rVz The diatonicNoteNumber of the lowest line of the clef. (Can be `None`) >>> clef.TrebleClef().lowestLine 31 rrc 4>[TU]"S0UD6 SUlg)Nr)r!r"rVr$s rr"PitchClef.__init__s $8$!rc>[TU]$)aK 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 rrPitchClef.octaveChange"s,w##rcxURnXlURbU=RX- S-- slgg)Nr#rV)r%r3oldOctaveChanges rrry:s8,,% ?? & OO :a? ?O 'rr|rbrerg) rrrrrjrrlr"rprrqrrrrss@rrUrUsU !I~"$$.@@rrUc<^\rSrSr%Sr0rS\S'U4SjrSrU=r $)rTiBa 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 B>[TU]"S0UD6 SUlSUlg)N percussionrvr)r!r"rrVr$s rr"PercussionClef.__init__Ys! $8$  %r)rVr rrrrrjrrlr"rrrrss@rrTrTBs(!#I~"&&rrTc<^\rSrSr%Sr0rS\S'U4SjrSrU=r $)NoClefi_z 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 4>[TU]"S0UD6 SUlg)Nnonerr!r"rr$s rr"NoClef.__init__ns $8$ rrrrss@rrr_s !#I~"rrc,^\rSrSrSrU4SjrSrU=r$) JianpuClefisz Jianpu notation does not use a clef, but musicxml marks it with a specialized "jianpu" sign. >>> jc = clef.JianpuClef() >>> jc.sign 'jianpu' c 4>[TU]"S0UD6 SUlg)Njianpurrr$s rr"JianpuClef.__init__}s $8$ rrrrrrrjr"rrrrss@rrrssrrcN^\rSrSrSrU4SjrSSS.S SjjrSrU=r$) TabClefizG represents a Tablature clef. >>> a = clef.TabClef() >>> a.sign 'TAB' c B>[TU]"S0UD6 SUlSUlg)NTABr)r!r"rrr$s rr"TabClef.__init__s! $8$  rTFr;cg)z5 Overridden to simply return 'down' for guitar tabs. rLr)r%rXr<r=s rr`"TabClef.getStemDirectionForPitchessr)rr)rXz#pitch.Pitch | Iterable[pitch.Pitch]r<rir=rircrh) rrrrrjr"r`rrrrss@rrrsE#!& 4      rrc,^\rSrSrSrU4SjrSrU=r$)GClefiz 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 4>[TU]"S0UD6 SUlg)NGrrr$s rr"GClef.__init__ $8$ rrrrss@rrrs rrc,^\rSrSrSrU4SjrSrU=r$)FrenchViolinClefiz 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 B>[TU]"S0UD6 SUlSUlg)Nr5!rr!r"rrVr$s rr"FrenchViolinClef.__init__! $8$ %rrrVrrss@rrr &&rrc,^\rSrSrSrU4SjrSrU=r$) TrebleClefiz 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 B>[TU]"S0UD6 SUlSUlg)Nrvrrr$s rr"TrebleClef.__init__rrrrrss@rrrs &&rrc,^\rSrSrSrU4SjrSrU=r$) Treble8vbClefizq A vocal tenor treble clef. Also for guitars. >>> a = clef.Treble8vbClef() >>> a.sign 'G' >>> a.octaveChange -1 c B>[TU]"S0UD6 SUlSUlg)NrIrr!r"rrVr$s rr"Treble8vbClef.__init__s" $8$%rrVrrrss@rrr&&rrc,^\rSrSrSrU4SjrSrU=r$) Treble8vaClefizu A treble clef an octave up (such as for piccolos) >>> a = clef.Treble8vaClef() >>> a.sign 'G' >>> a.octaveChange 1 c B>[TU]"S0UD6 SUlSUlg)Nr5rrrr$s rr"Treble8vaClef.__init__s" $8$%rrrrss@rrrrrrc,^\rSrSrSrU4SjrSrU=r$) GSopranoClefiz A G clef on the middle line, formerly occasionally used for soprano parts. >>> a = clef.GSopranoClef() >>> a.sign 'G' >>> a.line 3 c B>[TU]"S0UD6 SUlSUlg)Nrrr$s rr"GSopranoClef.__init__rrrrrss@rrr &&rrc,^\rSrSrSrU4SjrSrU=r$)CClefizI A generic C Clef, with no line set >>> a = clef.CClef() >>> a.sign 'C' c 4>[TU]"S0UD6 SUlg)NCrrr$s rr"CClef.__init__rrrrrss@rrrrrc,^\rSrSrSrU4SjrSrU=r$) SopranoClefizy A soprano clef, with C on the lowest line (found in Bach often) >>> a = clef.SopranoClef() >>> a.sign 'C' >>> a.line 1 c B>[TU]"S0UD6 SUlSUlg)Nr5rrrr$s rr"SopranoClef.__init__*rrrrrss@rrrrrrc,^\rSrSrSrU4SjrSrU=r$)MezzoSopranoClefi0z 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 B>[TU]"S0UD6 SUlSUlg)Nrrrr$s rr"MezzoSopranoClef.__init__<rrrrrss@rrr0rrrc,^\rSrSrSrU4SjrSrU=r$)AltoClefiBzW A C AltoClef, common for violas. >>> a = clef.AltoClef() >>> a.sign 'C' >>> a.line 3 c B>[TU]"S0UD6 SUlSUlg)Nrrrr$s rr"AltoClef.__init__Mrrrrrss@rrrBrrrc,^\rSrSrSrU4SjrSrU=r$) TenorClefiSz 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 B>[TU]"S0UD6 SUlSUlg)NrJrrr$s rr"TenorClef.__init__`rrrrrss@rrrSrrrc,^\rSrSrSrU4SjrSrU=r$) CBaritoneClefifzp A Baritone C clef (as opposed to an F Baritone Clef) >>> a = clef.CBaritoneClef() >>> a.sign 'C' >>> a.line 5 c B>[TU]"S0UD6 SUlSUlg)Nrrrr$s rr"CBaritoneClef.__init__qrrrrrss@rrrfrrrc,^\rSrSrSrU4SjrSrU=r$)FClefixzI A generic F-Clef, like a Bass clef >>> a = clef.FClef() >>> a.sign 'F' c 4>[TU]"S0UD6 SUlg)NFrrr$s rr"FClef.__init__rrrrrss@rrrxrrrc,^\rSrSrSrU4SjrSrU=r$) FBaritoneClefiz 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 B>[TU]"S0UD6 SUlSUlg)Nrrrrr$s rr"FBaritoneClef.__init__rrrrrss@rrrs &&rrc,^\rSrSrSrU4SjrSrU=r$)BassClefiz> A standard Bass Clef >>> a = clef.BassClef() >>> a.sign 'F' c B>[TU]"S0UD6 SUlSUlg)NrJrrr$s rr"BassClef.__init__rrrrrss@rrr&&rrc,^\rSrSrSrU4SjrSrU=r$) Bass8vbClefizp A bass clef configured to be an octave lower. >>> a = clef.Bass8vbClef() >>> a.sign 'F' >>> a.octaveChange -1 c P>[TU]"S0UD6 SUlSUlSUlg)NrJrIrrr!r"rrrVr$s rr"Bass8vbClef.__init__s) $8$ %rrrVrrrss@rrrs&&rrc,^\rSrSrSrU4SjrSrU=r$) Bass8vaClefizV A rarely used Bass Clef an octave higher. >>> a = clef.Bass8vaClef() >>> a.sign 'F' c P>[TU]"S0UD6 SUlSUlSUlg)NrJr5rrrr$s rr"Bass8vaClef.__init__s) $8$ %rrrrss@rrrs&&rrc,^\rSrSrSrU4SjrSrU=r$) SubBassClefizG An F clef on the top line. >>> a = clef.SubBassClef() >>> a.sign 'F' c B>[TU]"S0UD6 SUlSUlg)Nrrrr$s rr"SubBassClef.__init__rrrrrss@rrrrrr)rrrrz"dict[str, list[type[Clef] | None]]CLASS_FROM_TYPEc@UR5nUR5S;axUR5S:Xa [5$UR5S:Xa [5$UR5S:Xa [ 5$UR5S:Xa [ 5$[ U5S:Xa!USR5[US5pCO[ U5S:Xa1USR5nUS :XaSnOUS :XaS nOUS :XaS nOSnO[ U5S:aSSK J n UR5n[U5H`nSU;aM XgR5:waUS-UR5:waM7[XW5n[U[5(dMYU"5s $ [SU-5e[S5eUS:waDX4U4n U S:Xa [!5$U S:Xa [#5$U S:Xa [%5$U S:Xa ['5$USLdUSLa[SUS35eUS:dUS:a[SSU<3-5eU[(;a[(Un [U [*5(deXcUUS :Xa [-5n O=US :Xa [/5n O,US :Xa [15n OUS:Xa [5n O [35n XKlOSXn [6R8(aU ce[;U [25(deU "5n O[35n X;lXKlUS:waXlU $)a 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') )tabrrrrrrrrrr5rrrJrrF)r rr zCould not find clef z)Entry has clef info but no clef specified)rrrI)rrr5)rrJrI)rrJr5z cannot read z$ as clef str, should be G2, F4, etc.rz># s?G _G _GG Ua*++-VAQ'')#&(8AGGI(Ef(G'4((y 2U:;;GHHa[1 \ ! ? " { " ? " | #= { "= 5Gu,l5'1UVWW{gkZ MeYWXY Y?"#H- )T****   %3'S'S'U"!)#+"L )H+++!(I6666jG+  a* NrchSnSnSnU(aUR5OUR5nURnUHwnUR(aMUR(aUS- nXS"UR 5- nMBUR (dMUURHn US- nXS"U 5- nM My US:XaSn OXT- n U S:a [5$U(aU S:a [5$U(dU S:a [5$U(aU S:a [5$U S :a [5$[5$) a 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')])) cvURnURS:aUS- nU$URS:aUS- nU$)Nrrrr@)pInnerheights r findHeightbestClef..findHeightsI''  ! !B & aKF  # #b ( bLF rrr5g=@1  ) recurseiter notesAndRestsisRestisNoter isChordrWrrrrr) streamObjallowTreble8vbr"r totalNotes totalHeightsIternotesnr^ averageHeights rbestClefr0s@JK#*I    0@E   E  88  XX !OJ :agg. .K YYYYYa z!}, Q #0 r MB.|   2| MB.  z}rc\rSrSrSrSrg)Testic2SSKJn U"U[55 g)Nr) testCopyAll)music21.test.commonTestr4globals)r%r4s rtestCopyAndDeepcopyTest.testCopyAndDeepcopys7D')$rrN)rrrrr7rrrrr2r2s%rr2__main__)r)rcr)FF)r(z stream.StreamrcrU)7rj __future__rcollections.abcrrtypingrunittestrrrrr r rr Environment environLocalMusic21Exceptionr Music21ObjectrrUrTrrrrrrrrrrrrrrrrrrrrrrrlrr0TestCaser2 _DOC_ORDERrmainTestrrrrEs5 #. ??&&v.  L11 \4  \H/@/@d&T&:T(  i:I&&u&&&&*&J&"&J&"&5&( I &%&$&u&$&u&"&&&&E&$ I &E&, &u &&%&$ &% & &% &"  *lD$ G  -xM R dM8[ A $dD' 2 51Yz"k(k`%8  %J )  z Tr