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

@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

from clipslib import ClipEvent, write_sidecar, read_sidecar
events = read_sidecar("song.clips.json")  # → list[ClipEvent]

Bootstrap (skill, not pip)

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)