5.2.8. ytpb.locate

Locate segments by given times.

ytpb.locate.PARTIAL_SEGMENT_SIZE_BYTES = 2000

Number of bytes sufficient to cover the YouTube metadata in segment files. Note that the minimum value varies for different media formats, so the value was determined empirically for all available MPEG-DASH formats.

class ytpb.locate.SequenceMetadataPair(sequence: int, locator: SegmentLocator)

Bases: object

Represents a pair of segment sequence number and SegmentMetadata.

property sequence: int
property metadata
class ytpb.locate.LocateResult(sequence: int, time_difference: float, falls_in_gap: bool, track: list[tuple[int, float]])

Bases: NamedTuple

Represents a locate result.

sequence: int

A segment sequence number.

time_difference: float

A time difference between a target time and ytpb.segment.Segment.ingestion_start_date.

falls_in_gap: bool

Wheter a target time falls in gap.

track: list[tuple[int, float]]

Stores all locate steps as pairs of segment sequence nubmer and time difference.

class ytpb.locate.SegmentLocator(base_url: str, reference_sequence: int | None = None, temp_directory: Path | None = None, session: Session | None = None)

Bases: object

A class that locates a segment with a desired time.

A timeline may contain numerous gaps, which leads to under- or overestimation, and it needs to be taken into account.

The locating consists of three steps: (1) a “look around”, jump-based search to find a segment directly or outline a search domain (the jump length is based on the time difference and constant duration of segments); (2) search for a segment in the outlined domain using a binary search if a segment is not found in the previous step; (3) check whether a target time falls in gap or not.

__init__(base_url: str, reference_sequence: int | None = None, temp_directory: Path | None = None, session: Session | None = None) → Self

Constructs a segment locator.

Parameters:

  • base_url – A segment base URL.

  • reference_sequence – A segment sequence number used as a reference.

  • temp_directory – A temporary directory used to store downloaded segments during locating.

  • session – A request.Session object.

get_temp_directory()

Gets (and creates if needed) a temporary directory.

find_sequence_by_time(desired_time: float, end: bool = False) → LocateResult

Finds sequence number of a segment by the given timestamp.

Parameters:

  • desired_time – A target Unix timestamp.

  • end – Whether a segment belongs to the end of an interval.

Returns:

A LocateResult object.