Add known good MelodyFlow local setup

README.md

@@ -41,6 +41,48 @@ Where these findings are documented:
 - operational notes and fork workflow: [docs/MELODYFLOW.md](./docs/MELODYFLOW.md)
 - hub-facing model card notes: [model_cards/MELODYFLOW_MODEL_CARD.md](./model_cards/MELODYFLOW_MODEL_CARD.md)
 
+## Known Good Local Setup
+
+This is the local setup that actually produced usable text-to-music output during recovery work:
+
+- a Python environment dedicated to MelodyFlow inference
+- the released checkpoint directory, for example `facebook/melodyflow-t24-30secs`
+- the official MelodyFlow Space checkout or a maintained fork of that checkout
+- code that imports `MelodyFlow` from that Space checkout and loads checkpoints with `weights_only=False` when required on PyTorch 2.6+
+
+Operationally, the local flow looked like this:
+
+1. Set a model directory pointing at the released checkpoint folder.
+2. Set a code checkout pointing at the official Space or your maintained fork.
+3. Import `from audiocraft.models import MelodyFlow` from that checkout.
+4. Call `MelodyFlow.get_pretrained(...)` against the local checkpoint directory.
+5. Generate audio only after the code path and checkpoint-loading path are confirmed correct.
+
+Example pattern:
+
+```python
+import torch
+from pathlib import Path
+
+space_repo = Path("path/to/MelodyFlowSpace-or-your-fork")
+model_dir = Path("path/to/melodyflow-t24-30secs")
+
+original_load = torch.load
+
+def trusted_load(*args, **kwargs):
+    kwargs.setdefault("weights_only", False)
+    return original_load(*args, **kwargs)
+
+torch.load = trusted_load
+try:
+    from audiocraft.models import MelodyFlow
+    model = MelodyFlow.get_pretrained(str(model_dir), device="cuda")
+finally:
+    torch.load = original_load
+```
+
+If your local run does not resemble that shape, fix the setup first and only then investigate prompts or solver tuning.
+
 
 ## Installation
 AudioCraft requires Python 3.9, PyTorch 2.1.0. To install AudioCraft, you can run the following:

docs/MELODYFLOW.md

@@ -22,6 +22,18 @@ If you are running MelodyFlow locally, the main failure mode we hit was not prom
 
 Read the sections below before debugging sampler settings.
 
+### Known Good Local Shape
+
+The local inference path that worked reliably had these pieces:
+
+1. a dedicated MelodyFlow Python environment
+2. a local checkout of the official MelodyFlow Space or a maintained fork
+3. a local checkpoint directory for `facebook/melodyflow-t24-30secs`
+4. imports resolved from the Space checkout, not from an older generic AudioCraft clone
+5. a trusted checkpoint load path that can force `weights_only=False` on PyTorch 2.6+
+
+If any of those pieces differ, treat that as a setup issue first.
+
 
 ## Model Card