Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,98 @@
+---
+language:
+- zh
+license: mit
+tags:
+- music-source-separation
+- chinese-folk-music
+- audio
+- pytorch
+datasets:
+- ccmusic-database/CTIS
+- ccmusic-database/erhu_playing_tech
+- ccmusic-database/Guzheng_Tech99
+- M4Singer/M4Singer
+---
+
+# Loom of Time — Model Weights
+
+Model checkpoints for **Loom of Time (岁月织机)**, an interactive art installation
+presented at ACM Multimedia 2026 (Interactive Art Track).
+
+**GitHub repository:** [HAoyu-baller/Loom-of-Time-Music-Viz](https://github.com/HAoyu-baller/Loom-of-Time-Music-Viz)
+
+---
+
+## Contents
+
+```
+models/
+  separator/
+    best.pt       # BSRoformer 5-stem separator (best val loss)
+    last.pt       # BSRoformer 5-stem separator (final epoch)
+  classifier/
+    loom_best.pth # ResNet18 regional classifier (5 Chinese folk regions)
+```
+
+---
+
+## Models
+
+### BSRoformer Separator (`models/separator/best.pt`)
+
+Separates a Chinese folk music recording into 5 stems:
+**vocal · erhu · plucked strings · wind · percussion**
+
+| Config | Value |
+|---|---|
+| Architecture | Band-Split Rotary Transformer (BSRoformer) |
+| dim | 256 |
+| depth | 6 |
+| heads | 8 |
+| Parameters | ~15–20 M |
+| Sample rate | 22,050 Hz |
+| Chunk size | 132,300 samples (6 s) with 22,050-sample overlap |
+
+### ResNet18 Classifier (`models/classifier/loom_best.pth`)
+
+Classifies the regional origin of a Chinese folk song into one of 5 categories:
+**Jiangnan · Shaanxi · Yungui · Huanan · Dongbei**
+
+| Config | Value |
+|---|---|
+| Backbone | ResNet18 (ImageNet pretrained) |
+| Head | Dropout(0.4) → Linear(512,256) → ReLU → Dropout(0.3) → Linear(256,5) |
+| Input | Mel-spectrogram image (128 mel bins, magma colormap, 224×224 px) |
+| Inference | Chunk-based hard voting across 6-second clips |
+
+---
+
+## Usage
+
+See the [GitHub repository](https://github.com/HAoyu-baller/Loom-of-Time-Music-Viz)
+for full installation instructions and inference code.
+
+```python
+from huggingface_hub import hf_hub_download
+
+hf_hub_download('Haoyu123123/loom-of-time-models', 'models/separator/best.pt',
+                local_dir='backend/training/checkpoints')
+hf_hub_download('Haoyu123123/loom-of-time-models', 'models/classifier/loom_best.pth',
+                local_dir='backend/classifier/models')
+```
+
+---
+
+## Citation
+
+```bibtex
+@inproceedings{ruan2026loom,
+  title     = {Loom of Time: Real-Time Chinese Folk Music Decomposition
+               and Generative Weaving Visualization},
+  author    = {Ruan, Haoyu},
+  booktitle = {Proceedings of the 34th ACM International Conference on
+               Multimedia (Interactive Art Track)},
+  year      = {2026},
+  publisher = {ACM}
+}
+```