# `vllm_mlx.audio.processor`

Audio processing using mlx-audio.

[View the complete module source at #L1-L214](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L1-L214).

## 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.processor
    options:
      members:
        - logger
        - DEFAULT_SAM_MODEL
        - SeparationResult
        - AudioProcessor
        - separate_voice
      filters: []
      show_if_no_docstring: true

## 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.

<details class="api-contract" id="contract-vllm_mlx.audio.processor.SeparationResult" markdown="1">
<summary><code>vllm_mlx.audio.processor.SeparationResult</code> · class</summary>

```python
vllm_mlx.audio.processor.SeparationResult(target: np.ndarray, residual: np.ndarray, sample_rate: int, peak_memory: float)
```

Result from audio separation.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `target` | `np.ndarray` | `yes` | `none` | Required constructor field. |
| `residual` | `np.ndarray` | `yes` | `none` | Required constructor field. |
| `sample_rate` | `int` | `yes` | `none` | Required constructor field. |
| `peak_memory` | `float` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `vllm_mlx.audio.processor.SeparationResult`

**Exceptions and behavior**

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

[View source #L24-L30](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L24-L30).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor</code> · class</summary>

```python
vllm_mlx.audio.processor.AudioProcessor(model_name: str = DEFAULT_SAM_MODEL)
```

Audio processor for voice separation and enhancement.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `no` | `DEFAULT_SAM_MODEL` | HuggingFace model name. Supported: - mlx-community/sam-audio-large-fp16 (best quality) - mlx-community/sam-audio-large - mlx-community/sam-audio-small-fp16 (faster) - mlx-community/sam-audio-small |

**Returns**

- Constructs: `vllm_mlx.audio.processor.AudioProcessor`

**Exceptions and behavior**

Class `AudioProcessor` declares 6 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L33-L192](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L33-L192).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor.__init__" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor.__init__</code> · method</summary>

```python
vllm_mlx.audio.processor.AudioProcessor.__init__(model_name: str = DEFAULT_SAM_MODEL) -> not annotated
```

Initialize audio processor.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model_name` | `str` | `no` | `DEFAULT_SAM_MODEL` | HuggingFace model name. Supported: - mlx-community/sam-audio-large-fp16 (best quality) - mlx-community/sam-audio-large - mlx-community/sam-audio-small-fp16 (faster) - mlx-community/sam-audio-small |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Method `AudioProcessor.__init__` updates `self.model_name`, `self.model`, `self.processor`, `self._loaded`.
No direct `raise` statement appears in this definition.

[View source #L48-L66](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L48-L66).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor.load" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor.load</code> · method</summary>

```python
vllm_mlx.audio.processor.AudioProcessor.load() -> None
```

Load the SAM-Audio model.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`
- Direct return expressions: `None`

**Exceptions and behavior**

Method `AudioProcessor.load` updates `self.model`, `self.processor`, `self.sample_rate`, `self._loaded`; calls `SAMAudio.from_pretrained`, `SAMAudioProcessor.from_pretrained`, `hasattr`, `logger.info`; can raise `ImportError`; returns `None`.
Directly raised exceptions: `ImportError`.

[View source #L68-L88](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L68-L88).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor.separate" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor.separate</code> · method</summary>

```python
vllm_mlx.audio.processor.AudioProcessor.separate(audio_path: Union[str, Path], description: str = 'speech', chunk_seconds: Optional[float] = None) -> SeparationResult
```

Separate audio based on text description.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio_path` | `Union[str, Path]` | `yes` | `none` | Path to audio file |
| `description` | `str` | `no` | `'speech'` | What to isolate (e.g., "speech", "music", "a person speaking") |
| `chunk_seconds` | `Optional[float]` | `no` | `None` | Process in chunks for long audio (memory efficient) |

**Returns**

- Type: `SeparationResult`
- Direct return expressions: `SeparationResult(target=target, residual=residual, sample_rate=self.sample_rate, peak_memory=getattr(result, 'peak_memo…`

**Exceptions and behavior**

Method `AudioProcessor.separate` calls `self.load`, `str`, `self.processor`, `self.model.separate_long`; returns `SeparationResult(target=target, residual=residual, sample_rate=self.sample_rate, peak_memory=getattr(result, 'peak_memo…`.
No direct `raise` statement appears in this definition.

[View source #L90-L151](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L90-L151).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor._to_numpy" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor._to_numpy</code> · method</summary>

```python
vllm_mlx.audio.processor.AudioProcessor._to_numpy(audio) -> np.ndarray
```

Convert audio to numpy array.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio` | `not annotated` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `np.ndarray`
- Direct return expressions: `np.array(audio.tolist(), dtype=np.float32)`; `np.array(audio, dtype=np.float32)`

**Exceptions and behavior**

Method `AudioProcessor._to_numpy` calls `hasattr`, `np.array`, `audio.tolist`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L153-L157](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L153-L157).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor.save" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor.save</code> · method</summary>

```python
vllm_mlx.audio.processor.AudioProcessor.save(audio: np.ndarray, path: Union[str, Path], sample_rate: Optional[int] = None) -> None
```

Save audio to file.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio` | `np.ndarray` | `yes` | `none` | Audio data as numpy array |
| `path` | `Union[str, Path]` | `yes` | `none` | Output file path |
| `sample_rate` | `Optional[int]` | `no` | `None` | Sample rate (uses model default if None) |

**Returns**

- Type: `None`

**Exceptions and behavior**

Method `AudioProcessor.save` calls `save_audio`, `str`, `(audio * 32767).astype`, `wav.write`.
No direct `raise` statement appears in this definition.

[View source #L159-L185](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L159-L185).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.AudioProcessor.unload" markdown="1">
<summary><code>vllm_mlx.audio.processor.AudioProcessor.unload</code> · method</summary>

```python
vllm_mlx.audio.processor.AudioProcessor.unload() -> None
```

Unload model to free memory.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `None`

**Exceptions and behavior**

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

[View source #L187-L192](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L187-L192).

</details>

<details class="api-contract" id="contract-vllm_mlx.audio.processor.separate_voice" markdown="1">
<summary><code>vllm_mlx.audio.processor.separate_voice</code> · function</summary>

```python
vllm_mlx.audio.processor.separate_voice(audio_path: Union[str, Path], model_name: str = DEFAULT_SAM_MODEL, description: str = 'speech') -> Tuple[np.ndarray, np.ndarray]
```

Convenience function to separate voice from audio.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `audio_path` | `Union[str, Path]` | `yes` | `none` | Path to audio file |
| `model_name` | `str` | `no` | `DEFAULT_SAM_MODEL` | Model to use |
| `description` | `str` | `no` | `'speech'` | What to isolate |

**Returns**

- Type: `Tuple[np.ndarray, np.ndarray]`
- Direct return expressions: `(result.target, result.residual)`

**Exceptions and behavior**

Function `separate_voice` calls `AudioProcessor`, `processor.load`, `processor.separate`; returns `(result.target, result.residual)`.
No direct `raise` statement appears in this definition.

[View source #L195-L214](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L195-L214).

</details>

## 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 |
| --- | --- | --- | --- | --- |
| [`SeparationResult`](#contract-vllm_mlx.audio.processor.SeparationResult) | class | `SeparationResult(target: np.ndarray, residual: np.ndarray, sample_rate: int, peak_memory: float)` | Result from audio separation. | [#L24-L30](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L24-L30) |
| [`AudioProcessor`](#contract-vllm_mlx.audio.processor.AudioProcessor) | class | `AudioProcessor(model_name: str = DEFAULT_SAM_MODEL)` | Audio processor for voice separation and enhancement. | [#L33-L192](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L33-L192) |
| [`AudioProcessor.__init__`](#contract-vllm_mlx.audio.processor.AudioProcessor.__init__) | method | `AudioProcessor.__init__(model_name: str = DEFAULT_SAM_MODEL) -> not annotated` | Initialize audio processor. | [#L48-L66](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L48-L66) |
| [`AudioProcessor.load`](#contract-vllm_mlx.audio.processor.AudioProcessor.load) | method | `AudioProcessor.load() -> None` | Load the SAM-Audio model. | [#L68-L88](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L68-L88) |
| [`AudioProcessor.separate`](#contract-vllm_mlx.audio.processor.AudioProcessor.separate) | method | `AudioProcessor.separate(audio_path: Union[str, Path], description: str = 'speech', chunk_seconds: Optional[float] = None) -> SeparationResult` | Separate audio based on text description. | [#L90-L151](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L90-L151) |
| [`AudioProcessor._to_numpy`](#contract-vllm_mlx.audio.processor.AudioProcessor._to_numpy) | method | `AudioProcessor._to_numpy(audio) -> np.ndarray` | Convert audio to numpy array. | [#L153-L157](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L153-L157) |
| [`AudioProcessor.save`](#contract-vllm_mlx.audio.processor.AudioProcessor.save) | method | `AudioProcessor.save(audio: np.ndarray, path: Union[str, Path], sample_rate: Optional[int] = None) -> None` | Save audio to file. | [#L159-L185](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L159-L185) |
| [`AudioProcessor.unload`](#contract-vllm_mlx.audio.processor.AudioProcessor.unload) | method | `AudioProcessor.unload() -> None` | Unload model to free memory. | [#L187-L192](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L187-L192) |
| [`separate_voice`](#contract-vllm_mlx.audio.processor.separate_voice) | function | `separate_voice(audio_path: Union[str, Path], model_name: str = DEFAULT_SAM_MODEL, description: str = 'speech') -> Tuple[np.ndarray, np.ndarray]` | Convenience function to separate voice from audio. | [#L195-L214](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/audio/processor.py#L195-L214) |