Length-gate text-CFG, hide CFG knobs, cap max_frames

- Runner disables CFG (cfg_scale->1.0) when text exceeds
generation.cfg_max_text_tokens (default 10): CFG helps short phrases
but rushes/flattens long ones.
- AppConfig parses generation.cfg_max_text_tokens; engine passes it to
the runner.
- Remove CFG scale / CFG frames sliders from the UI; strength now comes
from config defaults, application from the length gate. app.py sources
both from config.defaults.
- Default max_frames 2000 -> 1075 (~50s at 21.5 fps).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app.py

@@ -48,8 +48,6 @@ def synthesize(
     ref_audio: str,
     text: str,
     temperature: float,
-    cfg_scale: float,
-    cfg_frames: float,
     top_k: float,
     stop_threshold: float,
     max_frames: float,
@@ -76,8 +74,10 @@ def synthesize(
     params = GenerationParams(
         temperature=temperature,
         top_k=int(top_k),
-        cfg_scale=cfg_scale,
-        cfg_frames=int(cfg_frames),
+        # CFG is not exposed in the UI: strength comes from config defaults and
+        # the runner's length gate decides whether it applies at all.
+        cfg_scale=config.defaults.cfg_scale,
+        cfg_frames=config.defaults.cfg_frames,
         stop_threshold=stop_threshold,
         max_frames=int(max_frames),
         repetition_penalty=repetition_penalty,

config.yaml

@@ -28,10 +28,17 @@ defaults:
   cfg_scale: 3.0
   cfg_frames: 0
   stop_threshold: 0.5
-  max_frames: 2000
+  max_frames: 1075
   repetition_penalty: 1.0
   repetition_window: 32
 
+generation:
+  # Text-CFG (cfg_scale > 1) rescues short phrases from running away, but on
+  # longer text it rushes delivery (~2x) and flattens prosody. So CFG is only
+  # applied when the input has <= this many text tokens; past it, cfg_scale is
+  # forced to 1.0 (off) regardless of the slider. Set to null to never gate.
+  cfg_max_text_tokens: 10
+
 app:
   max_ref_seconds: 60     # uploaded/recorded reference audio is truncated to this
   gpu_duration: 120       # ZeroGPU seconds budget per request

gepard_inference/engine.py

@@ -68,6 +68,9 @@ class AppConfig:
         max_ref_seconds: Recorded/uploaded reference audio is truncated to
             this many seconds before encoding.
         gpu_duration: ZeroGPU time budget per request (seconds).
+        cfg_max_text_tokens: Disable text-CFG when the input has more than this
+            many text tokens (CFG helps short phrases but rushes/flattens long
+            ones). None = never gate.
         root: Directory of the config file; relative paths resolve against it.
     """
 
@@ -79,6 +82,7 @@ class AppConfig:
     defaults: GenerationParams = field(default_factory=GenerationParams)
     max_ref_seconds: float = 60.0
     gpu_duration: int = 120
+    cfg_max_text_tokens: Optional[int] = None
     root: Path = field(default_factory=Path.cwd)
 
     @classmethod
@@ -90,8 +94,10 @@ class AppConfig:
         model = raw.get("model") or {}
         codec = raw.get("codec") or {}
         app = raw.get("app") or {}
+        generation = raw.get("generation") or {}
         if not model.get("checkpoint"):
             raise ValueError(f"{path}: model.checkpoint is required")
+        cfg_max = generation.get("cfg_max_text_tokens")
         return cls(
             checkpoint=str(model["checkpoint"]),
             attn_implementation=str(model.get("attn_implementation", "eager")),
@@ -101,6 +107,7 @@ class AppConfig:
             defaults=GenerationParams(**(raw.get("defaults") or {})),
             max_ref_seconds=float(app.get("max_ref_seconds", 60.0)),
             gpu_duration=int(app.get("gpu_duration", 120)),
+            cfg_max_text_tokens=int(cfg_max) if cfg_max is not None else None,
             root=path.parent.resolve(),
         )
 
@@ -212,6 +219,7 @@ class GepardEngine:
         tokens = self.runner.generate(
             text,
             ref_codes=ref_codes.to(self.device) if ref_codes is not None else None,
+            cfg_max_text_tokens=self.config.cfg_max_text_tokens,
             **params.to_generate_kwargs(),
         )  # (num_heads, T)
 

gepard_inference/runner.py

@@ -178,6 +178,7 @@ class GepardRunner:
         force_stop_frames: Optional[int] = None,
         cfg_scale: float = 1.0,
         cfg_frames: Optional[int] = None,
+        cfg_max_text_tokens: Optional[int] = None,
         cfg_uncond_mode: str = "empty_text",
     ) -> torch.LongTensor:
         """Generate audio tokens for ``text``, optionally with a reference voice
@@ -206,6 +207,13 @@ class GepardRunner:
                 first N frames; later frames use the cond branch alone (the
                 uncond branch is then skipped to save compute). None = guide
                 every frame.
+            cfg_max_text_tokens: Length gate for text-CFG. If set and the input
+                has MORE than this many text tokens, CFG is turned off
+                (``cfg_scale`` forced to 1.0) for this call. CFG rescues short
+                phrases from running away, but on longer text it rushes
+                delivery (~2x) and flattens prosody — so it is only worth
+                applying to short inputs. None = no gate (always honour
+                ``cfg_scale``).
             cfg_uncond_mode: How to build the text-free uncond branch:
                 "empty_text" → [BOS_text, EOT, BOS_audio] (cleanest contrast);
                 "audio_only" → [BOS_audio] (most aggressive; more OOD).
@@ -215,10 +223,21 @@ class GepardRunner:
             compatible with ``UnfoldedCodecModel.decode_from_codes()`` after
             adding a batch dim: ``tokens.unsqueeze(0)``.
         """
-        cfg_on = cfg_scale != 1.0
-
         # 1. Build cond text_ids (with adaptive repetition).
         text_token_ids = self.tokenizer.encode(text, add_special_tokens=False)
+
+        # Length gate: CFG only helps short phrases latch onto the speech
+        # manifold. On longer text it rushes delivery (~2x) and flattens
+        # prosody, so disable it past the threshold.
+        if cfg_max_text_tokens is not None and len(text_token_ids) > cfg_max_text_tokens:
+            if cfg_scale != 1.0:
+                print(
+                    f"[GepardRunner] text has {len(text_token_ids)} tokens "
+                    f"(> cfg_max_text_tokens={cfg_max_text_tokens}); disabling CFG."
+                )
+            cfg_scale = 1.0
+
+        cfg_on = cfg_scale != 1.0
         cond_ids = self.repeater.expand(text_token_ids)
 
         # 1b. Build uncond text_ids (SAME prefix later, text removed).

interface.py

@@ -85,9 +85,10 @@ class GepardInterface:
         config: Application config (slider defaults, speaker names, limits).
         speaker_names: Preset speaker display names for the dropdown.
         synthesize_fn: Callable with the signature
-            ``(mode, speaker, ref_audio, text, temperature, cfg_scale,
-              cfg_frames, top_k, stop_threshold, max_frames,
-              repetition_penalty, repetition_window) -> (sr, np.ndarray)``.
+            ``(mode, speaker, ref_audio, text, temperature, top_k,
+              stop_threshold, max_frames, repetition_penalty,
+              repetition_window) -> (sr, np.ndarray)``. CFG is not a UI knob;
+            it is driven by config defaults + the runner's length gate.
             Wrapped with the ZeroGPU decorator by the caller.
     """
 
@@ -124,7 +125,7 @@ class GepardInterface:
             """
             return self.synthesize_fn(
                 MODE_PRESET, speaker_name, None, example_text,
-                d.temperature, d.cfg_scale, d.cfg_frames, d.top_k,
+                d.temperature, d.top_k,
                 d.stop_threshold, d.max_frames, d.repetition_penalty,
                 d.repetition_window,
             )
@@ -175,16 +176,6 @@ class GepardInterface:
                             label="Temperature",
                             info="Sampling temperature; lower = more stable, higher = more varied.",
                         )
-                        cfg_scale = gr.Slider(
-                            1.0, 6.0, value=d.cfg_scale, step=0.25,
-                            label="CFG scale",
-                            info="Text guidance weight. 1 = off; 2–3 sharpens text/voice adherence.",
-                        )
-                        cfg_frames = gr.Slider(
-                            0, 200, value=d.cfg_frames, step=5,
-                            label="CFG frames",
-                            info="Guide only the first N frames (0 = guide the whole utterance).",
-                        )
                         top_k = gr.Slider(
                             0, 200, value=d.top_k, step=1,
                             label="Top-k",
@@ -243,7 +234,7 @@ class GepardInterface:
                 fn=self.synthesize_fn,
                 inputs=[
                     mode, speaker, ref_audio, text,
-                    temperature, cfg_scale, cfg_frames, top_k,
+                    temperature, top_k,
                     stop_threshold, max_frames, repetition_penalty, repetition_window,
                 ],
                 outputs=[output_audio],