,jSrSSKrSSKJrJrJrJrJrJrJ r J r J r J r J r SSKJr SSKJr SSKJr SSKJrJrJr \ (a SS KJr SSKr"S S 5rg) aW ######## Timeline ######## .. plot:: pyplots/timeline.py :class:`pyannote.core.Timeline` instances are ordered sets of non-empty segments: - ordered, because segments are sorted by start time (and end time in case of tie) - set, because one cannot add twice the same segment - non-empty, because one cannot add empty segments (*i.e.* start >= end) There are two ways to define the timeline depicted above: .. code-block:: ipython In [25]: from pyannote.core import Timeline, Segment In [26]: timeline = Timeline() ....: timeline.add(Segment(1, 5)) ....: timeline.add(Segment(6, 8)) ....: timeline.add(Segment(12, 18)) ....: timeline.add(Segment(7, 20)) ....: In [27]: segments = [Segment(1, 5), Segment(6, 8), Segment(12, 18), Segment(7, 20)] ....: timeline = Timeline(segments=segments, uri='my_audio_file') # faster ....: In [9]: for segment in timeline: ...: print(segment) ...: [ 00:00:01.000 --> 00:00:05.000] [ 00:00:06.000 --> 00:00:08.000] [ 00:00:07.000 --> 00:00:20.000] [ 00:00:12.000 --> 00:00:18.000] .. note:: The optional *uri* keyword argument can be used to remember which document it describes. Several convenient methods are available. Here are a few examples: .. code-block:: ipython In [3]: timeline.extent() # extent Out[3]: In [5]: timeline.support() # support Out[5]: , ])> In [6]: timeline.duration() # support duration Out[6]: 18 See :class:`pyannote.core.Timeline` for the complete reference. N) OptionalIterableListUnionCallableTextIOTuple TYPE_CHECKINGIteratorDictText) SortedList)PYANNOTE_SEGMENT)Segment)SupportLabelCropMode Annotationc\rSrSrSr\SDSSS\\SS4Sjj5rSES \\ \ S\4S jjr S r S r S rS\\ 4SjrS\S\ 4SjrSFSjrSFSjrS\ S\4SjrS\ SS4SjrS\ SS4SjrS\ SS4SjrSGSjrS\ SS4SjrSGSjrSGSjrSSS\\\ \ 44SjrSHS\S \ S!\!S\\"\\ \ 4\ 44S"jjr#SHS\S \ S!\!S\"S\S\$\ \ 4444S#jjr%S$\&S\'\ 4S%jr(S$\&S\\ 4S&jr)SIS'jr*SJS(\S \ SS4S)jjr+S*r,S+r-S,\"\ S44S-jr.SIS.jr/SSS\!4S/jr0SDS0\\1\ /\ 4SS4S1jjr2S\ 4S2jr3SKS3\&S\\ 4S4jjr4SKS3\&SS4S5jjr5S\&4S6jr6SDS\\S\\ 4S7jjr7SDS\\SS4S8jjr8SIS9jr9SLS:\"\\ \:SS4S;\\SS<4S=jjr;S\\<4S>jr=S\<4S?jr>S@\?4SAjr@SBrASCrBg)MTimelinesa Ordered set of segments. A timeline can be seen as an ordered set of non-empty segments (Segment). Segments can overlap -- though adding an already exisiting segment to a timeline does nothing. Parameters ---------- segments : Segment iterator, optional initial set of (non-empty) segments uri : string, optional name of segmented resource Returns ------- timeline : Timeline New timeline Ndfz pd.DataFrameurireturnc6[U[5nU"X2S9nU$)Nsegmentsr)listr)clsrrrtimelines ڤC:\Users\johnn\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\site-packages\pyannote/core/timeline.pyfrom_dfTimeline.from_dfs!+,-2rcUcSn[UVs/sH o3(dM UPM sn5nX@l[U5UlSU5n[U5UlX lgs snf)Nc36# UHoHo"v M M g7fNr(.0segmentboundarys r# $Timeline.__init__..Sl77xh7hl)set segments_set_rsegments_list_segments_boundaries_r)selfrrr- segments_set boundariess r#__init__Timeline.__init__sh  H8G8wG8GH ))6TlS $.z$:!Hs A A c,[UR5$)zLNumber of segments >>> len(timeline) # timeline contains three segments 3 lenr4r7s r#__len__Timeline.__len__s 4%%&&r&c"UR5$r*)__bool__r?s r# __nonzero__Timeline.__nonzero__s}}r&c2[UR5S:$)z`Emptiness >>> if timeline: ... # timeline is not empty ... else: ... # timeline is empty rr=r?s r#rCTimeline.__bool__s4%%&**r&c,[UR5$)zIterate over segments (in chronological order) >>> for segment in timeline: ... # do something with the segment See also -------- :class:`pyannote.core.Segment` describes how segments are sorted. )iterr5r?s r#__iter__Timeline.__iter__sD''((r&kc URU$)zvGet segment by index (in chronological order) >>> first_segment = timeline[0] >>> penultimate_segment = timeline[-2] )r5)r7rLs r# __getitem__Timeline.__getitem__s ""1%%r&otherc4URUR:H$)a)Equality Two timelines are equal if and only if their segments are equal. >>> timeline1 = Timeline([Segment(0, 1), Segment(2, 3)]) >>> timeline2 = Timeline([Segment(2, 3), Segment(0, 1)]) >>> timeline3 = Timeline([Segment(2, 3)]) >>> timeline1 == timeline2 True >>> timeline1 == timeline3 False r4r7rPs r#__eq__Timeline.__eq__s!!U%8%888r&c4URUR:g$) InequalityrRrSs r#__ne__Timeline.__ne__s!!U%8%888r&r-c8URRU5$)zGet index of (existing) segment Parameters ---------- segment : Segment Segment that is being looked for. Returns ------- position : int Index of `segment` in timeline Raises ------ ValueError if `segment` is not present. )r5indexr7r-s r#r[Timeline.indexs"""((11r&cURnX;dU(dU$URU5 URRU5 URnURUR5 URUR 5 U$)aAdd a segment (in place) Parameters ---------- segment : Segment Segment that is being added Returns ------- self : Timeline Updated timeline. Note ---- If the timeline already contains this segment, it will not be added again, as a timeline is meant to be a **set** of segments (not a list). If the segment is empty, it will not be added either, as a timeline only contains non-empty segments. )r4addr5r6startendr7r-r4r6s r#r_ Timeline.addss,**  #7K'" (#88  /  - r&cURnX;aU$URU5 URRU5 URnURUR5 URUR 5 U$)zRemove a segment (in place) Parameters ---------- segment : Segment Segment that is being removed Returns ------- self : Timeline Updated timeline. Note ---- If the timeline does not contain this segment, this does nothing )r4remover5r6r`rarbs r#reTimeline.removesq$**  'KW% ""7+#88##GMM2##GKK0 r&c$URU5$)zJSame as `remove` See also -------- :func:`pyannote.core.Timeline.remove` )rer\s r#discardTimeline.discard7s{{7##r&r"c$URU5$r*)updater7r"s r#__ior__Timeline.__ior__@s{{8$$r&cURnX!R-n[U5UlSU5n[U5UlU$)aGAdd every segments of an existing timeline (in place) Parameters ---------- timeline : Timeline Timeline whose segments are being added Returns ------- self : Timeline Updated timeline Note ---- Only segments that do not already exist will be added, as a timeline is meant to be a **set** of segments (not a list). c36# UHoHo"v M M g7fr*r(r+s r#r/"Timeline.update.._r1r2)r4rr5r6)r7r"r8r9s r#rkTimeline.updateCsK()) ... )6TlS $.z$:! r&c$URU5$r*)unionrls r#__or__Timeline.__or__dszz(##r&cZURUR-n[X RS9$)a^Create new timeline made of union of segments Parameters ---------- timeline : Timeline Timeline whose segments are being added Returns ------- union : Timeline New timeline containing the union of both timelines. Note ---- This does the same as timeline.update(...) except it returns a new timeline, and the original one is not modified. r)r4rr)r7r"rs r#rtTimeline.uniongs)$%%(>(>>xx88r&c## URH^n[URURS9nURRUS9H nUR U5(dMX$4v M" M` g7f)a+Iterate over pairs of intersecting segments >>> timeline1 = Timeline([Segment(0, 2), Segment(1, 2), Segment(3, 4)]) >>> timeline2 = Timeline([Segment(1, 3), Segment(3, 5)]) >>> for segment1, segment2 in timeline1.co_iter(timeline2): ... print(segment1, segment2) (, ) (, ) (, ) Parameters ---------- other : Timeline Second timeline Returns ------- iterable : (Segment, Segment) iterable Yields pairs of intersecting segments in chronological order. r`ramaximumN)r5rrairange intersects)r7rPr-temp other_segments r#co_iterTimeline.co_iter|sf,**G'++>D!&!5!5!loosestrict intersectionz9Mode must be one of 'loose', 'strict', or 'intersection'.z(Support must be a Segment or a Timeline.rrrNrr) ValueError isinstancerr TypeErrorr crop_iterrr) r7rrrryieldedr-_r mapped_tos r#rTimeline.crop_iters1 : :/0 0'GX#677FG G gw ' '#9hh?G>>':I*K K //# 7?"ll73  4  8 *.,,w*?&+!M+@ '+ll7&; "G/I(('>> timeline = Timeline([Segment(0, 2), Segment(1, 2), Segment(3, 4)]) >>> timeline.crop(Segment(1, 3)) ])> >>> timeline.crop(Segment(1, 3), mode='loose') , ])> >>> timeline.crop(Segment(1, 3), mode='strict') ])> >>> cropped, mapping = timeline.crop(Segment(1, 3), returns_mapping=True) >>> print(mapping) {: [, ]} rTrrr)rappendgetr rr)r7rrrrmappingr-rs r#crop Timeline.cropsb > !o "Bg&*nnW:HEI'5'K" *%,[[DF%Cwi%O" 'K X88>> timeline = Timeline([Segment(0, 2), Segment(1, 2), Segment(3, 5)]) >>> timeline.extrude(Segment(1, 2)) , ])> >>> timeline.extrude(Segment(1, 3), mode='loose') ])> >>> timeline.extrude(Segment(1, 3), mode='strict') , ])> rrrrr)rrrextentrgapsr)r7rr extent_tltruncating_supports r#extrudeTimeline.extrudeFsrD gw ' 'y)Gdkkm_$((; $\\)\< 7?D X Dyy+y77r&c[UR5nSn[UR5H"up4U[U5- nX#S-U:aSOS- nM$ US- nU$)zHuman-readable representation >>> timeline = Timeline(segments=[Segment(0, 10), Segment(1, 13.37)]) >>> print(timeline) [[ 00:00:00.000 --> 00:00:10.000] [ 00:00:01.000 --> 00:00:13.370]] [rz ])r>r5 enumeratestr)r7nstringir-s r#__str__Timeline.__str__tsb ## $#D$7$78JA c'l "F 1uqyeb 0F9 #  r&cRSUR<S[UR5<S3$)zComputer-readable representation >>> Timeline(segments=[Segment(0, 10), Segment(1, 13.37)]) , ])> z)rr r5r?s r#__repr__Timeline.__repr__s%59HH489L9L4MO Or&includedc[U[5(aXR;$[U[5(a%URR UR5$[ S5e)aInclusion Check whether every segment of `included` does exist in timeline. Parameters ---------- included : Segment or Timeline Segment or timeline being checked for inclusion Returns ------- contains : bool True if every segment in `included` exists in timeline, False otherwise Examples -------- >>> timeline1 = Timeline(segments=[Segment(0, 10), Segment(1, 13.37)]) >>> timeline2 = Timeline(segments=[Segment(0, 10)]) >>> timeline1 in timeline2 False >>> timeline2 in timeline1 >>> Segment(1, 13.37) in timeline1 True zCChecking for inclusion only supports Segment and Timeline instances)rrr4r issupersetr)r7rs r# __contains__Timeline.__contains__s^8 h ( (111 1 ( + +%%001G1GH H%& &r&c([URS9$)zkReturn an empty copy Returns ------- empty : Timeline Empty timeline using the same 'uri' attribute. r)rrr?s r#emptyTimeline.emptysDHH%%r&cnURUR5S9nURU5Hn g g)aCheck whether other timeline is fully covered by the timeline Parameter --------- other : Timeline Second timeline Returns ------- covers : bool True if timeline covers "other" timeline entirely. False if at least one segment of "other" is not fully covered by timeline rFT)rrr)r7rPrrs r#coversTimeline.coverss7"yyy0e$A% r& segment_funccUc[URURS9$[URVs/sH o!"U5PM snURS9$s snf)a_Get a copy of the timeline If `segment_func` is provided, it is applied to each segment first. Parameters ---------- segment_func : callable, optional Callable that takes a segment as input, and returns a segment. Defaults to identity function (segment_func(segment) = segment) Returns ------- timeline : Timeline Copy of the timeline r)rr5r)r7rss r#copy Timeline.copysW*  T%8%8dhhG G4;N;N!O;Na,q/;N!O HH& &!OsAcvUR(aURnUSnUSn[X#S9$[SSS9$)a5Extent The extent of a timeline is the segment of minimum duration that contains every segments of the timeline. It is unique, by definition. The extent of an empty timeline is an empty segment. A picture is worth a thousand words:: timeline |------| |------| |----| |--| |-----| |----------| timeline.extent() |--------------------------------| Returns ------- extent : Segment Timeline extent Examples -------- >>> timeline = Timeline(segments=[Segment(0, 1), Segment(9, 10)]) >>> timeline.extent() rrz)r4r6r)r7r6r`ras r#rTimeline.extentsE8   #'#<#< (+E&r*C0 0Sc**r&collarc## U(dgURSnUH*nX2- nU(aURU:aX#-nM$Uv UnM, Uv g7f)zqLike `support` but returns a segment generator instead See also -------- :func:`pyannote.core.Timeline.support` Nr)r5duration)r7r new_segmentr- possible_gaps r# support_iterTimeline.support_iter sb ))!, G#0L<#8#86#A& "!& !&sA AcH[URU5URS9$)a Timeline support The support of a timeline is the timeline with the minimum number of segments with exactly the same time span as the original timeline. It is (by definition) unique and does not contain any overlapping segments. A picture is worth a thousand words:: collar |---| timeline |------| |------| |----| |--| |-----| |----------| timeline.support() |------| |--------| |----------| timeline.support(collar) |------------------| |----------| Parameters ---------- collar : float, optional Merge separated by less than `collar` seconds. This is why there are only two segments in the final timeline in the above figure. Defaults to 0. Returns ------- support : Timeline Timeline support r)rrr)r7rs r#rTimeline.supportMs!F!2!26!:IIr&cB[SUR555$)zTimeline duration The timeline duration is the sum of the durations of the segments in the timeline support. Returns ------- duration : float Duration of timeline support, in seconds. c38# UHoRv M g7fr*)r)r,rs r#r/$Timeline.duration..s;':!::':s)sumrr?s r#rTimeline.durationrs;t'8'8':;;;r&c#X# UcUR5n[U[[45(d![ S[ U5R -5e[U[5(a{URnURUSS9R5H-n[X#RS9nU(aUv URnM/ [X!RS9nU(aUv gg[U[5(a2UR5HnURUS9HnUv M M gg7f)zlLike `gaps` but returns a segment generator instead See also -------- :func:`pyannote.core.Timeline.gaps` Nz3unsupported operand type(s) for -':%s and Timeline.rrrzr) rrrrrtype__name__r`rrra gaps_iter)r7rrar-gaps r#rTimeline.gaps_iters ?kkmG'GX#677/15g1G1GHI I gw ' '--C 99W>9BJJLC]];IkkM5C  * *#??,>>'>:CI;-+sD(D*cD[URUS9URS9$)aGaps A picture is worth a thousand words:: timeline |------| |------| |----| |--| |-----| |----------| timeline.gaps() |--| |--| Parameters ---------- support : None, Segment or Timeline Support in which gaps are looked for. Defaults to timeline extent Returns ------- gaps : Timeline Timeline made of all gaps from original timeline, and delimited by provided support See also -------- :func:`pyannote.core.Timeline.extent` rr)rrr)r7rs r#r Timeline.gapss%:!@ HH& &r&cUR5n[/5nUH'up4URU5 URU5 M) [U5n[ UR S9n[ U5S:Xa[ UR S9$/nUSnUSSHFn[X4S9nU(a1URUR5(aURU5 UnMH [ X`R S9$)aSegmentation Create the unique timeline with same support and same set of segment boundaries as original timeline, but with no overlapping segments. A picture is worth a thousand words:: timeline |------| |------| |----| |--| |-----| |----------| timeline.segmentation() |-|--|-| |-|---|--| |--|----|--| Returns ------- timeline : Timeline (unique) timeline with same support and same set of segment boundaries as original timeline, but with no overlapping segments. rrrNrzr) rr3r_sortedrrr>rrmiddler)r7r timestampsr`rar"rr-s r# segmentationTimeline.segmentations,,,.W  LU NN5 ! NN3 !J' ) z?a ) )1 ab>CE3G7..w~~>>(E "xx88r& generatormodalityrcSSKJn U"URUS9nUS:XaSSKJn U"5nOUS:Xa SSKJn U"5nUHn[ U5XG'M U$)aiTurn timeline into an annotation Each segment is labeled by a unique label. Parameters ---------- generator : 'string', 'int', or iterable, optional If 'string' (default) generate string labels. If 'int', generate integer labels. If iterable, use it to generate labels. modality : str, optional Returns ------- annotation : Annotation Annotation rr)rrr)string_generatorint) int_generator) annotationrrutils.generatorsrrnext)r7rrrrrrr-s r# to_annotationTimeline.to_annotation sZ* +DHHx@  :(*I %  7%IG"&y/J r&c## UR(a UROSn[U[5(aSU;aSUS3n[U5eUH&nUSURSSUR SS3v M( g7f) z}Generate lines for a UEM file for this timeline Returns ------- iterator: Iterator[str] An iterator over UEM text lines z zRSpace-separated UEM file format does not allow file URIs containing spaces (got: "z").z 1 z.3f N)rrr rr`ra)r7rmsgr-s r# _iter_uemTimeline._iter_uem0sy((dhh c4 SCZ//2e38CS/ !GEW]]3/qS0AD DsA9A;cjSRUR5Vs/sHoPM sn5$s snf)z`Serialize timeline as a string using UEM format Returns ------- serialized: str UEM string r)joinr)r7lines r#to_uemTimeline.to_uem@s.ww)9:)9)9:;;:s 0filecTUR5HnURU5 M g)zDump timeline to file using UEM format Parameters ---------- file : file object Usage ----- >>> with open('file.uem', 'w') as file: ... timeline.write_uem(file) N)rwrite)r7rrs r# write_uemTimeline.write_uemJs!NN$D JJt %r&cSSKJnJn U(d8[R"UR UR RS95 gSSKJn U"U5$)zJIPython notebook support See also -------- :mod:`pyannote.core.notebook` r)MATPLOTLIB_IS_AVAILABLEMATPLOTLIB_WARNING)klassN) repr_timeline) notebookr r warningswarnformat __class__rr)r7r r rs r# _repr_png_Timeline._repr_png_YsA J& MM,33$..:Q:Q3R S+T""r&)r6r5r4rr*)NN)rPr)r"rrr)rF)rr)r)r)rN)Cr __module__ __qualname____firstlineno____doc__ classmethodrrr$rrr:r@rDrCr rJrrNrTrXr[r_rerhrmrkrurtr rrrboolrrr rfloatrrrrrrrrrrrrrrrrrrrrrr rrrr r__static_attributes__r(r&r#rrsss(hsmz :> #HW$56,'+ )(7+ )&S&W& 992W22&"7"z"Hg*@$w$:$%w:B$9*1Z1HU7G;K5L,M1@$2*/8 "8  8 $(8 eGW$45w>?@ 8 x-%*;&;&;&#;&Zz48H3I'I!JJK ;&z .U .tG} . % HW,= %8"0,8 ,8,84>,8\$ O%&U7J+>%?%&N &J48&(G9g3E*F!G&&:"+"+H+5+8G3D+Z#Je#JZ#JJ<%< .'!2.hw>O.`&HW-&&@99xLT04!!&sHUOT4'G!H! ( !!FE8D>E << f  #r&r)rrtypingrrrrrrr r r r r sortedcontainersrrrr-r utils.typesrrrrrpandaspdrr(r&r#r$sP>;xHHHH(11 &s#s#r&