lacing.adapters.webvtt

WebVTT (W3C TimedText) adapter.

WebVTT is a flat caption format: one stream of cues, no tier hierarchy. Cues have a start time, an end time, optional id and settings, and a payload (text with limited inline markup).

We map cues to a single tier named cues (override with tier=). Each cue becomes one Annotation whose body holds:

{“text”: str, “id”: str | None, “settings”: dict[str, str]}

Lossy fields on dump:

Provenance, confidence, schema URIs, and tier metadata are dropped. Only the text, id (if present), and settings are emitted.

Time discipline:

WebVTT timestamps are HH:MM:SS.mmm or MM:SS.mmm (with milliseconds). Parsing goes through string fractions to avoid float ingestion. Default rate is 1000 (millisecond precision); override with rate= if your project uses a different canonical rate.

Spec: https://www.w3.org/TR/webvtt1/

lacing.adapters.webvtt.dump(store: IntervalAnnotationStore, target: str | PathLike | None = None, *, tier: str | None = None, **_kwargs: Any) → bytes | None[source]

Write annotations as WebVTT.

Parameters:

  • store – Source store. Only annotations from tier (default: all tiers) with a MediaRef interval are emitted, sorted by start.

  • target – Output path. If None, returns bytes (UTF-8).

  • tier – Restrict export to this tier. None = export all annotations.

lacing.adapters.webvtt.load(source: str | bytes | PathLike, *, rate: int = 1000, asset_id: str = 'webvtt:unspecified', attribution: str = 'anonymous', tier: str = 'cues', **_kwargs: Any) → IntervalAnnotationStore[source]

Parse a WebVTT file or string/bytes into a MemoryStore.