Add native MLX DeepFilterNet speech enhancement (v1/v2/v3)

CONTRIBUTIONS.md

@@ -8,3 +8,10 @@ This file acknowledges the original authors and contributors of models ported to
 - **Copyright**: Speech Lab, Alibaba Group
 - **License**: Apache License 2.0
 - **MLX Port**: Dmitry Starkov ([@starkdmi](https://github.com/starkdmi))
+
+## DeepFilterNet (Speech Enhancement)
+
+- **Original**: [Rikorose/DeepFilterNet](https://github.com/Rikorose/DeepFilterNet)
+- **Copyright**: Hendrik Schröter and contributors
+- **License**: MIT / Apache-2.0
+- **MLX Port**: Kyle Howells ([@kylehowells](https://github.com/kylehowells))

README.md

@@ -119,8 +119,9 @@ See the [Sortformer README](mlx_audio/vad/models/sortformer/README.md) for API d
 | Model | Description | Use Case | Repo |
 |-------|-------------|----------|------|
 | **SAM-Audio** | Text-guided source separation | Extract specific sounds | [mlx-community/sam-audio-large](https://huggingface.co/mlx-community/sam-audio-large) |
-| **Liquid2.5-Audio*** | Speech-to-Speech, Text-to-Speech and Speech-to-Text | Speech interactions | [mlx-community/LFM2.5-Audio-1.5B-8bit](https://huggingface.co/mlx-community/LFM2.5-Audio-1.5B-8bit)
+| **Liquid2.5-Audio*** | Speech-to-Speech, Text-to-Speech and Speech-to-Text | Speech interactions | [mlx-community/LFM2.5-Audio-1.5B-8bit](https://huggingface.co/mlx-community/LFM2.5-Audio-1.5B-8bit) |
 | **MossFormer2 SE** | Speech enhancement | Noise removal | [starkdmi/MossFormer2_SE_48K_MLX](https://huggingface.co/starkdmi/MossFormer2_SE_48K_MLX) |
+| **DeepFilterNet (1/2/3)** | Speech enhancement | Noise suppression | [iky1e/DeepFilterNet3-MLX](https://huggingface.co/iky1e/DeepFilterNet3-MLX) |
 
 ## Model Examples
 

examples/deepfilternet.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Example script for DeepFilterNet speech enhancement."""
+
+from mlx_audio.sts.deepfilternet import main
+
+if __name__ == "__main__":
+    main()

mlx_audio/sts/__init__.py

@@ -1,3 +1,11 @@
+from .models.deepfilternet import (
+    DeepFilterNet2Config,
+    DeepFilterNet3Config,
+    DeepFilterNetConfig,
+    DeepFilterNetModel,
+    DeepFilterNetStreamer,
+    DeepFilterNetStreamingConfig,
+)
 from .models.mossformer2_se import (
     MossFormer2SE,
     MossFormer2SEConfig,
@@ -11,7 +19,11 @@
     SeparationResult,
     save_audio,
 )
-from .voice_pipeline import VoicePipeline
+
+try:
+    from .voice_pipeline import VoicePipeline
+except ImportError:
+    VoicePipeline = None
 
 __all__ = [
     "SAMAudio",
@@ -21,6 +33,13 @@
     "save_audio",
     "SAMAudioConfig",
     "VoicePipeline",
+    # DeepFilterNet
+    "DeepFilterNetModel",
+    "DeepFilterNetConfig",
+    "DeepFilterNet2Config",
+    "DeepFilterNet3Config",
+    "DeepFilterNetStreamer",
+    "DeepFilterNetStreamingConfig",
     # MossFormer2 SE
     "MossFormer2SE",
     "MossFormer2SEConfig",

mlx_audio/sts/deepfilternet.py

@@ -0,0 +1,90 @@
+"""CLI entrypoint for DeepFilterNet speech enhancement."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from mlx_audio.sts.models.deepfilternet import DeepFilterNetModel
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Denoise audio with DeepFilterNet (MLX)"
+    )
+    parser.add_argument("input", help="Input noisy audio file (48 kHz)")
+    parser.add_argument("-o", "--output", help="Output denoised audio path")
+    parser.add_argument(
+        "-m",
+        "--model",
+        type=str,
+        default=None,
+        help=(
+            "Model name or path. Can be a Hugging Face repo id or local model directory."
+        ),
+    )
+    parser.add_argument(
+        "--stream",
+        action="store_true",
+        help="Run chunked streaming enhancement (stateful process_chunk/flush path)",
+    )
+    parser.add_argument(
+        "--chunk-ms",
+        type=float,
+        default=480.0,
+        help="Chunk size for --stream mode in milliseconds (default: 480)",
+    )
+    parser.add_argument(
+        "--pad-end-frames",
+        type=int,
+        default=3,
+        help="Extra zero frames to flush streaming tail (default: 3)",
+    )
+    parser.add_argument(
+        "--no-delay-compensation",
+        action="store_true",
+        help="Disable initial delay compensation crop in streaming output",
+    )
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+
+    in_path = Path(args.input).expanduser().resolve()
+    if not in_path.exists():
+        raise FileNotFoundError(f"Input file not found: {in_path}")
+
+    out_path = (
+        Path(args.output).expanduser().resolve()
+        if args.output
+        else in_path.with_stem(in_path.stem + "_enhanced_mlx")
+    )
+
+    model = DeepFilterNetModel.from_pretrained(model_name_or_path=args.model)
+    if args.stream:
+        sr = model.config.sample_rate
+        chunk_samples = max(model.config.hop_size, int(sr * args.chunk_ms / 1000.0))
+        try:
+            model.enhance_file_streaming(
+                in_path,
+                out_path,
+                chunk_samples=chunk_samples,
+                pad_end_frames=max(0, args.pad_end_frames),
+                compensate_delay=(not args.no_delay_compensation),
+            )
+        except NotImplementedError as exc:
+            raise NotImplementedError(
+                f"Streaming mode is unavailable for {model.model_version}: {exc}"
+            ) from exc
+    else:
+        model.enhance_file(in_path, out_path)
+
+    print(f"Input : {in_path}")
+    print(f"Model : {model.model_version}")
+    print(f"Mode  : {'streaming' if args.stream else 'offline'}")
+    print(f"Output: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

mlx_audio/sts/models/__init__.py

@@ -1,5 +1,13 @@
 # Copyright (c) 2025 Prince Canuma and contributors (https://github.com/Blaizzy/mlx-audio)
 
+from .deepfilternet import (
+    DeepFilterNet2Config,
+    DeepFilterNet3Config,
+    DeepFilterNetConfig,
+    DeepFilterNetModel,
+    DeepFilterNetStreamer,
+    DeepFilterNetStreamingConfig,
+)
 from .lfm_audio import (
     ChatState,
     GenerationConfig,
@@ -25,6 +33,13 @@
     "Batch",
     "save_audio",
     "SAMAudioConfig",
+    # DeepFilterNet
+    "DeepFilterNetModel",
+    "DeepFilterNetConfig",
+    "DeepFilterNet2Config",
+    "DeepFilterNet3Config",
+    "DeepFilterNetStreamer",
+    "DeepFilterNetStreamingConfig",
     # MossFormer2 SE
     "MossFormer2SE",
     "MossFormer2SEConfig",

mlx_audio/sts/models/deepfilternet/README.md

@@ -0,0 +1,46 @@
+# DeepFilterNet (MLX)
+
+DeepFilterNet speech enhancement in pure MLX with support for model versions 1, 2, and 3.
+
+## Quick Start
+
+```python
+from mlx_audio.sts.models.deepfilternet import DeepFilterNetModel
+
+model = DeepFilterNetModel.from_pretrained()
+model.enhance_file("noisy.wav", "clean.wav")
+```
+
+Or load from a local model directory (must contain `config.json` and weights):
+
+```python
+model = DeepFilterNetModel.from_pretrained("./models/MyDeepFilterNet")
+```
+
+Or load from a Hugging Face repo id:
+
+```python
+model = DeepFilterNetModel.from_pretrained("iky1e/DeepFilterNet3-MLX")
+```
+
+Streaming/chunked mode (true per-hop stateful processing for DF2/DF3):
+
+```python
+streamer = model.create_streamer(pad_end_frames=3, compensate_delay=True)
+out_1 = streamer.process_chunk(chunk_a)
+out_2 = streamer.process_chunk(chunk_b)
+out_tail = streamer.flush()
+```
+
+## Model Selection
+
+Model architecture is selected from `config.json` (`model_version`).
+
+## Example Script
+
+```bash
+python examples/deepfilternet.py examples/denoise/noisey_audio_10s.wav
+python examples/deepfilternet.py examples/denoise/noisey_audio_10s.wav --model ./models/DeepFilterNet3
+python examples/deepfilternet.py examples/denoise/noisey_audio_10s.wav --model iky1e/DeepFilterNet3-MLX
+python examples/deepfilternet.py examples/denoise/noisey_audio_10s.wav --stream
+```

mlx_audio/sts/models/deepfilternet/__init__.py

@@ -0,0 +1,19 @@
+"""DeepFilterNet speech enhancement model for MLX."""
+
+from .config import DeepFilterNet2Config, DeepFilterNet3Config, DeepFilterNetConfig
+from .model import DeepFilterNetModel
+from .streaming import DeepFilterNetStreamer, DeepFilterNetStreamingConfig
+
+Model = DeepFilterNetModel
+ModelConfig = DeepFilterNetConfig
+
+__all__ = [
+    "DeepFilterNetModel",
+    "DeepFilterNetConfig",
+    "DeepFilterNet2Config",
+    "DeepFilterNet3Config",
+    "DeepFilterNetStreamer",
+    "DeepFilterNetStreamingConfig",
+    "Model",
+    "ModelConfig",
+]