bug2context 0.1.0__py3-none-any.whl

bug2context/pipeline/assemble.py

@@ -0,0 +1,216 @@
+"""Stages 6-7: merge the timelines and write the output bundle."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..config import Config
+from .frames import FFmpegError, Frame, dedupe, extract_frames, probe_duration
+from .audio import transcribe
+from .logs import load_events
+from .ocr import available_backend, read_text, relevant_lines
+
+
+def format_timestamp(seconds: float) -> str:
+    """Seconds to MM:SS — the form used in the report timeline."""
+    minutes, secs = divmod(int(seconds), 60)
+    return f"{minutes:02d}:{secs:02d}"
+
+
+HELD_THRESHOLD = 5.0
+"""Below this, a screen simply had nothing to do; above it, it is worth saying.
+
+How long a state lasted is part of what happened, and the timeline cannot say
+it any other way: on a real capture whose last frame stood for 100 seconds, a
+list that stopped at 00:37 read as if the recording had ended there. Reporting
+the duration lets the reader judge whether that stillness means anything.
+"""
+
+
+def _describe_hold(seconds: float) -> str:
+    minutes, secs = divmod(int(seconds), 60)
+    return f"{minutes}m{secs:02d}s" if minutes else f"{secs}s"
+
+
+def _publish_frames(
+    kept: list[Frame], frames_dir: Path, cfg: Config, duration: float | None = None
+) -> tuple[list[dict], str | None]:
+    """Copy kept frames to their final names, OCR them, return their metadata."""
+    if frames_dir.exists():
+        shutil.rmtree(frames_dir)
+    frames_dir.mkdir(parents=True)
+
+    backend = available_backend() if cfg.ocr else None
+    published: list[dict] = []
+    previous_text: list[str] = []
+
+    for i, frame in enumerate(kept, start=1):
+        ends_at = kept[i].timestamp if i < len(kept) else duration
+        held = (ends_at - frame.timestamp) if ends_at is not None else 0.0
+        stamp = format_timestamp(frame.timestamp).replace(":", "-")
+        name = f"frame_{i:03d}_{stamp}.png"
+        shutil.copy2(frame.path, frames_dir / name)
+
+        text: list[str] = []
+        if backend:
+            text = read_text(frame.path, cfg.ocr_upscale, backend)
+
+        published.append({
+            "index": i,
+            "timestamp": round(frame.timestamp, 3),
+            "time": format_timestamp(frame.timestamp),
+            "change": int(frame.change),
+            "file": f"frames/{name}",
+            "held": round(held, 1),
+            "text": text,
+            "highlights": relevant_lines(text, previous_text, cfg.ocr_max_lines),
+        })
+        if text:
+            previous_text = text
+
+    return published, backend
+
+
+_KIND_ORDER = {"frame": 0, "log": 1, "speech": 2}
+
+
+def merge_timeline(
+    frames: list[dict], speech: list[dict], logs: list[dict] | None = None
+) -> list[dict]:
+    """Interleave the streams into one clock-ordered list.
+
+    On a tie the frame comes first, then logs, then narration: the picture is
+    what the other two are describing, and a log explains the frame more
+    directly than someone saying "look, it broke".
+    """
+    events = [{**f, "kind": "frame"} for f in frames]
+    events += [{**s, "kind": "speech"} for s in speech]
+    events += [{**entry, "kind": "log"} for entry in logs or []]
+    return sorted(events, key=lambda e: (e["timestamp"], _KIND_ORDER[e["kind"]]))
+
+
+def render_report(
+    video: Path,
+    duration: float | None,
+    frames: list[dict],
+    speech: list[dict] | None = None,
+    logs: list[dict] | None = None,
+) -> str:
+    """Chronological markdown an agent can read top to bottom."""
+    speech, logs = speech or [], logs or []
+    header = [
+        f"# Bug context — {video.name}",
+        "",
+        f"- Source: `{video}`",
+        f"- Duration: {format_timestamp(duration)}" if duration else "- Duration: unknown",
+        f"- Key frames: {len(frames)}",
+    ]
+    if speech:
+        header.append(f"- Narration segments: {len(speech)}")
+    if logs:
+        header.append(f"- Log entries: {len(logs)}")
+    header += ["", "## Timeline", ""]
+
+    if not (frames or speech or logs):
+        return "\n".join([*header, "_Nothing extracted._", ""])
+
+    lines = []
+    for event in merge_timeline(frames, speech, logs):
+        if event["kind"] == "frame":
+            reason = "start of recording" if event["index"] == 1 else "screen changed"
+            held = event.get("held", 0)
+            if held >= HELD_THRESHOLD:
+                reason += f", then unchanged for {_describe_hold(held)}"
+            lines.append(f"- `[{event['time']}]` 🖼 `{event['file']}` — {reason}")
+            for text in event.get("highlights", []):
+                lines.append(f"      OCR: {text}")
+        elif event["kind"] == "log":
+            repeats = event.get("repeats", 1)
+            suffix = f" (×{repeats})" if repeats > 1 else ""
+            lines.append(
+                f"- `[{event['time']}]` 📋 {event['level']}/{event['tag']}: "
+                f"{event['message']}{suffix}"
+            )
+        else:
+            lines.append(f"- `[{event['time']}]` 🎙 \"{event['text']}\"")
+    return "\n".join([*header, *lines, ""])
+
+
+def build_bundle(video: Path, out_dir: Path, cfg: Config) -> Path:
+    """Run the video pipeline end to end. Returns the path to report.md."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    raw_dir = out_dir / ".raw"
+
+    duration = probe_duration(video)
+    if cfg.max_duration and duration and duration > cfg.max_duration:
+        raise FFmpegError(
+            f"{video.name} runs {duration / 60:.0f} min, over the "
+            f"{cfg.max_duration / 60:.0f} min guard — it would spend longer "
+            "decoding than you want to wait.\n"
+            "Trim to the part that matters:\n"
+            f'  ffmpeg -i "{video}" -ss 00:00:00 -t 120 -c copy trimmed.mp4\n'
+            "Or pass --max-duration 0 to process it anyway."
+        )
+
+    frames = extract_frames(video, raw_dir, cfg)
+    kept = dedupe(frames, cfg)
+    entries, backend = _publish_frames(kept, out_dir / "frames", cfg, duration)
+    shutil.rmtree(raw_dir, ignore_errors=True)
+
+    speech: list[dict] = []
+    if cfg.transcribe:
+        speech = [
+            {
+                "timestamp": s.start,
+                "time": format_timestamp(s.start),
+                "end": s.end,
+                "text": s.text,
+            }
+            for s in transcribe(video, cfg.whisper_model, cfg.language)
+        ]
+
+    logs: list[dict] = []
+    if cfg.logcat_path:
+        started_at = (
+            datetime.fromisoformat(cfg.video_started_at)
+            if cfg.video_started_at
+            else None
+        )
+        logs = [
+            {
+                "timestamp": round(offset, 3),
+                "time": format_timestamp(offset),
+                "level": line.level,
+                "tag": line.tag,
+                "message": line.message,
+                "pid": line.pid,
+                "repeats": line.repeats,
+            }
+            for offset, line in load_events(
+                Path(cfg.logcat_path).expanduser(), started_at, duration,
+                cfg.log_levels, cfg.log_tag, cfg.log_offset,
+                pid=cfg.log_pid, limit=cfg.log_max_lines,
+            )
+        ]
+
+    report = render_report(video, duration, entries, speech, logs)
+    report_path = out_dir / "report.md"
+    report_path.write_text(report)
+
+    (out_dir / "meta.json").write_text(json.dumps({
+        "video": str(video),
+        "duration": duration,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "config": asdict(cfg),
+        "ocr_backend": backend,
+        "frames_examined": len(frames),
+        "frames": entries,
+        "speech": speech,
+        "logs": logs,
+    }, indent=2))
+
+    return report_path

bug2context/pipeline/audio.py

@@ -0,0 +1,94 @@
+"""Stage 4: turn spoken narration into timestamped text.
+
+Optional at every step: no audio track, a silent track, or no faster-whisper
+installed all degrade to "no narration" rather than failing the run.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+_MEAN_VOLUME = re.compile(r"mean_volume:\s*(-?\d+(?:\.\d+)?) dB")
+
+
+@dataclass(frozen=True)
+class Speech:
+    """One spoken segment, positioned on the video clock."""
+
+    start: float
+    end: float
+    text: str
+
+
+def whisper_available() -> bool:
+    try:
+        import faster_whisper  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def has_audio_track(video: Path) -> bool:
+    if shutil.which("ffprobe") is None:
+        return False
+    proc = subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "a",
+         "-show_entries", "stream=index", "-of", "csv=p=0", str(video)],
+        capture_output=True, text=True,
+    )
+    return bool(proc.stdout.strip())
+
+
+def mean_volume_db(video: Path) -> float | None:
+    """Average loudness of the audio track, or None if it cannot be measured."""
+    proc = subprocess.run(
+        ["ffmpeg", "-hide_banner", "-nostdin", "-i", str(video),
+         "-af", "volumedetect", "-f", "null", "-"],
+        capture_output=True, text=True,
+    )
+    match = _MEAN_VOLUME.search(proc.stderr)
+    return float(match.group(1)) if match else None
+
+
+def is_silent(video: Path, threshold_db: float = -50.0) -> bool:
+    """Whether the track is quiet enough that transcribing it is wasted work.
+
+    Whisper hallucinates confident sentences out of silence, so this guard is
+    about output quality, not only speed.
+    """
+    volume = mean_volume_db(video)
+    return volume is None or volume < threshold_db
+
+
+def extract_audio(video: Path, out_wav: Path) -> Path:
+    """Write the audio track as 16 kHz mono WAV — what whisper wants anyway."""
+    out_wav.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["ffmpeg", "-hide_banner", "-nostdin", "-y", "-i", str(video),
+         "-vn", "-ac", "1", "-ar", "16000", str(out_wav)],
+        capture_output=True, text=True, check=True,
+    )
+    return out_wav
+
+
+def transcribe(
+    video: Path, model_size: str = "small", language: str | None = None
+) -> list[Speech]:
+    """Timestamped narration. Empty when there is nothing worth transcribing."""
+    if not whisper_available() or not has_audio_track(video) or is_silent(video):
+        return []
+
+    from faster_whisper import WhisperModel
+
+    model = WhisperModel(model_size, device="cpu", compute_type="int8")
+    segments, _ = model.transcribe(str(video), language=language, vad_filter=True)
+
+    return [
+        Speech(round(s.start, 3), round(s.end, 3), s.text.strip())
+        for s in segments
+        if s.text.strip()
+    ]

bug2context/pipeline/frames.py

@@ -0,0 +1,185 @@
+"""Stages 1-2: extract candidate frames from a video, then deduplicate them."""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+import imagehash
+from PIL import Image
+
+from ..config import Config
+
+_PTS_TIME = re.compile(r"pts_time:(\d+(?:\.\d+)?)")
+
+SECONDS_PER_FRAME = 2.0
+MIN_FRAME_BUDGET = 20
+MAX_FRAME_BUDGET = 40
+"""Bounds on the automatic frame budget.
+
+Below the minimum a short recording loses states it barely has; above the
+maximum OCR alone would run over a minute, since Vision charges a flat ~1.6 s
+per frame regardless of size.
+"""
+
+
+def frame_budget(span: float, configured: int | None) -> int:
+    """How many frames to publish for a recording of `span` seconds."""
+    if configured is not None:
+        return configured
+    scaled = round(span / SECONDS_PER_FRAME)
+    return int(min(MAX_FRAME_BUDGET, max(MIN_FRAME_BUDGET, scaled)))
+
+
+@dataclass(frozen=True)
+class Frame:
+    """A candidate frame: its position in the video and where it was written."""
+
+    timestamp: float
+    path: Path
+    change: int = 0
+    """Perceptual distance from the previously kept frame; 0 for the first."""
+
+
+class FFmpegError(RuntimeError):
+    pass
+
+
+def require_ffmpeg() -> None:
+    if shutil.which("ffmpeg") is None:
+        raise FFmpegError(
+            "ffmpeg not found on PATH. Install it (macOS: brew install ffmpeg)."
+        )
+
+
+def probe_duration(video: Path) -> float | None:
+    """Video duration in seconds, or None if ffprobe is unavailable/fails."""
+    if shutil.which("ffprobe") is None:
+        return None
+    proc = subprocess.run(
+        ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+         "-of", "default=nw=1:nk=1", str(video)],
+        capture_output=True, text=True,
+    )
+    try:
+        return float(proc.stdout.strip())
+    except ValueError:
+        return None
+
+
+def _select_expr(cfg: Config) -> str:
+    # `+` is OR here: first frame, OR a scene cut, OR interval elapsed since the
+    # last kept frame. The interval fills gaps in screens that animate slowly.
+    return (
+        f"isnan(prev_selected_t)"
+        f"+gt(scene,{cfg.scene_threshold})"
+        f"+gte(t-prev_selected_t,{cfg.interval_seconds})"
+    )
+
+
+def extract_frames(video: Path, out_dir: Path, cfg: Config) -> list[Frame]:
+    """Write candidate frames as PNGs into out_dir, ordered by timestamp."""
+    require_ffmpeg()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for stale in out_dir.glob("raw_*.png"):
+        stale.unlink()
+
+    proc = subprocess.run(
+        [
+            "ffmpeg", "-hide_banner", "-nostdin", "-y",
+            "-i", str(video),
+            "-vf", f"select='{_select_expr(cfg)}',showinfo",
+            # passthrough, not vfr: vfr drops frames whose timestamps collide
+            # after rounding, and screen recorders emit variable frame rate. On
+            # a real 720x1612 adb capture that silently lost 29 of 118 frames.
+            "-fps_mode", "passthrough",
+            str(out_dir / "raw_%04d.png"),
+        ],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        raise FFmpegError(f"ffmpeg failed on {video}:\n{proc.stderr[-2000:]}")
+
+    timestamps = [float(m) for m in _PTS_TIME.findall(proc.stderr)]
+    paths = sorted(out_dir.glob("raw_*.png"))
+    if len(timestamps) != len(paths):
+        # showinfo logs one line per emitted frame; a mismatch means we cannot
+        # trust the pairing, and wrong timestamps are worse than none.
+        raise FFmpegError(
+            f"timestamp/frame mismatch: {len(timestamps)} pts_time vs {len(paths)} files"
+        )
+    return [Frame(ts, p) for ts, p in zip(timestamps, paths)]
+
+
+def dedupe(frames: list[Frame], cfg: Config) -> list[Frame]:
+    """Drop near-identical frames, then cap to the most visually distinct ones.
+
+    Scene cuts and interval sampling both over-produce: a static screen sampled
+    every 3 s yields the same picture repeatedly. Perceptual hashing collapses
+    those, and the leftover distance doubles as a "how much changed" score for
+    the cap, so no separate scene-score bookkeeping is needed.
+    """
+    if not frames:
+        return []
+
+    hashes = [imagehash.phash(Image.open(f.path)) for f in frames]
+    kept = [frames[0]]
+    last = 0
+    for i in range(1, len(frames)):
+        distance = hashes[i] - hashes[last]
+        if distance > cfg.phash_distance:
+            kept.append(Frame(frames[i].timestamp, frames[i].path, distance))
+            last = i
+
+    # The last candidate's timestamp is the recording's span, near enough to
+    # its duration and already at hand — no need to probe the file again.
+    limit = frame_budget(frames[-1].timestamp, cfg.max_frames)
+    if len(kept) <= limit:
+        return kept
+    return _spread_over_time(kept, limit)
+
+
+def _spread_over_time(kept: list[Frame], limit: int) -> list[Frame]:
+    """Trim to `limit` frames while still covering the whole recording.
+
+    Ranking purely by how much changed sounds right and fails badly: an app
+    with a live map animates constantly, so on a real 143 s capture the top 20
+    changes all landed in the first 27 s and the remaining 100 s went
+    unrepresented. The reader could not tell whether nothing happened or
+    nothing was captured.
+
+    Deciding which moment matters is the reader's job, not this function's.
+    The budget is therefore split into equal time windows, taking the
+    most-changed frame of each, so the report describes the whole recording.
+    Windows that hold nothing give their slot back to the most-changed frames
+    still unused.
+    """
+    first, rest = kept[0], kept[1:]
+    slots = limit - 1
+    if slots <= 0:
+        return [first]
+
+    span = rest[-1].timestamp - first.timestamp
+    if span <= 0:
+        return [first, *rest[:slots]]
+
+    windows: dict[int, Frame] = {}
+    for frame in rest:
+        index = min(int((frame.timestamp - first.timestamp) / span * slots), slots - 1)
+        if index not in windows or frame.change > windows[index].change:
+            windows[index] = frame
+
+    chosen = list(windows.values())
+    if len(chosen) < slots:
+        picked = {id(frame) for frame in chosen}
+        spare = sorted(
+            (f for f in rest if id(f) not in picked),
+            key=lambda f: f.change,
+            reverse=True,
+        )
+        chosen += spare[: slots - len(chosen)]
+
+    return sorted([first, *chosen], key=lambda f: f.timestamp)

bug2context/pipeline/logs.py

@@ -0,0 +1,187 @@
+"""Stage 5: put device logs on the video's clock.
+
+logcat timestamps are wall clock and carry no year; the video clock starts at
+zero. Aligning them is the whole job — a stack trace is only useful if it lands
+next to the frame that shows the crash.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+from datetime import datetime
+from pathlib import Path
+
+# `-v time`:       08-04 07:45:12.345 E/RideService( 1234): boom
+# `-v threadtime`: 08-04 07:45:12.345  1234  1250 E RideService: boom
+_TIME = re.compile(
+    r"^(?P<date>\d{2}-\d{2})\s+(?P<clock>\d{2}:\d{2}:\d{2}\.\d{3})\s+"
+    r"(?P<level>[VDIWEFS])/(?P<tag>[^(]+?)\s*\(\s*(?P<pid>\d+)\s*\):\s?(?P<message>.*)$"
+)
+_THREADTIME = re.compile(
+    r"^(?P<date>\d{2}-\d{2})\s+(?P<clock>\d{2}:\d{2}:\d{2}\.\d{3})\s+"
+    r"(?P<pid>\d+)\s+\d+\s+(?P<level>[VDIWEFS])\s+(?P<tag>\S+?)\s*:\s?(?P<message>.*)$"
+)
+
+DEFAULT_LEVELS = "WEF"
+_SEVERITY = "VDIWEFS"
+
+
+@dataclass(frozen=True)
+class LogLine:
+    """One device log entry, still on wall-clock time."""
+
+    when: datetime
+    level: str
+    tag: str
+    message: str
+    pid: int = 0
+    repeats: int = 1
+    """How many identical entries in a row this one stands for."""
+
+
+def parse_logcat(text: str, year: int | None = None) -> list[LogLine]:
+    """Parse `-v time` or `-v threadtime` output, skipping anything else.
+
+    logcat omits the year, so one is assumed — pass it explicitly when
+    processing a recording from a previous year.
+    """
+    year = year or datetime.now().year
+    lines: list[LogLine] = []
+
+    for raw in text.splitlines():
+        match = _THREADTIME.match(raw) or _TIME.match(raw)
+        if not match:
+            continue  # banners like "--------- beginning of main"
+        try:
+            when = datetime.strptime(
+                f"{year}-{match['date']} {match['clock']}", "%Y-%m-%d %H:%M:%S.%f"
+            )
+        except ValueError:
+            continue
+        lines.append(
+            LogLine(
+                when,
+                match["level"],
+                match["tag"].strip(),
+                match["message"],
+                int(match["pid"]),
+            )
+        )
+    return lines
+
+
+# A crash report from the app's own runtime, even when it is another process.
+_ALWAYS_KEEP_TAGS = frozenset({"AndroidRuntime", "DEBUG"})
+
+
+def filter_lines(
+    lines: list[LogLine],
+    levels: str = DEFAULT_LEVELS,
+    tag: str | None = None,
+    pid: int | None = None,
+) -> list[LogLine]:
+    """Keep entries at or above the given levels, optionally by tag or process.
+
+    Level alone is not enough on a real device: a 2 min capture from a phone
+    held 7,634 W/E/F lines, none of them from the app under test. `pid` is what
+    scopes the report to the app — measured 35 lines for the same capture.
+    """
+    wanted = {level.upper() for level in levels}
+    floor = min((_SEVERITY.index(level) for level in wanted), default=0)
+    needle = tag.casefold() if tag else None
+
+    return [
+        line
+        for line in lines
+        if _SEVERITY.index(line.level) >= floor
+        and (needle is None or needle in line.tag.casefold())
+        and (pid is None or line.pid == pid or line.tag in _ALWAYS_KEEP_TAGS)
+    ]
+
+
+def collapse_repeats(
+    events: list[tuple[float, LogLine]]
+) -> list[tuple[float, LogLine]]:
+    """Fold consecutive identical entries into one carrying a count.
+
+    Framework chatter arrives in bursts — one real capture had the same Flogger
+    warning 15 times in a single second. Printing it 15 times says nothing the
+    first line did not, and buries the entries that matter.
+    """
+    folded: list[tuple[float, LogLine]] = []
+    for offset, line in events:
+        if folded:
+            _, previous = folded[-1]
+            if (previous.level, previous.tag, previous.message) == (
+                line.level, line.tag, line.message
+            ):
+                folded[-1] = (
+                    folded[-1][0],
+                    replace(previous, repeats=previous.repeats + 1),
+                )
+                continue
+        folded.append((offset, line))
+    return folded
+
+
+def cap_lines(lines: list[LogLine], limit: int) -> list[LogLine]:
+    """Trim to the most severe entries, then restore chronological order.
+
+    A blind head(limit) on a busy device returns the first seconds of system
+    boot chatter and none of the crash.
+    """
+    if limit <= 0 or len(lines) <= limit:
+        return lines
+    severest = sorted(lines, key=lambda l: _SEVERITY.index(l.level), reverse=True)
+    return sorted(severest[:limit], key=lambda l: l.when)
+
+
+def align_to_video(
+    lines: list[LogLine], video_started_at: datetime, offset: float = 0.0
+) -> list[tuple[float, LogLine]]:
+    """Convert wall clock to seconds-into-the-video.
+
+    `offset` is the manual escape for when the device clock and the recorder
+    disagree: positive shifts logs later in the video.
+    """
+    positioned = [
+        ((line.when - video_started_at).total_seconds() + offset, line)
+        for line in lines
+    ]
+    return sorted(
+        (item for item in positioned if item[0] >= 0), key=lambda item: item[0]
+    )
+
+
+def load_events(
+    logcat_path: Path,
+    video_started_at: datetime | None,
+    duration: float | None = None,
+    levels: str = DEFAULT_LEVELS,
+    tag: str | None = None,
+    offset: float = 0.0,
+    year: int | None = None,
+    pid: int | None = None,
+    limit: int = 0,
+) -> list[tuple[float, LogLine]]:
+    """Read a logcat file and return entries positioned on the video clock.
+
+    Without a recording start time there is nothing to align against, so the
+    first log entry is assumed to be the moment recording began.
+    """
+    parsed = parse_logcat(logcat_path.read_text(errors="replace"), year)
+    lines = filter_lines(parsed, levels, tag, pid)
+    if not lines:
+        return []
+
+    anchor = video_started_at or min(line.when for line in lines)
+    events = align_to_video(lines, anchor, offset)
+    if duration is not None:
+        events = [item for item in events if item[0] <= duration + 1]
+
+    events = collapse_repeats(events)
+
+    # Cap after trimming to the video, so the budget is spent on what is in shot.
+    kept = set(map(id, cap_lines([line for _, line in events], limit)))
+    return [item for item in events if id(item[1]) in kept]