o pi@sdZddlZddlmZmZmZmZmZmZm Z m Z m Z m Z m Z ddlmZddlmZddlmZddlmZmZmZe rHdd lmZddlZGd d d ZdS) 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@sBeZdZdZedpdddeeddfddZ  dqd eee defd d Z d d Z ddZ ddZ dee fddZdede fddZdrddZdrddZde defddZde ddfdd Zde ddfd!d"Zde ddfd#d$Zdsd&d'Zd%e ddfd(d)Zdsd*d+Zdsd,d-Zdddeee e ffd.d/Z 0 1dtd2ed3ed4e dee!ee e fe ffd5d6Z" 0 1dtd2ed3ed4e de!dede#e e ffffd7d8Z$d9e%de&e fd:d;Z'd9e%dee fdd?Z) 0dvd@ed3eddfdAdBZ*dCdDZ+dEdFZ,dGe!e dffdHdIZ-dudJdKZ.ddde fdLdMZ/dpdNee0e ge fddfdOdPZ1de fdQdRZ2dwdTe%dee fdUdVZ3dwdTe%ddfdWdXZ4de%fdYdZZ5dpd2eedee fd[d\Z6dpd2eeddfd]d^Z7dud_d`Z8 a dxdbe!eee9ddfdceedddfdedfZ:dee;fdgdhZfdldmZ?dndoZ@dS)yTimelinea 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.DataFrameurireturncCst|t}|||d}|S)Nsegmentsr)listr)clsrrrtimelinerJ/home/ubuntu/.local/lib/python3.10/site-packages/pyannote/core/timeline.pyfrom_dfs  zTimeline.from_dfrcCsP|durd}tdd|D}||_t||_dd|D}t||_||_dS)NrcSsg|]}|r|qSrr).0segmentrrr z%Timeline.__init__..cs|] }|D]}|VqqdSNrr"r#boundaryrrr z$Timeline.__init__..)set segments_set_r segments_list_segments_boundaries_r)selfrr segments_set boundariesrrr __init__s   zTimeline.__init__cC t|jS)zdNumber of segments >>> len(timeline) # timeline contains three segments 3 lenr-r0rrr __len__ zTimeline.__len__cCs|Sr')__bool__r7rrr __nonzero__szTimeline.__nonzero__cCst|jdkS)zEmptiness >>> if timeline: ... # timeline is not empty ... else: ... # timeline is empty rr5r7rrr r:szTimeline.__bool__cCr4)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. )iterr.r7rrr __iter__s zTimeline.__iter__kcCs |j|S)zGet segment by index (in chronological order) >>> first_segment = timeline[0] >>> penultimate_segment = timeline[-2] )r.)r0r>rrr __getitem__r9zTimeline.__getitem__othercCs |j|jkS)aqEquality 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 r-r0r@rrr __eq__s zTimeline.__eq__cCs |j|jkS) InequalityrArBrrr __ne__s zTimeline.__ne__r#cCs |j|S)aIGet 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. )r.indexr0r#rrr rFs zTimeline.indexcCsN|j}||vs |s |S|||j||j}||j||j|S)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. )r-addr.r/startendr0r#r-r/rrr rHs     z Timeline.addcCsJ|j}||vr |S|||j||j}||j||j|S)aJRemove 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 )r-remover.r/rIrJrKrrr rLs    zTimeline.removecC ||S)zjSame as `remove` See also -------- :func:`pyannote.core.Timeline.remove` )rLrGrrr discard7s zTimeline.discardrcCrMr')updater0rrrr __ior__@ zTimeline.__ior__cCs6|j}||jO}t||_dd|D}t||_|S)aAdd 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). csr&r'rr(rrr r*_r+z"Timeline.update..)r-r r.r/)r0rr1r2rrr rOCs    zTimeline.updatecCrMr')unionrPrrr __or__drRzTimeline.__or__cCs|j|jB}t||jdS)aCreate 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)r-rr)r0rrrrr rSgs zTimeline.unionccsJ|jD]}t|j|jd}|jj|dD] }||r!||fVqqdS)aIterate 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. rIrJmaximumN)r.rrJirange intersects)r0r@r#temp other_segmentrrr co_iter|s   zTimeline.co_iter intersectionFsupportmodereturns_mappingc cs|dvr tdt|ttfstdt|tr8|r|g}ng}t||jd}|j|||dD]}|Vq0dS|}|dkrO||D]\}}|VqEdS|dkrf||D] \}}||vrc|VqXdS||D]\}}||@} | svqk|r~|| fVqk| VqkdS) zLike `crop` but returns a segment iterator instead See also -------- :func:`pyannote.core.Timeline.crop` >loosestrictr]z9Mode must be one of 'loose', 'strict', or 'intersection'.z(Support must be a Segment or a Timeline.rr_r`Nrarb) ValueError isinstancerr TypeErrorr crop_iterr^r\) r0r^r_r`ryieldedr#_r[ mapped_torrr rgsD    zTimeline.crop_itercCs||dkr2|r2gi}}|j|dddD]\}}||||t|g||<qt||jd|fSt|j||d|jdS)aCrop timeline to new support Parameters ---------- support : Segment or Timeline If `support` is a `Timeline`, its support is used. mode : {'strict', 'loose', 'intersection'}, optional Controls how segments that are not fully included in `support` are handled. 'strict' mode only keeps fully included segments. 'loose' mode keeps any intersecting segment. 'intersection' mode keeps any intersecting segment but replace them by their actual intersection. returns_mapping : bool, optional In 'intersection' mode, return a dictionary whose keys are segments of the cropped timeline, and values are list of the original segments that were cropped. Defaults to False. Returns ------- cropped : Timeline Cropped timeline mapping : dict When 'returns_mapping' is True, dictionary whose keys are segments of 'cropped', and values are lists of corresponding original segments. Examples -------- >>> 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) {: [, ]} r]Trcrr_)rgappendgetrrr)r0r^r_r`rmappingr#rjrrr crops 1  z Timeline.croptcCst||S)aGet list of segments overlapping `t` Parameters ---------- t : float Timestamp, in seconds. Returns ------- segments : list List of all segments of timeline containing time t )roverlapping_iter)r0rprrr overlappings zTimeline.overlappingccs6t||d}|jj|dD] }||r|VqdS)zLike `overlapping` but returns a segment iterator instead See also -------- :func:`pyannote.core.Timeline.overlapping` rUrVN)rr.rXoverlaps)r0rpr#rrr rq s  zTimeline.overlapping_itercCs@t|jd}||D]\}}||krq |||@q |S)aGet overlapping parts of the timeline. A simple illustration: .. code-block:: text timeline |------| |------| |----| |--| |-----| |----------| timeline.get_overlap() |--| |---| |----| Returns ------- overlap : `pyannote.core.Timeline` Timeline of the overlaps. r)rrr\rHr^)r0 overlaps_tls1s2rrr get_overlap,s zTimeline.get_overlapremovedcCs\t|tr t|g}t|g|jd}|j|d}|dkr!d}n|dkr'd}|j||dS)amRemove segments that overlap `removed` support. Parameters ---------- removed : Segment or Timeline If `support` is a `Timeline`, its support is used. mode : {'strict', 'loose', 'intersection'}, optional Controls how segments that are not fully included in `removed` are handled. 'strict' mode only removes fully included segments. 'loose' mode removes any intersecting segment. 'intersection' mode removes the overlapping part of any intersecting segment. Returns ------- extruded : Timeline Extruded timeline Examples -------- >>> 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') , ])> rtr^rarbrk)rerrextentrgapsro)r0ryr_ extent_tltruncating_supportrrr extrudeFs "  zTimeline.extrudecCsRt|j}d}t|jD]\}}|t|7}||d|krdnd7}q |d7}|S)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 ])r6r. enumeratestr)r0nstringir#rrr __str__ts  zTimeline.__str__cCsd|jt|jfS)zComputer-readable representation >>> Timeline(segments=[Segment(0, 10), Segment(1, 13.37)]) , ])> z)rrr.r7rrr __repr__szTimeline.__repr__includedcCs4t|tr ||jvSt|tr|j|jStd)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)rerr-r issupersetrf)r0rrrr __contains__s   zTimeline.__contains__cCs t|jdS)zReturn an empty copy Returns ------- empty : Timeline Empty timeline using the same 'uri' attribute. rt)rrr7rrr emptys zTimeline.emptycCs(|j|d}||D]}dSdS)atCheck 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 rzFT)r|r{r\)r0r@r|rirrr coversszTimeline.covers segment_funccs6dur t|j|jdStfdd|jD|jdS)aGet 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 Nrcsg|]}|qSrrr"srrr r$r%z!Timeline.copy..)rr.r)r0rrrr copys z Timeline.copycCs4|jr|j}|d}|d}t||dStdddS)aExtent 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() rrU)r-r/r)r0r/rIrJrrr r{s   zTimeline.extentrcollarccsR|sdS|jd}|D]}||A}|r|j|kr||O}q |V|}q |VdS)zLike `support` but returns a segment generator instead See also -------- :func:`pyannote.core.Timeline.support` Nr)r.duration)r0r new_segmentr# possible_gaprrr support_iter s    zTimeline.support_itercCst|||jdS)aTimeline 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)r0rrrr r^Ms#zTimeline.supportcCstdd|DS)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. css|]}|jVqdSr')rrrrr r*sz$Timeline.duration..)sumrr7rrr rrszTimeline.durationccs|dur |}t|ttfstdt|jt|trL|j}|j|dd D]}t||jd}|r8|V|j }q*t||j d}|rJ|VdSdSt|trd| D]}|j |dD]}|Vq]qUdSdS)zLike `gaps` but returns a segment generator instead See also -------- :func:`pyannote.core.Timeline.gaps` Nz3unsupported operand type(s) for -':%s and Timeline.r]rkrUrz) r{rerrrftype__name__rIror^rJ gaps_iter)r0r^rJr#gaprrr rs2     zTimeline.gaps_itercCst|j|d|jdS)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` rzr)rrr)r0r^rrr r|s z Timeline.gapscCs|}tg}|D]\}}||||q t|}t|jd}t|dkr/t|jdSg}|d}|ddD]}t||d}|rP||j rP| ||}q;t||jdS)avSegmentation 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. rtrrNrUr) r^r,rHsortedrrr6rrrmiddlerl)r0r^ timestampsrIrJrrr#rrr segmentations"        zTimeline.segmentationr generatormodalityrcCsjddlm}||j|d}|dkrddlm}|}n |dkr(ddlm}|}|D]}t|||<q*|S)aTurn 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)r0rrrrrrr#rrr to_annotation s   zTimeline.to_annotationccsf|jr|jnd}t|trd|vrd|d}t||D]}|d|jdd|jddVqdS) zGenerate 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)rrer rdrIrJ)r0rmsgr#rrr _iter_uem0s"zTimeline._iter_uemcCsddd|DS)zSerialize timeline as a string using UEM format Returns ------- serialized: str UEM string rcSsg|]}|qSrr)r"linerrr r$Hsz#Timeline.to_uem..)joinrr7rrr to_uem@szTimeline.to_uemfilecCs|D]}||qdS)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)r0rrrrr write_uemJs zTimeline.write_uemcCsBddlm}m}|st|j|jjddSddlm}||S)zjIPython notebook support See also -------- :mod:`pyannote.core.notebook` r)MATPLOTLIB_IS_AVAILABLEMATPLOTLIB_WARNING)klassN) repr_timeline) notebookrrwarningswarnformat __class__rr)r0rrrrrr _repr_png_Ys  zTimeline._repr_png_r')NN)r@r)rrrr)r]F)rr)r])r)rN)Ar __module__ __qualname____doc__ classmethodrrr!rrr3r8r;r:r r=rr?rCrErFrHrLrNrQrOrTrSrr\rrboolrrgr rofloatrrrrqrxrrrrrrrrr{rr^rrr|rrrr rrrrrrrrr rss     $  !   < =  . '  $-% 0 < # r)rrtypingrrrrrrrr r r r sortedcontainersr rrr#r utils.typesrrrrrpandaspdrrrrr s<4