fix: add missing ZipEnhancer/ModelScope transitive dependencies

  - setuptools: modelscope uses pkg_resources at runtime (not just build-time)
  - einops: tensor operations required by modelscope framework
  - attrs: attribute classes required by modelscope framework
  - Pillow: image processing required by modelscope framework
  - datasets: version bumped to >=3.0.0,<=3.6.0 to match modelscope constraint
  - whisperjav[huggingface]: cross-extra ref so enhance pulls transformers
  - llm extra added to installer_extras in build_release.py (was missing)
  - Updated docs to reflect all 5 speech enhancement backends

  Fixes ZipEnhancer 'No module named pkg_resources' error.

Author: meizhong986

installer/build_release.py

@@ -178,6 +178,7 @@ def generate_requirements_from_pyproject(self):
             "cli",
             "gui",
             "translate",
+            "llm",
             "enhance",
             "huggingface",
             "qwen",

pyproject.toml

@@ -164,19 +164,26 @@ llm = [
 #   sudo dnf install libsndfile       (Fedora/RHEL)
 #
 # VERSION NOTES:
-# - datasets: ZipEnhancer recommends ==2.18.0, we use >=2.14.0,<4.0 for flexibility.
-#   If you encounter ModelScope issues, try: pip install datasets==2.18.0
-# - modelscope: >=1.20 required, 1.22.0 recommended by ZipEnhancer docs.
+# - datasets: ModelScope requires >=3.0.0,<=3.6.0 (as of modelscope master 2026-03)
+# - modelscope: >=1.20 required, 1.22.0+ recommended.
+# - setuptools: Required by modelscope at runtime (uses pkg_resources in utils/plugins.py)
+# - einops: Required by modelscope framework for tensor operations
 enhance = [
     # ModelScope (ZipEnhancer) - core framework
     "modelscope>=1.20",
+    # setuptools: modelscope uses pkg_resources at runtime (not just build-time)
+    "setuptools",
+    # einops: tensor operations required by modelscope framework
+    "einops",
     # oss2: Alibaba Cloud OSS SDK - required by ModelScope to download models
     "oss2",
     "addict",
-    "datasets>=2.14.0,<4.0",  # 4.x breaks modelscope; ZipEnhancer recommends 2.18.0
+    "attrs",  # Required by modelscope framework
+    "datasets>=3.0.0,<=3.6.0",  # Must match modelscope's constraint (was >=2.14.0)
     "simplejson",
     "sortedcontainers",
     "packaging",
+    "Pillow",  # Required by modelscope framework
 
     # ClearVoice (fork with relaxed librosa)
     "clearvoice @ git+https://github.com/meizhong986/ClearerVoice-Studio.git#subdirectory=clearvoice",
@@ -186,6 +193,9 @@ enhance = [
 
     # ONNX inference
     "onnxruntime>=1.16.0",
+
+    # ModelScope framework requires transformers; pull via huggingface extra
+    "whisperjav[huggingface]",
 ]
 
 # HuggingFace ecosystem (for kotoba-whisper, model downloads)

whisperjav/installer/core/registry.py

@@ -102,7 +102,7 @@ class Extra(Enum):
     GUI = "gui"             # PyWebView GUI
     TRANSLATE = "translate" # AI translation (pysubtrans, OpenAI, Gemini)
     LLM = "llm"             # Local LLM server (FastAPI, uvicorn)
-    ENHANCE = "enhance"     # Speech enhancement (ClearVoice, BS-RoFormer)
+    ENHANCE = "enhance"     # Speech enhancement (ZipEnhancer, ClearVoice, BS-RoFormer, FFmpeg-DSP)
     HUGGINGFACE = "huggingface"  # HuggingFace Transformers
     QWEN = "qwen"           # Qwen3-ASR support (v1.8.3+)
     ANALYSIS = "analysis"   # Scientific analysis and visualization
@@ -602,9 +602,10 @@ def matches_platform(self, current_platform: str = None) -> bool:
     # Reference: https://modelscope.cn/models/iic/speech_zipenhancer_ans_multiloss_16k_base
     #
     # IMPORTANT - Version Sensitivity:
-    # - datasets: ZipEnhancer docs recommend ==2.18.0, but we use >=2.14.0,<4.0
-    #   for broader compatibility. If you encounter issues, try pinning to 2.18.0.
-    # - modelscope: >=1.20 required, 1.22.0 recommended by ZipEnhancer docs.
+    # - datasets: ModelScope requires >=3.0.0,<=3.6.0 (as of 2026-03)
+    # - modelscope: >=1.20 required, 1.22.0+ recommended
+    # - setuptools: Required at RUNTIME by modelscope (uses pkg_resources in utils/plugins.py)
+    # - einops: Required by modelscope framework for tensor operations
     #
     # LINUX SYSTEM DEPENDENCIES (not pip-installable):
     # - libsndfile1: Required for soundfile package. Install with:
@@ -618,6 +619,19 @@ def matches_platform(self, current_platform: str = None) -> bool:
         order=70,
         reason="ModelScope framework for ZipEnhancer speech enhancement",
     ),
+    Package(
+        name="setuptools",
+        extra=Extra.ENHANCE,
+        order=70,
+        import_name="pkg_resources",
+        reason="Runtime dependency of modelscope (uses pkg_resources in utils/plugins.py)",
+    ),
+    Package(
+        name="einops",
+        extra=Extra.ENHANCE,
+        order=70,
+        reason="Tensor operations - required by modelscope framework",
+    ),
     Package(
         name="oss2",
         extra=Extra.ENHANCE,
@@ -630,12 +644,18 @@ def matches_platform(self, current_platform: str = None) -> bool:
         order=72,
         reason="Dict subclass for modelscope configs",
     ),
+    Package(
+        name="attrs",
+        extra=Extra.ENHANCE,
+        order=72,
+        reason="Attribute classes - required by modelscope framework",
+    ),
     Package(
         name="datasets",
-        version=">=2.14.0,<4.0",
+        version=">=3.0.0,<=3.6.0",
         extra=Extra.ENHANCE,
         order=73,
-        reason="HuggingFace datasets - pinned <4.0 due to modelscope compat (ZipEnhancer recommends 2.18.0)",
+        reason="HuggingFace datasets - must match modelscope constraint (>=3.0.0)",
     ),
     Package(
         name="simplejson",
@@ -655,6 +675,13 @@ def matches_platform(self, current_platform: str = None) -> bool:
         order=76,
         reason="Version parsing for modelscope",
     ),
+    Package(
+        name="Pillow",
+        extra=Extra.ENHANCE,
+        order=76,
+        import_name="PIL",
+        reason="Image processing - required by modelscope framework",
+    ),
     Package(
         name="clearvoice",
         extra=Extra.ENHANCE,

whisperjav/modules/speech_enhancement/__init__.py

@@ -33,8 +33,10 @@
 
 Available Backends:
     - none: Passthrough (no enhancement)
-    - clearvoice: ClearerVoice speech enhancement (denoising)
-    - bs-roformer: BS-RoFormer vocal isolation
+    - ffmpeg-dsp: FFmpeg audio filters (loudnorm, compress, denoise)
+    - zipenhancer: ZipEnhancer 16kHz via ModelScope (lightweight, SOTA quality)
+    - clearvoice: ClearerVoice speech enhancement (denoising, 48kHz)
+    - bs-roformer: BS-RoFormer vocal isolation (44.1kHz)
 
 Design Principles:
     - Lazy loading: Backends loaded only when needed

whisperjav/modules/speech_enhancement/factory.py

@@ -3,11 +3,12 @@
 
 Supports lazy loading to avoid import overhead for unused backends.
 
-Design Decisions (v1.7.3):
+Design Decisions (v1.7.3, extended v1.8.x):
 - Single backend entry with model parameter (not separate entries per sample rate)
-- Default model is 48kHz variant for best quality
+- Default model varies by backend (e.g., 48kHz for ClearVoice, 16kHz for ZipEnhancer)
 - Graceful degradation handled at backend level
 - Consistent with SpeechSegmenterFactory pattern
+- Five backends: none, ffmpeg-dsp, zipenhancer, clearvoice, bs-roformer
 """
 
 from typing import Dict, Type, Optional, Any, List, Tuple