"""
WTF Attachment Classes
This module implements the core data structures for WTF (World Transcription Format)
attachments as defined in the draft specification.
"""
from enum import Enum
from typing import List, Dict, Optional, Union, Any
from datetime import datetime, timezone
import logging
logger = logging.getLogger(__name__)
[docs]class WTFProvider(Enum):
"""Supported transcription providers."""
WHISPER = "whisper"
DEEPGRAM = "deepgram"
ASSEMBLYAI = "assemblyai"
GOOGLE = "google"
AMAZON = "amazon"
AZURE = "azure"
REV_AI = "rev.ai"
SPEECHMATICS = "speechmatics"
WAV2VEC2 = "wav2vec2"
PARAKEET = "parakeet"
[docs]class Transcript:
"""Represents the high-level transcript information."""
def __init__(
self,
text: str,
language: str,
duration: float,
confidence: float
):
self.text = text
self.language = language
self.duration = duration
self.confidence = confidence
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
return {
"text": self.text,
"language": self.language,
"duration": self.duration,
"confidence": self.confidence
}
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Transcript':
"""Create from dictionary representation."""
return cls(
text=data["text"],
language=data["language"],
duration=data["duration"],
confidence=data["confidence"]
)
[docs]class Word:
"""Represents a single word in the transcription."""
def __init__(
self,
id: int,
start: float,
end: float,
text: str,
confidence: float,
speaker: Optional[Union[int, str]] = None,
is_punctuation: Optional[bool] = None
):
self.id = id
self.start = start
self.end = end
self.text = text
self.confidence = confidence
self.speaker = speaker
self.is_punctuation = is_punctuation
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
result = {
"id": self.id,
"start": self.start,
"end": self.end,
"text": self.text,
"confidence": self.confidence
}
if self.speaker is not None:
result["speaker"] = self.speaker
if self.is_punctuation is not None:
result["is_punctuation"] = self.is_punctuation
return result
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Word':
"""Create from dictionary representation."""
return cls(
id=data["id"],
start=data["start"],
end=data["end"],
text=data["text"],
confidence=data["confidence"],
speaker=data.get("speaker"),
is_punctuation=data.get("is_punctuation")
)
[docs]class Segment:
"""Represents a logical chunk of transcribed content."""
def __init__(
self,
id: int,
start: float,
end: float,
text: str,
confidence: float,
speaker: Optional[Union[int, str]] = None,
words: Optional[List[int]] = None
):
self.id = id
self.start = start
self.end = end
self.text = text
self.confidence = confidence
self.speaker = speaker
self.words = words or []
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
result = {
"id": self.id,
"start": self.start,
"end": self.end,
"text": self.text,
"confidence": self.confidence
}
if self.speaker is not None:
result["speaker"] = self.speaker
if self.words:
result["words"] = self.words
return result
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Segment':
"""Create from dictionary representation."""
return cls(
id=data["id"],
start=data["start"],
end=data["end"],
text=data["text"],
confidence=data["confidence"],
speaker=data.get("speaker"),
words=data.get("words")
)
[docs]class Speaker:
"""Represents speaker information for diarization."""
def __init__(
self,
id: Union[int, str],
label: str,
segments: List[int],
total_time: float,
confidence: float
):
self.id = id
self.label = label
self.segments = segments
self.total_time = total_time
self.confidence = confidence
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
return {
"id": self.id,
"label": self.label,
"segments": self.segments,
"total_time": self.total_time,
"confidence": self.confidence
}
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Speaker':
"""Create from dictionary representation."""
return cls(
id=data["id"],
label=data["label"],
segments=data["segments"],
total_time=data["total_time"],
confidence=data["confidence"]
)
[docs]class Quality:
"""Represents quality metrics for the transcription."""
def __init__(
self,
audio_quality: str,
background_noise: float,
multiple_speakers: bool,
overlapping_speech: bool,
silence_ratio: float,
average_confidence: float,
low_confidence_words: int,
processing_warnings: List[str]
):
self.audio_quality = audio_quality
self.background_noise = background_noise
self.multiple_speakers = multiple_speakers
self.overlapping_speech = overlapping_speech
self.silence_ratio = silence_ratio
self.average_confidence = average_confidence
self.low_confidence_words = low_confidence_words
self.processing_warnings = processing_warnings
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
return {
"audio_quality": self.audio_quality,
"background_noise": self.background_noise,
"multiple_speakers": self.multiple_speakers,
"overlapping_speech": self.overlapping_speech,
"silence_ratio": self.silence_ratio,
"average_confidence": self.average_confidence,
"low_confidence_words": self.low_confidence_words,
"processing_warnings": self.processing_warnings
}
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Quality':
"""Create from dictionary representation."""
return cls(
audio_quality=data["audio_quality"],
background_noise=data["background_noise"],
multiple_speakers=data["multiple_speakers"],
overlapping_speech=data["overlapping_speech"],
silence_ratio=data["silence_ratio"],
average_confidence=data["average_confidence"],
low_confidence_words=data["low_confidence_words"],
processing_warnings=data["processing_warnings"]
)
[docs]class WTFAttachment:
"""
Represents a WTF transcription attachment.
This class handles the creation, validation, and processing of WTF
transcription attachments according to the draft specification.
"""
def __init__(
self,
transcript: Transcript,
segments: List[Segment],
metadata: Metadata,
words: Optional[List[Word]] = None,
speakers: Optional[Dict[str, Speaker]] = None,
alternatives: Optional[List[Dict[str, Any]]] = None,
enrichments: Optional[Dict[str, Any]] = None,
extensions: Optional[Dict[str, Any]] = None,
quality: Optional[Quality] = None,
streaming: Optional[Dict[str, Any]] = None
):
self.transcript = transcript
self.segments = segments
self.metadata = metadata
self.words = words or []
self.speakers = speakers or {}
self.alternatives = alternatives or []
self.enrichments = enrichments or {}
self.extensions = extensions or {}
self.quality = quality
self.streaming = streaming or {}
[docs] def get_speaking_time(self) -> Dict[str, float]:
"""Calculate speaking time for each speaker."""
speaking_times = {}
for speaker_id, speaker in self.speakers.items():
speaking_times[speaker_id] = speaker.total_time
return speaking_times
[docs] def find_low_confidence_segments(self, threshold: float = 0.5) -> List[Segment]:
"""Find segments with confidence below threshold."""
return [segment for segment in self.segments if segment.confidence < threshold]
[docs] def export_to_srt(self) -> str:
"""Export transcription to SRT subtitle format."""
srt_content = []
for i, segment in enumerate(self.segments, 1):
# Convert timestamps to SRT format (HH:MM:SS,mmm)
start_time = self._format_srt_timestamp(segment.start)
end_time = self._format_srt_timestamp(segment.end)
srt_content.append(f"{i}")
srt_content.append(f"{start_time} --> {end_time}")
srt_content.append(segment.text)
srt_content.append("") # Empty line between segments
return "\n".join(srt_content)
[docs] def export_to_vtt(self) -> str:
"""Export transcription to WebVTT format."""
vtt_content = ["WEBVTT", ""]
for segment in self.segments:
start_time = self._format_vtt_timestamp(segment.start)
end_time = self._format_vtt_timestamp(segment.end)
vtt_content.append(f"{start_time} --> {end_time}")
vtt_content.append(segment.text)
vtt_content.append("")
return "\n".join(vtt_content)
def _format_srt_timestamp(self, seconds: float) -> str:
"""Format timestamp for SRT format."""
hours = int(seconds // 3600)
minutes = int((seconds % 3600) // 60)
secs = int(seconds % 60)
millisecs = int((seconds % 1) * 1000)
return f"{hours:02d}:{minutes:02d}:{secs:02d},{millisecs:03d}"
def _format_vtt_timestamp(self, seconds: float) -> str:
"""Format timestamp for WebVTT format."""
hours = int(seconds // 3600)
minutes = int((seconds % 3600) // 60)
secs = seconds % 60
return f"{hours:02d}:{minutes:02d}:{secs:06.3f}"
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
result = {
"transcript": self.transcript.to_dict(),
"segments": [segment.to_dict() for segment in self.segments],
"metadata": self.metadata.to_dict()
}
if self.words:
result["words"] = [word.to_dict() for word in self.words]
if self.speakers:
result["speakers"] = {
str(speaker_id): speaker.to_dict()
for speaker_id, speaker in self.speakers.items()
}
if self.alternatives:
result["alternatives"] = self.alternatives
if self.enrichments:
result["enrichments"] = self.enrichments
if self.extensions:
result["extensions"] = self.extensions
if self.quality:
result["quality"] = self.quality.to_dict()
if self.streaming:
result["streaming"] = self.streaming
return result
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'WTFAttachment':
"""Create from dictionary representation."""
# Parse speakers
speakers = {}
if "speakers" in data:
for speaker_id, speaker_data in data["speakers"].items():
speakers[speaker_id] = Speaker.from_dict(speaker_data)
return cls(
transcript=Transcript.from_dict(data["transcript"]),
segments=[Segment.from_dict(s) for s in data["segments"]],
metadata=Metadata.from_dict(data["metadata"]),
words=[Word.from_dict(w) for w in data.get("words", [])],
speakers=speakers,
alternatives=data.get("alternatives"),
enrichments=data.get("enrichments"),
extensions=data.get("extensions"),
quality=Quality.from_dict(data["quality"]) if data.get("quality") else None,
streaming=data.get("streaming")
)