wirenote 0.1.0__py3-none-any.whl

wirenote/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+__version__ = "0.1.0"

wirenote/calendar/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav

wirenote/calendar/ics.py

@@ -0,0 +1,236 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""ICS calendar matching (docs/dev/PLAN.md › Defaults › Calendar window and refresh).
+
+Sources are ICS links (https, webcal) or file paths, refreshed every
+calendar_refresh_s. An event is in the window when it starts within
+calendar_before_s, started at most calendar_after_start_s ago, or is in
+progress. Tie-break (docs/dev/m2-m4-design.md › M4): prefer an event with a link
+for the detected service, else the only event in the window, else none.
+
+A calendar feed is outside input: anyone can send an invite. So links must be
+https, a feed is capped in size, each event series expands to at most
+MAX_PER_EVENT occurrences, a series that would take too many recurrence steps to
+reach the window is skipped, and errors never repeat the (secret) link.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import math
+import re
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from urllib.parse import urlsplit
+
+LINK = re.compile(r"https?://[^\s<>\"']+", re.IGNORECASE)
+# Hosts that mean "this event is an online call", by service name.
+SERVICE_HOSTS = {
+    "Jitsi": ("jitsi", "meet.jit.si"),
+    "Zoom": ("zoom.us",),
+    "Teams": ("teams.microsoft.com", "teams.live.com"),
+    "Meet": ("meet.google.com",),
+    "Rocket.Chat": ("rocket",),
+    "Discord": ("discord.com", "discord.gg"),
+    "Whereby": ("whereby.com",),
+}
+LOOKAHEAD = dt.timedelta(hours=24)
+LOOKBEHIND = dt.timedelta(hours=12)
+MAX_BYTES = 10_000_000
+MAX_PER_EVENT = 50
+MAX_EVENTS = 2000
+MAX_TITLE = 200
+# Expanding a series walks every occurrence from its DTSTART, also those before
+# the window. Estimate those steps and skip series (and feeds) that cost too much:
+# 500,000 steps take about a second.
+FREQ_S = {"SECONDLY": 1, "MINUTELY": 60, "HOURLY": 3600, "DAILY": 86400,
+          "WEEKLY": 7 * 86400, "MONTHLY": 28 * 86400, "YEARLY": 365 * 86400}
+BY_PARTS = ("BYSECOND", "BYMINUTE", "BYHOUR", "BYDAY", "BYMONTHDAY", "BYYEARDAY",
+            "BYWEEKNO", "BYMONTH", "BYSETPOS")
+MAX_SERIES_STEPS = 200_000
+MAX_FEED_STEPS = 500_000
+SCHEME = re.compile(r"^(https?|webcal)://", re.IGNORECASE)
+
+
+class CalendarError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Event:
+    title: str
+    start: dt.datetime
+    end: dt.datetime
+    links: tuple[str, ...] = ()
+    attendees: tuple[str, ...] = field(default=())
+    emails: tuple[str, ...] = field(default=())
+
+    def as_meta(self) -> dict:
+        d = asdict(self)
+        d["start"], d["end"] = self.start.isoformat(), self.end.isoformat()
+        d["attendees"], d["links"] = list(self.attendees), list(self.links)
+        d["emails"] = list(self.emails)
+        return d
+
+    def service_links(self, service: str | None) -> list[str]:
+        hosts = SERVICE_HOSTS.get(service, ()) if service else \
+            tuple(h for hs in SERVICE_HOSTS.values() for h in hs)
+        return [l for l in self.links if any(h in l.lower() for h in hosts)]
+
+
+def parse(text: str | bytes, now: dt.datetime) -> list[Event]:
+    """Timed events (all-day events are skipped) around now, recurrences expanded.
+
+    Each series (one UID) is expanded on its own and lazily, so one event that
+    repeats every second costs MAX_PER_EVENT occurrences, not the whole window."""
+    import icalendar
+    import recurring_ical_events
+
+    cal = icalendar.Calendar.from_ical(text)
+    start, end = now - LOOKBEHIND, now + LOOKAHEAD
+    zones = list(cal.walk("VTIMEZONE"))
+    series: dict[str, list] = {}
+    for i, ev in enumerate(cal.walk("VEVENT")):
+        series.setdefault(str(ev.get("UID") or f"#{i}"), []).append(ev)
+    out: list[Event] = []
+    budget = MAX_FEED_STEPS
+    for comps in series.values():
+        cost = _steps_before(comps, start)
+        if cost > MAX_SERIES_STEPS or cost > budget:
+            continue
+        budget -= cost
+        sub = icalendar.Calendar()
+        for c in zones + comps:
+            sub.add_component(c)
+        kept = 0
+        for seen, ev in enumerate(recurring_ical_events.of(sub).after(start)):
+            if seen >= 4 * MAX_PER_EVENT or kept >= MAX_PER_EVENT:
+                break
+            first = ev.decoded("DTSTART", None)
+            if not isinstance(first, dt.datetime):
+                if isinstance(first, dt.date) and first > end.date():
+                    break
+                continue
+            if _aware(first) >= end:
+                break
+            out.append(_event(ev))
+            kept += 1
+        if len(out) >= MAX_EVENTS:
+            return out[:MAX_EVENTS]
+    return out
+
+
+def _steps_before(comps: list, start: dt.datetime) -> float:
+    """About how many recurrence steps expanding comps walks before reaching start.
+    Overestimates (BY* lists may limit rather than expand); unknown counts as too many."""
+    total = 0.0
+    for ev in comps:
+        rules = ev.get("RRULE")
+        if rules is None:
+            continue
+        try:
+            first = ev.decoded("DTSTART")
+            if not isinstance(first, dt.datetime):
+                first = dt.datetime.combine(first, dt.time(), start.tzinfo)
+            span = max(0.0, (start - _aware(first)).total_seconds())
+            for rule in rules if isinstance(rules, list) else [rules]:
+                step = FREQ_S[str(rule["FREQ"][0]).upper()] * max(1, int(rule.get("INTERVAL", [1])[0]))
+                factor = math.prod(max(1, len(rule.get(part) or [])) for part in BY_PARTS)
+                total += span / step * factor
+        except (KeyError, ValueError, TypeError, IndexError):
+            return math.inf
+    return total
+
+
+def _event(ev) -> Event:
+    start, end = ev.decoded("DTSTART"), ev.decoded("DTEND", None)
+    if not isinstance(end, dt.datetime):
+        end = start + (ev.decoded("DURATION", None) or dt.timedelta(hours=1))
+    start, end = _aware(start), _aware(end)
+    text_fields = " ".join(str(ev.get(k, "")) for k in ("LOCATION", "DESCRIPTION", "URL"))
+    links = tuple(dict.fromkeys(m.rstrip(".,;)") for m in LINK.findall(text_fields)))
+    att = ev.get("ATTENDEE", [])
+    att = att if isinstance(att, list) else [att]
+    emails = tuple(re.sub(r"^mailto:", "", str(a), flags=re.IGNORECASE) for a in att)
+    names = tuple(str(a.params.get("CN") or e) for a, e in zip(att, emails))
+    title = str(ev.get("SUMMARY", "")).strip()[:MAX_TITLE] or "(no title)"
+    return Event(title, start, end, links, names, tuple(e for e in emails if "@" in e))
+
+
+def _aware(t: dt.datetime) -> dt.datetime:
+    return t if t.tzinfo else t.astimezone()
+
+
+def in_window(events: list[Event], now: dt.datetime, before_s: float,
+              after_start_s: float) -> list[Event]:
+    before, after = dt.timedelta(seconds=before_s), dt.timedelta(seconds=after_start_s)
+    return [e for e in events
+            if e.start - before <= now and (now <= e.start + after or now < e.end)]
+
+
+def pick(events: list[Event], service: str | None) -> Event | None:
+    linked = [e for e in events if e.service_links(service)]
+    if len(linked) == 1:
+        return linked[0]
+    if len(events) == 1:
+        return events[0]
+    return None
+
+
+def has_call_link(events: list[Event]) -> bool:
+    return any(e.service_links(None) for e in events)
+
+
+class _HttpsOnlyRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if urlsplit(newurl).scheme.lower() != "https":
+            raise CalendarError("the calendar redirected away from https; refused")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _open(req: urllib.request.Request, timeout_s: float):
+    return urllib.request.build_opener(_HttpsOnlyRedirect).open(req, timeout=timeout_s)
+
+
+def source_label(source: str) -> str:
+    """What may be shown or logged for a source: the host of a link, the name of a file."""
+    if SCHEME.match(source):
+        return urlsplit(source).hostname or "calendar link"
+    return Path(source).name or "calendar file"
+
+
+def fetch(source: str, timeout_s: float = 30.0) -> bytes:
+    if SCHEME.match(source):
+        url = re.sub(r"^webcal://", "https://", source, flags=re.IGNORECASE)
+        if urlsplit(url).scheme.lower() != "https":
+            raise CalendarError("calendar links must use https")
+        req = urllib.request.Request(url, headers={"User-Agent": "wirenote"})
+        with _open(req, timeout_s) as resp:
+            data = resp.read(MAX_BYTES + 1)
+    else:
+        with Path(source).expanduser().open("rb") as f:
+            data = f.read(MAX_BYTES + 1)
+    if len(data) > MAX_BYTES:
+        raise CalendarError(f"calendar too large (over {MAX_BYTES // 1_000_000} MB)")
+    return data
+
+
+def describe_error(source: str, e: Exception) -> str:
+    """An error line without the link or path, which can be secret."""
+    detail = f": {e}" if isinstance(e, CalendarError) else ""
+    if isinstance(e, urllib.error.HTTPError):
+        detail = f": HTTP {e.code}"
+    return f"{source_label(source)}: {type(e).__name__}{detail}"
+
+
+def load(sources: tuple[str, ...], now: dt.datetime) -> tuple[list[Event], list[str]]:
+    """All events from all sources, plus one error string per failed source."""
+    events, errors = [], []
+    for i, src in enumerate(sources):
+        try:
+            events += parse(fetch(src), now)
+        except Exception as e:  # noqa: BLE001 - one bad calendar must not hide the others
+            errors.append(f"calendar {i + 1}: {describe_error(src, e)}")
+    return events, errors

wirenote/capture/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav

wirenote/capture/recorder.py

@@ -0,0 +1,304 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""Two-track recording with pw-record (docs/dev/PLAN.md › Capture, docs/dev/m2-m4-design.md › M2).
+
+One directory per recording holds manifest.json plus one WAV per segment:
+mic-000.wav, system-000.wav, ... A new segment starts when a track's child
+is restarted or the mic target changes; processing stitches segments by
+their start offsets.
+
+- Mic: the Audio/Source the meeting app is linked to. With no target the
+  child follows the default source, like the app does.
+- System: the default sink's monitor (stream.capture.sink=true), no target.
+  WirePlumber moves it when the default sink changes
+  (linking.follow-default-target, checked 2026-10-26), so a sink switch does
+  not need a new segment.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ctypes
+import datetime as dt
+import json
+import os
+import signal
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from . import wav
+
+MANIFEST = "manifest.json"
+STOP_WAIT_S = 3.0
+MAX_RESTARTS = 3
+
+
+def now_iso() -> str:
+    return dt.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def _die_with_parent() -> None:
+    """Child setup: get SIGINT (clean WAV close) if the daemon dies."""
+    try:
+        ctypes.CDLL("libc.so.6", use_errno=True).prctl(1, signal.SIGINT)  # PR_SET_PDEATHSIG
+    except OSError:
+        pass
+
+
+async def spawn_pw_record(argv: list[str]):
+    return await asyncio.create_subprocess_exec(
+        *argv, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.DEVNULL, preexec_fn=_die_with_parent)
+
+
+Spawner = Callable[[list[str]], Awaitable]
+
+
+@dataclass
+class Segment:
+    track: str                    # "mic" or "system"
+    file: str
+    target: str | None            # node.name, or None for the default
+    start_offset_s: float
+    pid: int | None = None
+    end_offset_s: float | None = None
+    end_reason: str | None = None
+
+
+@dataclass
+class _Track:
+    name: str
+    target: str | None
+    proc: object = None
+    segment: Segment | None = None
+    last_size: int = 0
+    last_growth: float = 0.0
+    stalled: bool = False
+    restarts: int = 0
+
+
+@dataclass(frozen=True)
+class TrackEvent:
+    track: str
+    kind: str        # "stalled", "recovered", "restarted", "gave_up"
+    detail: str = ""
+
+
+@dataclass
+class RecordingMeta:
+    app: str
+    name: str
+    service: str | None = None
+    room: str | None = None
+    calendar: dict | None = None
+    extra: dict = field(default_factory=dict)
+
+
+class Recording:
+    def __init__(self, root: Path, meta: RecordingMeta, node_prefix: str = "wirenote-",
+                 heartbeat_s: float = 5.0, spawn: Spawner = spawn_pw_record,
+                 clock: Callable[[], float] = time.monotonic, system_target: str = "") -> None:
+        self.started_wall = dt.datetime.now().astimezone()
+        self.id = f"{self.started_wall:%Y%m%d-%H%M%S}-{meta.app}"
+        self.dir = root / self.id
+        self.meta = meta
+        self.prefix = node_prefix
+        self.heartbeat_s = heartbeat_s
+        self.spawn = spawn
+        self.clock = clock
+        self.system_target = system_target or None
+        self.t0 = clock()
+        self.segments: list[Segment] = []
+        self.tracks: dict[str, _Track] = {}
+        self.ended: str | None = None
+        self.end_reason: str | None = None
+
+    # Lifecycle -------------------------------------------------------------
+
+    async def start(self, mic_target: str | None) -> None:
+        self.dir.mkdir(mode=0o700, parents=True, exist_ok=False)
+        self.tracks = {"mic": _Track("mic", mic_target),
+                       "system": _Track("system", self.system_target)}
+        try:
+            for t in self.tracks.values():
+                await self._open_segment(t)
+        except BaseException:
+            await self.stop("capture failed to start")
+            raise
+        self._write_manifest()
+
+    async def stop(self, reason: str) -> Path:
+        for t in self.tracks.values():
+            await self._close_segment(t, reason)
+        self.ended, self.end_reason = now_iso(), reason
+        self._write_manifest()
+        return self.dir
+
+    async def retarget_mic(self, target: str | None) -> bool:
+        t = self.tracks.get("mic")
+        if t is None or t.target == target:
+            return False
+        await self._close_segment(t, f"mic moved to {target or 'default'}")
+        t.target = target
+        await self._open_segment(t)
+        self._write_manifest()
+        return True
+
+    async def heartbeat(self) -> list[TrackEvent]:
+        """Check each track; call about once a second (docs/dev/PLAN.md › Capture heartbeat)."""
+        events: list[TrackEvent] = []
+        now = self.clock()
+        for t in self.tracks.values():
+            if t.proc is None:
+                continue
+            rc = t.proc.returncode
+            if rc is not None:
+                await self._close_segment(t, f"pw-record exited with {rc}")
+                if t.restarts >= MAX_RESTARTS:
+                    t.proc = None
+                    events.append(TrackEvent(t.name, "gave_up", f"exited {t.restarts + 1} times"))
+                    continue
+                t.restarts += 1
+                await self._open_segment(t)
+                events.append(TrackEvent(t.name, "restarted", f"pw-record exited with {rc}"))
+                continue
+            size = self._size(t)
+            if size > t.last_size:
+                t.last_size, t.last_growth = size, now
+                if t.stalled:
+                    t.stalled = False
+                    events.append(TrackEvent(t.name, "recovered"))
+            elif not t.stalled and now - t.last_growth >= self.heartbeat_s:
+                t.stalled = True
+                events.append(TrackEvent(t.name, "stalled",
+                                         f"no audio for {self.heartbeat_s:g} s"))
+        if events:
+            self._write_manifest()
+        return events
+
+    # Internals -------------------------------------------------------------
+
+    def _argv(self, t: _Track, path: Path) -> list[str]:
+        props = f"node.name={self.prefix}{t.name} media.name={self.prefix}{t.name}"
+        if t.name == "system":
+            props += " stream.capture.sink=true"
+        argv = ["pw-record", "--rate", str(wav.RATE), "--channels", "1", "--format", "s16",
+                "-P", "{ " + props + " }"]
+        if t.target:
+            argv += ["--target", t.target]
+        return argv + [str(path)]
+
+    async def _open_segment(self, t: _Track) -> None:
+        n = sum(1 for s in self.segments if s.track == t.name)
+        name = f"{t.name}-{n:03d}.wav"
+        seg = Segment(t.name, name, t.target, round(self.clock() - self.t0, 3))
+        t.proc = await self.spawn(self._argv(t, self.dir / name))
+        seg.pid = t.proc.pid
+        # The header alone is not audio.
+        t.segment, t.last_size, t.last_growth, t.stalled = seg, wav.HEADER, self.clock(), False
+        self.segments.append(seg)
+
+    async def _close_segment(self, t: _Track, reason: str) -> None:
+        seg, proc = t.segment, t.proc
+        if seg is None:
+            return
+        if proc is not None and proc.returncode is None:
+            try:
+                proc.send_signal(signal.SIGINT)
+                await asyncio.wait_for(proc.wait(), STOP_WAIT_S)
+            except ProcessLookupError:
+                pass
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.wait()
+        path = self.dir / seg.file
+        if path.exists():
+            wav.repair(path)
+        seg.end_offset_s = round(self.clock() - self.t0, 3)
+        seg.end_reason = reason
+        t.segment = None
+
+    def _size(self, t: _Track) -> int:
+        try:
+            return (self.dir / t.segment.file).stat().st_size if t.segment else 0
+        except OSError:
+            return 0
+
+    def manifest(self) -> dict:
+        m = self.meta
+        return {"version": 1, "id": self.id, "app": m.app, "name": m.name,
+                "service": m.service, "room": m.room, "calendar": m.calendar, **m.extra,
+                "started": self.started_wall.isoformat(timespec="seconds"),
+                "ended": self.ended, "end_reason": self.end_reason,
+                "segments": [asdict(s) for s in self.segments]}
+
+    def _write_manifest(self) -> None:
+        write_manifest(self.dir, self.manifest())
+
+
+def read_manifest(rec_dir: Path) -> dict:
+    return json.loads((rec_dir / MANIFEST).read_text())
+
+
+def write_manifest(rec_dir: Path, data: dict) -> None:
+    tmp = rec_dir / (MANIFEST + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2))
+    tmp.replace(rec_dir / MANIFEST)
+
+
+def recover(root: Path) -> list[Path]:
+    """Close recordings left open by a crash: stop orphaned children, fix headers.
+
+    Returns the recordings that were recovered, so the caller can queue them.
+    """
+    out = []
+    if not root.is_dir():
+        return out
+    for rec_dir in sorted(p for p in root.iterdir() if (p / MANIFEST).is_file()):
+        try:
+            m = read_manifest(rec_dir)
+        except (OSError, ValueError):
+            continue
+        if m.get("ended"):
+            continue
+        for seg in m.get("segments", []):
+            path = rec_dir / seg["file"]
+            _stop_orphan(seg.get("pid"), path)
+            if path.exists():
+                wav.repair(path)
+            if seg.get("end_offset_s") is None:
+                seg["end_offset_s"] = round(seg["start_offset_s"] + wav.duration_s(path), 3)
+                seg["end_reason"] = "crash"
+        mtimes = [(rec_dir / s["file"]).stat().st_mtime for s in m.get("segments", [])
+                  if (rec_dir / s["file"]).exists()]
+        end = dt.datetime.fromtimestamp(max(mtimes) if mtimes else time.time()).astimezone()
+        m["ended"], m["end_reason"] = end.isoformat(timespec="seconds"), "crash"
+        write_manifest(rec_dir, m)
+        out.append(rec_dir)
+    return out
+
+
+def _stop_orphan(pid: int | None, path: Path) -> None:
+    """SIGINT a pw-record that outlived us, but only if it still writes this file."""
+    if not pid:
+        return
+    try:
+        cmdline = Path(f"/proc/{pid}/cmdline").read_bytes().split(b"\0")
+    except OSError:
+        return
+    if str(path).encode() not in cmdline:
+        return
+    try:
+        os.kill(pid, signal.SIGINT)
+    except OSError:
+        return
+    for _ in range(30):
+        if not Path(f"/proc/{pid}").exists():
+            return
+        time.sleep(0.1)
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except OSError:
+        pass

wirenote/capture/wav.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 Hrishikesh Jadhav
+"""WAV helpers for pw-record output: header repair and sample loading.
+
+pw-record writes a 44-byte PCM header and fixes the sizes on SIGINT. After a
+kill -9 the header still says RIFF size 8 and data size 0 while the samples
+are intact (checked 2026-10-26, PipeWire 1.6.8), so repair rewrites the two
+size fields from the file length.
+"""
+
+from __future__ import annotations
+
+import struct
+import wave
+from pathlib import Path
+
+HEADER = 44
+RATE = 16000   # docs/dev/PLAN.md › Defaults › Audio format: 16 kHz mono 16-bit
+
+
+def repair(path: Path) -> bool:
+    """Fix the RIFF and data sizes of a truncated WAV. Returns True if changed."""
+    size = path.stat().st_size
+    if size < HEADER:
+        return False
+    with path.open("r+b") as f:
+        head = f.read(HEADER)
+        if head[:4] != b"RIFF" or head[8:12] != b"WAVE" or head[36:40] != b"data":
+            return False
+        riff, data = struct.unpack_from("<I", head, 4)[0], struct.unpack_from("<I", head, 40)[0]
+        want_data = (size - HEADER) // 2 * 2
+        if riff == want_data + 36 and data == want_data:
+            return False
+        f.seek(4)
+        f.write(struct.pack("<I", want_data + 36))
+        f.seek(40)
+        f.write(struct.pack("<I", want_data))
+    return True
+
+
+def duration_s(path: Path) -> float:
+    try:
+        with wave.open(str(path)) as w:
+            return w.getnframes() / w.getframerate()
+    except (OSError, wave.Error, EOFError):
+        return 0.0
+
+
+def load_float(path: Path):
+    """Samples as float32 in [-1, 1], for faster-whisper (16 kHz mono expected)."""
+    import numpy as np
+
+    with wave.open(str(path)) as w:
+        if (w.getframerate(), w.getnchannels(), w.getsampwidth()) != (RATE, 1, 2):
+            raise ValueError(f"{path.name}: expected 16 kHz mono s16, got "
+                             f"{w.getframerate()} Hz, {w.getnchannels()} ch, {w.getsampwidth() * 8} bit")
+        raw = w.readframes(w.getnframes())
+    return np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0