Repository: livekit/agents
File: livekit-plugins/livekit-plugins-elevenlabs/livekit/plugins/elevenlabs/stt.py (Python)

Code before:
    min_speech_duration_ms: int | None
    """Minimum speech duration in milliseconds. Default to 250"""
    min_silence_duration_ms: int | None
    """Minimum silence duration in milliseconds. Default to 2500"""


# https://elevenlabs.io/docs/overview/models#models-overview
ElevenLabsSTTModels = Literal["scribe_v1", "scribe_v2", "scribe_v2_realtime"]

# Mapping of ISO 639-3 language codes used by Scribe to ISO 639-1 used by Livekit turn detector multilingual model
ISO_639_3_TO_1 = {
    "eng": "en",
    "spa": "es",
    "fra": "fr",
    "deu": "de",
    "ita": "it",
    "por": "pt",
    "nld": "nl",
    "zho": "zh",
    "jpn": "ja",
    "kor": "ko",
    "ind": "id",
    "tur": "tr",
    "rus": "ru",
    "hin": "hi",
}

def iso639_3_to_1(code):
    """Convert ISO 639-3 to ISO 639-1. Returns None if no mapping exists."""
    return ISO_639_3_TO_1.get(code.lower())

@dataclass
class STTOptions:
    model_id: ElevenLabsSTTModels | str
    api_key: str
    base_url: str
    language_code: str | None
    tag_audio_events: bool
    include_timestamps: bool
    sample_rate: STTRealtimeSampleRates
    server_vad: NotGivenOr[VADOptions | None]


class STT(stt.STT):
    def __init__(
        self,
        *,
        api_key: NotGivenOr[str] = NOT_GIVEN,
        base_url: NotGivenOr[str] = NOT_GIVEN,
        language_code: NotGivenOr[str] = NOT_GIVEN,
        tag_audio_events: bool = True,

Review comment (suggestion):
One small thing: we should include all the languages, and let the EOT decide if it is supported or not. This information might be used in other places/components where language is important (TTS/LLM). We can include a comment to the link as well https://elevenlabs.io/docs/overview/capabilities/speech-to-text#supported-languages

You can definitely create a separate `languages.py` to list all the values.

Code after:
    """Threshold for voice activity detection. Default to 0.4"""
    min_speech_duration_ms: int | None
    """Minimum speech duration in milliseconds. Default to 250"""
    min_silence_duration_ms: int | None
    """Minimum silence duration in milliseconds. Default to 2500"""


# https://elevenlabs.io/docs/overview/models#models-overview
ElevenLabsSTTModels = Literal["scribe_v1", "scribe_v2", "scribe_v2_realtime"]


@dataclass
class STTOptions:
    model_id: ElevenLabsSTTModels | str
    api_key: str
    base_url: str
    language_code: str | None
    tag_audio_events: bool
    include_timestamps: bool
    sample_rate: STTRealtimeSampleRates
    server_vad: NotGivenOr[VADOptions | None]


class STT(stt.STT):
    def __init__(
        self,
        *,
        api_key: NotGivenOr[str] = NOT_GIVEN,
        base_url: NotGivenOr[str] = NOT_GIVEN,
        language_code: NotGivenOr[str] = NOT_GIVEN,
        tag_audio_events: bool = True,
        use_realtime: NotGivenOr[bool] = NOT_GIVEN,  # Deprecated
        sample_rate: STTRealtimeSampleRates = 16000,
        server_vad: NotGivenOr[VADOptions] = NOT_GIVEN,
        include_timestamps: bool = False,
        http_session: aiohttp.ClientSession | None = None,
        model_id: NotGivenOr[ElevenLabsSTTModels | str] = NOT_GIVEN,
    ) -> None:
        """
        Create a new instance of ElevenLabs STT.

        Args:
            api_key (NotGivenOr[str]): ElevenLabs API key. Can be set via argument or `ELEVEN_API_KEY` environment variable.
            base_url (NotGivenOr[str]): Custom base URL for the API. Optional.
            language_code (NotGivenOr[str]): Language code for the STT model. Optional.
            tag_audio_events (bool): Whether to tag audio events like (laughter), (footsteps), etc. in the transcription.
                Only supported for Scribe v1 model. Default is True.
            use_realtime (bool): Whether to use "scribe_v2_realtime" model for streaming mode. Default is NOT_GIVEN.
                Note that this flag is deprecated in favour of explicitly specifying the model id.
            sample_rate (STTRealtimeSampleRates): Audio sample rate in Hz. Default is 16000.
            server_vad (NotGivenOr[VADOptions]): Server-side VAD options, only supported for Scribe v2 realtime model.