Update README: add model descriptions, update conversion path to direct PyTorch export

README.md

@@ -22,16 +22,16 @@ Demucs is a music source separation model that splits audio into stems: `drums`,
 
 ## Models
 
-| Model | Architecture | Sub-models | Sources | Weights | Tensors |
-|-------|-------------|-----------|---------|---------|---------|
-| `htdemucs` | HTDemucs (v4) | 1 | 4 | 160 MB | 573 |
-| `htdemucs_ft` | HTDemucs (v4) | 4 (fine-tuned) | 4 | 641 MB | 2292 |
-| `htdemucs_6s` | HTDemucs (v4) | 1 | 6 | 105 MB | 565 |
-| `hdemucs_mmi` | HDemucs (v3) | 1 | 4 | 319 MB | 379 |
-| `mdx` | Demucs + HDemucs | 4 (bag) | 4 | 1.3 GB | 1298 |
-| `mdx_extra` | HDemucs | 4 (bag) | 4 | 1.2 GB | 1516 |
-| `mdx_q` | Demucs + HDemucs | 4 (bag) | 4 | 1.3 GB | 1298 |
-| `mdx_extra_q` | HDemucs | 4 (bag) | 4 | 1.2 GB | 1516 |
+| Model | What it is | Architecture | Sub-models | Sources | Weights | Tensors |
+|-------|-----------|-------------|-----------|---------|---------|---------|
+| `htdemucs` | Default v4 model, best speed/quality balance | HTDemucs (v4) | 1 | 4 | 160 MB | 573 |
+| `htdemucs_ft` | Fine-tuned v4, best overall quality | HTDemucs (v4) | 4 (fine-tuned) | 4 | 641 MB | 2292 |
+| `htdemucs_6s` | 6-source v4 (adds guitar + piano stems) | HTDemucs (v4) | 1 | 6 | 105 MB | 565 |
+| `hdemucs_mmi` | v3 hybrid, trained on more data | HDemucs (v3) | 1 | 4 | 319 MB | 379 |
+| `mdx` | v3 bag-of-models ensemble | Demucs + HDemucs | 4 (bag) | 4 | 1.3 GB | 1298 |
+| `mdx_extra` | v3 ensemble trained on extra data | HDemucs | 4 (bag) | 4 | 1.2 GB | 1516 |
+| `mdx_q` | Quantized v3 ensemble (same quality, smaller) | Demucs + HDemucs | 4 (bag) | 4 | 1.3 GB | 1298 |
+| `mdx_extra_q` | Quantized v3 extra ensemble | HDemucs | 4 (bag) | 4 | 1.2 GB | 1516 |
 
 All models output stereo audio at 44.1 kHz.
 
@@ -39,8 +39,7 @@ All models output stereo audio at 44.1 kHz.
 
 - Original model/repo: [adefossez/demucs](https://github.com/adefossez/demucs)
 - License: MIT (same as original Demucs)
-- Conversion path: PyTorch checkpoints → `demucs-mlx` pickle → safetensors + JSON config
-- MLX Python port: [ssmall256/demucs-mlx](https://github.com/ssmall256/demucs-mlx)
+- Conversion path: PyTorch checkpoints → safetensors + JSON config (direct, no intermediary)
 - Swift MLX port: [iky1e/demucs-mlx-swift](https://github.com/iky1e/demucs-mlx-swift)
 
 No fine-tuning or quantization was applied — these are direct conversions of the original pretrained weights.
@@ -52,14 +51,6 @@ Each model consists of two files at the repo root:
 - `{model_name}.safetensors` — model weights (float32)
 - `{model_name}_config.json` — model class, architecture config, and bag-of-models metadata
 
-Conversion scripts are also included:
-
-| Script | Description |
-|--------|-------------|
-| `export_all_models.py` | Batch export all demucs-mlx pickle checkpoints to safetensors |
-| `export_mdx.py` | Specialized PyTorch → safetensors converter for heterogeneous mdx bags |
-| `convert_demucs_mlx_checkpoint.py` | Single checkpoint converter (demucs-mlx pickle → safetensors) |
-
 ## Usage
 
 ### Swift (demucs-mlx-swift)
@@ -93,23 +84,22 @@ pip install demucs-mlx
 demucs-mlx -n htdemucs song.wav
 ```
 
-## Converting from demucs-mlx checkpoints
+## Converting from PyTorch
 
-To reproduce the export from existing `demucs-mlx` cache checkpoints:
+To reproduce the export directly from PyTorch Demucs checkpoints:
 
 ```bash
-# Export all models at once
-python export_all_models.py \
-  --cache-dir ~/.cache/demucs-mlx \
-  --out-dir ./output
-
-# Export a single model
-python convert_demucs_mlx_checkpoint.py \
-  --checkpoint ~/.cache/demucs-mlx/htdemucs_mlx.pkl \
-  --out-dir ./output \
-  --name htdemucs
+pip install demucs safetensors numpy
+
+# Export all 8 models
+python export_from_pytorch.py --out-dir ./output
+
+# Export specific models
+python export_from_pytorch.py --models htdemucs htdemucs_ft --out-dir ./output
 ```
 
+The conversion script (`export_from_pytorch.py`) is available in the [demucs-mlx-swift](https://github.com/iky1e/demucs-mlx-swift) repo under `scripts/`.
+
 ## Citation
 
 ```bibtex