rhPSrSSKJr SSKrSSKJr SSKrSSKrSSK J r SSK J r SSK J r \R(a SSK Jr SS K Jr \ R""S 5r"S S \ R&5r"S S5r"SS\5r"SS\5r"SS\R05r\S:XaSSK r \ R6"\5 gg)za Tools for grouping notes and chords into a searchable tree organized by start and stop offsets. ) annotationsN)inf) OffsetQLIn) environment) exceptions21)basestreamz tree.spansc\rSrSrSrg)TimespanException$N__name__ __module__ __qualname____firstlineno____static_attributes__rL/home/james-whalen/.local/lib/python3.13/site-packages/music21/tree/spans.pyr r $rr cp\rSrSrSr\*\4SjrSrSr\ S5r \ S5r SS jr S r S rS rS rg)Timespan*a A span of time, with a start offset and stop offset. Useful for demonstrating various properties of the timespan-collection class family. >>> timespan = tree.spans.Timespan(-1.5, 3.25) >>> print(timespan) A timespan has two attributes, its offset and its endTime. They are immutable. >>> timespan.offset -1.5 >>> timespan.endTime 3.25 To create a changed timespan, call the .new() method on the timespan. >>> ts2 = timespan.new(offset=0.0) >>> ts2 >>> ts3 = timespan.new(endTime=5.0) >>> ts3 Two timespans are equal if they have the same offset and endTime >>> ts4 = tree.spans.Timespan(-1.5, 5.0) >>> ts3 == ts4 True >>> ts4 == ts2 False cUb [U5nXlUb [U5nX lUbUbX:a[SU<SU<35eggg)Noffset z must be after endTime )float_offset_endTimer selfoffsetendTimes r__init__Timespan.__init__Osc  6]F  GnG  '"5''&;RSZR](^__ #6 rc[U5[U5La5URUR:XaURUR:Xagg)NTF)typer"r#)r!exprs r__eq__Timespan.__eq__Zs8 :d #{{dkk)<<4<</rcl[U5RnSUSURSURS3$)N< >)r'rr"r#r!typeNames r__repr__Timespan.__repr__as4:&&8*Adkk]!DLL>;;rcUR$)a The start offset of the Timespan, relative to its containing score. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> verticality = scoreTree.getVerticalityAt(1.0) >>> timespan = verticality.startTimespans[0] >>> timespan.offset 1.0 )rr!s rr"Timespan.offsetes||rcUR$)a The stop offset of the Timespan, relative to its containing score. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> verticality = scoreTree.getVerticalityAt(1.0) >>> timespan = verticality.startTimespans[0] >>> timespan.endTime 2.0 )rr4s rr#Timespan.endTimeus}}rNc\Uc URnUc URn[U5"XS9$)z7 return a new object with the given offset and endTime r"r#)r"r#r'r s rnew Timespan.news/ >[[F ?llGDz99rc[U[U55(d SUSUS3nSU4$URUR:Xd'URUR:Xd SUSUS3nSU4$g)a< returns a tuple of (True or False) if these timespans can be merged with the second element being a message or None. >>> ts1 = tree.spans.Timespan(0, 5) >>> ts2 = tree.spans.Timespan(5, 7) >>> ts1.canMerge(ts2) (True, '') >>> ts3 = tree.spans.Timespan(6, 10) >>> ts1.canMerge(ts3) (False, 'Cannot merge with : not contiguous') Overlapping Timespans cannot be merged, just contiguous ones. >>> ts4 = tree.spans.Timespan(3, 4) >>> ts1.canMerge(ts4) (False, 'Cannot merge with : not contiguous') Cannot merge  with z : wrong typesFz: not contiguous)T) isinstancer'r#r")r!othermessages rcanMergeTimespan.canMergesw&%d,,%dV6% FG7# #-MMT[[0%dV6%8HIG7# #rcURU5up#USLa [U5eURUR:aURURS9nU$URURS9nU$)a Merges two consecutive/contiguous timespans, keeping the information from the former of the two. >>> ts1 = tree.spans.Timespan(0, 5) >>> ts2 = tree.spans.Timespan(5, 7) >>> ts3 = ts1.mergeWith(ts2) >>> ts3 Note that (for now), overlapping timespans cannot be merged: >>> ts4 = tree.spans.Timespan(6, 10) >>> ts3.mergeWith(ts4) Traceback (most recent call last): music21.tree.spans.TimespanException: Cannot merge with : not contiguous Fr#)rCr r"r:r#)r!rAcanrBmergedTimespans r mergeWithTimespan.mergeWithsn&}}U+  %<#G, , ;; %!XXemmX>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> verticality = scoreTree.getVerticalityAt(0) >>> verticality >>> timespan = verticality.startTimespans[0] >>> timespan > >>> for shard in timespan.splitAt(0.25): ... shard ... > > >>> timespan.splitAt(1000) (>,) rF)r")r"r#r:)r!r"leftrights rsplitAtTimespan.splitAtsH0 KK 4<<7Nxxx''{r)rr)NN)rrrr__doc__rr$r)r1propertyr"r#r:rCrIrNrrrrrr*s]"H #dC `<     :8:rrc^\rSrSr%SrSS0rS\S'SSU4SjjjrSrS r \ S 5r SS jr \ S 5r S r\ S5rSSSjjrSrU=r$)ElementTimespana A span of time anchored to an element in a score. The span of time may be the same length as the element in the score. It may be shorter (a "slice" of an element) or it may be longer (in the case of a timespan that is anchored to a single element but extends over rests or other notes following a note) PitchedTimespans give information about an element (such as a Note). It knows its absolute position with respect to the element passed into TimespanTree. It contains information about what measure it's in, what part it's in, etc. Example, getting a passing tone from a known location from a Bach chorale. First we create an Offset tree: >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> scoreTree > Then get the verticality from offset 6.5, which is beat two-and-a-half of measure 2 (the piece is in 4/4 with a quarter-note pickup) >>> verticality = scoreTree.getVerticalityAt(6.5) >>> verticality There are four PitchedTimespans in the verticality -- each representing a note. The notes are arranged from lowest to highest. We can find all the PitchedTimespans that start exactly at 6.5. There's one. >>> verticality.startTimespans (>,) >>> pitchedTimespan = verticality.startTimespans[0] >>> pitchedTimespan > What can we do with a PitchedTimespan? We can get its Part object and from there the Part object name >>> pitchedTimespan.part >>> pitchedTimespan.part.partName 'Tenor' Find out what measure it's in: >>> pitchedTimespan.measureNumber 2 >>> pitchedTimespan.parentOffset 5.0 The position in the measure is given by subtracting that from the .offset: >>> pitchedTimespan.offset - pitchedTimespan.parentOffset 1.5 >>> pitchedTimespan.element These are not dynamic, so changing the Score object does not change the measureNumber, etc. parentageau The Stream hierarchy above the element in a ElementTimespan. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> verticality = scoreTree.getVerticalityAt(1.0) >>> pitchedTimespan = verticality.startTimespans[0] >>> pitchedTimespan > >>> for streamSite in pitchedTimespan.parentage: ... streamSite zdict[str, str] _DOC_ATTRc>[TU]XVS9 XlX@lUb [ U5nX lUb [ U5nX0lUbUbX#:a[SU<SU<35eggg)Nr9rz must be after parentEndTime )superr$elementrUr parentOffset parentEndTimer r!rYrZr[rUr"r# __class__s rr$ElementTimespan.__init__Es 807 "  # .L(  $!-0M*  # (A+'l--J=J[\^^,)B #rcXL$)Nr)r!rAs rr)ElementTimespan.__eq__^s }rc [U5RnSUSURSURSUR<S3 $)Nr,z (z to z) r.)r'rr"r#rYr/s rr1ElementTimespan.__repr__as?:&&8*Bt{{m4 ~R ?OqQQrc4URUR- $)a  The quarterLength of the Timespan, which, due to manipulation, may be different from that of the element. >>> n = note.Note('D-') >>> n.offset = 1.0 >>> n.duration.quarterLength = 2.0 >>> pts = tree.spans.PitchedTimespan(n, offset=n.offset, endTime=3.0) >>> pts > >>> pts.quarterLength 2.0 >>> n.duration.quarterLength 2.0 >>> pts2 = pts.new(offset=0.0) >>> pts2 > >>> pts2.quarterLength 3.0 >>> pts2.element.duration.quarterLength 2.0 )r#r"r4s r quarterLengthElementTimespan.quarterLengthgs4||dkk))rc U=(d URnUc URnUc URnUc URnUc URn[ U5"UUUUR UUS9$)a Create a new object that is identical to the calling object but with some parameters overridden. >>> n = note.Note('C#') >>> pts = tree.spans.PitchedTimespan(n, offset=11.0, endTime=12.0) >>> pts > >>> pts2 = pts.new(endTime=13.0) >>> pts2 > >>> pts.element is pts2.element True rYrZr[rUr"r#)rYrZr[r"r#r'rU)r!rYrZr[r"r#s rr:ElementTimespan.newsw*)T\\  ,,L   ..M >[[F ?llGDz%'nn   rc.URR$)a The measure number of the measure containing the element. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> verticality = scoreTree.getVerticalityAt(1.0) >>> pitchedTimespan = verticality.startTimespans[0] >>> pitchedTimespan.measureNumber 1 )rY measureNumberr4s rrjElementTimespan.measureNumbers||)))rcRURHn[X!5(dMUs $ g)a returns that is the first parentage that has this classList. default stream.Part >>> score = corpus.parse('bwv66.6') >>> score.id = 'bach' >>> scoreTree = score.asTimespans() >>> verticality = scoreTree.getVerticalityAt(1.0) >>> pitchedTimespan = verticality.startTimespans[2] >>> pitchedTimespan > >>> pitchedTimespan.getParentageByClass(classList=(stream.Part,)) >>> pitchedTimespan.getParentageByClass(classList=(stream.Measure,)) >>> pitchedTimespan.getParentageByClass(classList=(stream.Score,)) The closest parent is returned in case of a multiple list: >>> searchTuple = (stream.Voice, stream.Measure, stream.Part) >>> pitchedTimespan.getParentageByClass(classList=searchTuple) TODO: this should take a normal class list. N)rUr@)r! classListparents rgetParentageByClass#ElementTimespan.getParentageByClasss'6nnF&,, %rcBSSKJn URUR4S9$)ag find the object in the parentage that is a Part object: >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> verticality = scoreTree.getVerticalityAt(1.0) >>> pitchedTimespan = verticality.startTimespans[2] >>> pitchedTimespan > >>> pitchedTimespan.part rr )rm)music21r roPart)r!r s rpartElementTimespan.parts! #''6;;.'AArcURnUcgU(a9Un[R"U5nX2RlSURlUR URlU$)z~ Return a copy of the element (or the same one if makeCopy is False) with the quarterLength set to the length of the timespan Nzspans.makeElement)rYcopydeepcopy derivationoriginmethodrdduration)r!makeCopyelel_olds r makeElementElementTimespan.makeElementsX \\ : Fv&B#)MM #6BMM $($6$6 ! r)rYr[rZrU)NNNrNN) rYbase.Music21Object | NonerZOffsetQLIn | Noner[rrUztuple[stream.Stream, ...]r"rr#r)NNNNN)T)r}boolreturnr)rrrrrPrV__annotations__r$r)r1rQrdr:rjrortrr __classcell__r]s@rrSrSsCN !I~,,0(,)-/1"&#'^(^&^' ^ - ^  ^!^^2R **< & T * *&@BB rrScT^\rSrSrSU4Sjjr\S5rU4SjrSrU=r $)PitchedTimespani c *>[TU]UUUUUUS9 g)Nrg)rXr$r\s rr$PitchedTimespan.__init__ s( &2'4#, &!(  *rc.URR$)aI Gets the pitches of the element wrapped by this PitchedTimespan. >>> c = chord.Chord('C4 E4 G4') >>> pts = tree.spans.PitchedTimespan(c, offset=0.0, endTime=1.0) >>> pts.pitches (, , ) >>> pts.pitches == c.pitches True >>> pts.pitches is c.pitches False )rYpitchesr4s rrPitchedTimespan.pitchess||###rc>[TU]U5up#USLa%URUR:wa SUSUS3nSnX#4$)a sub-method of base canMerge that checks to see if the pitches are the same. For quick score reductions, we can merge two consecutive like-pitched element timespans, keeping score-relevant information from the first of the two, such as its Music21 Element. This is useful when using timespans to perform score reduction. Let's demonstrate merging some contiguous E's in the alto part of a Bach chorale: >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> timespan_one = scoreTree[12] >>> print(timespan_one) > >>> print(timespan_one.part) >>> timespan_two = scoreTree.findNextPitchedTimespanInSameStreamByClass(timespan_one) >>> print(timespan_two) > >>> timespan_one.canMerge(timespan_two) (True, '') >>> merged = timespan_one.mergeWith(timespan_two) >>> print(merged) > >>> merged.part is timespan_one.part True Attempting to merge timespans which are not contiguous, or which do not have identical pitches will result in error: >>> scoreTree[0].canMerge(scoreTree[50]) (False, 'Cannot merge > with >: not contiguous') >>> scoreTree[0].mergeWith(scoreTree[50]) Traceback (most recent call last): music21.tree.spans.TimespanException: Cannot merge > with >: not contiguous This is probably not what you want to do: get the next element timespan in the same score: >>> timespan_twoWrong = scoreTree.findNextPitchedTimespanInSameStreamByClass( ... timespan_one, classList=(stream.Score,)) >>> print(timespan_twoWrong) > >>> print(timespan_twoWrong.part) Tr=r>z: different pitchesF)rXrCr)r!rArGrBr]s rrCPitchedTimespan.canMerge*sP@w'.  $;||u}},)$veWrs# + ??&&|4  22 {{@ZhZ~fofV 8    z Tr