stenograf 0.1.0__py3-none-any.whl

stenograf/__init__.py

@@ -0,0 +1,8 @@
+"""stenograf — accuracy-first local meeting transcription. Audio never touches disk."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("stenograf")
+except PackageNotFoundError:  # running from a source tree without installation
+    __version__ = "0.0.0.dev0"

stenograf/aec.py

@@ -0,0 +1,355 @@
+"""Acoustic echo cancellation: subtract the speakers from the microphone.
+
+The default way to sit in an online meeting is speakers + built-in mic. The
+remote participants come out of the speakers, back into the mic, and land on the
+mic channel — where the pipeline attributes them to *you*. Measured on this
+machine, that echo sits ~24 dB above the mic's noise floor: loud enough to
+transcribe, so it produces duplicate lines under a ``Local-N`` label.
+
+We already capture the far end: the system channel *is* the audio the speakers
+played. So this is a textbook echo-cancellation setup — near end (mic), far end
+(system reference) — and we hand both to WebRTC's AEC3 via livekit's
+``AudioProcessingModule``. The mic channel is replaced by its cleaned version;
+the system channel passes through untouched (nothing echoes into the tap).
+
+Why AEC3 and not Apple's Voice Processing IO, which is one flag away in the
+capture helper: VPIO ducks other applications' audio, which would attenuate the
+remote speech we are trying to transcribe (measured: −36 dB on the system
+channel), and its AVAudioEngine binding delivered no mic frames at all on macOS
+26. See native/README.md. Chrome ships both and defaults to this one.
+
+Two properties of AEC3 shape the design:
+
+- It consumes **exactly 10 ms frames** (160 samples at 16 kHz), far end first,
+  then near end, for the same instant. Hence the tick pump below.
+- Its internal delay estimator does the real work; ``set_stream_delay_ms`` is a
+  hint. Feeding a deliberately wrong 500 ms hint measured the same 26 dB ERLE as
+  the correct 25 ms, so the constant below is a nicety, not a load-bearing value.
+
+Measured across the PLAN-AEC.md scenario matrix (quiet/loud, batch/live,
+built-in/Bluetooth, double-talk), a canceller with a live reference leaks
+nothing the ASR decodes. What residual echo survives comes from *losing* the
+reference — a stalled or mis-clocked tap — which ``far_end_missing_ticks``
+counts; a cross-channel text backstop at merge time arms itself on that signal
+(``session.MeetingRecorder``), and the CLI warns when it had to act.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from stenograf.capture.base import (
+    ORDER_TOLERANCE_SAMPLES,
+    SAMPLE_RATE,
+    AudioFrame,
+    CaptureProvider,
+    Channel,
+)
+from stenograf.recording import WavTee
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+TICK_SAMPLES = SAMPLE_RATE // 100
+"""AEC3 processes exactly 10 ms at a time; neither channel may be fed anything else."""
+
+DEFAULT_DELAY_MS = 25
+"""Measured speaker → air → mic → tap round trip on a MacBook Pro (24.6 ms)."""
+
+_FAR_HISTORY_S = 0.5
+"""Reference kept behind the current tick, so a late mic frame can still pair up."""
+
+_MAX_HOLD_S = 0.5
+"""Mic backlog tolerated while waiting for the reference. Past this we cancel
+against silence rather than stall the live captions: a stalled tap (device
+change, sleep/wake) must degrade to "no cancellation", never to "no captions"."""
+
+
+class _Track:
+    """A contiguous run of one channel's samples, and the timestamp of sample 0.
+
+    Providers deliver frames monotonically per channel, but a device that drops
+    buffers leaves a hole. Padding it with silence keeps the sample index and
+    the timeline in agreement, which is the only reason the far-end reference
+    can be looked up by timestamp at all.
+    """
+
+    def __init__(self, channel: Channel) -> None:
+        self._channel = channel
+        self._buf = np.zeros(0, dtype=np.int16)
+        self.start_ts: float | None = None
+
+    @property
+    def available(self) -> int:
+        return self._buf.size
+
+    @property
+    def end_ts(self) -> float | None:
+        if self.start_ts is None:
+            return None
+        return self.start_ts + self._buf.size / SAMPLE_RATE
+
+    def append(self, frame: AudioFrame) -> None:
+        if self.start_ts is None:
+            self.start_ts = frame.timestamp
+            self._buf = frame.samples.astype(np.int16, copy=True)
+            return
+        assert self.end_ts is not None
+        gap = int(round((frame.timestamp - self.end_ts) * SAMPLE_RATE))
+        if gap < -ORDER_TOLERANCE_SAMPLES:
+            raise ValueError(
+                f"{self._channel.value} frame went backwards by {-gap} samples; "
+                "the capture stream desynced"
+            )
+        pieces = [self._buf]
+        if gap > ORDER_TOLERANCE_SAMPLES:
+            pieces.append(np.zeros(gap, dtype=np.int16))
+        pieces.append(frame.samples)
+        self._buf = np.concatenate(pieces)
+
+    def take(self, count: int) -> np.ndarray:
+        """Remove and return the first ``count`` samples, advancing the timeline."""
+        assert self.start_ts is not None
+        head, self._buf = self._buf[:count], self._buf[count:]
+        self.start_ts += head.size / SAMPLE_RATE
+        return head
+
+    def window(self, ts: float, count: int) -> np.ndarray | None:
+        """``count`` samples starting at ``ts``, or None if they have not arrived.
+
+        A window starting before this track does is padded with silence: the mic
+        opens after the tap, so the reverse case (mic first) only happens when
+        the tap is late, and silence is the honest reference for audio nobody
+        has heard yet.
+        """
+        if self.start_ts is None:
+            return None
+        index = int(round((ts - self.start_ts) * SAMPLE_RATE))
+        if index >= 0:
+            if index + count > self._buf.size:
+                return None
+            return self._buf[index : index + count]
+        pad = min(-index, count)
+        if pad == count:
+            return np.zeros(count, dtype=np.int16)
+        tail = self._buf[: count - pad]
+        if tail.size < count - pad:
+            return None
+        return np.concatenate([np.zeros(pad, dtype=np.int16), tail])
+
+    def trim_before(self, ts: float) -> None:
+        if self.start_ts is None or ts <= self.start_ts:
+            return
+        drop = min(int((ts - self.start_ts) * SAMPLE_RATE), self._buf.size)
+        if drop > 0:
+            self._buf = self._buf[drop:]
+            self.start_ts += drop / SAMPLE_RATE
+
+
+class EchoCanceller:
+    """Replaces mic frames with echo-cancelled ones, using system as reference.
+
+    Feed it every frame in arrival order; it returns the frames to forward. The
+    system channel is returned immediately and unchanged, so remote transcription
+    is never delayed or altered. Mic frames are buffered until the reference
+    covers the same instant, then emitted 10 ms at a time (re-aggregated into one
+    frame per call, preserving the input's timestamps).
+
+    With no system channel there is nothing to cancel against, and every frame
+    passes straight through.
+    """
+
+    def __init__(
+        self,
+        channels: set[Channel],
+        *,
+        delay_ms: int = DEFAULT_DELAY_MS,
+        noise_suppression: bool = False,
+        cancel: bool = True,
+    ) -> None:
+        self.enabled = cancel and Channel.MIC in channels and Channel.SYSTEM in channels
+        self.far_end_missing_ticks = 0
+        self._delay_ms = delay_ms
+        self._near = _Track(Channel.MIC)
+        self._far = _Track(Channel.SYSTEM)
+        self._apm = None
+        if self.enabled:
+            # Imported here: the native lib is ~9 MB and no other path needs it.
+            from livekit import rtc
+
+            self._rtc = rtc
+            self._apm = rtc.AudioProcessingModule(
+                echo_cancellation=True,
+                # AGC pumps the gain and fights the ASR front end; NS is off by
+                # default because this is an accuracy-first transcriber and the
+                # suppressor colours speech. Neither is needed to cancel echo.
+                auto_gain_control=False,
+                noise_suppression=noise_suppression,
+                high_pass_filter=True,
+            )
+
+    def process(self, frame: AudioFrame) -> list[AudioFrame]:
+        if not self.enabled:
+            return [frame]
+        if frame.channel is Channel.SYSTEM:
+            self._far.append(frame)
+            return [frame]
+        self._near.append(frame)
+        return self._drain()
+
+    def drain(self) -> list[AudioFrame]:
+        """Flush the tail at end of stream, padding the last partial tick."""
+        if not self.enabled or self._near.available == 0:
+            return []
+        return self._drain(flush=True)
+
+    def _drain(self, *, flush: bool = False) -> list[AudioFrame]:
+        hold = int(_MAX_HOLD_S * SAMPLE_RATE)
+        ticks: list[np.ndarray] = []
+        first_ts: float | None = None
+
+        while self._near.available > 0:
+            partial = self._near.available < TICK_SAMPLES
+            if partial and not flush:
+                break
+            ts = self._near.start_ts
+            assert ts is not None
+
+            far = self._far.window(ts, TICK_SAMPLES)
+            if far is None:
+                # The reference has not caught up. Wait — unless the mic backlog
+                # says the tap has stopped, in which case forward uncancelled
+                # audio rather than freezing the captions.
+                if not flush and self._near.available < hold:
+                    break
+                far = np.zeros(TICK_SAMPLES, dtype=np.int16)
+                if not flush:
+                    # Only mid-capture counts as reference loss. At end-of-stream
+                    # flush the far end has legitimately ended a hair before the
+                    # mic tail; counting those ticks made every clean meeting
+                    # report a phantom "ran without its reference for 0.0s" and
+                    # spuriously armed the echo-text backstop.
+                    self.far_end_missing_ticks += 1
+
+            count = min(TICK_SAMPLES, self._near.available)
+            near = self._near.take(count)
+            if count < TICK_SAMPLES:
+                near = np.concatenate([near, np.zeros(TICK_SAMPLES - count, dtype=np.int16)])
+
+            cleaned = self._tick(far, near)[:count]
+            if first_ts is None:
+                first_ts = ts
+            ticks.append(cleaned)
+            self._far.trim_before(ts - _FAR_HISTORY_S)
+
+        if first_ts is None:
+            return []
+        return [AudioFrame(channel=Channel.MIC, timestamp=first_ts, samples=np.concatenate(ticks))]
+
+    def _tick(self, far: np.ndarray, near: np.ndarray) -> np.ndarray:
+        """One 10 ms step: reference first, then the mic, per AEC3's contract."""
+        assert self._apm is not None
+        reverse = self._rtc.AudioFrame(far.tobytes(), SAMPLE_RATE, 1, TICK_SAMPLES)
+        self._apm.process_reverse_stream(reverse)
+        self._apm.set_stream_delay_ms(self._delay_ms)
+        capture = self._rtc.AudioFrame(near.tobytes(), SAMPLE_RATE, 1, TICK_SAMPLES)
+        self._apm.process_stream(capture)
+        return np.frombuffer(bytes(capture.data), dtype=np.int16)
+
+
+class AecDump:
+    """The mic/lpb/enh WAV triple that ``eval/aec_score.py`` scores.
+
+    AECMOS naming: ``mic.wav`` is the near end as the device heard it,
+    ``lpb.wav`` (loopback) is the far-end reference the canceller saw, and
+    ``enh.wav`` is the mic as the ASR receives it. All three are mono 16 kHz
+    and share the capture clock's t=0 (``WavTee`` pads each file's head up to
+    its first frame's timestamp), so they are sample-aligned for scoring.
+
+    Opt-in via ``--aec-dump``: like ``--record-audio``, this writes meeting
+    audio to disk.
+    """
+
+    def __init__(self, directory: Path) -> None:
+        directory.mkdir(parents=True, exist_ok=True)
+        self._mic = WavTee(directory / "mic.wav", {Channel.MIC})
+        self._lpb = WavTee(directory / "lpb.wav", {Channel.SYSTEM})
+        self._enh = WavTee(directory / "enh.wav", {Channel.MIC})
+
+    def add_input(self, frame: AudioFrame) -> None:
+        (self._mic if frame.channel is Channel.MIC else self._lpb).add(frame)
+
+    def add_output(self, frame: AudioFrame) -> None:
+        if frame.channel is Channel.MIC:
+            self._enh.add(frame)
+
+    def close(self) -> None:
+        self._mic.close()
+        self._lpb.close()
+        self._enh.close()
+
+
+class EchoCancellingProvider(CaptureProvider):
+    """Wraps a provider, cancelling speaker bleed out of its mic channel.
+
+    ``cancel=False`` keeps the wrapper as a pure pass-through — used with
+    ``dump_dir`` to record the uncancelled baseline the eval rig compares
+    against (``--no-aec --aec-dump``).
+    """
+
+    def __init__(
+        self,
+        inner: CaptureProvider,
+        *,
+        delay_ms: int = DEFAULT_DELAY_MS,
+        noise_suppression: bool = False,
+        cancel: bool = True,
+        dump_dir: Path | None = None,
+    ) -> None:
+        self._inner = inner
+        self._delay_ms = delay_ms
+        self._noise_suppression = noise_suppression
+        self._cancel = cancel
+        self._dump_dir = dump_dir
+        self._dump: AecDump | None = None
+        self._canceller: EchoCanceller | None = None
+
+    @property
+    def canceller(self) -> EchoCanceller | None:
+        return self._canceller
+
+    def start(self, channels: set[Channel]) -> None:
+        self._canceller = EchoCanceller(
+            channels,
+            delay_ms=self._delay_ms,
+            noise_suppression=self._noise_suppression,
+            cancel=self._cancel,
+        )
+        if self._dump_dir is not None:
+            self._dump = AecDump(self._dump_dir)
+        self._inner.start(channels)
+
+    def frames(self) -> Iterator[AudioFrame]:
+        assert self._canceller is not None, "frames() called before start()"
+        try:
+            for frame in self._inner.frames():
+                if self._dump is not None:
+                    self._dump.add_input(frame)
+                for produced in self._canceller.process(frame):
+                    if self._dump is not None:
+                        self._dump.add_output(produced)
+                    yield produced
+            for produced in self._canceller.drain():
+                if self._dump is not None:
+                    self._dump.add_output(produced)
+                yield produced
+        finally:
+            if self._dump is not None:
+                self._dump.close()
+                self._dump = None
+
+    def stop(self) -> None:
+        self._inner.stop()

stenograf/archive.py

@@ -0,0 +1,330 @@
+"""Meeting archive: a managed library of finalized transcripts.
+
+Phase 4 turns ``steno start`` into a tool with memory. Every run writes its
+transcript into a managed directory whose name *is* a stable meeting id
+(``meeting-YYYYMMDD-HHMMSS`` + a collision suffix), and a maintained JSON index
+records lightweight metadata for each — so the web UI's "meeting archive" view
+lists meetings without re-scanning and re-parsing every transcript on disk
+(PLAN.md §5 Stage B1).
+
+Design mirrors :class:`~stenograf.profiles.ProfileStore`:
+
+- The archive lives in the platform **data** dir (``data_dir()/meetings/``),
+  distinct from the re-downloadable model cache — a transcript library is
+  precious user data.
+- The index (``meetings/index.json``) is written atomically (temp + replace), so
+  a crash mid-save never corrupts the library.
+- The index is *maintained* (updated on every add/remove), not derived by
+  scanning — but :meth:`MeetingArchive.reconcile` self-heals it against the
+  actual directories (dropping records whose dir vanished, adopting orphan
+  meeting dirs written while the index was unavailable).
+
+The **in-RAM-only privacy guarantee is preserved**: a record references audio
+only when ``--record-audio`` actually wrote a WAV, which :meth:`MeetingRecord.
+has_audio` gates (audio playback and archived re-diarize check it — PLAN.md §5
+Stage B4). A record with no audio still supports text click-to-jump, because the
+word timestamps live in the transcript JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from stenograf.config import Language
+from stenograf.profiles import data_dir
+from stenograf.transcript import Transcript, UnsupportedTranscriptVersion
+
+_INDEX_VERSION = 1
+
+TRANSCRIPT_STEM = "transcript"
+"""Basename (without extension) of the managed transcript files in a meeting dir:
+``transcript.json`` / ``transcript.md`` / ``transcript.srt`` / ``transcript.vtt``."""
+
+TRANSCRIPT_FORMATS = ("md", "json", "srt", "vtt")
+"""Transcript file extensions the archive recognizes when summarizing a dir."""
+
+_FORMAT_METHODS = {"md": "to_markdown", "json": "to_json", "srt": "to_srt", "vtt": "to_vtt"}
+"""Transcript extension → the :class:`Transcript` method that renders it."""
+
+AUDIO_NAME = "audio.wav"
+"""Managed name of the opt-in ``--record-audio`` WAV inside a meeting dir."""
+
+_ID_TIMESTAMP = re.compile(r"^meeting-(\d{8})-(\d{6})")
+
+
+@dataclass
+class MeetingRecord:
+    """Lightweight index metadata for one archived meeting.
+
+    Denormalized into the index so the archive can be listed without opening each
+    transcript. ``dir`` is where the transcript files actually live — normally the
+    managed ``meetings/<id>/`` but an explicit ``--out`` can point elsewhere while
+    still registering here. Plain (unfrozen) dataclass: records are value-compared
+    for round-trip tests but deliberately unhashable (the ``speakers`` dict would
+    make a frozen hash raise — see :class:`~stenograf.profiles.SpeakerProfile`)."""
+
+    id: str
+    title: str | None
+    created_at: str
+    """ISO-8601 creation timestamp (string, so the index is plain JSON)."""
+    duration_s: float
+    language: Language | None
+    speakers: dict[str, int | None] = field(default_factory=dict)
+    """Per-channel resolved speaker count (``mic``/``system``, or ``audio`` for a
+    file transcribe); ``None`` for a channel whose count was left at a default."""
+    formats: tuple[str, ...] = ()
+    dir: Path = field(default=Path())
+    audio_path: Path | None = None
+
+    def has_audio(self) -> bool:
+        """True only when a recorded WAV actually exists on disk.
+
+        The single predicate gating archived audio *playback* and archived
+        *re-diarize* (PLAN.md §5 Stage B4) — both contradict the in-memory-only
+        guarantee unless ``--record-audio`` was used, and a referenced file can
+        also have been deleted since."""
+        return self.audio_path is not None and self.audio_path.exists()
+
+    def _to_json(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "created_at": self.created_at,
+            "duration_s": self.duration_s,
+            "language": self.language.value if self.language else None,
+            "speakers": dict(self.speakers),
+            "formats": list(self.formats),
+            "dir": str(self.dir),
+            "audio_path": str(self.audio_path) if self.audio_path is not None else None,
+        }
+
+    @classmethod
+    def _from_json(cls, data: dict) -> MeetingRecord:
+        audio = data.get("audio_path")
+        language = data.get("language")
+        return cls(
+            id=data["id"],
+            title=data.get("title"),
+            created_at=data.get("created_at", ""),
+            duration_s=data.get("duration_s", 0.0),
+            language=Language(language) if language is not None else None,
+            speakers=dict(data.get("speakers", {})),
+            formats=tuple(data.get("formats", ())),
+            dir=Path(data["dir"]),
+            audio_path=Path(audio) if audio is not None else None,
+        )
+
+
+class MeetingArchive:
+    """A managed, index-backed library of :class:`MeetingRecord` s.
+
+    Load with :meth:`load` (a missing index is an empty archive), mutate with
+    :meth:`add`/:meth:`remove` (each persists atomically), read a transcript back
+    through the A1 loader with :meth:`load_transcript`, and self-heal the index
+    against the directory tree with :meth:`reconcile`.
+    """
+
+    def __init__(
+        self, root: Path | None = None, records: list[MeetingRecord] | None = None
+    ) -> None:
+        self.root = Path(root) if root is not None else meetings_dir()
+        # Keyed by id (== dir name) so get/remove are O(1) and ids stay unique;
+        # dict preserves insertion order for a stable listing.
+        self._records: dict[str, MeetingRecord] = {r.id: r for r in (records or [])}
+
+    @property
+    def index_path(self) -> Path:
+        return self.root / "index.json"
+
+    # ---- persistence ------------------------------------------------------
+
+    @classmethod
+    def load(cls, root: Path | None = None) -> MeetingArchive:
+        root = Path(root) if root is not None else meetings_dir()
+        index = root / "index.json"
+        if not index.exists():
+            return cls(root)
+        data = json.loads(index.read_text(encoding="utf-8"))
+        records = [MeetingRecord._from_json(r) for r in data.get("meetings", [])]
+        return cls(root, records)
+
+    def save(self) -> None:
+        """Write the index to ``index_path`` atomically (temp file + replace)."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(
+            {"version": _INDEX_VERSION, "meetings": [r._to_json() for r in self._records.values()]},
+            ensure_ascii=False,
+            indent=2,
+        )
+        with tempfile.NamedTemporaryFile(
+            "w", dir=self.root, suffix=".part", delete=False, encoding="utf-8"
+        ) as tmp:
+            tmp.write(payload)
+            tmp_path = Path(tmp.name)
+        tmp_path.replace(self.index_path)
+
+    # ---- reads ------------------------------------------------------------
+
+    def records(self) -> list[MeetingRecord]:
+        """Every record, in insertion order (callers sort as they like)."""
+        return list(self._records.values())
+
+    def get(self, meeting_id: str) -> MeetingRecord | None:
+        return self._records.get(meeting_id)
+
+    def meeting_dir(self, meeting_id: str) -> Path:
+        """The managed directory for ``meeting_id`` (``root/<id>``); the default
+        ``steno start`` output location for a new meeting."""
+        return self.root / meeting_id
+
+    def load_transcript(self, meeting_id: str) -> Transcript:
+        """Read a meeting's transcript back through :meth:`Transcript.from_json`."""
+        record = self._records.get(meeting_id)
+        if record is None:
+            raise KeyError(meeting_id)
+        text = (record.dir / f"{TRANSCRIPT_STEM}.json").read_text(encoding="utf-8")
+        return Transcript.from_json(text)
+
+    # ---- writes -----------------------------------------------------------
+
+    def allocate_id(self, created_at: datetime) -> str:
+        """Mint a stable, unique meeting id for ``created_at``.
+
+        Base form ``meeting-YYYYMMDD-HHMMSS``; on collision (same second, or a dir
+        already present) append ``-2``, ``-3``, … so the id — and therefore the
+        managed dir name — is always free."""
+        base = f"meeting-{created_at:%Y%m%d-%H%M%S}"
+        candidate = base
+        suffix = 2
+        while candidate in self._records or (self.root / candidate).exists():
+            candidate = f"{base}-{suffix}"
+            suffix += 1
+        return candidate
+
+    def add(self, record: MeetingRecord) -> None:
+        """Insert or replace a record by id and persist the index."""
+        self._records[record.id] = record
+        self.save()
+
+    def rewrite(self, record: MeetingRecord, transcript: Transcript) -> MeetingRecord:
+        """Rewrite a meeting's managed transcript files from ``transcript`` and
+        refresh its index metadata under the same id.
+
+        The persistence half of the reverse-control channel (PLAN.md §5 Stage B4):
+        after a rename or re-finalize produces a new transcript, re-render each of
+        the record's formats into ``<dir>/transcript.{fmt}`` (atomic temp+replace,
+        so a reader never sees a half-written file) and re-derive the metadata that
+        can have changed — title, language, per-channel speaker counts, duration —
+        while keeping the id, created_at, dir, formats, and audio reference. The
+        updated record is re-added (persisting the index) and returned."""
+        record.dir.mkdir(parents=True, exist_ok=True)
+        for fmt in record.formats:
+            method = _FORMAT_METHODS.get(fmt)
+            if method is None:
+                continue  # an unknown extension in the record — nothing to render
+            path = record.dir / f"{TRANSCRIPT_STEM}.{fmt}"
+            _atomic_write_text(path, getattr(transcript, method)())
+        updated = MeetingRecord(
+            id=record.id,
+            title=transcript.profile.title,
+            created_at=record.created_at,
+            duration_s=max((e.end for e in transcript.entries), default=0.0),
+            language=transcript.language,
+            speakers=_speakers_from_transcript(transcript),
+            formats=record.formats,
+            dir=record.dir,
+            audio_path=record.audio_path,
+        )
+        self.add(updated)
+        return updated
+
+    def remove(self, meeting_id: str) -> bool:
+        """Drop a record from the index (leaves its files alone). Persists if changed."""
+        if self._records.pop(meeting_id, None) is None:
+            return False
+        self.save()
+        return True
+
+    def reconcile(self) -> None:
+        """Self-heal the index against the actual meeting directories.
+
+        Drops records whose ``dir`` has vanished, and adopts orphan managed dirs
+        (a ``meetings/<id>/`` holding a ``transcript.json`` that the index doesn't
+        know about — e.g. written while the index was unavailable). External
+        ``--out`` dirs are never scanned for adoption; only the managed root is."""
+        for meeting_id, record in list(self._records.items()):
+            if not record.dir.exists():
+                del self._records[meeting_id]
+        if self.root.exists():
+            for child in sorted(self.root.iterdir()):
+                if not child.is_dir() or child.name in self._records:
+                    continue
+                adopted = _record_from_dir(child)
+                if adopted is not None:
+                    self._records[adopted.id] = adopted
+        self.save()
+
+
+def _record_from_dir(directory: Path) -> MeetingRecord | None:
+    """Reconstruct a record from a managed meeting dir, or ``None`` if it holds no
+    readable transcript (a half-written or unrelated directory)."""
+    transcript_json = directory / f"{TRANSCRIPT_STEM}.json"
+    if not transcript_json.exists():
+        return None
+    try:
+        transcript = Transcript.from_json(transcript_json.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, UnsupportedTranscriptVersion, KeyError):
+        return None
+    audio = directory / AUDIO_NAME
+    formats = tuple(
+        ext for ext in TRANSCRIPT_FORMATS if (directory / f"{TRANSCRIPT_STEM}.{ext}").exists()
+    )
+    return MeetingRecord(
+        id=directory.name,
+        title=transcript.profile.title,
+        created_at=_created_at_from_id(directory.name),
+        duration_s=max((e.end for e in transcript.entries), default=0.0),
+        language=transcript.language,
+        speakers=_speakers_from_transcript(transcript),
+        formats=formats,
+        dir=directory,
+        audio_path=audio if audio.exists() else None,
+    )
+
+
+def _speakers_from_transcript(transcript: Transcript) -> dict[str, int | None]:
+    """Per-channel resolved speaker counts off a transcript's parameters (empty
+    when it has none — e.g. a crash checkpoint predating the finalize)."""
+    if transcript.parameters is None:
+        return {}
+    return {ch: rv.value for ch, rv in transcript.parameters.speakers.items()}  # type: ignore[misc]
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` via a temp file + replace, so a reader never sees a partial
+    file (the same discipline :meth:`MeetingArchive.save` uses for the index)."""
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    tmp.replace(path)
+
+
+def _created_at_from_id(meeting_id: str) -> str:
+    """Recover an ISO timestamp from a ``meeting-YYYYMMDD-HHMMSS`` id (the id
+    encodes it), or ``""`` for a non-standard dir name adopted during reconcile."""
+    match = _ID_TIMESTAMP.match(meeting_id)
+    if match:
+        try:
+            return datetime.strptime(match.group(1) + match.group(2), "%Y%m%d%H%M%S").isoformat()
+        except ValueError:
+            pass
+    return ""
+
+
+def meetings_dir() -> Path:
+    """Managed archive root: ``data_dir()/meetings`` (honors ``$STENOGRAF_DATA``)."""
+    return data_dir() / "meetings"