Upload README.md with huggingface_hub

README.md

@@ -76,58 +76,112 @@ Trained on [REAL-PS4](https://huggingface.co/datasets/TaurenMountain/REAL-PS4),
 
 ## Usage
 
-### Load the Model
+### Quick Start (recommended)
+
+Use the included [`inference.py`](inference.py) — a self-contained script with absolutely no external dependencies beyond `torch`, `torchaudio`, and `numpy`:
+
+```bash
+# Install dependencies
+pip install torch torchaudio numpy
+
+# Single file extraction
+python inference.py \
+    --checkpoint checkpoint_epoch037.pt \
+    --mix mix.wav \
+    --enroll target_speaker.wav \
+    --output result.wav
+
+# Use GPU
+python inference.py \
+    --checkpoint checkpoint_epoch037.pt \
+    --mix mix.wav \
+    --enroll target.wav \
+    --output result.wav \
+    --device cuda
+
+# Batch mode (process all .wav files in a directory)
+python inference.py \
+    --checkpoint checkpoint_epoch037.pt \
+    --mix-dir ./mixtures/ \
+    --enroll-dir ./enrollments/ \
+    --output-dir ./results/ \
+    --device cuda
+
+# List available CUDA devices
+python inference.py --list-devices
+```
+
+### Python API
 
 ```python
 import torch
+from inference import BSRNN, load_audio, extract_speaker, load_checkpoint, build_model
 
-# Load checkpoint
-ckpt = torch.load("checkpoint_epoch037.pt", map_location="cpu")
+# Build model and load weights
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+model = build_model(device)
+load_checkpoint("checkpoint_epoch037.pt", model, device)
+
+# Load audio (16 kHz mono)
+mix = load_audio("mixture.wav")
+enroll = load_audio("enrollment.wav")
+
+# Run extraction
+extracted = extract_speaker(model, mix, enroll, device)
 
-# The checkpoint contains the full TSE model state dict
-# Compatible with the wesep BSRNN + ECAPA-TDNN framework
-model_state = ckpt["model"] if "model" in ckpt else ckpt
+# Save result
+torchaudio.save("result.wav", extracted, 16000)
 ```
 
-### Inference Example
+### Advanced: Manual Model Loading
 
 ```python
 import torch
 import torchaudio
-from wesep.models import get_model
+from inference import BSRNN
 
-# Initialize model (must match training config)
-model = get_model("BSRNN")(
+# Build model with exact training config
+model = BSRNN(
     feat_type="consistent",
     feature_dim=128,
     num_repeat=6,
     spk_emb_dim=192,
     spk_fuse_type="multiply",
+    multi_fuse=False,
     spk_model="ECAPA_TDNN_GLOB_c512",
-    sr=16000,
-    win=512,
-    stride=128,
+    sr=16000, win=512, stride=128,
+    spk_args={"feat_dim": 80, "embed_dim": 192, "pooling_func": "ASTP"},
+    spk_model_freeze=True,
+    use_spk_transform=False,
+    joint_training=True,
+    multi_task=False,
+    spk_feat=False,
 )
-
-# Load PS4 weights
-ckpt = torch.load("checkpoint_epoch037.pt", map_location="cpu")
-model.load_state_dict(ckpt["model"] if "model" in ckpt else ckpt)
 model.eval()
 
-# Load mixture and enrollment audio (16 kHz mono)
-mixture, sr = torchaudio.load("mixture.wav")
-enrollment, sr = torchaudio.load("enrollment.wav")
+# Load checkpoint
+ckpt = torch.load("checkpoint_epoch037.pt", map_location="cpu")
+state_dict = ckpt["model"] if "model" in ckpt else ckpt
+model.load_state_dict(state_dict, strict=False)
 
-# Run extraction
+# Run inference
+mix, sr = torchaudio.load("mixture.wav")
+enroll, sr = torchaudio.load("enrollment.wav")
 with torch.no_grad():
-    extracted = model(mixture, enrollment)
+    extracted, _ = model(mix, enroll)
 ```
 
-> **Note:** The speaker encoder is frozen during training (`spk_model_freeze: true`). For inference, use the same ResNet34-LM speaker encoder as the evaluation pipeline: `voxceleb_resnet34_LM` for English, `cnceleb_resnet34_LM` for Chinese.
+## What's in this repository
 
-## Pretrained Backbone
+| File | Description |
+|------|-------------|
+| `checkpoint_epoch037.pt` | PS4 model weights (epoch 37, proxy-supervised fine-tuned) |
+| [`inference.py`](inference.py) | Self-contained inference script (no external ML libs required) |
+| `README.md` | This file |
 
-PS4 is fine-tuned from `bsrnn_ecapa_vox1`, a BSRNN + ECAPA-TDNN model pretrained on VoxCeleb1. The proxy-supervised fine-tuning on REAL-PS4 adapts the model to real far-field multi-speaker meeting conditions.
+The training code, dataset, and full evaluation pipeline are available at:
+- **Training code:** [GitHub - TaurenMountain/real-t](https://github.com/TaurenMountain/real-t) (see `opensource/code/`)
+- **Dataset:** [TaurenMountain/REAL-PS4](https://huggingface.co/datasets/TaurenMountain/REAL-PS4)
 
 ## Citation