screex 0.1.0__tar.gz

screex-0.1.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include screex/SKILL.md

screex-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,126 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "screex"
+version = "0.1.0"
+description = "Screen-recording understanding: turn a screencast into a queryable index of UI states for transcripts, Q&A, and how-to / bug-report generation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Rushikesh Hiray", email = "rhiray03@gmail.com" }]
+keywords = [
+    "screen-recording",
+    "screencast",
+    "ocr",
+    "llm",
+    "claude",
+    "claude-skill",
+    "agents",
+    "video-understanding",
+    "ui-understanding",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "opencv-python",
+    "numpy",
+    "rapidocr-onnxruntime",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+screex = "screex.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/blueprintparadise/Screex"
+Repository = "https://github.com/blueprintparadise/Screex"
+Issues = "https://github.com/blueprintparadise/Screex/issues"
+
+[tool.setuptools]
+packages = ["screex", "screex.core"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+screex = ["SKILL.md"]

screex-0.1.0/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-0.1.0/screex/__init__.py

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

screex-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-0.1.0/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-0.1.0/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")))