fix: guidance_scale 1.0 everywhere, ace-understand auto-detect

guidance_scale:
- Replaced all remaining 7.0 with 1.0 (README, examples, tests).
- Fixed debug-dit-cossim.py CFG threshold: > 1.0 to match C++ (was > 0,
  causing Python to run 2x forward + APG while C++ skipped CFG).

ace-understand:
- Reads acestep.is_turbo from DiT GGUF and writes matching defaults
  (steps/shift/guidance) so the output JSON works as-is with dit-vae.
  The rest is up to the JSON, dit-vae just does what it says.

examples/understand-roundtrip.sh:
- Roundtrip: audio -> ace-understand -> dit-vae -> 4 WAV variations.
  Uses --src-audio with audio_cover_strength 0.04 (2 out of 50 SFT steps
  use the source as context). High values stay close to the source, low
  values let the model diverge.

Author: ServeurpersoCom

README.md

@@ -238,7 +238,7 @@ cat > /tmp/repaint.json << 'EOF'
     "repainting_start": 10.0,
     "repainting_end": 25.0,
     "inference_steps": 50,
-    "guidance_scale": 7.0,
+    "guidance_scale": 1.0,
     "shift": 1.0
 }
 EOF
@@ -263,7 +263,7 @@ cat > /tmp/lego.json << 'EOF'
     "lyrics": "[Instrumental]",
     "lego": "guitar",
     "inference_steps": 50,
-    "guidance_scale": 7.0,
+    "guidance_scale": 1.0,
     "shift": 1.0
 }
 EOF
@@ -383,7 +383,7 @@ Valid names: `vocals`, `backing_vocals`, `drums`, `bass`, `guitar`,
 When set, passes the source audio to the DiT as context and builds the
 instruction `"Generate the {TRACK} track based on the audio context:"`.
 `audio_cover_strength` is forced to 1.0 (all steps see the source audio).
-Use `inference_steps=50`, `guidance_scale=7.0`, `shift=1.0` for base model.
+Use `inference_steps=50`, `guidance_scale=1.0`, `shift=1.0` for base model.
 
 ### LM sampling (ace-qwen3)
 

examples/ace-understand.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Roundtrip: audio -> understand -> SFT DiT -> 4 WAV variations
+#
+# Usage: ./understand-roundtrip.sh input.wav (or input.mp3)
+#
+# understand:
+# input -> ace-understand.json (audio codes + metadata)
+#
+# dit-vae:
+# ace-understand.json -> output0.wav .. output3.wav
+
+set -eu
+
+if [ $# -lt 1 ]; then
+    echo "Usage: $0 <input.wav|input.mp3>"
+    exit 1
+fi
+
+input="$1"
+
+../build/ace-understand \
+    --src-audio "$input" \
+    --dit ../models/acestep-v15-sft-Q8_0.gguf \
+    --vae ../models/vae-BF16.gguf \
+    --model ../models/acestep-5Hz-lm-4B-Q8_0.gguf \
+    -o ace-understand.json
+
+sed -i \
+    -e 's/"audio_cover_strength": *[0-9.]*/"audio_cover_strength": 0.04/' \
+    ace-understand.json
+
+../build/dit-vae \
+    --src-audio "$input" \
+    --request ace-understand.json \
+    --text-encoder ../models/Qwen3-Embedding-0.6B-Q8_0.gguf \
+    --dit ../models/acestep-v15-sft-Q8_0.gguf \
+    --vae ../models/vae-BF16.gguf \
+    --batch 4 \
+    --wav

examples/dit-only.json

@@ -7,5 +7,6 @@
     "timesignature": "4",
     "vocal_language": "en",
     "inference_steps": 8,
+    "guidance_scale": 1.0,
     "shift": 3.0
 }

examples/lego.json

@@ -3,6 +3,6 @@
     "lyrics": "[Instrumental]",
     "lego": "guitar",
     "inference_steps": 50,
-    "guidance_scale": 7.0,
+    "guidance_scale": 1.0,
     "shift": 1.0
 }

examples/partial.json

@@ -4,5 +4,6 @@
     "duration": 200,
     "vocal_language": "fr",
     "inference_steps": 8,
+    "guidance_scale": 1.0,
     "shift": 3.0
-}
+}

examples/simple-sft.json

@@ -1,7 +1,7 @@
 {
     "caption": "Upbeat pop rock anthem with driving electric guitars, punchy drums, catchy vocal hooks, and a singalong chorus",
+    "vocal_language": "fr"
     "inference_steps": 50,
     "guidance_scale": 1.0,
     "shift": 1.0,
-    "vocal_language": "fr"
 }

examples/simple.json

@@ -1,6 +1,7 @@
 {
     "caption": "Upbeat pop rock anthem with driving electric guitars, punchy drums, catchy vocal hooks, and a singalong chorus",
+    "vocal_language": "fr"
     "inference_steps": 8,
+    "guidance_scale": 1.0,
     "shift": 3.0,
-    "vocal_language": "fr"
 }

tests/debug-dit-cossim.py

@@ -23,7 +23,7 @@
     "sft": {
         "gguf_base": "acestep-v15-sft",
         "config_path": "acestep-v15-sft",
-        "steps": 50, "shift": 1.0, "guidance": 7.0,
+        "steps": 50, "shift": 1.0, "guidance": 1.0,
     },
 }
 
@@ -146,7 +146,7 @@ def run_python(dump_dir, req, cfg, lora_dir=None):
     from acestep.handler import AceStepHandler
 
     os.makedirs(dump_dir, exist_ok=True)
-    has_cfg = cfg["guidance"] > 0
+    has_cfg = cfg["guidance"] > 1.0
 
     caption  = req["caption"]
     lyrics   = req.get("lyrics", "")
@@ -319,7 +319,7 @@ def detok_hook(module, input, output):
 # comparison
 
 def build_stages(cfg):
-    has_cfg = cfg["guidance"] > 0
+    has_cfg = cfg["guidance"] > 1.0
     steps = cfg["steps"]
     stages = [
         "text_hidden", "lyric_embed", "enc_hidden", "detok_output", "context", "noise",
@@ -434,7 +434,7 @@ def run_mode(mode_name, cfg, req, gguf_path, lora_dir=None):
 
     tag = mode_name.upper() if mode_name == "sft" else mode_name.capitalize()
     cfg_str = f"steps={cfg['steps']}, shift={cfg['shift']}"
-    if cfg['guidance'] > 0:
+    if cfg['guidance'] > 1.0:
         cfg_str += f", CFG={cfg['guidance']}"
     print(f"[{tag}] {cfg_str} | {os.path.basename(gguf_path)}")
 

tools/ace-understand.cpp

@@ -583,6 +583,24 @@ int main(int argc, char ** argv) {
         out.timesignature  = parsed.timesignature;
         out.vocal_language = parsed.vocal_language;
         out.audio_codes    = codes_str;
+
+        // Set DiT defaults from model type (turbo vs SFT/base)
+        if (dit_gguf) {
+            GGUFModel gf = {};
+            if (gf_load(&gf, dit_gguf)) {
+                if (gf_get_bool(gf, "acestep.is_turbo")) {
+                    out.inference_steps = 8;
+                    out.shift           = 3.0f;
+                    out.guidance_scale  = 1.0f;
+                } else {
+                    out.inference_steps = 50;
+                    out.shift           = 1.0f;
+                    out.guidance_scale  = 1.0f;
+                }
+                gf_close(&gf);
+            }
+        }
+
         request_write(&out, output_path);
     }