msteams-transcripts 1.0.0__py3-none-any.whl

teams_transcripts/cli.py

@@ -0,0 +1,228 @@
+"""Command line: browser, list, get, batch."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from .browser import ensure_browser, log
+from .config import PROG, SETTINGS, configure
+from .download import download_ref
+from .errors import TranscriptError
+from .model import parse_date, refs_from_recap_url, thread_id_from, transcript_refs_from_contents
+from .session import TeamsSession
+
+DESCRIPTION = """\
+Download Microsoft Teams meeting transcripts from the command line.
+
+Start the dedicated browser once with the 'browser' command and sign in to Teams
+there. Everything else replays the requests the Teams web client makes, so it
+reaches exactly the meetings you can already open.
+"""
+
+EPILOG = f"""\
+examples:
+  {PROG} browser
+  {PROG} list --from 2026-09-01 --to today
+  {PROG} get 3 --details
+  {PROG} get "https://teams.cloud.microsoft/l/meetingrecap?driveId=...&driveItemId=..." -f all
+  {PROG} batch --from 2026-09-01 --to 2026-09-30 --details -o ./transcripts
+"""
+
+
+def default_out() -> str:
+    return str(Path.cwd() / "transcripts")
+
+
+async def cmd_list(args) -> list[dict]:
+    """Print one row per transcript and cache the rows for 'get N'."""
+    start, end = parse_date(args.frm), parse_date(args.to, end=True)
+    async with TeamsSession() as s:
+        events = await s.calendar(start, end)
+        now = datetime.now(timezone.utc)
+        meetings = []
+        for e in events:
+            if not e.get("isOnlineMeeting") or e.get("isCancelled"):
+                continue
+            tid = thread_id_from(e.get("skypeTeamsMeetingUrl", "")) or thread_id_from(
+                json.dumps(e.get("skypeTeamsDataObject") or e.get("skypeTeamsData") or "")
+            )
+            if not tid:
+                continue
+            try:
+                ends = datetime.fromisoformat(e.get("endTime", "").replace("Z", "+00:00"))
+            except Exception:
+                ends = now
+            if ends > now:
+                continue
+            meetings.append(
+                {
+                    "subject": e.get("subject", ""),
+                    "start": e.get("startTime", ""),
+                    "end": e.get("endTime", ""),
+                    "threadId": tid,
+                    "iCalUID": e.get("iCalUID", ""),
+                    "organizer": e.get("organizerName", ""),
+                    "objectId": e.get("objectId", ""),
+                }
+            )
+        log(f"{len(events)} calendar events, {len(meetings)} past online meetings. Checking for transcripts ...")
+
+        rows: list[dict] = []
+        seen_threads: set[str] = set()
+        for m in meetings:
+            if m["threadId"] in seen_threads:
+                continue
+            seen_threads.add(m["threadId"])
+            contents = await s.meeting_contents(m["threadId"], m["iCalUID"])
+            same_thread = [x for x in meetings if x["threadId"] == m["threadId"]]
+            for ref in transcript_refs_from_contents(contents, m["subject"]):
+                # Match a transcript to the occurrence whose window contains its start.
+                occ = next((x for x in same_thread if ref["start"] and x["start"] <= ref["start"] <= x["end"]), None)
+                ref["subject"] = m["subject"]
+                ref["meetingStart"] = (occ or m)["start"]
+                ref["threadId"] = m["threadId"]
+                ref["organizer"] = m["organizer"]
+                ref["objectId"] = (occ or m)["objectId"]
+                ref["iCalUID"] = (occ or m)["iCalUID"]
+                if start.isoformat() <= (ref["start"] or ref["meetingStart"]) <= end.isoformat():
+                    rows.append(ref)
+        rows.sort(key=lambda r: r["start"] or r["meetingStart"])
+        for i, r in enumerate(rows, 1):
+            r["n"] = i
+
+        SETTINGS.state_dir.mkdir(parents=True, exist_ok=True)
+        SETTINGS.last_list.write_text(json.dumps(rows, indent=1), encoding="utf-8")
+        if args.json:
+            print(json.dumps(rows, indent=1))
+        else:
+            print(f"{'#':>3}  {'Start (UTC)':<17} {'Subject':<50} Organizer")
+            for r in rows:
+                st = (r["start"] or r["meetingStart"])[:16].replace("T", " ")
+                print(f"{r['n']:>3}  {st:<17} {r['subject'][:50]:<50} {r['organizer']}")
+            log(f"{len(rows)} transcript(s). Use:  {PROG} get <#>   or   {PROG} batch --from ... --to ...")
+        return rows
+
+
+async def _download_by_thread(s: TeamsSession, thread_id: str, args) -> None:
+    refs = transcript_refs_from_contents(await s.meeting_contents(thread_id))
+    if not refs:
+        raise TranscriptError("No transcript was found for that meeting.")
+    for r in refs:
+        await download_ref(s, r, Path(args.out), args.format, args.details)
+
+
+async def cmd_get(args) -> None:
+    """Download one transcript, named by row number, recap link or thread id."""
+    target: str = args.target
+    async with TeamsSession() as s:
+        if target.isdigit():
+            if not SETTINGS.last_list.exists():
+                raise TranscriptError(f"No previous list. Run:  {PROG} list --from ... --to ...")
+            rows = json.loads(SETTINGS.last_list.read_text(encoding="utf-8"))
+            ref = next((r for r in rows if r["n"] == int(target)), None)
+            if not ref:
+                raise TranscriptError(f"There is no row {target} in the last list.")
+        elif target.startswith("http"):
+            ref = refs_from_recap_url(target)
+            if ref is None:
+                tid = thread_id_from(target)
+                if not tid:
+                    raise TranscriptError("That link has neither drive identifiers nor a meeting thread id.")
+                await _download_by_thread(s, tid, args)
+                return
+        else:
+            await _download_by_thread(s, thread_id_from(target) or target, args)
+            return
+        if args.sharepoint_host:
+            ref["host"] = args.sharepoint_host
+        await download_ref(s, ref, Path(args.out), args.format, args.details)
+
+
+async def cmd_batch(args) -> None:
+    """Download every transcript in a date range."""
+    rows = await cmd_list(argparse.Namespace(frm=args.frm, to=args.to, json=False))
+    if args.only:
+        want = {int(x) for x in re.split(r"[,\s]+", args.only.strip()) if x}
+        rows = [r for r in rows if r["n"] in want]
+    if not rows:
+        return
+    async with TeamsSession() as s:
+        ok = fail = 0
+        for r in rows:
+            try:
+                await download_ref(s, r, Path(args.out), args.format, args.details)
+                ok += 1
+            except Exception as ex:
+                fail += 1
+                log(f"  FAILED {r.get('subject')}: {ex}")
+        log(f"Done: {ok} downloaded, {fail} failed. Output: {Path(args.out).resolve()}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog=PROG,
+        description=DESCRIPTION,
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    ap.add_argument("--port", type=int, default=0, help="browser debugging port (default 9222, or TT_CDP_PORT)")
+    ap.add_argument("--profile", default="", help="browser profile directory (or TT_PROFILE_DIR)")
+    ap.add_argument("--browser", default="", help="path to the Edge or Chrome executable (or TT_BROWSER_EXE)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("browser", help="start or check the dedicated browser instance")
+
+    p = sub.add_parser("list", help="list past online meetings that have transcripts")
+    p.add_argument("--from", dest="frm", required=True, metavar="YYYY-MM-DD")
+    p.add_argument("--to", required=True, metavar="YYYY-MM-DD", help="a date, or 'today'")
+    p.add_argument("--json", action="store_true", help="print JSON instead of a table")
+
+    p = sub.add_parser("get", help="download one transcript")
+    p.add_argument("target", help="row number from 'list', a recap URL, or 19:meeting_...@thread.v2")
+    p.add_argument("-o", "--out", default=None, help="output directory (default ./transcripts)")
+    p.add_argument("-f", "--format", choices=["txt", "json", "vtt", "all"], default="txt")
+    p.add_argument("--sharepoint-host", default="", help="override the SharePoint host, e.g. contoso-my.sharepoint.com")
+    p.add_argument(
+        "-d",
+        "--details",
+        action="store_true",
+        help="add organizer, location, invited attendees, speakers, shared files and invitation text; also writes .meta.json",
+    )
+
+    p = sub.add_parser("batch", help="download every transcript in a date range")
+    p.add_argument("--from", dest="frm", required=True, metavar="YYYY-MM-DD")
+    p.add_argument("--to", required=True, metavar="YYYY-MM-DD")
+    p.add_argument("-o", "--out", default=None, help="output directory (default ./transcripts)")
+    p.add_argument("-f", "--format", choices=["txt", "json", "vtt", "all"], default="txt")
+    p.add_argument("-d", "--details", action="store_true", help="same as for 'get'")
+    p.add_argument("--only", default="", help="comma-separated row numbers instead of all, e.g. 3,7,12")
+    return ap
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    configure(port=args.port, profile=args.profile, browser=args.browser)
+    if getattr(args, "out", None) is None:
+        args.out = default_out()
+    try:
+        if args.cmd == "browser":
+            ensure_browser()
+            log(f"Debugging endpoint: {SETTINGS.cdp_url}   profile: {SETTINGS.profile_dir}")
+            return
+        runner = {"list": cmd_list, "get": cmd_get, "batch": cmd_batch}[args.cmd]
+        asyncio.run(runner(args))
+    except TranscriptError as ex:
+        sys.exit(str(ex))
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

teams_transcripts/config.py

@@ -0,0 +1,88 @@
+"""Runtime settings: where the browser is, which profile it uses, where state lives.
+
+Every value can be set by an environment variable, and the command line can
+override them again before any command runs.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+PROG = "msteams-transcripts"
+TEAMS_URL = "https://teams.cloud.microsoft/"
+
+WINDOWS_BROWSERS = [
+    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+    r"C:\Program Files\Microsoft\Edge\Application\msedge.exe",
+    r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+]
+MACOS_BROWSERS = [
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+]
+LINUX_BROWSERS = ["microsoft-edge", "microsoft-edge-stable", "google-chrome", "chromium", "chromium-browser"]
+
+
+def _default_profile_dir() -> Path:
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share")
+    return base / "TeamsTranscriptProfile"
+
+
+def browser_candidates(explicit: str = "") -> list[str]:
+    """Browser executables to try, most preferred first."""
+    found = [explicit] if explicit else []
+    if sys.platform == "win32":
+        found += WINDOWS_BROWSERS
+    elif sys.platform == "darwin":
+        found += MACOS_BROWSERS
+    else:
+        found += [p for name in LINUX_BROWSERS if (p := shutil.which(name))]
+    return [p for p in found if p]
+
+
+@dataclass
+class Settings:
+    cdp_port: int = field(default_factory=lambda: int(os.environ.get("TT_CDP_PORT", "9222")))
+    profile_dir: Path = field(
+        default_factory=lambda: Path(os.environ["TT_PROFILE_DIR"]).expanduser()
+        if os.environ.get("TT_PROFILE_DIR")
+        else _default_profile_dir()
+    )
+    browser_exe: str = field(default_factory=lambda: os.environ.get("TT_BROWSER_EXE", ""))
+    state_dir: Path = field(
+        default_factory=lambda: Path(os.environ["TT_STATE_DIR"]).expanduser()
+        if os.environ.get("TT_STATE_DIR")
+        else Path.home() / ".teams_transcripts"
+    )
+
+    @property
+    def cdp_url(self) -> str:
+        return f"http://127.0.0.1:{self.cdp_port}"
+
+    @property
+    def last_list(self) -> Path:
+        """Where the rows printed by the last `list` run are cached."""
+        return self.state_dir / "last_list.json"
+
+
+SETTINGS = Settings()
+
+
+def configure(port: int | None = None, profile: str = "", browser: str = "") -> Settings:
+    """Apply command-line overrides to the process-wide settings."""
+    if port:
+        SETTINGS.cdp_port = port
+    if profile:
+        SETTINGS.profile_dir = Path(profile).expanduser()
+    if browser:
+        SETTINGS.browser_exe = browser
+    return SETTINGS

teams_transcripts/download.py

@@ -0,0 +1,108 @@
+"""Writing a transcript to disk, optionally with the meeting details."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .browser import log
+from .errors import TranscriptError
+from .formats import invite_description, speakers_of, transcript_to_text
+from .model import safe_name, shared_files_from_contents
+from .session import TeamsSession
+
+# Recording file names look like "<subject>-20260903_141403-Transcription....mp4"
+RECORDING_NAME_RE = re.compile(r"^(.*?)-(\d{8})_(\d{6})(?:-.*)?$")
+
+
+async def collect_details(s: TeamsSession, ref: dict) -> dict:
+    """Calendar event and shared files for a transcript reference."""
+    details = {"event": await s.event_details(ref.get("objectId", ""), ref.get("iCalUID", ""))}
+    if ref.get("threadId"):
+        try:
+            details["files"] = shared_files_from_contents(await s.meeting_contents(ref["threadId"], ref.get("iCalUID", "")))
+        except TranscriptError:
+            details["files"] = []
+    return details
+
+
+def _meta_document(ref: dict, det: dict, doc: dict, subject: str, when: str) -> dict:
+    ev = det.get("event") or {}
+    return {
+        "subject": subject,
+        "start": when,
+        "organizer": {"name": ev.get("organizerName", ""), "email": ev.get("organizerAddress", "")},
+        "location": ev.get("location", ""),
+        "attendees": ev.get("attendees", []),
+        "speakers": [{"name": n, "segments": c} for n, c in speakers_of(doc)],
+        "files": det.get("files", []),
+        "description": invite_description(ev.get("bodyContent", "")),
+        "threadId": ref.get("threadId", ""),
+        "iCalUID": ref.get("iCalUID", ""),
+        "source": ref.get("webUrl") or ref.get("location") or "",
+    }
+
+
+async def download_ref(
+    s: TeamsSession,
+    ref: dict,
+    out_dir: Path,
+    fmt: str = "txt",
+    details: bool = False,
+) -> list[Path]:
+    """Download one transcript reference. Returns the files written.
+
+    fmt is 'txt', 'json', 'vtt' or 'all'. With details, a header is added to the
+    text file and a '.meta.json' sidecar is written alongside it.
+    """
+    host, drive, item = ref["host"], ref["driveId"], ref["driveItemId"]
+    if not host:
+        raise TranscriptError("No SharePoint host is known for this transcript; pass --sharepoint-host.")
+    tids = [ref["transcriptId"]] if ref.get("transcriptId") else [t["id"] for t in await s.list_transcripts(host, drive, item)]
+    if not tids:
+        log(f"  no transcript found for {ref.get('subject')}")
+        return []
+
+    subject = ref.get("subject") or ref.get("fileTitle") or ""
+    name_match = RECORDING_NAME_RE.match(subject)
+    if name_match:
+        subject = name_match.group(1)
+    when = (ref.get("start") or ref.get("meetingStart") or "")[:16].replace("T", " ")
+    if not when:
+        # The recording's creation time is UTC, matching the times shown by 'list'.
+        when = (await s.item_created(host, drive, item) or "")[:16].replace("T", " ")
+    if not when and name_match:
+        d, t = name_match.group(2), name_match.group(3)
+        when = f"{d[:4]}-{d[4:6]}-{d[6:]} {t[:2]}:{t[2:4]}"
+
+    det = await collect_details(s, ref) if details else None
+    if det and det.get("event", {}).get("subject"):
+        subject = det["event"]["subject"]
+
+    stem = safe_name(f"{when.replace(':', '')} - {subject or 'meeting'}".strip(" -"))
+    out_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for i, tid in enumerate(tids):
+        suffix = f" ({i + 1})" if len(tids) > 1 else ""
+        base = out_dir / (stem + suffix)
+        doc_json = await s.fetch_transcript(host, drive, item, tid, "json")
+        doc = json.loads(doc_json)
+        source = ref.get("webUrl") or ref.get("location") or ""
+        if fmt in ("txt", "all"):
+            p = base.with_suffix(".txt")
+            p.write_text(transcript_to_text(doc, subject or stem, when or "unknown", source, det), encoding="utf-8")
+            written.append(p)
+        if det:
+            p = base.with_suffix(".meta.json")
+            p.write_text(json.dumps(_meta_document(ref, det, doc, subject, when), indent=1, ensure_ascii=False), encoding="utf-8")
+            written.append(p)
+        if fmt in ("json", "all"):
+            p = base.with_suffix(".json")
+            p.write_text(doc_json, encoding="utf-8")
+            written.append(p)
+        if fmt in ("vtt", "all"):
+            p = base.with_suffix(".vtt")
+            p.write_text(await s.fetch_transcript(host, drive, item, tid, "vtt"), encoding="utf-8")
+            written.append(p)
+        log(f"  saved {written[-1].name}  ({len(doc.get('entries', []))} entries)")
+    return written

teams_transcripts/errors.py

@@ -0,0 +1,10 @@
+"""Exception types raised by the package."""
+from __future__ import annotations
+
+
+class TranscriptError(Exception):
+    """Something went wrong that the user can act on.
+
+    The command line catches this and prints the message without a traceback,
+    so messages should read as advice, not as internal state.
+    """

teams_transcripts/formats.py

@@ -0,0 +1,120 @@
+"""Turning the raw transcript document into readable text."""
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+
+
+def fmt_offset(off: str | None) -> str:
+    """'00:01:02.3450000' to '00:01:02'."""
+    if not off:
+        return "--:--:--"
+    return off.split(".")[0]
+
+
+class _Text(HTMLParser):
+    """Minimal HTML to text, keeping link targets and dropping style blocks."""
+
+    SKIP = ("style", "script", "head", "title")
+
+    def __init__(self):
+        super().__init__()
+        self.parts: list[str] = []
+        self.skip = 0
+        self.href = ""
+
+    def handle_data(self, d):
+        if not self.skip:
+            self.parts.append(d)
+
+    def handle_starttag(self, tag, attrs):
+        if tag in self.SKIP:
+            self.skip += 1
+        elif tag in ("br", "p", "div", "li", "tr"):
+            self.parts.append("\n")
+        elif tag == "a":
+            href = dict(attrs).get("href", "") or ""
+            keep = href.startswith("http") and "/meetup-join/" not in href and "/meet/" not in href
+            self.href = href if keep else ""
+
+    def handle_endtag(self, tag):
+        if tag in self.SKIP and self.skip:
+            self.skip -= 1
+        elif tag == "a" and self.href:
+            self.parts.append(f" <{self.href}>")
+            self.href = ""
+
+
+def html_to_text(html: str) -> str:
+    t = _Text()
+    t.feed(html or "")
+    lines = [re.sub(r"\s+", " ", line).strip() for line in "".join(t.parts).splitlines()]
+    return "\n".join(line for line in lines if re.search(r"[A-Za-z0-9]", line))
+
+
+def invite_description(body_html: str) -> str:
+    """The invitation text, with the Teams join boilerplate cut off."""
+    txt = html_to_text(body_html)
+    marks = [i for i in (txt.find("Microsoft Teams meeting"), txt.find("____"), txt.find("Join the meeting now")) if i >= 0]
+    return txt[: min(marks)].strip() if marks else txt.strip()
+
+
+def speakers_of(doc: dict) -> list[tuple[str, int]]:
+    """Who spoke, and how many segments each, most talkative first."""
+    counts: dict[str, int] = {}
+    for e in doc.get("entries", []):
+        n = (e.get("speakerDisplayName") or e.get("speakerId") or "Unknown").strip()
+        counts[n] = counts.get(n, 0) + 1
+    return sorted(counts.items(), key=lambda x: -x[1])
+
+
+def details_header(details: dict, doc: dict) -> list[str]:
+    """Comment lines describing the meeting, placed above the transcript body."""
+    ev = details.get("event") or {}
+    out: list[str] = []
+    if ev.get("organizerName") or ev.get("organizerAddress"):
+        out.append(f"# Organizer: {ev.get('organizerName', '')} <{ev.get('organizerAddress', '')}>".replace(" <>", ""))
+    if ev.get("location"):
+        out.append(f"# Location: {ev['location']}")
+    att = ev.get("attendees") or []
+    if att:
+        out.append(f"# Invited ({len(att)}):")
+        for a in att:
+            kind = a.get("type") or "Required"
+            resp = (a.get("status") or {}).get("response") or ""
+            resp = "" if resp in ("None", "NotResponded", "") else f", {resp}"
+            out.append(f"#   {a.get('name', '')} <{a.get('address', '')}> ({kind}{resp})")
+    sp = speakers_of(doc)
+    if sp:
+        out.append(f"# Speakers in transcript ({len(sp)}):")
+        out.extend(f"#   {n} ({c} segments)" for n, c in sp)
+    files = details.get("files") or []
+    if files:
+        out.append(f"# Files shared in meeting chat ({len(files)}):")
+        out.extend(f"#   {f['title']}  {f['url']}" for f in files)
+    is_html = (ev.get("bodyContentType") or "html").lower() == "html"
+    desc = invite_description(ev.get("bodyContent", "")) if is_html else (ev.get("bodyContent") or "")
+    if desc:
+        out.append("# Invitation text:")
+        out.extend(f"#   {line}" for line in desc.splitlines()[:40])
+    return out
+
+
+def transcript_to_text(doc: dict, title: str, when: str, source: str, details: dict | None = None) -> str:
+    """Plain text: a comment header, then '[hh:mm:ss] Speaker:' with their lines."""
+    lines = [f"# {title}", f"# Date: {when}", f"# Source: {source}"]
+    if details:
+        lines += details_header(details, doc)
+    lines.append("")
+    prev_speaker = None
+    for e in doc.get("entries", []):
+        speaker = (e.get("speakerDisplayName") or e.get("speakerId") or "Unknown").strip()
+        text = (e.get("text") or "").strip()
+        if not text:
+            continue
+        if speaker != prev_speaker:
+            lines.append("")
+            lines.append(f"[{fmt_offset(e.get('startOffset'))}] {speaker}:")
+            prev_speaker = speaker
+        lines.append(f"    {text}")
+    return "\n".join(lines).strip() + "\n"