teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/domain/vtt.py

@@ -0,0 +1,444 @@
+"""Pure VTT generation, merging, and post-processing functions.
+
+All functions in this module are pure: no I/O, no network, no logging,
+no global state.  They take string content in and return string content out.
+"""
+
+from __future__ import annotations
+
+import re
+import typing
+from html import escape as html_escape
+from html import unescape as html_unescape
+
+from teams_transcripts.domain.models import TranscriptCue
+from teams_transcripts.domain.timestamps import (
+    format_vtt_timestamp,
+    parse_meeting_times,
+    parse_vtt_timestamp,
+)
+
+if typing.TYPE_CHECKING:
+    from teams_transcripts.domain.models import MeetingParticipants, RosterMember
+
+
+def merge_parts(vtt_contents: list[str]) -> str:
+    """Merge multiple VTT file contents into a single VTT.
+
+    Each part's timestamps are offset so that Part 2 continues from
+    Part 1's last cue end time, and so on.  Cues are renumbered
+    sequentially across all parts.
+
+    Args:
+        vtt_contents: List of VTT file contents (strings), one per part.
+
+    Returns:
+        Merged VTT content as a single string.
+    """
+    timestamp_re = re.compile(r"(\d{2}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2}\.\d{3})")
+
+    all_cues: list[tuple[float, float, list[str]]] = []
+    cumulative_offset = 0.0
+
+    for vtt_text in vtt_contents:
+        lines = vtt_text.split("\n")
+        part_cues: list[tuple[float, float, list[str]]] = []
+
+        i = 0
+        while i < len(lines):
+            line = lines[i].strip()
+            ts_match = timestamp_re.match(line)
+            if ts_match:
+                start = parse_vtt_timestamp(ts_match.group(1))
+                end = parse_vtt_timestamp(ts_match.group(2))
+                # Collect cue content lines (everything until next blank line)
+                content_lines = []
+                i += 1
+                while i < len(lines) and lines[i].strip():
+                    content_lines.append(lines[i])
+                    i += 1
+                part_cues.append(
+                    (start + cumulative_offset, end + cumulative_offset, content_lines)
+                )
+            else:
+                i += 1
+
+        # Update offset: next part starts after this part's last cue end
+        if part_cues:
+            last_end = max(end for _, end, _ in part_cues)
+            cumulative_offset = last_end
+
+        all_cues.extend(part_cues)
+
+    # Build merged VTT
+    result = ["WEBVTT", ""]
+    for idx, (start, end, content_lines) in enumerate(all_cues, 1):
+        result.append(str(idx))
+        result.append(f"{format_vtt_timestamp(start)} --> {format_vtt_timestamp(end)}")
+        result.extend(content_lines)
+        result.append("")
+
+    return "\n".join(result)
+
+
+def prepend_metadata(
+    content: str,
+    config: dict,
+    *,
+    participants: MeetingParticipants | None = None,
+) -> str:
+    """Insert a VTT NOTE block with meeting metadata after the WEBVTT header.
+
+    The NOTE block contains the meeting title, participant information,
+    and start/end times.
+
+    When ``participants`` is provided, the block uses categorised lines
+    (Organiser, Invited, Speakers, Attendees).  Otherwise it falls back
+    to the legacy roster/speaker-map format.
+
+    Args:
+        content: Raw VTT file content.
+        config: Meeting configuration dict with keys ``"meeting"``,
+            ``"date"``, ``"time"``, and optionally ``"roster_members"``,
+            ``"speaker_map"``, ``"meeting_time_text"``.
+        participants: Optional :class:`MeetingParticipants` with
+            categorised participant lists.
+
+    Returns:
+        VTT content with the metadata NOTE block inserted.
+    """
+    # Build the NOTE block
+    lines = ["NOTE Meeting Metadata"]
+    lines.append(f"Meeting: {config['meeting']}")
+
+    if participants is not None:
+        _append_participant_lines(lines, participants)
+    else:
+        _append_legacy_roster_lines(lines, config)
+
+    # Start/end times
+    time_text = config.get("meeting_time_text", "")
+    if time_text:
+        start_dt, end_dt = parse_meeting_times(time_text, config["date"])
+    else:
+        start_dt = config["date"]
+        if config.get("time"):
+            start_dt = f"{config['date']}T{config['time']}"
+        end_dt = ""
+
+    lines.append(f"Start: {start_dt}")
+    if end_dt:
+        lines.append(f"End: {end_dt}")
+
+    note_block = "\n".join(lines)
+
+    # Insert after the WEBVTT header line
+    if content.startswith("WEBVTT"):
+        content = content.replace("WEBVTT\n\n", f"WEBVTT\n\n{note_block}\n\n", 1)
+    else:
+        content = f"WEBVTT\n\n{note_block}\n\n{content}"
+
+    return content
+
+
+_INLINE_NAME_THRESHOLD = 10
+"""Maximum number of members/attendees to list by name inline.
+
+Above this threshold, a count is shown instead (e.g. "127 members").
+"""
+
+
+def _append_participant_lines(lines: list[str], participants: MeetingParticipants) -> None:
+    """Append categorised participant lines to the NOTE block."""
+    # Organiser
+    if participants.organiser:
+        org = participants.organiser[0]
+        if org.email:
+            lines.append(f"Organiser: {org.name} <{org.email}>")
+        else:
+            lines.append(f"Organiser: {org.name}")
+
+    # Invited
+    if participants.invited:
+        count = len(participants.invited)
+        if count <= _INLINE_NAME_THRESHOLD:
+            names = ", ".join(m.name for m in participants.invited)
+            lines.append(f"Invited: {names}")
+        else:
+            rsvp_summary = _rsvp_summary(participants.invited)
+            if rsvp_summary:
+                lines.append(f"Invited: {count} members ({rsvp_summary})")
+            else:
+                lines.append(f"Invited: {count} members")
+
+    # Speakers
+    if participants.speakers:
+        names = ", ".join(m.name for m in participants.speakers)
+        lines.append(f"Speakers: {names}")
+
+    # Attendees
+    if participants.attendees:
+        count = len(participants.attendees)
+        if count <= _INLINE_NAME_THRESHOLD:
+            names = ", ".join(m.name for m in participants.attendees)
+            lines.append(f"Attendees: {names}")
+        else:
+            lines.append(f"Attendees: {count} participants")
+
+
+def _rsvp_summary(members: list[RosterMember]) -> str:
+    """Build a compact RSVP summary string for the NOTE block.
+
+    Returns a string like ``"50 accepted, 5 tentative, 2 declined, 33 no response"``
+    or empty string if no RSVP data is available.
+
+    Args:
+        members: List of roster members (may have empty ``rsvp_status``).
+
+    Returns:
+        Compact summary string, or empty string when no RSVP data present.
+    """
+    from collections import Counter
+
+    counts: Counter[str] = Counter()
+    for m in members:
+        if m.rsvp_status:
+            counts[m.rsvp_status] += 1
+
+    if not counts:
+        return ""
+
+    # Display order: accepted, tentative, declined, organizer, none
+    parts: list[str] = []
+    display_order = ["accepted", "tentative", "declined", "organizer", "none"]
+    for status in display_order:
+        if status in counts:
+            label = "no response" if status == "none" else status
+            parts.append(f"{counts[status]} {label}")
+
+    # Any remaining statuses not in the display order
+    for status, count in sorted(counts.items()):
+        if status not in display_order:
+            parts.append(f"{count} {status}")
+
+    return ", ".join(parts)
+
+
+def _append_legacy_roster_lines(lines: list[str], config: dict) -> None:
+    """Append legacy roster/speaker lines to the NOTE block.
+
+    Used when no :class:`MeetingParticipants` is available (backward
+    compatibility).
+    """
+    roster = config.get("roster_members")
+    if roster:
+        organiser_names = sorted(m["name"] for m in roster if m["role"] == "organiser")
+        member_names = sorted(m["name"] for m in roster)
+        lines.append(f"Members: {', '.join(member_names)}")
+        if organiser_names:
+            lines.append(f"Organiser: {', '.join(organiser_names)}")
+
+        # Email addresses for all members that have one
+        email_entries = sorted((m["name"], m["email"]) for m in roster if m.get("email"))
+        if email_entries:
+            email_strs = [f"{name} <{email}>" for name, email in email_entries]
+            lines.append(f"Emails: {', '.join(email_strs)}")
+    else:
+        # Fallback: speakers only (from Recap)
+        speaker_map = config.get("speaker_map")
+        if speaker_map:
+            names = sorted(speaker_map.values())
+            lines.append(f"Speakers: {', '.join(names)}")
+
+
+def ensure_trailing_newline(content: str) -> str:
+    """Ensure the VTT content ends with a trailing newline.
+
+    Args:
+        content: VTT file content.
+
+    Returns:
+        Content with a trailing newline appended if missing.
+    """
+    if content and not content.endswith("\n"):
+        return content + "\n"
+    return content
+
+
+def generate_vtt_from_segments(segments: list[dict]) -> str:
+    """Generate VTT content from Approach B DOM-extracted segments.
+
+    Each segment dict must have ``"speaker"``, ``"ts_sec"`` (int seconds),
+    and ``"text"`` keys.  Timestamps must already be filled (no ``None``
+    values).
+
+    Cue end times are set to the next segment's start time.  The last
+    cue gets a 10-second duration.  If a cue's end time is not greater
+    than its start, 10 seconds is added.
+
+    Args:
+        segments: Ordered list of segment dicts.
+
+    Returns:
+        Complete VTT content string.
+    """
+    from teams_transcripts.domain.timestamps import sec_to_vtt_int
+
+    vtt = ["WEBVTT", ""]
+    for i, seg in enumerate(segments):
+        ss = seg["ts_sec"]
+        es = segments[i + 1]["ts_sec"] if i + 1 < len(segments) else ss + 10
+        if es <= ss:
+            es = ss + 10
+        vtt.extend(
+            [
+                str(i + 1),
+                f"{sec_to_vtt_int(ss)} --> {sec_to_vtt_int(es)}",
+                f"<v {_escape_vtt_text(seg['speaker'])}>{_escape_vtt_text(seg['text'])}</v>",
+                "",
+            ]
+        )
+
+    return "\n".join(vtt)
+
+
+def _escape_vtt_text(value: object) -> str:
+    """Escape user-controlled text for a VTT cue or voice tag."""
+    return html_escape(str(value), quote=False)
+
+
+# ---------------------------------------------------------------------------
+# VTT parsing: content string -> structured cues
+# ---------------------------------------------------------------------------
+
+_VOICE_TAG_RE = re.compile(r"^<v ([^>]+)>(.*?)(?:</v>)?$", re.DOTALL)
+"""Match a VTT voice tag: ``<v Speaker Name>text</v>`` or ``<v Speaker Name>text``."""
+
+
+def parse_cues(content: str) -> list[TranscriptCue]:
+    """Parse VTT content into a list of structured cue objects.
+
+    Extracts each cue's ID, timestamps, speaker (from ``<v>`` voice tags),
+    and plain text content.  NOTE blocks and the WEBVTT header are skipped.
+
+    Cues without a ``<v>`` voice tag have ``speaker=None``.
+
+    Args:
+        content: Complete VTT file content (must start with ``WEBVTT``).
+
+    Returns:
+        Ordered list of :class:`TranscriptCue` objects.
+    """
+    timestamp_re = re.compile(r"(\d{2}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2}\.\d{3})")
+
+    lines = content.split("\n")
+    cues: list[TranscriptCue] = []
+    i = 0
+
+    while i < len(lines):
+        line = lines[i].strip()
+
+        # Skip NOTE blocks (single or multi-line)
+        if line.startswith("NOTE"):
+            i += 1
+            while i < len(lines) and lines[i].strip():
+                i += 1
+            i += 1  # skip the blank line after NOTE
+            continue
+
+        # Skip WEBVTT header
+        if line == "WEBVTT":
+            i += 1
+            continue
+
+        # Skip blank lines
+        if not line:
+            i += 1
+            continue
+
+        # Try to match a cue ID (numeric line before timestamp)
+        cue_id: int | None = None
+        if line.isdigit():
+            cue_id = int(line)
+            i += 1
+            if i >= len(lines):
+                break
+            line = lines[i].strip()
+
+        # Try to match a timestamp line
+        ts_match = timestamp_re.match(line)
+        if not ts_match:
+            i += 1
+            continue
+
+        start_str = ts_match.group(1)
+        end_str = ts_match.group(2)
+        start_sec = parse_vtt_timestamp(start_str)
+        end_sec = parse_vtt_timestamp(end_str)
+
+        # Collect content lines until blank line or end
+        i += 1
+        content_lines: list[str] = []
+        while i < len(lines) and lines[i].strip():
+            content_lines.append(lines[i].rstrip())
+            i += 1
+
+        # Parse speaker and text from content
+        raw_text = "\n".join(content_lines)
+        speaker, text = _extract_speaker_and_text(raw_text)
+
+        cues.append(
+            TranscriptCue(
+                id=cue_id if cue_id is not None else len(cues) + 1,
+                start=start_str,
+                end=end_str,
+                start_sec=start_sec,
+                end_sec=end_sec,
+                speaker=speaker,
+                text=text,
+            )
+        )
+
+        i += 1  # skip blank line after cue
+
+    return cues
+
+
+def _extract_speaker_and_text(raw: str) -> tuple[str | None, str]:
+    """Extract speaker name and plain text from cue content.
+
+    Handles:
+    - ``<v Speaker Name>text</v>`` — returns (Speaker Name, text)
+    - ``<v Speaker Name>text`` (no closing tag) — returns (Speaker Name, text)
+    - Plain text without voice tag — returns (None, text)
+    - Multi-line content where the first line has the voice tag
+
+    Args:
+        raw: Raw cue content (may be multi-line).
+
+    Returns:
+        Tuple of (speaker_or_None, plain_text).
+    """
+    # Try matching the first line for a voice tag
+    first_line_end = raw.find("\n")
+    if first_line_end == -1:
+        first_line = raw
+        rest = ""
+    else:
+        first_line = raw[:first_line_end]
+        rest = raw[first_line_end + 1 :]
+
+    m = _VOICE_TAG_RE.match(first_line)
+    if m:
+        speaker = html_unescape(m.group(1))
+        text = html_unescape(m.group(2))
+        if rest:
+            text = text + "\n" + html_unescape(rest)
+        # Strip any remaining </v> tags from text
+        text = text.replace("</v>", "")
+        return speaker, text.strip()
+
+    # No voice tag — entire content is plain text
+    # Still strip any stray </v> tags
+    text = html_unescape(raw.replace("</v>", "").strip())
+    return None, text

teams_transcripts/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure -- cross-cutting concerns: logging, signals, errors, config."""