Skip to content

vllm_mlx.audio.stt

Speech-to-Text (STT) engine using mlx-audio.

View the complete module source at #L1-L160.

API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

vllm_mlx.audio.stt

Speech-to-Text (STT) engine using mlx-audio.

Supports: - Whisper (multilingual, 99+ languages) - Parakeet (English-focused, fast)

vllm_mlx.audio.stt.logger module-attribute 

logger = logging.getLogger(__name__)

vllm_mlx.audio.stt.DEFAULT_WHISPER_MODEL module-attribute 

DEFAULT_WHISPER_MODEL = 'mlx-community/whisper-large-v3-mlx'

vllm_mlx.audio.stt.DEFAULT_PARAKEET_MODEL module-attribute 

DEFAULT_PARAKEET_MODEL = 'mlx-community/parakeet-tdt-0.6b-v2'

vllm_mlx.audio.stt.TranscriptionResult dataclass 

TranscriptionResult(text: str, language: Optional[str] = None, duration: Optional[float] = None, segments: Optional[list] = None)

Result from audio transcription.

vllm_mlx.audio.stt.TranscriptionResult.text instance-attribute 

text: str

vllm_mlx.audio.stt.TranscriptionResult.language class-attribute instance-attribute 

language: Optional[str] = None

vllm_mlx.audio.stt.TranscriptionResult.duration class-attribute instance-attribute 

duration: Optional[float] = None

vllm_mlx.audio.stt.TranscriptionResult.segments class-attribute instance-attribute 

segments: Optional[list] = None

vllm_mlx.audio.stt.STTEngine 

STTEngine(model_name: str = DEFAULT_WHISPER_MODEL)

Speech-to-Text engine supporting Whisper and Parakeet models.

Usage

engine = STTEngine("mlx-community/whisper-large-v3-mlx") engine.load() result = engine.transcribe("audio.mp3") print(result.text)

Initialize STT engine.

Parameters:

  • model_name (str, default: DEFAULT_WHISPER_MODEL ) –

    HuggingFace model name. Supported: - mlx-community/whisper-large-v3-mlx (multilingual) - mlx-community/whisper-large-v3-turbo (fast) - mlx-community/whisper-medium-mlx - mlx-community/whisper-small-mlx - mlx-community/parakeet-tdt-0.6b-v2 (English, fastest) - mlx-community/parakeet-tdt-0.6b-v3

Source code in vllm_mlx/audio/stt.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def __init__(
    self,
    model_name: str = DEFAULT_WHISPER_MODEL,
):
    """
    Initialize STT engine.

    Args:
        model_name: HuggingFace model name. Supported:
            - mlx-community/whisper-large-v3-mlx (multilingual)
            - mlx-community/whisper-large-v3-turbo (fast)
            - mlx-community/whisper-medium-mlx
            - mlx-community/whisper-small-mlx
            - mlx-community/parakeet-tdt-0.6b-v2 (English, fastest)
            - mlx-community/parakeet-tdt-0.6b-v3
    """
    self.model_name = model_name
    self.model = None
    self._loaded = False
    self._is_parakeet = "parakeet" in model_name.lower()

vllm_mlx.audio.stt.STTEngine.model_name instance-attribute 

model_name = model_name

vllm_mlx.audio.stt.STTEngine.model instance-attribute 

model = None

vllm_mlx.audio.stt.STTEngine._loaded instance-attribute 

_loaded = False

vllm_mlx.audio.stt.STTEngine._is_parakeet instance-attribute 

_is_parakeet = 'parakeet' in model_name.lower()

vllm_mlx.audio.stt.STTEngine.load 

load() -> None

Load the STT model.

Source code in vllm_mlx/audio/stt.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def load(self) -> None:
    """Load the STT model."""
    if self._loaded:
        return

    try:
        from mlx_audio.stt.utils import load_model

        self.model = load_model(self.model_name)
        self._loaded = True
        logger.info(f"STT model loaded: {self.model_name}")
    except ImportError as e:
        logger.error(f"mlx-audio not installed: {e}")
        raise ImportError(
            "mlx-audio is required for STT. Install with: pip install mlx-audio"
        ) from e

vllm_mlx.audio.stt.STTEngine.transcribe 

transcribe(audio_path: Union[str, Path], language: Optional[str] = None, task: str = 'transcribe') -> TranscriptionResult

Transcribe audio file to text.

Parameters:

  • audio_path (Union[str, Path]) –

    Path to audio file (mp3, wav, m4a, etc.)

  • language (Optional[str], default: None ) –

    Language code (e.g., "en", "es"). Auto-detected if None.

  • task (str, default: 'transcribe' ) –

    "transcribe" or "translate" (translate to English)

Returns:

Source code in vllm_mlx/audio/stt.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def transcribe(
    self,
    audio_path: Union[str, Path],
    language: Optional[str] = None,
    task: str = "transcribe",
) -> TranscriptionResult:
    """
    Transcribe audio file to text.

    Args:
        audio_path: Path to audio file (mp3, wav, m4a, etc.)
        language: Language code (e.g., "en", "es"). Auto-detected if None.
        task: "transcribe" or "translate" (translate to English)

    Returns:
        TranscriptionResult with text and metadata
    """
    if not self._loaded:
        self.load()

    audio_path = str(audio_path)

    try:
        # Use the model's generate method directly
        kwargs = {"verbose": False}
        if language and not self._is_parakeet:
            kwargs["language"] = language
        if task and not self._is_parakeet:
            kwargs["task"] = task

        result = self.model.generate(audio_path, **kwargs)

        # Extract text and metadata from result
        text = getattr(result, "text", str(result)) if result else ""
        segments = getattr(result, "segments", None)
        detected_lang = getattr(result, "language", None)

        # Calculate duration from segments if available
        duration = None
        if segments:
            last_seg = segments[-1] if segments else None
            if last_seg and hasattr(last_seg, "end"):
                duration = last_seg.end

        return TranscriptionResult(
            text=text.strip() if isinstance(text, str) else str(text),
            language=detected_lang,
            duration=duration,
            segments=segments,
        )
    except Exception as e:
        logger.error(f"Transcription failed: {e}")
        raise

vllm_mlx.audio.stt.STTEngine.unload 

unload() -> None

Unload model to free memory.

Source code in vllm_mlx/audio/stt.py 
135
136
137
138
139
def unload(self) -> None:
    """Unload model to free memory."""
    self.model = None
    self._loaded = False
    logger.info("STT model unloaded")

vllm_mlx.audio.stt.transcribe_audio 

transcribe_audio(audio_path: Union[str, Path], model_name: str = DEFAULT_WHISPER_MODEL, language: Optional[str] = None) -> TranscriptionResult

Convenience function to transcribe audio without managing engine.

Parameters:

  • audio_path (Union[str, Path]) –

    Path to audio file

  • model_name (str, default: DEFAULT_WHISPER_MODEL ) –

    Model to use

  • language (Optional[str], default: None ) –

    Language code (optional)

Returns:

Source code in vllm_mlx/audio/stt.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def transcribe_audio(
    audio_path: Union[str, Path],
    model_name: str = DEFAULT_WHISPER_MODEL,
    language: Optional[str] = None,
) -> TranscriptionResult:
    """
    Convenience function to transcribe audio without managing engine.

    Args:
        audio_path: Path to audio file
        model_name: Model to use
        language: Language code (optional)

    Returns:
        TranscriptionResult
    """
    engine = STTEngine(model_name)
    engine.load()
    return engine.transcribe(audio_path, language=language)

Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

vllm_mlx.audio.stt.TranscriptionResult · class 
vllm_mlx.audio.stt.TranscriptionResult(text: str, language: Optional[str] = None, duration: Optional[float] = None, segments: Optional[list] = None)

Result from audio transcription.

Parameters

Name Type Required Default Description
text str yes none Required constructor field.
language Optional[str] no None Optional constructor field; defaults to None.
duration Optional[float] no None Optional constructor field; defaults to None.
segments Optional[list] no None Optional constructor field; defaults to None.

Returns

  • Constructs: vllm_mlx.audio.stt.TranscriptionResult

Exceptions and behavior

Class TranscriptionResult declares 0 direct member(s). No direct raise statement appears in this definition.

View source #L23-L29.

vllm_mlx.audio.stt.STTEngine · class 
vllm_mlx.audio.stt.STTEngine(model_name: str = DEFAULT_WHISPER_MODEL)

Speech-to-Text engine supporting Whisper and Parakeet models.

Parameters

Name Type Required Default Description
model_name str no DEFAULT_WHISPER_MODEL HuggingFace model name. Supported: - mlx-community/whisper-large-v3-mlx (multilingual) - mlx-community/whisper-large-v3-turbo (fast) - mlx-community/whisper-medium-mlx - mlx-community/whisper-small-mlx - mlx-community/parakeet-tdt-0.6b-v2 (English, fastest) - mlx-community/parakeet-tdt-0.6b-v3

Returns

  • Constructs: vllm_mlx.audio.stt.STTEngine

Exceptions and behavior

Class STTEngine declares 4 direct member(s). No direct raise statement appears in this definition.

View source #L32-L139.

vllm_mlx.audio.stt.STTEngine.__init__ · method 
vllm_mlx.audio.stt.STTEngine.__init__(model_name: str = DEFAULT_WHISPER_MODEL) -> not annotated

Initialize STT engine.

Parameters

Name Type Required Default Description
model_name str no DEFAULT_WHISPER_MODEL HuggingFace model name. Supported: - mlx-community/whisper-large-v3-mlx (multilingual) - mlx-community/whisper-large-v3-turbo (fast) - mlx-community/whisper-medium-mlx - mlx-community/whisper-small-mlx - mlx-community/parakeet-tdt-0.6b-v2 (English, fastest) - mlx-community/parakeet-tdt-0.6b-v3

Returns

  • Type: not annotated

Exceptions and behavior

Method STTEngine.__init__ updates self.model_name, self.model, self._loaded, self._is_parakeet; calls model_name.lower. No direct raise statement appears in this definition.

View source #L43-L62.

vllm_mlx.audio.stt.STTEngine.load · method 
vllm_mlx.audio.stt.STTEngine.load() -> None

Load the STT model.

Parameters

This callable has no explicit inputs.

Returns

  • Type: None
  • Direct return expressions: None

Exceptions and behavior

Method STTEngine.load updates self.model, self._loaded; calls load_model, logger.info, logger.error, ImportError; can raise ImportError; returns None. Directly raised exceptions: ImportError.

View source #L64-L79.

vllm_mlx.audio.stt.STTEngine.transcribe · method 
vllm_mlx.audio.stt.STTEngine.transcribe(audio_path: Union[str, Path], language: Optional[str] = None, task: str = 'transcribe') -> TranscriptionResult

Transcribe audio file to text.

Parameters

Name Type Required Default Description
audio_path Union[str, Path] yes none Path to audio file (mp3, wav, m4a, etc.)
language Optional[str] no None Language code (e.g., "en", "es"). Auto-detected if None.
task str no 'transcribe' "transcribe" or "translate" (translate to English)

Returns

  • Type: TranscriptionResult
  • Direct return expressions: TranscriptionResult(text=text.strip() if isinstance(text, str) else str(text), language=detected_lang, duration=duratio…

Exceptions and behavior

Method STTEngine.transcribe calls self.load, str, self.model.generate, getattr; returns TranscriptionResult(text=text.strip() if isinstance(text, str) else str(text), language=detected_lang, duration=duratio…. No direct raise statement appears in this definition.

View source #L81-L133.

vllm_mlx.audio.stt.STTEngine.unload · method 
vllm_mlx.audio.stt.STTEngine.unload() -> None

Unload model to free memory.

Parameters

This callable has no explicit inputs.

Returns

  • Type: None

Exceptions and behavior

Method STTEngine.unload updates self.model, self._loaded; calls logger.info. No direct raise statement appears in this definition.

View source #L135-L139.

vllm_mlx.audio.stt.transcribe_audio · function 
vllm_mlx.audio.stt.transcribe_audio(audio_path: Union[str, Path], model_name: str = DEFAULT_WHISPER_MODEL, language: Optional[str] = None) -> TranscriptionResult

Convenience function to transcribe audio without managing engine.

Parameters

Name Type Required Default Description
audio_path Union[str, Path] yes none Path to audio file
model_name str no DEFAULT_WHISPER_MODEL Model to use
language Optional[str] no None Language code (optional)

Returns

  • Type: TranscriptionResult
  • Direct return expressions: engine.transcribe(audio_path, language=language)

Exceptions and behavior

Function transcribe_audio calls STTEngine, engine.load, engine.transcribe; returns engine.transcribe(audio_path, language=language). No direct raise statement appears in this definition.

View source #L142-L160.

Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

Symbol Kind Signature and inputs What it does Source
TranscriptionResult class TranscriptionResult(text: str, language: Optional[str] = None, duration: Optional[float] = None, segments: Optional[list] = None) Result from audio transcription. #L23-L29
STTEngine class STTEngine(model_name: str = DEFAULT_WHISPER_MODEL) Speech-to-Text engine supporting Whisper and Parakeet models. #L32-L139
STTEngine.__init__ method STTEngine.__init__(model_name: str = DEFAULT_WHISPER_MODEL) -> not annotated Initialize STT engine. #L43-L62
STTEngine.load method STTEngine.load() -> None Load the STT model. #L64-L79
STTEngine.transcribe method STTEngine.transcribe(audio_path: Union[str, Path], language: Optional[str] = None, task: str = 'transcribe') -> TranscriptionResult Transcribe audio file to text. #L81-L133
STTEngine.unload method STTEngine.unload() -> None Unload model to free memory. #L135-L139
transcribe_audio function transcribe_audio(audio_path: Union[str, Path], model_name: str = DEFAULT_WHISPER_MODEL, language: Optional[str] = None) -> TranscriptionResult Convenience function to transcribe audio without managing engine. #L142-L160