plaudio 0.1.0__py3-none-any.whl

plaudio/__init__.py

@@ -0,0 +1,2 @@
+"""Plaudio: voice-bank-first speaker labelling for the Plaud Note family."""
+__version__ = "0.1.0"

plaudio/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface."""

plaudio/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Subcommand handlers."""

plaudio/cli/commands/clean.py

@@ -0,0 +1,74 @@
+"""`plaudio clean TRANSCRIPT_MD [--corrections FILE]`"""
+from __future__ import annotations
+import argparse, pathlib, re, sys
+from plaudio.core.clean import (
+    load_corrections, apply_corrections, strip_silence_fillers,
+    merge_fragments, reflow_speaker_paragraphs, fmt_ts, wrap_para,
+)
+
+TRANSCRIPT_RE = re.compile(r"^## Transcript\s*$", re.M)
+SEG_RE = re.compile(
+    r"\*\*\[(\d+):(\d+)[–—\-](\d+):(\d+)\] ([^*:]+):\*\* "
+    r"((?:.|\n(?!\*\*\[))+?)(?=\n\*\*\[|\Z)",
+    re.MULTILINE,
+)
+NEXT_SECTION_RE = re.compile(r"^## (?!Transcript)", re.M)
+
+def parse_transcript_block(content: str):
+    m_start = TRANSCRIPT_RE.search(content)
+    if not m_start:
+        return [], -1, -1
+    rest = content[m_start.end():]
+    m_next = NEXT_SECTION_RE.search(rest)
+    end_idx = m_start.end() + (m_next.start() if m_next else len(rest))
+    block = content[m_start.end():end_idx]
+    segments = []
+    for match in SEG_RE.finditer(block):
+        m1, s1, m2, s2, speaker, text = match.groups()
+        segments.append({
+            "speaker": speaker.strip(),
+            "t_start": int(m1) * 60 + int(s1),
+            "t_end": int(m2) * 60 + int(s2),
+            "text": " ".join(text.split()),
+        })
+    return segments, m_start.start(), end_idx
+
+def render_transcript(segments, meta_line):
+    lines = ["## Transcript", "", meta_line, ""]
+    for seg in segments:
+        if not seg["text"].strip(): continue
+        lines.append(f"**[{fmt_ts(seg['t_start'])}–{fmt_ts(seg['t_end'])}] {seg['speaker']}:** "
+                     f"{wrap_para(seg['text'])}")
+        lines.append("")
+    return "\n".join(lines)
+
+def cmd_clean(args: argparse.Namespace) -> int:
+    path = pathlib.Path(args.path).expanduser()
+    if not path.exists():
+        print(f"not found: {path}", file=sys.stderr); return 2
+    corrections = load_corrections(pathlib.Path(args.corrections).expanduser()) if args.corrections else []
+    content = path.read_text()
+    if "<!-- cleaned: true -->" in content and not args.force:
+        print(f"  skip (already cleaned): {path.name}")
+        return 0
+    segments, start, end = parse_transcript_block(content)
+    if not segments:
+        print(f"  no transcript block found: {path.name}", file=sys.stderr); return 1
+    for seg in segments:
+        seg["text"] = apply_corrections(seg["text"], corrections)
+        seg["text"] = strip_silence_fillers(seg["text"])
+        seg["text"] = re.sub(r"\s+", " ", seg["text"]).strip()
+    segments = merge_fragments(segments)
+    segments = reflow_speaker_paragraphs(segments)
+    meta_line = "*Local pipeline transcript. Cleaned for readability.*"
+    new_block = render_transcript(segments, meta_line) + "\n<!-- cleaned: true -->\n"
+    path.write_text(content[:start] + new_block + content[end:])
+    print(f"  cleaned: {path.name}")
+    return 0
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("clean", help="clean a transcript markdown file")
+    p.add_argument("path")
+    p.add_argument("--corrections", help="path to a JSON list of [wrong, right] pairs")
+    p.add_argument("--force", action="store_true")
+    p.set_defaults(func=cmd_clean)

plaudio/cli/commands/db.py

@@ -0,0 +1,97 @@
+"""`plaudio db ingest|search|list`"""
+from __future__ import annotations
+import argparse, os, pathlib, sys
+from plaudio.core.corpus import TranscriptCorpus
+
+
+def _corpus_path() -> pathlib.Path:
+    return pathlib.Path(os.environ.get("PLAUDIO_CORPUS", str(TranscriptCorpus.default_path()))).expanduser()
+
+
+def _parse_speaker_map(items: list[str] | None) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in items or []:
+        if "=" not in item:
+            continue
+        k, v = item.split("=", 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def cmd_ingest(args: argparse.Namespace) -> int:
+    corpus = TranscriptCorpus(_corpus_path())
+    p = pathlib.Path(args.plaud_json).expanduser()
+    if not p.exists():
+        print(f"transcript not found: {p}", file=sys.stderr)
+        return 2
+    corpus.ingest(p,
+                  meeting_id=args.meeting_id,
+                  date=args.date,
+                  title=args.title,
+                  speakers=_parse_speaker_map(args.speaker),
+                  vault_note=args.vault_note,
+                  audio_path=args.audio_path)
+    print(f"ingested meeting '{args.meeting_id}'")
+    return 0
+
+
+def _fmt_ms(ms: int) -> str:
+    s = ms // 1000
+    return f"{s//60:02d}:{s%60:02d}"
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    corpus = TranscriptCorpus(_corpus_path())
+    rows = corpus.search(args.query, speaker=args.speaker,
+                         since=args.since, until=args.until, limit=args.limit)
+    if not rows:
+        print("(no matches)")
+        return 0
+    last = None
+    for r in rows:
+        if r["meeting_id"] != last:
+            print(f"\n-- {r['date']} | {r['title']} ({r['meeting_id']}) --")
+            last = r["meeting_id"]
+        speaker = r["speaker_name"] or r["speaker_label"]
+        print(f"  [{_fmt_ms(r['start_ms'])}-{_fmt_ms(r['end_ms'])}] {speaker}: {r['content'][:200]}")
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    corpus = TranscriptCorpus(_corpus_path())
+    rows = corpus.list_meetings()
+    if not rows:
+        print("(empty)")
+        return 0
+    for r in rows:
+        dur = f"{(r['duration_ms'] or 0)/60000:.1f}min" if r['duration_ms'] else "?"
+        print(f"  {r['date']}  {r['title'][:55]:<55s}  {dur:>8s}  "
+              f"{(r['language'] or '?'):>4s}  {str(r['n_speakers'] or '?'):>2s}sp  {r['n_segments']:>5d}seg")
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    db = sub.add_parser("db", help="searchable transcripts corpus")
+    dbsub = db.add_subparsers(dest="db_cmd", required=True)
+
+    i = dbsub.add_parser("ingest", help="ingest a .plaud.json transcript into the corpus")
+    i.add_argument("plaud_json", help="path to .plaud.json file")
+    i.add_argument("--meeting-id", required=True, help="unique meeting identifier")
+    i.add_argument("--date", required=True, help="meeting date YYYY-MM-DD")
+    i.add_argument("--title", required=True, help="meeting title")
+    i.add_argument("--vault-note", help="path to vault note for this meeting")
+    i.add_argument("--audio-path", help="path to source audio file")
+    i.add_argument("--speaker", action="append", metavar="LABEL=Name",
+                   help="speaker label to real-name mapping; repeat for multiple")
+    i.set_defaults(func=cmd_ingest)
+
+    s = dbsub.add_parser("search", help="full-text search across transcripts")
+    s.add_argument("query", help="search query (trigram, supports ZH+EN)")
+    s.add_argument("--speaker", help="filter to a specific speaker name or label")
+    s.add_argument("--since", metavar="YYYY-MM-DD", help="earliest meeting date")
+    s.add_argument("--until", metavar="YYYY-MM-DD", help="latest meeting date")
+    s.add_argument("--limit", type=int, default=50, help="max results (default 50)")
+    s.set_defaults(func=cmd_search)
+
+    lst = dbsub.add_parser("list", help="list all ingested meetings")
+    lst.set_defaults(func=cmd_list)

plaudio/cli/commands/doctor.py

@@ -0,0 +1,85 @@
+"""`plaudio doctor` -- environment + dependency checks. High-leverage support tool."""
+from __future__ import annotations
+import argparse, os, pathlib, platform, shutil, sys
+
+
+def _ok(name: str, detail: str = "") -> None:
+    print(f"  ok {name}" + (f": {detail}" if detail else ""))
+
+
+def _bad(name: str, detail: str = "") -> int:
+    print(f"  fail {name}" + (f" -- {detail}" if detail else ""))
+    return 1
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    print("Plaudio doctor -- environment check\n")
+    fails = 0
+
+    if platform.system() == "Darwin":
+        _ok("macOS", platform.mac_ver()[0])
+    else:
+        fails |= _bad("platform", f"{platform.system()} (Plaudio supports macOS only)")
+
+    if platform.machine() == "arm64":
+        _ok("Apple Silicon", "arm64")
+    else:
+        fails |= _bad("CPU", f"{platform.machine()} (Apple Silicon required for mlx-whisper)")
+
+    pv = sys.version_info
+    if pv >= (3, 11):
+        _ok("Python", f"{pv.major}.{pv.minor}.{pv.micro}")
+    else:
+        fails |= _bad("Python", f"{pv.major}.{pv.minor} (>= 3.11 required)")
+
+    ff = shutil.which("ffmpeg")
+    if ff:
+        _ok("ffmpeg", ff)
+    else:
+        fails |= _bad("ffmpeg", "not on PATH; install: brew install ffmpeg")
+
+    mw = shutil.which("mlx_whisper")
+    if mw:
+        _ok("mlx_whisper", mw)
+    else:
+        fails |= _bad("mlx_whisper", "not installed; pip install mlx-whisper")
+
+    try:
+        import pyannote.audio as _pa
+        _ok("pyannote.audio", getattr(_pa, "__version__", "?"))
+    except ImportError as e:
+        fails |= _bad("pyannote.audio", f"import failed: {e}")
+
+    token_path = pathlib.Path(
+        os.environ.get("PLAUDIO_HF_TOKEN_FILE", "~/.huggingface/token")
+    ).expanduser()
+    if token_path.exists() and token_path.read_text().strip():
+        _ok("HF token", str(token_path))
+    else:
+        fails |= _bad(
+            "HF token",
+            f"not found at {token_path}. pyannote/speaker-diarization-3.1 is gated; "
+            f"accept at https://huggingface.co/pyannote/speaker-diarization-3.1 and "
+            f"save your token at {token_path}",
+        )
+
+    try:
+        import torch
+        if torch.backends.mps.is_available():
+            _ok("torch MPS", "available")
+        else:
+            print("  - torch MPS not available (will fall back to CPU; slower)")
+    except ImportError:
+        fails |= _bad("torch", "not installed")
+
+    print()
+    if fails:
+        print("Doctor: some checks failed. See messages above.")
+        return 1
+    print("Doctor: all checks passed.")
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("doctor", help="environment + dependency check")
+    p.set_defaults(func=cmd_doctor)

plaudio/cli/commands/enrol.py

@@ -0,0 +1,56 @@
+"""`plaudio enrol AUDIO --name X --start S --end S`"""
+from __future__ import annotations
+import argparse, os, pathlib, sys
+from plaudio.core.voicebank import VoiceBank
+
+DEFAULT_TOKEN_FILE = pathlib.Path("~/.huggingface/token").expanduser()
+
+CONSENT_TEXT = """\
+plaudio enrol: enrolling a person's voice creates a biometric profile.
+Only enrol with the speaker's knowledge. The voicebank lives at
+{path} (mode 0600); back it up explicitly if you want it elsewhere.
+"""
+
+def _bank_path() -> pathlib.Path:
+    return pathlib.Path(os.environ.get("PLAUDIO_VOICEBANK", str(VoiceBank.default_path()))).expanduser()
+
+def cmd_enrol(args: argparse.Namespace) -> int:
+    bank_path = _bank_path()
+    if not bank_path.exists():
+        print(CONSENT_TEXT.format(path=bank_path), file=sys.stderr)
+    token_file = pathlib.Path(args.hf_token_file).expanduser()
+    if not token_file.exists():
+        print(f"HF token not found at {token_file}; create it or pass --hf-token-file.", file=sys.stderr)
+        return 2
+    hf_token = token_file.read_text().strip()
+    bank = VoiceBank.load(bank_path)
+    audio = pathlib.Path(args.audio).expanduser()
+    try:
+        profile = bank.enrol_from_audio(
+            audio,
+            name=args.name,
+            start_s=args.start,
+            end_s=args.end,
+            hf_token=hf_token,
+            notes=args.notes,
+            num_speakers=args.num_speakers,
+        )
+    except Exception as e:
+        print(f"enrolment failed: {e}", file=sys.stderr)
+        return 1
+    bank.save(bank_path)
+    print(f"enrolled {profile.name} (dim={profile.embedding_dim}, duration={profile.duration_s:.0f}s)")
+    print(f"voicebank: {bank_path}")
+    return 0
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("enrol", help="enrol a voice profile from audio")
+    p.add_argument("audio")
+    p.add_argument("--name", required=True)
+    p.add_argument("--start", type=float, default=None, help="start (sec) of the clean window")
+    p.add_argument("--end", type=float, default=None, help="end (sec) of the clean window")
+    p.add_argument("--num-speakers", type=int, default=None,
+                   help="hint to pyannote; helps when the audio has few speakers")
+    p.add_argument("--notes", default="")
+    p.add_argument("--hf-token-file", default=str(DEFAULT_TOKEN_FILE))
+    p.set_defaults(func=cmd_enrol)

plaudio/cli/commands/label.py

@@ -0,0 +1,240 @@
+"""`plaudio label AUDIO TRANSCRIPT [--enrol] [--batch-label "L=Name,..."]`"""
+from __future__ import annotations
+import argparse, json, os, pathlib, platform, subprocess, sys
+from collections import defaultdict
+from plaudio.core.voicebank import VoiceBank
+
+DEFAULT_TOKEN_FILE = pathlib.Path("~/.huggingface/token").expanduser()
+
+def _bank_path() -> pathlib.Path:
+    return pathlib.Path(os.environ.get("PLAUDIO_VOICEBANK", str(VoiceBank.default_path()))).expanduser()
+
+def fmt_ms(ms): s = int(ms / 1000); return f"{s//60:02d}:{s%60:02d}"
+
+def find_best_clip(segs, target_speaker, min_dur_s=15, max_dur_s=45):
+    spans = []
+    cur_start = cur_end = None
+    for s in sorted(segs, key=lambda x: x['start_time']):
+        if s['speaker'] != target_speaker: continue
+        if cur_start is None:
+            cur_start, cur_end = s['start_time'], s['end_time']
+        elif s['start_time'] - cur_end < 3000:
+            cur_end = s['end_time']
+        else:
+            spans.append((cur_start, cur_end))
+            cur_start, cur_end = s['start_time'], s['end_time']
+    if cur_start is not None: spans.append((cur_start, cur_end))
+    if not spans: return None
+    longest = max(spans, key=lambda t: t[1]-t[0])
+    if (longest[1]-longest[0])/1000 < min_dur_s: return None
+    return (longest[0], min(longest[1], longest[0] + max_dur_s*1000))
+
+def find_enrol_window(segs, target_speaker, max_dur_s=180):
+    spans = []
+    cur_start = cur_end = None
+    for s in sorted(segs, key=lambda x: x['start_time']):
+        if s['speaker'] != target_speaker: continue
+        if cur_start is None:
+            cur_start, cur_end = s['start_time'], s['end_time']
+        elif s['start_time'] - cur_end < 5000:
+            cur_end = s['end_time']
+        else:
+            spans.append((cur_start, cur_end))
+            cur_start, cur_end = s['start_time'], s['end_time']
+    if cur_start is not None: spans.append((cur_start, cur_end))
+    if not spans: return None
+    longest = max(spans, key=lambda t: t[1]-t[0])
+    return (longest[0], min(longest[1], longest[0] + max_dur_s*1000))
+
+def play_clip_bg(audio_path, start_ms, end_ms):
+    tmp = pathlib.Path(f"/tmp/plaudio-clip-{start_ms}-{end_ms}.wav")
+    dur_s = (end_ms - start_ms) / 1000
+    try:
+        r = subprocess.run(
+            ["ffmpeg", "-y", "-ss", str(start_ms/1000), "-t", str(dur_s),
+             "-i", str(audio_path), "-ar", "16000", "-ac", "1", str(tmp)],
+            capture_output=True, text=True, timeout=30)
+        if r.returncode != 0:
+            return None, f"ffmpeg exit {r.returncode}: {r.stderr[-300:]}"
+        if not tmp.exists() or tmp.stat().st_size == 0:
+            return None, "ffmpeg produced empty file"
+        player = "afplay" if platform.system() == "Darwin" else "ffplay"
+        args_list = [player, str(tmp)] if player == "afplay" \
+                    else [player, "-nodisp", "-autoexit", "-loglevel", "quiet", str(tmp)]
+        proc = subprocess.Popen(args_list, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return proc, tmp
+    except FileNotFoundError as e:
+        return None, f"missing executable: {e}"
+    except Exception as e:
+        return None, f"unexpected: {e}"
+
+def stop_playback(proc, tmp):
+    if proc is not None and proc.poll() is None:
+        try:
+            proc.terminate(); proc.wait(timeout=2)
+        except Exception:
+            try: proc.kill()
+            except Exception: pass
+    if tmp is not None:
+        try: tmp.unlink(missing_ok=True)
+        except Exception: pass
+
+def save_labels(data, jpath, mapping):
+    for s in data['segments']:
+        if s['speaker'] in mapping:
+            if 'original_speaker' not in s:
+                s['original_speaker'] = s['speaker']
+            s['speaker'] = mapping[s['speaker']]
+    jpath.write_text(json.dumps(data, ensure_ascii=False, indent=2))
+
+def _enrol(name, audio, start_ms, end_ms, hf_token, num_speakers=None):
+    print(f"  enrolling {name} from [{fmt_ms(start_ms)}-{fmt_ms(end_ms)}]...")
+    bank = VoiceBank.load(_bank_path())
+    try:
+        bank.enrol_from_audio(
+            pathlib.Path(audio),
+            name=name,
+            start_s=start_ms/1000,
+            end_s=end_ms/1000,
+            hf_token=hf_token,
+            notes=f"via plaudio label interactive labelling",
+            num_speakers=num_speakers,
+        )
+        bank.save(_bank_path())
+        print(f"  enrolled {name}")
+    except Exception as e:
+        print(f"  enrolment failed: {e}", file=sys.stderr)
+
+def cmd_label(args: argparse.Namespace) -> int:
+    audio = pathlib.Path(args.audio).expanduser()
+    jpath = pathlib.Path(args.transcript).expanduser()
+    if not audio.exists(): print(f"audio not found: {audio}", file=sys.stderr); return 2
+    if not jpath.exists(): print(f"transcript not found: {jpath}", file=sys.stderr); return 2
+
+    hf_token = ""
+    if args.enrol or args.batch_label:
+        tf = pathlib.Path(args.hf_token_file).expanduser()
+        if not tf.exists():
+            print(f"HF token not found at {tf}; enrolment needs it", file=sys.stderr); return 2
+        hf_token = tf.read_text().strip()
+
+    data = json.loads(jpath.read_text())
+    segs = data.get('segments', [])
+    if not segs: print("no segments in json", file=sys.stderr); return 2
+
+    by_spk = defaultdict(list)
+    for s in segs:
+        by_spk[s['speaker']].append(s)
+    durs = {k: sum((x['end_time']-x['start_time'])/1000 for x in v) for k,v in by_spk.items()}
+    main_spk = sorted([k for k,v in durs.items() if v > 5], key=lambda k: -durs[k])
+
+    if args.batch_label:
+        mapping = {}
+        enrol_windows = {}
+        for pair in args.batch_label.split(","):
+            if "=" not in pair: continue
+            spk, name = pair.split("=", 1)
+            spk, name = spk.strip(), name.strip()
+            if spk not in by_spk:
+                print(f"  warn: {spk} not in transcript, skipping"); continue
+            mapping[spk] = name
+            es = find_enrol_window(by_spk[spk], spk, max_dur_s=180)
+            if es: enrol_windows[name] = es
+        if mapping:
+            save_labels(data, jpath, mapping)
+            print(f"batch-labelled {len(mapping)} speakers: {mapping}")
+            if args.enrol:
+                print("\n=== Enrolling voice profiles ===")
+                for name, (s_ms, e_ms) in enrol_windows.items():
+                    if name == "Unknown": continue
+                    _enrol(name, audio, s_ms, e_ms, hf_token)
+        return 0
+
+    print(f"\n{len(main_spk)} clusters to label (> 5s)\n")
+    mapping = {}
+    enrol_windows = {}
+
+    try:
+        for spk in main_spk:
+            if not (spk.startswith("SPEAKER_") or spk == "Unknown"):
+                print(f"\n{spk}: already labelled, skipping")
+                continue
+            clip = find_best_clip(by_spk[spk], spk, args.min_dur, args.max_dur)
+            if not clip:
+                print(f"  {spk}: no clean >={args.min_dur}s clip, skipping")
+                continue
+            start_ms, end_ms = clip
+            dur_s = (end_ms - start_ms) / 1000
+            print(f"\n{'='*70}")
+            print(f"Speaker: {spk}  |  Airtime: {durs[spk]:.0f}s ({durs[spk]/60:.1f}min)")
+            print(f"Clip: {fmt_ms(start_ms)}-{fmt_ms(end_ms)} ({dur_s:.0f}s)")
+            in_window = [x for x in by_spk[spk] if x['start_time'] >= start_ms and x['start_time'] < end_ms]
+            text = " ".join(x['content'] for x in in_window)
+            print(f"Text: \"{text[:500]}\"")
+            print()
+            playback_proc = playback_tmp = None
+            if not args.no_play:
+                playback_proc, playback_tmp = play_clip_bg(audio, start_ms, end_ms)
+                if playback_proc is None:
+                    print(f"  playback error: {playback_tmp}")
+                    playback_tmp = None
+                else:
+                    print("  (playing in background; type at any time to stop)")
+            try:
+                ans = input("name / [s]kip / [u]nknown / [r]eplay / [q]uit: ").strip()
+            except EOFError:
+                ans = 'q'
+            finally:
+                stop_playback(playback_proc, playback_tmp)
+            while ans.lower() == 'r':
+                if args.no_play:
+                    print("  (--no-play; cannot replay)")
+                    try: ans = input("name / [s]kip / [u]nknown / [q]uit: ").strip()
+                    except EOFError: ans = 'q'
+                    break
+                pp, pt = play_clip_bg(audio, start_ms, end_ms)
+                if pp is None:
+                    print(f"  replay error: {pt}")
+                else:
+                    print("  (replaying)")
+                try:
+                    ans = input("name / [s]kip / [u]nknown / [r]eplay / [q]uit: ").strip()
+                except EOFError:
+                    ans = 'q'
+                finally:
+                    stop_playback(pp, pt)
+            if ans.lower() in ('q', 'quit'): raise KeyboardInterrupt
+            if ans.lower() in ('s', 'skip', ''): continue
+            if ans.lower() in ('u', 'unknown'):
+                mapping[spk] = "Unknown"
+                save_labels(data, jpath, {spk: "Unknown"})
+                print(f"  -> {spk} = Unknown (saved)")
+                continue
+            mapping[spk] = ans
+            enrol_span = find_enrol_window(by_spk[spk], spk, max_dur_s=180)
+            enrol_windows[ans] = enrol_span if enrol_span else (start_ms, end_ms)
+            es_start, es_end = enrol_windows[ans]
+            save_labels(data, jpath, {spk: ans})
+            print(f"  -> {spk} = {ans} (saved); enrolment will use [{fmt_ms(es_start)}-{fmt_ms(es_end)}]")
+    except KeyboardInterrupt:
+        print("\n\n(quitting; labels saved so far)")
+
+    print(f"\nwrote {len(mapping)} labels to {jpath}")
+    if args.enrol and enrol_windows:
+        print(f"\n=== Enrolling voice profiles ({len(enrol_windows)} people) ===")
+        for name, (start_ms, end_ms) in enrol_windows.items():
+            if name == "Unknown": continue
+            _enrol(name, audio, start_ms, end_ms, hf_token)
+    return 0
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("label", help="interactive speaker labelling")
+    p.add_argument("audio")
+    p.add_argument("transcript")
+    p.add_argument("--enrol", action="store_true")
+    p.add_argument("--no-play", action="store_true")
+    p.add_argument("--batch-label", type=str)
+    p.add_argument("--min-dur", type=int, default=15)
+    p.add_argument("--max-dur", type=int, default=15)
+    p.add_argument("--hf-token-file", default=str(DEFAULT_TOKEN_FILE))
+    p.set_defaults(func=cmd_label)

plaudio/cli/commands/match.py

@@ -0,0 +1,59 @@
+"""`plaudio match AUDIO TRANSCRIPT [--threshold T] [--report]`"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import pathlib
+import sys
+from plaudio.core.voicebank import VoiceBank
+from plaudio.core.slidingmatch import SlidingMatcher, DEFAULT_THRESHOLD
+
+
+def _bank_path() -> pathlib.Path:
+    return pathlib.Path(
+        os.environ.get("PLAUDIO_VOICEBANK", str(VoiceBank.default_path()))
+    ).expanduser()
+
+
+def cmd_match(args: argparse.Namespace) -> int:
+    audio = pathlib.Path(args.audio).expanduser()
+    jpath = pathlib.Path(args.transcript).expanduser()
+    if not audio.exists():
+        print(f"audio not found: {audio}", file=sys.stderr)
+        return 2
+    if not jpath.exists():
+        print(f"transcript not found: {jpath}", file=sys.stderr)
+        return 2
+    bank = VoiceBank.load(_bank_path())
+    matcher = SlidingMatcher(bank, threshold=args.threshold)
+    data = json.loads(jpath.read_text())
+    segs = data.get("segments", [])
+    report = matcher.label_segments(audio, segs)
+    jpath.write_text(json.dumps(data, ensure_ascii=False, indent=2))
+    print(
+        f"  {report.get('n_matched', 0)} / {report.get('n_total', 0)} windows matched"
+        f" at threshold {args.threshold}"
+    )
+    print(
+        f"  coalesced into {report.get('n_runs', 0)} runs,"
+        f" relabelled {report.get('n_segments_relabelled', 0)} segments"
+    )
+    if args.report:
+        from collections import defaultdict
+
+        durs: dict[str, float] = defaultdict(float)
+        for s in segs:
+            durs[s["speaker"]] += (s["end_time"] - s["start_time"]) / 1000.0
+        print("\nPer-speaker durations:")
+        for k, v in sorted(durs.items(), key=lambda x: -x[1]):
+            print(f"  {k}: {v:.0f}s ({v/60:.1f}min)")
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("match", help="re-label transcript via voice-bank sliding match")
+    p.add_argument("audio")
+    p.add_argument("transcript")
+    p.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD)
+    p.add_argument("--report", action="store_true")
+    p.set_defaults(func=cmd_match)

plaudio/cli/commands/plaud.py

@@ -0,0 +1,22 @@
+"""`plaudio plaud login|list|sync` -- stubs in v0.1, full impl in v0.2."""
+from __future__ import annotations
+import argparse
+
+V02_MSG = (
+    "Plaud cloud sync is not implemented in v0.1. See README -> Roadmap. "
+    "For now: use the Plaud MCP via your editor's MCP host, or the Plaud "
+    "mobile app, then point `plaudio transcribe` at the downloaded audio."
+)
+
+
+def cmd_stub(args: argparse.Namespace) -> int:
+    print(V02_MSG)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("plaud", help="Plaud cloud sync (v0.2)")
+    psub = p.add_subparsers(dest="plaud_cmd", required=True)
+    psub.add_parser("login").set_defaults(func=cmd_stub)
+    psub.add_parser("list").set_defaults(func=cmd_stub)
+    psub.add_parser("sync").set_defaults(func=cmd_stub)

plaudio/cli/commands/transcribe.py

@@ -0,0 +1,30 @@
+"""`plaudio transcribe AUDIO [--vocab FILE] [--language LANG] [--out DIR]`"""
+from __future__ import annotations
+import argparse, pathlib, sys
+from plaudio.core.transcribe import transcribe, load_vocab_prompt, DEFAULT_MODEL
+
+
+def cmd_transcribe(args: argparse.Namespace) -> int:
+    audio = pathlib.Path(args.audio).expanduser()
+    out_dir = pathlib.Path(args.out).expanduser() if args.out else audio.parent
+    vocab = load_vocab_prompt(pathlib.Path(args.vocab).expanduser()) if args.vocab else ""
+    try:
+        segs, elapsed = transcribe(audio, out_dir=out_dir, language=args.language,
+                                   vocab=vocab, model=args.model)
+    except FileNotFoundError as e:
+        print(f"audio not found: {e}", file=sys.stderr)
+        return 2
+    print(f"ok {len(segs)} segments in {elapsed:.1f}s "
+          f"({len(segs)/max(elapsed,1e-3):.1f} seg/s)")
+    print(f"  output: {out_dir / (audio.stem + '.json')}")
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    t = sub.add_parser("transcribe", help="mlx-whisper ASR on an audio file")
+    t.add_argument("audio")
+    t.add_argument("--vocab", help="path to a vocab file (one term per line); default empty")
+    t.add_argument("--language", default="en")
+    t.add_argument("--out", help="output directory; default: same as audio")
+    t.add_argument("--model", default=DEFAULT_MODEL)
+    t.set_defaults(func=cmd_transcribe)