screex 0.1.0__py3-none-any.whl

screex/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: screex
+description: Use when the user wants Claude to understand a screen recording / screencast / demo / bug-repro video — e.g. "what are the steps in this recording?", "turn this into a how-to doc", "write a bug report from this repro", "what URL did they open?". Screex builds a queryable index of UI states (with on-screen text) and Claude reads it to produce a transcript, answer questions, or generate docs.
+---
+
+# Screex — screen-recording understanding
+
+## When to use
+The user points you at a screen recording (a screencast, demo, tutorial, or bug repro) and
+wants a step transcript, a how-to doc, a bug report, or answers to questions about it.
+
+## Build the index
+Run:
+`python -m screex.cli index <recording> --fps 2`
+(raise `--fps` for fast-moving recordings; lower `--change-threshold` to split states more
+eagerly.) This writes `<recording>.screex/index.json` plus per-state `frames/NNNNN.png`
+(full-res keyframe) and `frames/NNNNN_thumb.png` (thumbnail).
+
+## Read the index
+`Read` `index.json`. It is an ordered list of UI `states`, each with `t_start`/`t_end`,
+`ocr_text` (the on-screen text), `text_added` / `text_removed` (what text appeared or
+disappeared vs the previous state — the strongest signal of what the user did), and paths to
+a `thumbnail` and full-res `keyframe`. The on-screen text is plain text — reading it across
+states is cheap.
+
+## Produce one of three views
+
+- **Action transcript:** walk the states in order; use `text_added`/`text_removed` plus the
+  thumbnail to narrate timestamped steps, e.g. "0:04 opened Settings; 0:09 entered an API
+  key; 0:14 an 'invalid key' error appeared."
+- **Q&A:** answer the user's question by scanning `ocr_text` across states (cheap). `Read`
+  the full-res `keyframe` PNG for a state only when the text is insufficient (small icons,
+  layout, colour).
+- **Doc / bug report:** format the transcript into a how-to guide, or a structured
+  reproduction report (steps to reproduce, expected vs actual).
+
+## Cost discipline
+The `ocr_text` and `text_*` fields are text and nearly free to read. Escalate to a
+`keyframe` image only for the few states where the text doesn't answer the question.
+
+## Caveats
+`ocr_text` can contain minor OCR noise (stray glyphs), and a busy recording can produce many
+near-duplicate consecutive states — collapse states whose `ocr_text` is essentially identical
+when you narrate. Tune `--change-threshold` up to merge states, down to split them.

screex/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

screex/cli.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from screex import __version__
+from screex.core import source, mapper, analyzer
+from screex.core.manifest import Manifest, FrameRecord
+
+
+def analyze(video, fps=5.0, cols=120, sensitivity=0.06, edge=False, out=None, cut_threshold=0.5):
+    import cv2
+
+    video = Path(video)
+    info = source.video_info(str(video))
+    out_dir = Path(out) if out else video.parent / f"{video.stem}.screex"
+    frames_dir = out_dir / "frames"
+    frames_dir.mkdir(parents=True, exist_ok=True)
+
+    records = []
+    similarities = []
+    prev_gray = None
+    for idx, t, bgr in source.iter_frames(str(video), fps):
+        gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
+        score = 0.0 if prev_gray is None else analyzer.motion_score(prev_gray, gray)
+        sim = 1.0 if prev_gray is None else analyzer.histogram_similarity(prev_gray, gray)
+        prev_gray = gray
+        similarities.append(sim)
+
+        ascii_text = mapper.frame_to_ascii(gray, cols, edge=edge)
+        name = f"{idx:05d}"
+        png_rel = f"frames/{name}.png"
+        txt_rel = f"frames/{name}.txt"
+        cv2.imwrite(str(out_dir / png_rel), bgr)
+        (out_dir / txt_rel).write_text(ascii_text, encoding="utf-8")
+
+        records.append(FrameRecord(
+            idx=idx, t=round(t, 3), score=round(score, 4),
+            event=False, ascii=txt_rel, png=png_rel,
+        ))
+
+    scores = [r.score for r in records]
+    times = [r.t for r in records]
+    flags = analyzer.flag_events(scores, sensitivity)
+    for r, f in zip(records, flags):
+        r.event = f
+    events = analyzer.group_events(scores, times, flags)
+    events = analyzer.classify_events(events, similarities, cut_threshold)
+
+    manifest = Manifest(
+        video=video.name, duration=round(info["duration"], 3),
+        sampled_fps=fps, cols=cols, frames=records, events=events,
+    )
+    manifest_path = out_dir / "manifest.json"
+    manifest.save(manifest_path)
+    return manifest_path
+
+
+def index(recording, fps=2.0, change_threshold=0.04, thumb_width=320, out=None):
+    import cv2
+    from screex.core import source, segment, ocr
+    from screex.core.index import ScreenState, ScreenIndex
+
+    recording = Path(recording)
+    info = source.video_info(str(recording))
+    out_dir = Path(out) if out else recording.parent / f"{recording.stem}.screex"
+    frames_dir = out_dir / "frames"
+    frames_dir.mkdir(parents=True, exist_ok=True)
+
+    states = []
+    prev_ocr = []
+    for seg in segment.segment_stream(source.iter_frames(str(recording), fps), change_threshold):
+        bgr = seg.frame_bgr
+        text = ocr.extract_text(bgr)
+        added, removed = ocr.text_diff(prev_ocr, text)
+        prev_ocr = text
+
+        name = f"{seg.idx:05d}"
+        key_rel = f"frames/{name}.png"
+        thumb_rel = f"frames/{name}_thumb.png"
+        cv2.imwrite(str(out_dir / key_rel), bgr)
+        th = max(1, int(bgr.shape[0] * thumb_width / bgr.shape[1]))
+        cv2.imwrite(str(out_dir / thumb_rel), cv2.resize(bgr, (thumb_width, th)))
+
+        states.append(ScreenState(
+            idx=seg.idx, t_start=round(seg.t_start, 3), t_end=round(seg.t_end, 3),
+            thumbnail=thumb_rel, keyframe=key_rel,
+            ocr_text=text, text_added=added, text_removed=removed,
+        ))
+
+    screen_index = ScreenIndex(
+        video=recording.name, duration=round(info["duration"], 3),
+        sampled_fps=fps, states=states,
+    )
+    index_path = out_dir / "index.json"
+    screen_index.save(index_path)
+    return index_path
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="screex")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("analyze", help="analyze a video into ASCII frames + manifest")
+    a.add_argument("video")
+    a.add_argument("--fps", type=float, default=5.0, help="frames sampled per second")
+    a.add_argument("--cols", type=int, default=120, help="ASCII grid width")
+    a.add_argument("--sensitivity", type=float, default=0.06,
+                   help="motion threshold (0..1) for flagging event frames")
+    a.add_argument("--edge", action="store_true", help="emphasize edges/structure")
+    a.add_argument("--out", default=None, help="output dir (default <video>.screex)")
+    a.add_argument("--cut-threshold", type=float, default=0.5,
+                   help="histogram-similarity below which an event is a scene cut (0..1)")
+
+    ix = sub.add_parser("index", help="build a ScreenIndex from a screen recording")
+    ix.add_argument("recording")
+    ix.add_argument("--fps", type=float, default=2.0, help="frames sampled per second")
+    ix.add_argument("--change-threshold", type=float, default=0.04,
+                    help="motion fraction (0..1) that marks a new UI state")
+    ix.add_argument("--thumb-width", type=int, default=320, help="thumbnail width in px")
+    ix.add_argument("--out", default=None, help="output dir (default <recording>.screex)")
+
+    c = sub.add_parser("capture", help="record a short webcam clip")
+    c.add_argument("--webcam", action="store_true")
+    c.add_argument("--seconds", type=float, default=10.0)
+    c.add_argument("--out", default="capture.mp4")
+
+    sk = sub.add_parser("skill", help="install or locate the Screex Claude skill (SKILL.md)")
+    sk.add_argument("--install", action="store_true",
+                    help="copy the bundled SKILL.md into the skills dir (default action)")
+    sk.add_argument("--dir", default=None,
+                    help="target skills dir (default ~/.claude/skills/screex)")
+    sk.add_argument("--path", action="store_true",
+                    help="print the install target path without writing")
+
+    args = p.parse_args(argv)
+    if args.cmd == "analyze":
+        path = analyze(args.video, fps=args.fps, cols=args.cols,
+                       sensitivity=args.sensitivity, edge=args.edge, out=args.out,
+                       cut_threshold=args.cut_threshold)
+        print(f"manifest: {path}")
+    elif args.cmd == "index":
+        path = index(args.recording, fps=args.fps, change_threshold=args.change_threshold,
+                     thumb_width=args.thumb_width, out=args.out)
+        print(f"index: {path}")
+    elif args.cmd == "capture":
+        out = source.capture_webcam(args.out, args.seconds)
+        print(f"captured: {out}")
+    elif args.cmd == "skill":
+        from screex import skill as skill_mod
+        target_dir = Path(args.dir) if args.dir else skill_mod.default_skill_dir()
+        if args.path:
+            print(target_dir / "SKILL.md")
+        else:
+            target = skill_mod.install_skill(args.dir)
+            print(f"installed skill: {target}")
+
+
+if __name__ == "__main__":
+    main()

screex/core/analyzer.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import numpy as np
+
+from screex.core.manifest import EventRecord
+
+
+def motion_score(prev_gray: np.ndarray, cur_gray: np.ndarray) -> float:
+    a = np.asarray(prev_gray, dtype=np.int16)
+    b = np.asarray(cur_gray, dtype=np.int16)
+    return float(np.abs(b - a).mean()) / 255.0
+
+
+def histogram_similarity(prev_gray, cur_gray, bins: int = 64) -> float:
+    a = np.asarray(prev_gray)
+    b = np.asarray(cur_gray)
+    if a.shape == b.shape and np.array_equal(a, b):
+        return 1.0
+    ha, _ = np.histogram(a, bins=bins, range=(0, 256))
+    hb, _ = np.histogram(b, bins=bins, range=(0, 256))
+    ha = ha.astype(np.float64)
+    hb = hb.astype(np.float64)
+    if ha.sum() > 0:
+        ha /= ha.sum()
+    if hb.sum() > 0:
+        hb /= hb.sum()
+    if ha.std() == 0 or hb.std() == 0:
+        return 1.0 if np.array_equal(ha, hb) else 0.0
+    corr = float(np.corrcoef(ha, hb)[0, 1])
+    return max(0.0, corr)
+
+
+def flag_events(scores, threshold: float):
+    return [s >= threshold for s in scores]
+
+
+def group_events(scores, times, flags):
+    events = []
+    n = len(flags)
+    i = 0
+    while i < n:
+        if not flags[i]:
+            i += 1
+            continue
+        j = i
+        while j + 1 < n and flags[j + 1]:
+            j += 1
+        peak = max(range(i, j + 1), key=lambda k: scores[k])
+        events.append(
+            EventRecord(
+                t_start=times[i],
+                t_end=times[j],
+                peak_frame=peak,
+                peak_score=scores[peak],
+            )
+        )
+        i = j + 1
+    return events
+
+
+def classify_events(events, similarities, cut_threshold: float = 0.5):
+    for e in events:
+        s = similarities[e.peak_frame]
+        if s < cut_threshold:
+            e.type = "cut"
+            e.confidence = round((cut_threshold - s) / cut_threshold, 3) if cut_threshold > 0 else 1.0
+        else:
+            denom = 1.0 - cut_threshold
+            e.type = "motion"
+            e.confidence = round((s - cut_threshold) / denom, 3) if denom > 0 else 1.0
+    return events

screex/core/index.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+
+
+@dataclass
+class ScreenState:
+    idx: int
+    t_start: float
+    t_end: float
+    thumbnail: str
+    keyframe: str
+    ocr_text: list = field(default_factory=list)
+    text_added: list = field(default_factory=list)
+    text_removed: list = field(default_factory=list)
+
+
+@dataclass
+class ScreenIndex:
+    video: str
+    duration: float
+    sampled_fps: float
+    states: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "video": self.video,
+            "duration": self.duration,
+            "sampled_fps": self.sampled_fps,
+            "states": [asdict(s) for s in self.states],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ScreenIndex":
+        return cls(
+            video=d["video"],
+            duration=d["duration"],
+            sampled_fps=d["sampled_fps"],
+            states=[ScreenState(**s) for s in d["states"]],
+        )
+
+    def save(self, path) -> None:
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path) -> "ScreenIndex":
+        return cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))

screex/core/manifest.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+
+
+@dataclass
+class FrameRecord:
+    idx: int
+    t: float
+    score: float
+    event: bool
+    ascii: str
+    png: str
+
+
+@dataclass
+class EventRecord:
+    t_start: float
+    t_end: float
+    peak_frame: int
+    peak_score: float
+    type: str = "motion"
+    confidence: float = 0.0
+
+
+@dataclass
+class Manifest:
+    video: str
+    duration: float
+    sampled_fps: float
+    cols: int
+    frames: list = field(default_factory=list)
+    events: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "video": self.video,
+            "duration": self.duration,
+            "sampled_fps": self.sampled_fps,
+            "cols": self.cols,
+            "frames": [asdict(f) for f in self.frames],
+            "events": [asdict(e) for e in self.events],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Manifest":
+        return cls(
+            video=d["video"],
+            duration=d["duration"],
+            sampled_fps=d["sampled_fps"],
+            cols=d["cols"],
+            frames=[FrameRecord(**f) for f in d["frames"]],
+            events=[EventRecord(**e) for e in d["events"]],
+        )
+
+    def save(self, path) -> None:
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path) -> "Manifest":
+        return cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))

screex/core/mapper.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import numpy as np
+
+RAMP = " .:-=+*#%@"
+
+
+def gray_to_ascii(gray: np.ndarray, ramp: str = RAMP) -> str:
+    arr = np.asarray(gray, dtype=np.uint16)
+    n = len(ramp) - 1
+    idx = (arr * n // 255).astype(np.intp)
+    lut = np.array(list(ramp))
+    chars = lut[idx]
+    return "\n".join("".join(row) for row in chars)
+
+
+def auto_rows(width: int, height: int, cols: int, char_aspect: float = 2.0) -> int:
+    return max(1, round(cols * (height / width) / char_aspect))
+
+
+def edge_magnitude(gray: np.ndarray) -> np.ndarray:
+    g = np.asarray(gray, dtype=np.float32)
+    gy, gx = np.gradient(g)
+    mag = np.hypot(gx, gy)
+    peak = float(mag.max())
+    if peak > 0:
+        mag = mag / peak * 255.0
+    return mag.astype(np.uint8)
+
+
+def frame_to_ascii(gray: np.ndarray, cols: int, ramp: str = RAMP, edge: bool = False) -> str:
+    import cv2
+
+    h, w = gray.shape[:2]
+    rows = auto_rows(w, h, cols)
+    small = cv2.resize(gray, (cols, rows), interpolation=cv2.INTER_AREA)
+    if edge:
+        small = edge_magnitude(small)
+    return gray_to_ascii(small, ramp)

screex/core/ocr.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+_engine = None
+
+
+def _get_engine():
+    global _engine
+    if _engine is None:
+        from rapidocr_onnxruntime import RapidOCR
+        _engine = RapidOCR()
+    return _engine
+
+
+def extract_text(bgr) -> list:
+    """Return on-screen text lines from a BGR frame, in reading order (top->bottom, left->right)."""
+    engine = _get_engine()
+    result, _ = engine(bgr)
+    if not result:
+        return []
+
+    def sort_key(item):
+        box = item[0]  # 4 corner points [[x,y],...]
+        ys = [p[1] for p in box]
+        xs = [p[0] for p in box]
+        return (round(min(ys) / 10.0), min(xs))
+
+    ordered = sorted(result, key=sort_key)
+    return [str(item[1]).strip() for item in ordered if str(item[1]).strip()]
+
+
+def text_diff(prev_lines, cur_lines):
+    """Return (added, removed): lines in cur not in prev, and lines in prev not in cur."""
+    prev_set = set(prev_lines)
+    cur_set = set(cur_lines)
+    added = [line for line in cur_lines if line not in prev_set]
+    removed = [line for line in prev_lines if line not in cur_set]
+    return added, removed

screex/core/segment.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from screex.core.analyzer import motion_score
+
+
+@dataclass
+class Segment:
+    idx: int
+    t_start: float
+    t_end: float
+    frame_bgr: object  # numpy BGR array: the settled keyframe of this UI state
+
+
+def segment_stream(frames, change_threshold: float = 0.04):
+    """Yield one Segment per UI state. A new state begins when frame-to-frame motion
+    crosses change_threshold; the representative keyframe is the last (settled) frame
+    of the state. Holds only the current state's last frame (memory-bounded)."""
+    import cv2
+
+    prev_gray = None
+    seg_idx = 0
+    cur_start_t = None
+    last_t = None
+    last_bgr = None
+
+    for idx, t, bgr in frames:
+        gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
+        if prev_gray is None:
+            cur_start_t = t
+        elif motion_score(prev_gray, gray) >= change_threshold:
+            yield Segment(seg_idx, cur_start_t, last_t, last_bgr)
+            seg_idx += 1
+            cur_start_t = t
+        prev_gray = gray
+        last_t = t
+        last_bgr = bgr
+
+    if last_bgr is not None:
+        yield Segment(seg_idx, cur_start_t, last_t, last_bgr)

screex/core/source.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+
+def _open(path):
+    import cv2
+
+    cap = cv2.VideoCapture(str(path))
+    if not cap.isOpened():
+        raise FileNotFoundError(f"cannot open video: {path}")
+    return cap
+
+
+def video_info(path: str) -> dict:
+    import cv2
+
+    cap = _open(path)
+    try:
+        fps = cap.get(cv2.CAP_PROP_FPS) or 0.0
+        count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+        w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
+        h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
+    finally:
+        cap.release()
+    duration = count / fps if fps else 0.0
+    return {"fps": fps, "count": count, "width": w, "height": h, "duration": duration}
+
+
+def iter_frames(path: str, sample_fps: float):
+    cap = _open(path)
+    import cv2
+
+    native = cap.get(cv2.CAP_PROP_FPS) or sample_fps or 1.0
+    step = max(1, round(native / sample_fps)) if sample_fps else 1
+    raw_idx = 0
+    out_idx = 0
+    try:
+        while True:
+            if not cap.grab():
+                break
+            if raw_idx % step == 0:
+                ok, frame = cap.retrieve()
+                if not ok:
+                    break
+                yield out_idx, raw_idx / native, frame
+                out_idx += 1
+            raw_idx += 1
+    finally:
+        cap.release()
+
+
+def capture_webcam(out_path: str, seconds: float, fps: float = 15.0, device: int = 0) -> str:
+    """Record a short clip from the default webcam into out_path. Manual/hardware path."""
+    import cv2
+
+    cap = cv2.VideoCapture(device)
+    if not cap.isOpened():
+        raise RuntimeError("cannot open webcam")
+    w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) or 640
+    h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) or 480
+    fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+    writer = cv2.VideoWriter(str(out_path), fourcc, fps, (w, h))
+    try:
+        for _ in range(int(seconds * fps)):
+            ok, frame = cap.read()
+            if not ok:
+                break
+            writer.write(frame)
+    finally:
+        cap.release()
+        writer.release()
+    return str(out_path)

screex/skill.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def skill_text() -> str:
+    """Return the bundled SKILL.md content (shipped as package data)."""
+    from importlib.resources import files
+
+    return (files("screex") / "SKILL.md").read_text(encoding="utf-8")
+
+
+def default_skill_dir() -> Path:
+    """Default Claude Code skill directory for Screex (~/.claude/skills/screex)."""
+    return Path.home() / ".claude" / "skills" / "screex"
+
+
+def install_skill(dest_dir=None) -> Path:
+    """Write the bundled SKILL.md into a skills directory; return the written file path."""
+    target_dir = Path(dest_dir) if dest_dir else default_skill_dir()
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / "SKILL.md"
+    target.write_text(skill_text(), encoding="utf-8")
+    return target

screex-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: screex
+Version: 0.1.0
+Summary: Screen-recording understanding: turn a screencast into a queryable index of UI states for transcripts, Q&A, and how-to / bug-report generation.
+Author-email: Rushikesh Hiray <rhiray03@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/blueprintparadise/Screex
+Project-URL: Repository, https://github.com/blueprintparadise/Screex
+Project-URL: Issues, https://github.com/blueprintparadise/Screex/issues
+Keywords: screen-recording,screencast,ocr,llm,claude,claude-skill,agents,video-understanding,ui-understanding
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python
+Requires-Dist: numpy
+Requires-Dist: rapidocr-onnxruntime
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# Screex
+
+**Screen-recording understanding for agents.** Screex turns a screencast into a queryable
+**index** of UI states — each with the on-screen text (OCR), what text changed since the
+previous state, a thumbnail, and a full-resolution keyframe — so an LLM/agent can produce an
+action transcript, answer questions, or generate a how-to guide / bug report from a recording.
+
+- **Training-free & model-agnostic** — no fine-tuned UI model; any LLM can read the index.
+- **`pip install`-only** — OCR via [`rapidocr-onnxruntime`](https://pypi.org/project/rapidocr-onnxruntime/), no system binaries.
+- **Cheap by design** — the on-screen text is plain text (nearly free to read); full-res
+  keyframes are escalated to only when the text is insufficient.
+
+---
+
+## Install
+
+### From PyPI
+```bash
+pip install screex
+```
+
+### From source
+```bash
+git clone https://github.com/blueprintparadise/Screex.git
+cd Screex
+pip install -e .          # add ".[test]" to also install pytest
+```
+
+Both give you a `screex` command (entry point `screex.cli:main`). Requires Python ≥ 3.9.
+First run downloads the small RapidOCR ONNX models automatically.
+
+---
+
+## Quickstart (CLI)
+
+```bash
+# Build the index for a screen recording
+screex index path/to/recording.mp4 --fps 2
+#   (or, without installing the package:)
+python -m screex.cli index path/to/recording.mp4 --fps 2
+```
+
+This writes:
+```
+path/to/recording.screex/
+  index.json            # the ScreenIndex (ordered UI states)
+  frames/00000.png      # full-res keyframe per state
+  frames/00000_thumb.png# thumbnail per state
+  ...
+```
+
+### `index` options
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--fps` | `2` | frames sampled per second (raise for fast-moving recordings) |
+| `--change-threshold` | `0.04` | visual-change fraction (0–1) that starts a new UI state — lower = more states, higher = fewer |
+| `--thumb-width` | `320` | thumbnail width in px |
+| `--out` | `<recording>.screex` | output directory |
+
+### What `index.json` contains
+An ordered list of `states`, each with:
+`t_start` / `t_end`, `ocr_text` (on-screen text lines), `text_added` / `text_removed`
+(text that appeared/disappeared vs the previous state — the strongest signal of what the user
+did), and `thumbnail` / `keyframe` paths.
+
+---
+
+## Use as a Claude skill
+
+Screex ships a `SKILL.md` that teaches Claude to build the index and turn it into one of three
+views: an **action transcript**, **Q&A** over the recording, or a **how-to / bug report**.
+
+1. **Install the package** so `python -m screex.cli` is available in the environment Claude
+   uses (`pip install -e .`).
+2. **Install the skill** — the package bundles `SKILL.md`, so one command installs it where
+   Claude Code discovers skills:
+   ```bash
+   screex skill --install                                          # ~/.claude/skills/screex/
+   screex skill --install --dir <project>/.claude/skills/screex    # per-project
+   screex skill --path                                             # just print the target path
+   ```
+3. **Use it** — in Claude Code, just ask in natural language, e.g.:
+   - *"Use screex to turn `~/Downloads/bug-repro.mp4` into a bug report."*
+   - *"What steps does this screen recording show?"*
+   - *"From this demo, write a how-to doc."*
+
+   Claude runs `screex index`, reads `index.json`, skims the on-screen text across states, and
+   escalates to a full-res keyframe only when the text isn't enough — then produces the
+   transcript / answer / document.
+
+> The skill is model-agnostic: the same `index.json` can be read by any LLM/agent, not only
+> Claude.
+
+---
+
+## How it works
+
+```
+recording → sample frames → segment into UI states → per state: OCR text + text-diff
+          → write thumbnail + full-res keyframe → index.json
+                                                      ↓
+            views (agent-driven): transcript · Q&A · how-to / bug report
+```
+
+`screex/core/`:
+- `source` — decode & sample frames (OpenCV)
+- `segment` — group frames into settled UI states by visual change
+- `ocr` — RapidOCR text extraction + text-diff between states
+- `index` — the `ScreenState` / `ScreenIndex` schema (JSON)
+
+`screex/cli.py` wires them into the `screex index` command.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest -q
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Rushikesh Hiray

screex-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+screex/SKILL.md,sha256=vQainJuBGt1U8xLaNF530fOf3mpmskkgKQQ0eqU2AdA,2464
+screex/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+screex/cli.py,sha256=OOjTAwVQhD58aLlHZMrwPjoX6fzHI4ztvzw950LScZI,6765
+screex/skill.py,sha256=sp_dgWDMxfLQHdFq42IA0xXN7Rq_sAycSiQhfzil7RI,814
+screex/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+screex/core/analyzer.py,sha256=SFTZqgvc22kMGi2XzuWUeGqcHgUi-F8krbtp5swmsQA,2064
+screex/core/index.py,sha256=rb17ooCSLTGe1GhbAXPe3in3gHj6yRP_nXN65vVKBvA,1290
+screex/core/manifest.py,sha256=577LQKggjVZ9E05tucz1x5TwgJnrHGgZuCdkFjcm1xw,1528
+screex/core/mapper.py,sha256=5sJxZx2KLIA5lrQ_eyCPw4YHtjMnwYw-0Q2IEVI4Its,1098
+screex/core/ocr.py,sha256=F-n7fLAE9kmh-t4Y-cgx299hiWGTIZ4J12ICkb37vEc,1102
+screex/core/segment.py,sha256=Wrf9j6IrbQNrq6wwJvcytSzc0s9PsCgU_KFACF9PrFY,1187
+screex/core/source.py,sha256=4pMBZwnb9tXqVNSsOczfi5Xv-bjrHCmaFwdQ80Te8fQ,2068
+screex-0.1.0.dist-info/licenses/LICENSE,sha256=MdvXhyva5tRpxRdCOqEVZeLX5-TsdhfRyhJjHwr-nwQ,1072
+screex-0.1.0.dist-info/METADATA,sha256=dx6F_5fsAwflitY34KPL7thIo-vH5wYwgW1k5o0oPwc,5573
+screex-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+screex-0.1.0.dist-info/entry_points.txt,sha256=6JxbGLdyll0xXosUweomxCp2fhJgwQf5qL8N5_nzcxg,43
+screex-0.1.0.dist-info/top_level.txt,sha256=VC_6j_HPuiRzlDg30hmAbnIsk99zAiR5sZDSztde1ew,7
+screex-0.1.0.dist-info/RECORD,,

screex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

screex-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+screex = screex.cli:main

screex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rushikesh Hiray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

screex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+screex