kimal3 0.4.0 → 0.6.0

package/zeigen/zeitleiste.py

@@ -0,0 +1,393 @@
+# Zeitleiste, Einzelbild und Sprachmodell hinter `kimal3 zeigen auswerten | bild` und `einrichten` (Ruling R-6: eigene
+# Datei, werkzeug.py ruft nur auf). Laeuft mit dem Python des Aufnehmers, Arbeitsordner = Aufnahmeordner.
+#
+# Die Regel steckt in `zeitleiste_aus` (rein, ohne Modell geprueft von scripts/zeigen/test_zeitleiste.py); `auswerten`
+# liest nur die Aufnahme, wandelt Ton in Woerter und schreibt die Datei. Spec 2026-10-18-k3zeigen-design.md, US-7/US-8.
+#
+# 🔴 Was hier zurueckkommt, sind Zahlen und feste Codes -- nie Gesagtes, Getipptes, Fenstertitel, keine Meldung einer
+# fremden Bibliothek. Die Zeitleiste selbst liest Claude erst nach Sabines Ja.
+import io
+import json
+import logging
+import math
+import os
+import re
+import sqlite3
+import time
+import warnings
+
+# Vor jedem Import von huggingface_hub (auch dem in werkzeug._hf_cache, das nach `import zeitleiste` laeuft): sonst
+# schreibt der Download Fortschrittsbalken nach stderr.
+os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+
+MODELL = "large-v3-turbo"
+SATZ_PAUSE_SEK = 0.8
+TIPP_PAUSE_SEK = 2.0
+BILD_BREITE = 1600  # Lesekosten bei 3440 x 2880 (Spec US-8)
+DATEI = "zeitleiste.md"
+ROH = "roh"  # Zwilling von gemeinsam.ROH: die Aufnahme selbst liegt dort, Zeitleiste und Bilder eine Ebene hoeher
+
+TEXTE = {
+    "de": {"titel": "# Zeitleiste", "aufgabe": "Aufgabe", "datum": "Datum", "dauer": "Dauer", "ohne_aufgabe": "(keine)",
+           "sagt": "sagt", "tippt": "tippt", "klickt": "klickt", "auf": "„", "zu": "\"",
+           "passwort": "[Passwortfeld, ausgeblendet]", "ausgelassen": "[getippt, ausgelassen]",
+           "unbekannt": "[unbekanntes Element]", "Strg": "Strg", "Umschalt": "Umschalt"},
+    "en": {"titel": "# Timeline", "aufgabe": "Task", "datum": "Date", "dauer": "Duration", "ohne_aufgabe": "(none)",
+           "sagt": "says", "tippt": "types", "klickt": "clicks", "auf": "“", "zu": "”",
+           "passwort": "[password field, hidden]", "ausgelassen": "[typed, left out]",
+           "unbekannt": "[unknown element]", "Strg": "Ctrl", "Umschalt": "Shift"},
+}
+
+# Tasten des Aufnehmers (pynput-Namen). AltGr fehlt in KOMBI absichtlich: AltGr+Q ist „@", getippt, keine Kombination.
+UMSCHALTER = {"ctrl": "Strg", "ctrl_l": "Strg", "ctrl_r": "Strg", "alt": "Alt", "alt_l": "Alt", "alt_r": "Alt",
+              "cmd": "Win", "cmd_l": "Win", "cmd_r": "Win", "shift": "Umschalt", "shift_l": "Umschalt",
+              "shift_r": "Umschalt", "alt_gr": "AltGr"}
+KOMBI = ("Strg", "Alt", "Win")
+ZEICHEN = {"space": " ", "enter": "⏎", "tab": "⇥", "up": "↑", "down": "↓", "left": "←", "right": "→"}
+# Passwortfelder: Windows meldet `IsPassword`, gespeichert wird das Merkmal aber nicht (StructuralElement kennt kein
+# Feld dafuer, structural.py). Deshalb wie der Aufnehmer selbst (shadow/events.py native_field_is_secure) zusaetzlich
+# an Rolle, Klasse und Automation-ID -- und am Namen eines Eingabefelds, dort auch auf Deutsch.
+# `\bpass\d*\b`/`\bpw\d*\b` fuer Web-Kennungen wie user_pass, pass2, login-pw (nach _woerter_teilen: "user pass").
+GEHEIM = re.compile(r"passw|kennw|passcode|\bpass\d*\b|\bpw\d*\b|\bpin\b|\bpwd\b|\botp\b|\btan\b|secret|geheim",
+                    re.IGNORECASE)
+
+
+def _uhr(sek: float) -> str:
+    sek = max(0, int(sek))
+    return f"{sek // 60}:{sek % 60:02d}"
+
+
+def _eine_zeile(wert) -> str:
+    """Jedes Ereignis bleibt eine Zeile: Zeilenumbrueche und Tabulatoren in Namen und Gesagtem werden Leerzeichen."""
+    return " ".join(str(wert or "").split())
+
+
+def _woerter_teilen(text: str) -> str:
+    return re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", re.sub(r"[-_.#]+", " ", text))
+
+
+def passwortfeld(beobachtung: dict | None) -> bool:
+    if not isinstance(beobachtung, dict):
+        return False
+    e = beobachtung.get("element") or {}
+    if e.get("is_password") is True or e.get("IsPassword") is True:
+        return True
+    rollen = " ".join(str(e.get(k) or "") for k in ("role", "control_type", "class_name")).casefold()
+    if "password" in rollen or "secure" in rollen:
+        return True
+    namen = [e.get("automation_id"), e.get("class_name")]
+    if str(e.get("control_type") or e.get("role") or "").casefold() == "edit":
+        namen.append(e.get("name"))
+    return any(isinstance(n, str) and GEHEIM.search(_woerter_teilen(n)) for n in namen)
+
+
+def _programm(beobachtung: dict) -> str | None:
+    name = ((beobachtung.get("process") or {}).get("process_name") or "").strip()  # nie window.title (Spec US-7)
+    return re.sub(r"\.exe$", "", name, flags=re.IGNORECASE).casefold() or None
+
+
+def _klick_text(beobachtung: dict | None, t: dict) -> str:
+    if not isinstance(beobachtung, dict) or not beobachtung.get("element"):
+        return t["unbekannt"]
+    e = beobachtung["element"]
+    teile = [_eine_zeile(e.get("role") or e.get("control_type"))]
+    if _eine_zeile(e.get("name")):
+        teile.append(f"{t['auf']}{_eine_zeile(e['name'])}{t['zu']}")
+    programm = _programm(beobachtung)
+    if programm:
+        teile.append(f"({programm})")
+    return " ".join(x for x in teile if x) or t["unbekannt"]
+
+
+def _saetze(woerter: list) -> list:
+    # Pause = Stille zwischen Ende des einen und Anfang des naechsten Worts. Nur Anfaenge zu vergleichen trennte
+    # gedehnte Woerter mitten im Satz (gemessen an wetter-3: „aktuellen" 1,6 s lang, 0 s Stille vor „Tag.").
+    saetze, satz, ende = [], [], None
+    for zeit, bis, wort in sorted(woerter):
+        wort = _eine_zeile(wort)
+        if not wort:
+            continue
+        if satz and zeit - ende > SATZ_PAUSE_SEK:
+            saetze.append(satz)
+            satz = []
+        satz.append((zeit, wort))
+        ende = bis
+        if wort[-1] in ".!?…":
+            saetze.append(satz)
+            satz = []
+    return saetze + ([satz] if satz else [])
+
+
+def _kombi_name(e: dict) -> str:
+    zeichen = e.get("zeichen") or ""
+    if len(zeichen) == 1 and 1 <= ord(zeichen) <= 26:  # Strg+Buchstabe kommt als Steuerzeichen: \x03 = Strg+C
+        return chr(64 + ord(zeichen))
+    if zeichen.isprintable() and zeichen:
+        return zeichen.upper()
+    return (e.get("taste") or "?").replace("_", " ").title()
+
+
+def zeitleiste_aus(kopf: dict, woerter: list, ereignisse: list, sprache: str, ohne_getipptes: bool) -> tuple:
+    """Text der Zeitleiste und ihre Zahlen. kopf: aufgabe, datum (fertiger Text), dauer_sek. woerter: (Anfang, Ende, Wort)
+    in Sekunden ab Aufnahmestart. ereignisse: dicts mit t, art (click|press|release|…), beobachtung, bei Tasten
+    taste und zeichen."""
+    t = TEXTE[sprache]
+    zahlen = {"saetze": 0, "klicks": 0, "tippstellen": 0, "passwortfelder": 0}
+    zeilen = []  # (Sekunde, Verb, Text)
+
+    for satz in _saetze(woerter):
+        zeilen.append((satz[0][0], t["sagt"], f"{t['auf']}{' '.join(w for _, w in satz)}{t['zu']}"))
+        zahlen["saetze"] += 1
+
+    folge = None  # laufende Tippfolge: t, text, geheim, zuletzt
+    gehalten = set()
+    klick_geheim = False
+
+    def folge_ende():
+        nonlocal folge
+        if folge and folge["text"]:
+            if folge["geheim"]:
+                text, zaehler = t["passwort"], "passwortfelder"
+            elif ohne_getipptes:
+                text, zaehler = t["ausgelassen"], "tippstellen"
+            else:
+                text, zaehler = f"{t['auf']}{folge['text']}{t['zu']}", "tippstellen"
+            zeilen.append((folge["t"], t["tippt"], text))
+            zahlen[zaehler] += 1
+        folge = None
+
+    for e in sorted(ereignisse, key=lambda e: e["t"]):
+        art, taste = e["art"], e.get("taste")
+        if art == "click":
+            folge_ende()
+            gehalten.clear()
+            klick_geheim = passwortfeld(e.get("beobachtung"))
+            zeilen.append((e["t"], t["klickt"], _klick_text(e.get("beobachtung"), t)))
+            zahlen["klicks"] += 1
+            continue
+        if art == "release":
+            gehalten.discard(UMSCHALTER.get(taste))
+            continue
+        if art != "press":
+            continue  # Mausbewegung, Scrollen
+        if taste in UMSCHALTER:
+            gehalten.add(UMSCHALTER[taste])
+            continue
+        zeichen = e.get("zeichen") or ""
+        steuer = taste is None and len(zeichen) == 1 and 1 <= ord(zeichen) <= 26  # Tab/Enter haben einen Namen
+        # Windows meldet AltGr als ctrl_l + alt_r, also Strg+Alt: ein druckbares Zeichen dabei ist Text („@", „€").
+        altgr = bool(zeichen) and zeichen.isprintable() and ("AltGr" in gehalten or {"Strg", "Alt"} <= gehalten)
+        # Im Passwortfeld wird keine Kombination eine eigene Zeile: sie verriete Tasten und teilte die Ausblendung.
+        geheim = klick_geheim or (folge is not None and folge["geheim"]) or passwortfeld(e.get("beobachtung"))
+        kombi = [m for m in KOMBI if m in gehalten] or (["Strg"] if steuer else [])
+        if kombi and not altgr and not geheim:
+            folge_ende()
+            mods = kombi + (["Umschalt"] if "Umschalt" in gehalten else [])
+            zeilen.append((e["t"], t["tippt"], "[" + "+".join(t.get(m, m) for m in mods) + f"+{_kombi_name(e)}]"))
+            gehalten.clear()  # eine Kombination verbraucht die Umschalter; die naechste Taste kommt wieder mit eigenen
+            continue
+        gehalten.clear()
+        if folge and e["t"] - folge["zuletzt"] > TIPP_PAUSE_SEK:
+            folge_ende()
+        if folge is None:
+            folge = {"t": e["t"], "text": "", "geheim": klick_geheim, "zuletzt": e["t"]}
+        folge["zuletzt"] = e["t"]
+        folge["geheim"] = folge["geheim"] or passwortfeld(e.get("beobachtung"))
+        if taste == "backspace":
+            folge["text"] = folge["text"][:-1]
+        elif zeichen and zeichen.isprintable():
+            folge["text"] += zeichen
+        else:
+            folge["text"] += ZEICHEN.get(taste) or f"[{(taste or '?').replace('_', ' ').title()}]"
+    folge_ende()
+
+    kopfzeilen = [t["titel"], "", f"{t['aufgabe']}: {kopf.get('aufgabe') or t['ohne_aufgabe']}",
+                  f"{t['datum']}: {kopf['datum']}", f"{t['dauer']}: {_uhr(kopf['dauer_sek'])}", ""]
+    rumpf = [f"{_uhr(s)}  {verb:<8}{text}" for s, verb, text in sorted(zeilen, key=lambda z: z[0])]
+    return "\n".join(kopfzeilen + rumpf) + "\n", zahlen
+
+
+# --- Aufnahme lesen, Ton in Woerter ------------------------------------------------------------------------------
+
+def _lies_aufnahme(ordner: str):
+    db = sqlite3.connect(f"file:{os.path.join(ordner, ROH, 'recording.db')}?mode=ro", uri=True)
+    try:
+        start, beschreibung = db.execute("select timestamp, task_description from recording").fetchone()
+        start = float(start)
+        ereignisse = []
+        for zeit, art, taste, zeichen, gedrueckt, roh in db.execute(
+                "select timestamp, name, key_name, key_char, mouse_pressed, structural_observation from action_event "
+                "where name in ('click', 'press', 'release') order by timestamp"):
+            if art == "click" and not gedrueckt:
+                continue  # Loslassen der Maustaste: doppelt zum Klick davor
+            try:
+                beobachtung = json.loads(roh) if roh else None
+            except ValueError:
+                beobachtung = None
+            ereignisse.append({"t": float(zeit) - start, "art": art, "taste": taste, "zeichen": zeichen,
+                               "beobachtung": beobachtung})
+        letzte = db.execute("select max(timestamp) from action_event").fetchone()[0]
+        ton = [(float(ts) - start, flac) for ts, flac in
+               db.execute("select timestamp, flac_data from audio_info where length(flac_data) > 0 order by timestamp")]
+    finally:
+        db.close()
+    return start, beschreibung, ereignisse, (float(letzte) - start if letzte is not None else 0.0), ton
+
+
+def _still() -> None:
+    """Fremde Bibliotheken schreiben sonst nach stderr (loguru im Aufnehmer, Warnungen, logging) -- womoeglich mit
+    Fenstertiteln oder Erkanntem. Vor ihrem Import aufrufen."""
+    warnings.simplefilter("ignore")
+    logging.disable(logging.CRITICAL)
+    try:
+        from loguru import logger
+
+        logger.remove()
+    except ImportError:
+        pass
+
+
+def _dekodiere(flac: bytes):
+    """16 kHz mono float32 direkt ueber PyAV (faster_whisper.decode_audio scheitert an PyAV 19, Befund B3)."""
+    import av
+    import numpy
+
+    teile = []
+    with av.open(io.BytesIO(flac)) as quelle:
+        wandler = av.AudioResampler(format="flt", layout="mono", rate=16000)
+        for rahmen in quelle.decode(audio=0):
+            teile += [r.to_ndarray().reshape(-1) for r in wandler.resample(rahmen)]
+        teile += [r.to_ndarray().reshape(-1) for r in wandler.resample(None)]
+    return numpy.concatenate(teile) if teile else numpy.zeros(0, dtype=numpy.float32)
+
+
+def _erkenne(ton: list, sprache: str) -> tuple:
+    """Woerter (Anfang, Ende ab Aufnahmestart, Wort) und Ende des Tons. Ob das Modell da ist, prueft auswerten vorher."""
+    os.environ["HF_HUB_OFFLINE"] = "1"  # das Modell hat `einrichten` geladen; hier geht nichts ins Netz
+    _still()
+    from faster_whisper import WhisperModel
+
+    modell = WhisperModel(MODELL, device="cpu", compute_type="int8")
+    woerter, ende = [], 0.0
+    for abstand, flac in ton:
+        samples = _dekodiere(flac)
+        ende = max(ende, abstand + len(samples) / 16000)
+        if not len(samples):
+            continue
+        segmente, _ = modell.transcribe(samples, language=sprache, word_timestamps=True, vad_filter=True)
+        woerter += [(abstand + w.start, abstand + w.end, w.word) for s in segmente for w in (s.words or [])]
+    return woerter, ende
+
+
+def _aufgabe(ordner: str, beschreibung: str | None) -> str | None:
+    try:
+        with open(os.path.join(ordner, "aufgabe.txt"), encoding="utf-8-sig") as f:
+            return f.read().strip() or beschreibung
+    except OSError:
+        return beschreibung
+
+
+def _weg(pfad: str) -> None:
+    try:
+        os.remove(pfad)
+    except FileNotFoundError:
+        pass
+
+
+def auswerten(ordner: str, sprache: str, ohne_getipptes: bool, modell_da) -> dict:
+    """`modell_da()` = werkzeug.modell_da gegen den Zwischenspeicher: nur ein fehlendes Modell heisst modell-fehlt."""
+    daten = {"ergebnis": "fehler", "dauer_sek": 0.0, "saetze": 0, "klicks": 0, "tippstellen": 0, "passwortfelder": 0,
+             "grund": None}
+    if not os.path.isdir(ordner):
+        return dict(daten, grund="ordner-fehlt")
+    ziel = os.path.join(ordner, DATEI)
+    _weg(ziel)  # eine alte Zeitleiste darf nie als Ergebnis dieses Laufs dastehen
+    _weg(ziel + ".tmp")
+    if not os.path.isfile(os.path.join(ordner, ROH, "recording.db")):
+        return dict(daten, grund="keine-aufnahme")
+    try:
+        start, beschreibung, ereignisse, letzte, ton = _lies_aufnahme(ordner)
+    except (sqlite3.Error, TypeError, ValueError):
+        return dict(daten, grund="aufnahme-unlesbar")
+    daten["dauer_sek"] = round(max(letzte, 0.0), 2)
+    if not ton:
+        return dict(daten, ergebnis="kein-ton")
+    if not modell_da():
+        return dict(daten, grund="modell-fehlt")
+    try:
+        woerter, ton_ende = _erkenne(ton, sprache)
+    except Exception:
+        return dict(daten, grund="erkennung")  # kein Text der Ausnahme: sie koennte Erkanntes tragen
+    dauer = max(letzte, ton_ende)
+    kopf = {"aufgabe": _aufgabe(ordner, beschreibung), "datum": time.strftime("%Y-%m-%d %H:%M", time.localtime(start)),
+            "dauer_sek": dauer}
+    text, zahlen = zeitleiste_aus(kopf, woerter, ereignisse, sprache, ohne_getipptes)
+    daten.update(zahlen, dauer_sek=round(dauer, 2))
+    if zahlen["saetze"] == 0:
+        return dict(daten, ergebnis="keine-sprache")
+    try:
+        with open(ziel + ".tmp", "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+        os.replace(ziel + ".tmp", ziel)
+    except OSError:
+        _weg(ziel + ".tmp")
+        return dict(daten, grund="schreiben-gescheitert")
+    return dict(daten, ergebnis="fertig")
+
+
+# --- Einzelbild ----------------------------------------------------------------------------------------------------
+
+def bild_name(sekunden: float) -> str:
+    return _uhr(sekunden).replace(":", "-") + ".png"
+
+
+def _einzelbild(ordner: str, sekunden: float):
+    _still()
+    from openadapt_capture.capture import CaptureSession  # erst nach chdir: der Aufnehmer liest beim Import eine .env
+
+    sitzung = CaptureSession.load(os.path.join(ordner, ROH))
+    if sitzung.video_path is None:
+        return None
+    return sitzung.get_frame_at(sitzung._recording.timestamp + sekunden, tolerance=1.0)
+
+
+def bild(ordner: str, sekunden: float) -> dict:
+    if not os.path.isdir(ordner):
+        return {"ergebnis": "fehler", "datei": None, "grund": "ordner-fehlt"}
+    if not math.isfinite(sekunden) or sekunden < 0:
+        return {"ergebnis": "fehler", "datei": None, "grund": "zeit-ungueltig"}
+    roh_ordner = os.path.join(ordner, ROH)
+    if not (os.path.isdir(roh_ordner) and any(n.endswith(".mp4") for n in os.listdir(roh_ordner))):
+        return {"ergebnis": "fehler", "datei": None, "grund": "kein-video"}
+    try:
+        roh = _einzelbild(ordner, sekunden)
+    except Exception:
+        roh = None
+    if roh is None:
+        return {"ergebnis": "fehler", "datei": None, "grund": "kein-bild"}
+    if roh.width > BILD_BREITE:
+        roh = roh.resize((BILD_BREITE, round(roh.height * BILD_BREITE / roh.width)))
+    os.makedirs(os.path.join(ordner, "bilder"), exist_ok=True)
+    datei = os.path.join(ordner, "bilder", bild_name(sekunden))
+    roh.convert("RGB").save(datei, "PNG")
+    return {"ergebnis": "fertig", "datei": datei, "grund": None}
+
+
+# --- Sprachmodell ----------------------------------------------------------------------------------------------------
+
+def _lade_modell() -> None:
+    _still()
+    from faster_whisper.utils import download_model
+
+    download_model(MODELL)
+
+
+def modell_laden(vollstaendig) -> dict:
+    """`vollstaendig()` = werkzeug.modell_da gegen den Zwischenspeicher; erst danach zaehlt ein Laden als geladen."""
+    if vollstaendig():
+        return {"ergebnis": "da", "grund": None}
+    try:
+        _lade_modell()
+    except Exception:
+        return {"ergebnis": "fehler", "grund": "laden-gescheitert"}
+    return {"ergebnis": "geladen", "grund": None} if vollstaendig() else {"ergebnis": "fehler", "grund": "unvollstaendig"}