Time Slices

TSSlice and TSSlices represent time intervals using offset ranges. They are useful for segment arithmetic: intersections, unions, gap detection, and array indexing.

Creating Slices

from sgnts.base import TSSlice, TSSlices, Offset

# From raw offsets
s = TSSlice(start=0, stop=16384)

# From seconds (converted to offsets)
s = TSSlice(start=Offset.fromsec(0), stop=Offset.fromsec(1.0))

A TSSlices is an ordered collection:

from sgnts.base import TSSlice, TSSlices

slices = TSSlices([
    TSSlice(start=0, stop=16384),
    TSSlice(start=32768, stop=49152),
])

Slice Properties

from sgnts.base import TSSlice

s = TSSlice(start=0, stop=16384)
print(s.start)             # 0
print(s.stop)              # 16384
print(s.stop - s.start)    # 16384 (span in offset units)

Intersection

Find the overlap between two slices:

from sgnts.base import TSSlice

a = TSSlice(start=0, stop=32768)
b = TSSlice(start=16384, stop=49152)

overlap = a & b  # TSSlice(start=16384, stop=32768)

For finding the common region across all slices in a collection, use intersection():

from sgnts.base import TSSlice, TSSlices

slices = TSSlices([TSSlice(0, 32768), TSSlice(16384, 49152)])
result = slices.intersection()  # TSSlice(start=16384, stop=32768)

To find common regions across multiple TSSlices objects, use intersection_of_multiple():

from sgnts.base import TSSlice, TSSlices

s1 = TSSlices([TSSlice(0, 32768)])
s2 = TSSlices([TSSlice(16384, 49152)])

result = TSSlices.intersection_of_multiple([s1, s2])

Union

Merge overlapping or adjacent slices using + on individual TSSlice objects:

from sgnts.base import TSSlice

a = TSSlice(0, 16384)
b = TSSlice(16384, 32768)

result = a + b  # [TSSlice(start=0, stop=32768)]

Gap Detection

Find gaps within a range by inverting a slice collection:

from sgnts.base import TSSlice, TSSlices

segments = TSSlices([
    TSSlice(0, 16384),
    TSSlice(32768, 49152),
])

# Invert within a bounding range to find gaps
gaps = segments.invert(TSSlice(0, 49152))
# TSSlices([TSSlice(16384, 32768)])

Simplification

Merge overlapping slices in a collection:

from sgnts.base import TSSlice, TSSlices

messy = TSSlices([
    TSSlice(0, 16384),
    TSSlice(8192, 32768),
])

clean = messy.simplify()  # TSSlices([TSSlice(0, 32768)])

Other Operations

Difference — returns the non-overlapping parts of two slices:

from sgnts.base import TSSlice

a = TSSlice(start=0, stop=32768)
b = TSSlice(start=16384, stop=49152)

diff = a - b  # [TSSlice(0, 16384), TSSlice(32768, 49152)]

Split — divide a slice at a specific offset:

from sgnts.base import TSSlice

left, right = TSSlice(0, 32768).split(16384)

Search — find slices that overlap a given range, optionally truncating them to fit:

from sgnts.base import TSSlice, TSSlices

slices = TSSlices([TSSlice(0, 16384), TSSlice(32768, 49152)])
result = slices.search(TSSlice(8192, 32768), align=True)

Aligning to a Sample Rate

Snap slice boundaries to sample boundaries at a given rate:

from sgnts.base import TSSlice, TSSlices

slices = TSSlices([TSSlice(start=100, stop=20000)])
aligned = slices.align_to_rate(target_rate=2048)