feat: add transcript format parameter to GET endpoint (#709)

* feat: add transcript format parameter to GET endpoint

Add transcript_format query parameter to /v1/transcripts/{id} endpoint
with support for multiple output formats using discriminated unions.

Formats supported:
- text: Plain speaker dialogue (default)
- text-timestamped: Dialogue with [MM:SS] timestamps
- webvtt-named: WebVTT subtitles with participant names
- json: Structured segments with full metadata

Response models use Pydantic discriminated unions with transcript_format
as discriminator field. POST/PATCH endpoints return GetTranscriptWithParticipants
for minimal responses. GET endpoint returns format-specific models.

* Copy transcript format

* Regenerate types

* Fix transcript formats

* Don't throw inside try

* Remove any type

* Toast share copy errors

* transcript_format exhaustiveness and python idiomatic assert_never

* format_timestamp_mmss clear type definition

* Rename seconds_to_timestamp

* Test transcript format with overlapping speakers

* exact match for vtt multispeaker test

---------

Co-authored-by: Sergey Mankovsky <sergey@monadical.com>
Co-authored-by: Igor Loskutov <igor.loskutoff@gmail.com>

server/reflector/utils/transcript_formats.py

@@ -0,0 +1,125 @@
+"""Utilities for converting transcript data to various output formats."""
+
+import webvtt
+
+from reflector.db.transcripts import TranscriptParticipant, TranscriptTopic
+from reflector.processors.types import (
+    Transcript as ProcessorTranscript,
+)
+from reflector.processors.types import (
+    words_to_segments,
+)
+from reflector.schemas.transcript_formats import TranscriptSegment
+from reflector.utils.webvtt import seconds_to_timestamp
+
+
+def get_speaker_name(
+    speaker: int, participants: list[TranscriptParticipant] | None
+) -> str:
+    """Get participant name for speaker or default to 'Speaker N'."""
+    if participants:
+        for participant in participants:
+            if participant.speaker == speaker:
+                return participant.name
+    return f"Speaker {speaker}"
+
+
+def format_timestamp_mmss(seconds: float | int) -> str:
+    """Format seconds as MM:SS timestamp."""
+    minutes = int(seconds // 60)
+    secs = int(seconds % 60)
+    return f"{minutes:02d}:{secs:02d}"
+
+
+def transcript_to_text(
+    topics: list[TranscriptTopic], participants: list[TranscriptParticipant] | None
+) -> str:
+    """Convert transcript topics to plain text with speaker names."""
+    lines = []
+    for topic in topics:
+        if not topic.words:
+            continue
+
+        transcript = ProcessorTranscript(words=topic.words)
+        segments = transcript.as_segments()
+
+        for segment in segments:
+            speaker_name = get_speaker_name(segment.speaker, participants)
+            text = segment.text.strip()
+            lines.append(f"{speaker_name}: {text}")
+
+    return "\n".join(lines)
+
+
+def transcript_to_text_timestamped(
+    topics: list[TranscriptTopic], participants: list[TranscriptParticipant] | None
+) -> str:
+    """Convert transcript topics to timestamped text with speaker names."""
+    lines = []
+    for topic in topics:
+        if not topic.words:
+            continue
+
+        transcript = ProcessorTranscript(words=topic.words)
+        segments = transcript.as_segments()
+
+        for segment in segments:
+            speaker_name = get_speaker_name(segment.speaker, participants)
+            timestamp = format_timestamp_mmss(segment.start)
+            text = segment.text.strip()
+            lines.append(f"[{timestamp}] {speaker_name}: {text}")
+
+    return "\n".join(lines)
+
+
+def topics_to_webvtt_named(
+    topics: list[TranscriptTopic], participants: list[TranscriptParticipant] | None
+) -> str:
+    """Convert transcript topics to WebVTT format with participant names."""
+    vtt = webvtt.WebVTT()
+
+    for topic in topics:
+        if not topic.words:
+            continue
+
+        segments = words_to_segments(topic.words)
+
+        for segment in segments:
+            speaker_name = get_speaker_name(segment.speaker, participants)
+            text = segment.text.strip()
+            text = f"<v {speaker_name}>{text}"
+
+            caption = webvtt.Caption(
+                start=seconds_to_timestamp(segment.start),
+                end=seconds_to_timestamp(segment.end),
+                text=text,
+            )
+            vtt.captions.append(caption)
+
+    return vtt.content
+
+
+def transcript_to_json_segments(
+    topics: list[TranscriptTopic], participants: list[TranscriptParticipant] | None
+) -> list[TranscriptSegment]:
+    """Convert transcript topics to a flat list of JSON segments."""
+    segments = []
+
+    for topic in topics:
+        if not topic.words:
+            continue
+
+        transcript = ProcessorTranscript(words=topic.words)
+        for segment in transcript.as_segments():
+            speaker_name = get_speaker_name(segment.speaker, participants)
+            segments.append(
+                TranscriptSegment(
+                    speaker=segment.speaker,
+                    speaker_name=speaker_name,
+                    text=segment.text.strip(),
+                    start=segment.start,
+                    end=segment.end,
+                )
+            )
+
+    return segments