Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
10.9 KB
Raw Blame
"""
Base classes and data types for transcription connectors.
"""

import json
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from enum import Enum, auto
from typing import Optional, List, Dict, Any, BinaryIO, Callable, Set, Type, FrozenSet


class TranscriptionCapability(Enum):
    """Capabilities that connectors can declare support for."""
    DIARIZATION = auto()           # Speaker diarization
    CHUNKING = auto()              # Automatic file chunking for large files
    TIMESTAMPS = auto()            # Word/segment timestamps
    LANGUAGE_DETECTION = auto()    # Auto language detection
    KNOWN_SPEAKERS = auto()        # Support for known speaker references (future)
    SPEAKER_EMBEDDINGS = auto()    # Return speaker embeddings
    SPEAKER_COUNT_CONTROL = auto() # Support for min/max speaker count parameters
    EXACT_SPEAKER_COUNT = auto()   # Accepts exactly-N speakers only (no range); UI shows a single count field
    HOTWORDS = auto()              # Hotword/keyword biasing (or prompt-based equivalent)
    INITIAL_PROMPT = auto()        # Free-text initial prompt / context hint
    STREAMING = auto()             # Real-time streaming transcription


@dataclass
class ConnectorSpecifications:
    """
    Provider-specific constraints and requirements.

    Each connector declares its constraints so the application can automatically
    handle chunking, format conversion, and other preprocessing as needed.
    """
    # Size constraints
    max_file_size_bytes: Optional[int] = None  # None = unlimited

    # Duration constraints
    max_duration_seconds: Optional[int] = None  # None = unlimited
    min_duration_for_chunking: Optional[int] = None  # Provider's internal chunking threshold

    # Chunking behavior
    handles_chunking_internally: bool = False  # Provider handles large files
    requires_chunking_param: bool = False  # Must send chunking_strategy param
    recommended_chunk_seconds: int = 600  # 10 minutes default

    # Audio format support - connector-specific codec restrictions
    # None = use system defaults from get_supported_codecs()
    # Set = only allow these codecs (overrides defaults)
    supported_codecs: Optional[FrozenSet[str]] = None
    # Codecs this connector doesn't support (removed from defaults)
    # Merged with AUDIO_UNSUPPORTED_CODECS env var
    unsupported_codecs: Optional[FrozenSet[str]] = None
    # Provider accepts original audio; do not transcode or repair its container.
    preserve_original_audio: bool = False


# Default specifications for connectors that don't define their own
DEFAULT_SPECIFICATIONS = ConnectorSpecifications()


@dataclass
class TranscriptionRequest:
    """Standardized transcription request."""
    audio_file: BinaryIO
    filename: str
    mime_type: Optional[str] = None
    language: Optional[str] = None

    # Diarization options
    diarize: bool = False
    min_speakers: Optional[int] = None
    max_speakers: Optional[int] = None
    known_speaker_names: Optional[List[str]] = None
    # known_speaker_references: Dict mapping speaker label to either BinaryIO or data URL string
    known_speaker_references: Optional[Dict[str, Any]] = None

    # Advanced options
    prompt: Optional[str] = None
    hotwords: Optional[str] = None  # Comma-separated words to bias recognition
    temperature: Optional[float] = None

    # Per-request model override. When set, the connector uses this model name
    # instead of its configured default. Only honoured if the connector supports
    # multiple models (asr_endpoint, openai_*, mistral). Issue #266.
    model: Optional[str] = None

    # Provider-specific options (passthrough)
    extra_options: Dict[str, Any] = field(default_factory=dict)

    # Saved provider task, for connectors with SUPPORTS_TASK_RESUME. A
    # connector calls save_provider_task(task) as soon as the service accepts
    # a job (and with None to forget it); a retry of the same processing job
    # receives that task back in provider_task and polls it instead of
    # submitting the audio again. Both are None outside a processing job.
    provider_task: Optional[Dict[str, Any]] = None
    save_provider_task: Optional[Callable[[Optional[Dict[str, Any]]], None]] = None


@dataclass
class TranscriptionSegment:
    """Single segment of transcription with optional metadata."""
    text: str
    speaker: Optional[str] = None
    start_time: Optional[float] = None
    end_time: Optional[float] = None
    confidence: Optional[float] = None
    words: Optional[List[Dict[str, Any]]] = None


@dataclass
class TranscriptionResponse:
    """Standardized transcription response."""
    # Core content
    text: str                                    # Plain text transcription
    segments: Optional[List[TranscriptionSegment]] = None  # Detailed segments

    # Metadata
    language: Optional[str] = None               # Detected language
    duration: Optional[float] = None             # Audio duration in seconds

    # Speaker information
    speakers: Optional[List[str]] = None         # List of speakers found
    speaker_embeddings: Optional[Dict[str, List[float]]] = None

    # Provider info
    provider: str = ""
    model: str = ""

    # Raw response for debugging
    raw_response: Optional[Dict[str, Any]] = None

    def to_storage_format(self) -> str:
        """
        Convert to the JSON format used for storage in database.

        Returns a JSON string in the format expected by the existing codebase:
        [
            {
                "speaker": "SPEAKER_00",
                "sentence": "Text here",
                "start_time": 0.0,
                "end_time": 5.5
            },
            ...
        ]
        """
        if self.segments:
            return json.dumps([
                {
                    'speaker': seg.speaker or 'Unknown Speaker',
                    'sentence': seg.text,
                    'start_time': seg.start_time,
                    'end_time': seg.end_time
                }
                for seg in self.segments
            ])
        # If no segments, return plain text (for non-diarized transcriptions)
        return self.text

    def has_diarization(self) -> bool:
        """Check if this response contains diarization data."""
        if not self.segments:
            return False
        return any(seg.speaker for seg in self.segments)


class BaseTranscriptionConnector(ABC):
    """Abstract base class for transcription connectors."""

    # Class-level capability declarations - subclasses should override
    CAPABILITIES: Set[TranscriptionCapability] = set()
    PROVIDER_NAME: str = "unknown"

    # Provider-specific constraints - subclasses should override
    SPECIFICATIONS: ConnectorSpecifications = DEFAULT_SPECIFICATIONS

    # Submit-and-poll services that charge per job set this and use
    # TranscriptionRequest.provider_task / save_provider_task.
    SUPPORTS_TASK_RESUME: bool = False

    def __init__(self, config: Dict[str, Any]):
        """
        Initialize connector with configuration.

        Args:
            config: Provider-specific configuration dict
        """
        self.config = config
        self._validate_config()

    @abstractmethod
    def _validate_config(self) -> None:
        """
        Validate required configuration is present.

        Raises:
            ConfigurationError: If required config is missing or invalid
        """
        pass

    @abstractmethod
    def transcribe(self, request: TranscriptionRequest) -> TranscriptionResponse:
        """
        Perform transcription.

        Args:
            request: Standardized transcription request

        Returns:
            Standardized transcription response

        Raises:
            TranscriptionError: On transcription failure
            ConfigurationError: On configuration issues
        """
        pass

    def supports(self, capability: TranscriptionCapability) -> bool:
        """Check if connector supports a capability."""
        return capability in self.CAPABILITIES

    def _effective_model(self, request: 'TranscriptionRequest') -> str:
        """Resolve which model to use for a given request.

        Honours the per-request override (issue #266) if present, otherwise
        falls back to the connector's configured default model.
        """
        override = (request.model or '').strip() if request and request.model else ''
        return override or getattr(self, 'model', '') or ''

    def get_capabilities(self) -> Set[TranscriptionCapability]:
        """Get all supported capabilities."""
        return self.CAPABILITIES.copy()

    @property
    def supports_diarization(self) -> bool:
        """Check if connector supports speaker diarization."""
        return TranscriptionCapability.DIARIZATION in self.CAPABILITIES

    @property
    def supports_chunking(self) -> bool:
        """Check if connector supports automatic file chunking."""
        return TranscriptionCapability.CHUNKING in self.CAPABILITIES

    @property
    def supports_speaker_count_control(self) -> bool:
        """Check if connector supports min/max speaker count parameters."""
        return TranscriptionCapability.SPEAKER_COUNT_CONTROL in self.CAPABILITIES

    @property
    def supports_exact_speaker_count(self) -> bool:
        """Check if connector accepts an exact speaker count (no range)."""
        return TranscriptionCapability.EXACT_SPEAKER_COUNT in self.CAPABILITIES

    @property
    def supports_hotwords(self) -> bool:
        """Check if connector accepts hotword/keyword biasing input."""
        return TranscriptionCapability.HOTWORDS in self.CAPABILITIES

    @property
    def supports_initial_prompt(self) -> bool:
        """Check if connector accepts an initial prompt / context hint."""
        return TranscriptionCapability.INITIAL_PROMPT in self.CAPABILITIES

    @property
    def specifications(self) -> ConnectorSpecifications:
        """Get connector specifications."""
        return self.SPECIFICATIONS

    @classmethod
    def get_config_schema(cls) -> Dict[str, Any]:
        """
        Return JSON schema for this connector's configuration.
        Useful for admin UI and validation.

        Returns:
            JSON schema dict describing required and optional config
        """
        return {}

    def list_models(self) -> List[Dict[str, Any]]:
        """Discover models the upstream provider exposes.

        Connectors that talk to an OpenAI-compatible /v1/models endpoint
        should override this. Each item is a dict with at minimum 'id' and
        an optional 'label' or 'owned_by'. The default raises
        NotImplementedError so callers can detect unsupported providers.
        """
        raise NotImplementedError(
            f"{type(self).__name__} does not implement list_models()"
        )

    def health_check(self) -> bool:
        """
        Check if the connector is properly configured and reachable.

        Returns:
            True if the connector is healthy, False otherwise
        """
        return True