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

Code before:
            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 False.
            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.
            http_session (aiohttp.ClientSession | None): Custom HTTP session for API requests. Optional.
        """  # noqa: E501

        super().__init__(
            capabilities=STTCapabilities(
                streaming=use_realtime,
                interim_results=True,
                aligned_transcript="word" if include_timestamps and use_realtime else False,
            )
        )

        if not use_realtime and is_given(server_vad):
            logger.warning("Server-side VAD is only supported for Scribe v2 realtime model")

        if use_realtime and model_id != "scribe_v2_realtime":
            logger.warning(
                "When use_realtime=True, the only supported model is currently scribe_v2_realtime, so setting model_id to scribe_v2_realtime"
            )
            model_id = "scribe_v2_realtime"

        if not use_realtime and "realtime" in model_id:
            raise ValueError(
                "The currently selected model is a realtime model but use_realtime is False"
            )

        elevenlabs_api_key = api_key if is_given(api_key) else os.environ.get("ELEVEN_API_KEY")
        if not elevenlabs_api_key:
            raise ValueError(
                "ElevenLabs API key is required, either as argument or "
                "set ELEVEN_API_KEY environmental variable"
            )
        self._opts = STTOptions(
            api_key=elevenlabs_api_key,
            base_url=base_url if is_given(base_url) else API_BASE_URL_V1,
            language_code=language_code or None,
            tag_audio_events=tag_audio_events,
            sample_rate=sample_rate,
            server_vad=server_vad,
            include_timestamps=include_timestamps,
            model_id=model_id,
        )
        self._session = http_session
        self._streams = weakref.WeakSet[SpeechStream]()

    @property
    def model(self) -> str:

Review comment (suggestion):
can you make `use_realtime`'s default to `NOT_GIVEN`, and mark it deprecated? so when it's True, we change the model id to `scribe_v2_realtime` and add a deprecated warning, and only raise the error when it's explicitly specified as False.

```suggestion
        if use_realtime is False and "realtime" in model_id:
```

Code after:
            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.
            http_session (aiohttp.ClientSession | None): Custom HTTP session for API requests. Optional.
            model_id (ElevenLabsSTTModels | str): ElevenLabs STT model to use. If not specified a default model will
                be selected based on parameters provided.
        """

        if is_given(use_realtime):
            if is_given(model_id):
                logger.warning(
                    "both `use_realtime` and `model_id` parameters are provided. `use_realtime` will be ignored."
                )
            else:
                logger.warning(
                    "`use_realtime` parameter is deprecated. "
                    "Specify a realtime model_id to enable streaming. "
                    "Defaulting model_id to one based on use_realtime parameter. "
                )
                model_id = "scribe_v2_realtime" if use_realtime else "scribe_v1"
        model_id = model_id if is_given(model_id) else "scribe_v1"
        use_realtime = model_id == "scribe_v2_realtime"

        if not use_realtime and is_given(server_vad):
            logger.warning("Server-side VAD is only supported for Scribe v2 realtime model")

        super().__init__(
            capabilities=STTCapabilities(
                streaming=use_realtime,
                interim_results=True,
                aligned_transcript="word" if include_timestamps and use_realtime else False,
            )
        )

        elevenlabs_api_key = api_key if is_given(api_key) else os.environ.get("ELEVEN_API_KEY")
        if not elevenlabs_api_key:
            raise ValueError(
                "ElevenLabs API key is required, either as argument or "
                "set ELEVEN_API_KEY environmental variable"
            )

        self._opts = STTOptions(
            api_key=elevenlabs_api_key,
            base_url=base_url if is_given(base_url) else API_BASE_URL_V1,
            language_code=language_code or None,
            tag_audio_events=tag_audio_events,
            sample_rate=sample_rate,
            server_vad=server_vad,