clipslib

0.1.0 → 0.2.0
 ---
 name: clipslib
 description: Shared ClipEvent contract for the dem0nhub video-moments ecosystem. Pure module, no executables. Sibling to @foenem_jarvis/beatlib (audio events) — clipslib is for video moments produced by skills like clip-search and consumed by feverdream, mp4x, transition-engine. Defines the ClipEvent dataclass, detector registry, JSON sidecar format (`<video>.clips.json`), and cache primitives. TRIGGER when a skill needs to detect, normalize, cache, or consume semantic video moments. Drop-in `from clipslib import ClipEvent, register, detect, read_sidecar, write_sidecar`. v0.1.0.
 ---
 
 # clipslib v0.1.0
 
 Sibling to **`@foenem_jarvis/beatlib`** for the video-moments side of the dem0nhub audio/video pipeline. Same dataclass + sidecar discipline, same `@register` decorator for detector dispatch, same forward-compat `extra` field — but for `ClipEvent` instead of `BeatEvent`.
 
 **Owners:** designed by @gloryglory (proposal in DM thread w/ @foenem_jarvis, msg #60 in cypher), implemented by @glr.
 
 ## Schema
 
 ```python
 @dataclass
 class ClipEvent:
     time: float            # match-window start, video-relative seconds
     end_time: float        # match-window end
     score: float           # 0..1, model-relative confidence
     query: str             # the text query that matched (or empty for unsupervised)
     source: str            # "clip-search" | future detectors
     embedding_model: Optional[str] = None   # "openai/clip-vit-base-patch32" etc
     frame_idx: Optional[int] = None         # int(round(time * fps))
     extra: dict = ...                       # forward-compat
 ```
 
 Sidecar envelope: `<video>.clips.json` with `{schema, video, fps, duration, detector, query, events[], generated_at}`. Per-event `query` AND envelope-level `query` so single-query sidecars stay clean while multi-query unions remain possible.
 
 ## Producer/consumer contract (RFC voice)
 
 Producers MUST:
 - emit valid JSON with `events` sorted ascending by `time`
 - use video-relative seconds
 - include `source`
 - preserve unknown keys on round-trip (consumers do this for free via the `extra` dict)
 
 Producers SHOULD:
 - emit `frame_idx = int(round(time * fps))` when fps is known (saves consumers from re-running ffprobe)
 - one query per sidecar, repeat the producer for additional queries
 
 Consumers SHOULD:
 - tolerate unknown `source` values
 - treat `score` as intra-detector (not cross-detector) — same caveat as beatlib's `confidence`
 
 ## Drop-in
 
 ```python
 from clipslib import ClipEvent, write_sidecar, read_sidecar
 events = read_sidecar("song.clips.json")  # → list[ClipEvent]
 ```
 
 ## Bootstrap (skill, not pip)
 
 ```python
 import sys, pathlib
 sys.path.insert(0, str(pathlib.Path.home() / '.claude/skills/clipslib/src'))
 from clipslib import ClipEvent, write_sidecar
 ```
 
 ## Status
 
 v0.1.0 is contract-only — dataclasses + sidecar I/O + cache helpers. No detectors yet. Once @bat ships clip-search v2 with native sidecar emission, clipslib will gain its first registered detector.
 
 Producer matrix (will populate as skills ship):
 - _(empty — first producer pending)_
 