update README with final state, full pipeline inference, LM generation step

README.md

@@ -26,100 +26,98 @@ startup_duration_timeout: 2h
 
 ## Features
 
-- **Music Generation** - Text/lyrics to stereo 48kHz MP3 via GGUF quantized models
-- **LoRA Training** - Fine-tune on your own audio (Side-Step engine, Adafactor optimizer)
-- **Multiple LM Sizes** - 0.6B / 1.7B / 4B language models (on-demand download)
-- **CPU Only** - Runs on free HuggingFace Spaces (2 vCPU, 18GB RAM)
+- **Music Generation** -- text/lyrics to stereo 48kHz MP3 via GGUF quantized models
+- **LoRA Training** -- fine-tune on your own audio (~11s/epoch CPU, ~1.4s/epoch GPU)
+- **Auto-Captioning** -- librosa BPM/key/signature + LM understand mode (caption + lyrics extraction)
+- **Multiple LM Sizes** -- 0.6B / 1.7B / 4B language models (on-demand download)
+- **Cancel + Download** -- cancel training mid-epoch, download trained LoRA adapter
 
 ## Music Generation
 
-1. Enter a music description (e.g. "upbeat electronic dance music")
+1. Enter a music description
 2. Enter lyrics or check **Instrumental**
 3. Adjust BPM, duration, steps, seed
-4. Select LM model (1.7B default, fastest on CPU)
-5. Select LoRA adapter if trained
-6. Click **Generate Music**
+4. Select LoRA adapter if trained
+5. Click **Generate Music**
 
-**Timing:** ~270s for 10s audio with 1.7B LM, 8 steps.
+**Timing:** ~270s for 10s audio with 1.7B LM, 8 steps on CPU.
 
 ## LoRA Training
 
-1. Go to **Train LoRA** tab
-2. Upload audio files (WAV/MP3, max 240s each)
-3. Set LoRA name, epochs (1-10), rank (default 16)
-4. Click **Train** - ace-server stops during training, restarts after
-5. Use **Cancel** to stop early (saves checkpoint)
-6. Trained adapter appears in the LoRA dropdown for inference
+1. Upload audio files (any length, auto-tiled at 30s chunks by VAE)
+2. Set LoRA name, epochs, learning rate, rank
+3. Click **Train** -- ace-server stops during training, restarts after
+4. Use **Cancel** to stop early (saves checkpoint)
+5. **Download** the trained adapter file
+6. Trained adapter appears in the LoRA dropdown
 
-**Timing:** ~170s preprocessing + ~10s/epoch on CPU.
+**Timing:** ~170s preprocessing + ~11s/epoch on CPU. GPU: ~1.4s/epoch.
 
-## Models
+**Limits:** 30 min total audio across all files. Files exceeding the cap are truncated with a warning. 50 files max. 8h training timeout.
 
-| Component | GGUF | Size |
-|-----------|------|------|
-| DiT (music) | acestep-v15-xl-turbo-Q4_K_M | 2.8 GB |
-| LM (captions) | acestep-5Hz-lm-1.7B-Q8_0 | 1.7 GB |
-| Text Encoder | Qwen3-Embedding-0.6B-Q8_0 | 0.75 GB |
-| VAE | vae-BF16 | 0.32 GB |
+**Settings (per Side-Step author recommendations):**
+- LR: 3e-4
+- Rank: 32, Alpha: 64
+- Epochs: 200-500 for 3-10 files
+- Optimizer: Adafactor (minimal memory)
+- Variant: standard turbo (not XL -- XL swaps on 18GB)
 
-LM alternatives (on-demand download): 0.6B Q8_0 (slow), 4B Q5_K_M (best quality, ~515s).
+## Captioning Pipeline
 
----
+Training audio is auto-captioned before preprocessing:
+
+| Method | What it extracts | Speed |
+|--------|-----------------|-------|
+| **librosa** | BPM, key, time signature | ~3s/file |
+| **LM understand** (GPU) | Rich caption + lyrics + metadata | ~52s/file |
+| **ace-server /understand** (Space) | Same as LM, via GGUF | ~30s/file |
+| **.txt/.json sidecar** | User-provided caption (if present) | instant |
+
+On Space: uses ace-server /understand before training. Locally: uses PyTorch LM understand.
+
+## Models
+
+| Component | GGUF | Size | Purpose |
+|-----------|------|------|---------|
+| DiT XL turbo | acestep-v15-xl-turbo-Q4_K_M | 2.8 GB | Music generation (no LoRA) |
+| DiT standard turbo | acestep-v15-turbo-Q4_K_M | 1.1 GB | Music generation (with LoRA) |
+| LM 1.7B | acestep-5Hz-lm-1.7B-Q8_0 | 1.7 GB | Caption understanding |
+| Text Encoder | Qwen3-Embedding-0.6B-Q8_0 | 0.75 GB | Text encoding |
+| VAE | vae-BF16 | 0.32 GB | Audio encode/decode |
 
 ## API
 
-### Python Client - Generate Music
+### Generate Music
 
 ```python
 from gradio_client import Client
 
 client = Client("WeReCooking/ACE-Step-CPU")
-
 result = client.predict(
     caption="upbeat electronic dance music",
     lyrics="[Instrumental]",
-    instrumental=True,
-    bpm=120,
-    duration=10,
-    seed=-1,                          # -1 = random
-    steps=8,                          # 1-32, fewer = faster
-    lora_select="None (no LoRA)",     # or trained adapter name
+    instrumental=True, bpm=120, duration=10, seed=-1, steps=8,
+    lora_select="None (no LoRA)",
     lm_model_select="acestep-5Hz-lm-1.7B-Q8_0.gguf",
     api_name="/generate"
 )
-print(result)  # (audio_path, status_message)
 ```
 
-### Python Client - Train LoRA
+### Train LoRA
 
 ```python
 from gradio_client import Client, handle_file
 
 client = Client("WeReCooking/ACE-Step-CPU")
-
 result = client.predict(
     audio_files=[handle_file("song.mp3")],
-    lora_name="my-style",
-    epochs=3,
-    lr=0.0001,
-    rank=16,
+    lora_name="my-style", epochs=200, lr=0.0003, rank=32,
     api_name="/train_lora"
 )
-print(result)  # (log_text, train_btn, cancel_btn)
-```
-
-### Python Client - Server Status
-
-```python
-result = client.predict(api_name="/server_status")
-print(result)  # JSON with model info
 ```
 
 ### MCP (Model Context Protocol)
 
-This Space supports MCP for AI assistants (Claude Desktop, Cursor, VS Code).
-
-**MCP Config:**
 ```json
 {
   "mcpServers": {
@@ -128,44 +126,24 @@ This Space supports MCP for AI assistants (Claude Desktop, Cursor, VS Code).
 }
 ```
 
----
-
-## CLI Usage
+## CLI
 
 ```bash
-# Generate music
-python app.py "upbeat electronic dance music" --duration 10 --steps 8 --format mp3
-
-# With lyrics
-python app.py "pop ballad" --lyrics "Hello world\nThis is a test" -d 30
-
-# With LoRA adapter
+python app.py "upbeat electronic dance music" --duration 10 --steps 8
 python app.py "jazz piano" --adapter my-style --seed 42
-
-# Custom server URL
-python app.py "ambient" --server http://localhost:8085
 ```
 
----
-
 ## Architecture
 
-```
-ace-server (C++ GGUF)     Gradio UI (Python)
-  /lm    -> LM generate     app.py
-  /synth -> DiT + VAE       train_engine.py (Side-Step)
-  /health                    |
-  /props                     +-- preprocess_audio()
-  /job                       +-- train_lora_generator()
-```
-
-- **Inference:** GGUF via [acestep.cpp](https://github.com/ServeurpersoCom/acestep.cpp) HTTP API
-- **Training:** PyTorch via ported [Side-Step](https://github.com/koda-dernet/Side-Step) engine
-- Training stops ace-server (free RAM), restarts after with new adapters
+- **Inference:** GGUF via [acestep.cpp](https://github.com/ServeurpersoCom/acestep.cpp)
+- **Training:** PyTorch, ported from [Side-Step](https://github.com/koda-dernet/Side-Step) (commit ecd13bd)
+- **Captioning:** librosa + LM understand (PyTorch or ace-server /understand)
+- Training stops ace-server to free RAM, restarts after with new adapters
+- Inference blocked during training with clear message
 
 ## Credits
 
-- [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) - Model architecture
-- [acestep.cpp](https://github.com/ServeurpersoCom/acestep.cpp) - GGUF inference engine
-- [Side-Step](https://github.com/koda-dernet/Side-Step) - Training engine (ported)
-- [Serveurperso/ACE-Step-1.5-GGUF](https://huggingface.co/Serveurperso/ACE-Step-1.5-GGUF) - Quantized models
+- [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5)
+- [acestep.cpp](https://github.com/ServeurpersoCom/acestep.cpp)
+- [Side-Step](https://github.com/koda-dernet/Side-Step)
+- [Serveurperso/ACE-Step-1.5-GGUF](https://huggingface.co/Serveurperso/ACE-Step-1.5-GGUF)